How to use Golden Products

In this how to guide we discuss what are Golden Products and how to manipulate them using the Operator API

  8 minute read  

What you’ll learn

  • What’s a Golden Product and how does it relate to regular products
  • Use-cases when a Golden Product can be useful
  • The queries and mutations you can use to manipulate Golden Products

What’s a Golden Product?

Before answering what is a “Golden Product” it’s worth reviewing the characteristics of a regular product, or as we call them here at Marketplacer, Adverts:

Note: We’ll use the term “product” and “advert” interchangeably in this article

  • Adverts are created, and placed for sale on the operators marketplace by a seller
  • An Advert has a large number of attributes (full list here)
  • Adverts must have at least 1 variant, as it’s at the variant level that concepts such as inventory, barcodes and SKUs reside.
    • Indeed when orders are placed, it is the variantId that is used to identify the purchased item.
  • Adverts “belong” to each individual seller, so while 2 or more separate sellers on the marketplace can sell the “same” product, from a Marketplacer perspective they are separate Advert objects, each with a unique Marketplacer ID.

The diagram below shows a simple set up with 2 sellers, each selling their own products.

Advert Schema

Enter the Golden Product

So what is a Golden Product and why would we use one? Imagine the following scenarios:

  1. The marketplace operator wants to ensure details for certain products (adverts) are provided in a consistent way
  2. The marketplace operator wants the seller experience of creating products to be a fast as possible
  3. The marketplace operator wants to have the ability group the same product sold by different sellers into a “buy box” or similar
  4. The marketplace operator wants to ingest product descriptions and definitions from 3rd party services to act as the template for products on their marketplace

These scenarios illustrate some of the benefits in adopting Golden Products, which are effectively product templates from which other products can be defined.

How it works

The following outlines how Golden Products can be created and leveraged to enhance the onboarding of seller products

Step 1 - Create a Golden Product

Golden Products reside in the Central Product Database (CPD), and can be created in 1 of 2 ways:

  1. Created directly by the operator using either:
    • The Operator Portal
    • The GraphQL API (covered in this Guide)
    • Spreadsheet upload
  2. Created indirectly when a new product is created by a seller that:
    • Does not already exist in the CPD
    • Contains enough detail to be used to create a Golden Product
    • The auto-create from variant option is enabled
    • [Optional] If product vetting is enabled - then the product will need to be approved

We will only be focused on direct Golden Product creation using the GraphQL API in this guide.

Step 2 - Create Seller Products

When sellers then create their products they can be linked to Golden products in 1 of ways:

  1. Via the barcode
  2. Directly linking the seller variant Id to the Golden Variant

These 2 methods are described in more detail below

1. Barcode Linking
  • A barcode that is supplied with the seller product variant matches a barcode related to a Golden Product variant
  • Auto linking is enabled (i.e seller products will be linked to Golden Products)
  • [Optional] If product vetting is enabled - then the product will need to be approved

The newly created seller product will have its data attributes backfilled from the Golden Product - noting that the backfill process runs on an hourly schedule and is not immediate.

2. Direct Variant Id Linking

You can elect to directly link seller created variants to Golden Product Variants by associating the seller variant Id to the respective Golden Variant.

The diagram below illustrates 2 seller products linked to a Golden Product via barcode:

Golden Product

Golden Product Queries & Mutations

Query Golden Products

This query is used to return the Golden Products that you have created.

Query

query GetAllGoldenProducts(
	$pageSize: Int,
	$advertPageSize: Int,
	$activeStatus: GoldenProductActiveStatusEnum
) {
	goldenProducts(
		first: $pageSize, 
		after: null, 
		activeStatus: $activeStatus) {
		totalCount
		pageInfo {
			...PageInfoPartial
		}
		nodes {
			id
			title
			goldenProductVariants {
				nodes {
					id
				}
			}
			adverts(first: $advertPageSize, after: null) {
				nodes {
					id
					title
					seller {
						businessName
					}
				}
				totalCount
				pageInfo {
					...PageInfoPartial
				}
			}
		}
	}
}

fragment PageInfoPartial on PageInfo {
	hasNextPage
	endCursor
}

Variables

{
	"gpPageSize": 20,
	"advertPageSize": 20,
	"activeStatus": "ACTIVE"
}

Query Golden Product Associated to an Advert

This query enables you to view the Golden Products associated to an individual Advert.

Query

query GetGoldenProductForAdvert($id: ID!) {
	node(id: $id) {
		... on Advert {
			id
			title
			legacyId
			variants {
				nodes {
					id
					legacyId
					barcode
					sku
				}
			}
			goldenProduct {
				id
				goldenProductVariants {
					nodes {
						id
					}
				}
			}
		}
	}
}

Variables

{
	"id": "QWR2ZXJ0LTEwMDA3NzY4OQ=="
}

Query Golden Product Associated to an Variant

This query enables you to view the Golden Products Variants associated to an individual variant.

Query

query GetGoldenProductForVariant($id: ID!) {
	node(id: $id) {
		... on Variant {
			id
			goldenProductVariant {
				id
			}
		}
	}
}

Variables

{
	"id": "VmFyaWFudC00OTU1"
}

Create a Golden Product

This mutation enables you to create a new Golden Product.

Mutation

mutation goldenProductCreate($attributes: GoldenProductInput!) {
	goldenProductCreate(input: { attributes: $attributes }) {
		goldenProduct {
			id
			legacyId
			title
			description
			goldenProductVariants {
				nodes {
					id
				}
			}
			adverts {
				nodes {
					id
				}
			}
			active
		}
		errors {
			field
			messages
		}
	}
}

Variables

{
	"attributes": {
		"title": "Golden Egg WiFi Router",
		"brandId": "QnJhbmQtNjg=",
		"taxonId": "VGF4b24tMjc4",
		"description": "This is a top of the line router",
		"saleType": "BUY_ONLINE_OR_CLICK_AND_COLLECT",
		"images": [
			{
				"sourceUrl": "https://picsum.photos/200"
			}
		]
	}
}

Update a Golden Product

This mutation enables you to update an existing Golden Product.

Mutation

mutation goldenProductUpdate(
	$goldenProductId: ID!
	$attributes: GoldenProductUpdateInput!
) {
	goldenProductUpdate(
		input: { goldenProductId: $goldenProductId, attributes: $attributes }
	) {
		goldenProduct {
			id
			# other GoldenProduct fields
		}
		errors {
			field
			messages
		}
	}
}

Variables

{
	"goldenProductId": "R29sZGVuUHJvZHVjdC03Ng==",
	"attributes": {
		"description": "This is an updated version of the original description"
	}
}

Delete a Golden Product

This mutation enables you to delete an existing Golden Product.

Mutation

mutation goldenProductDelete($id: ID!) {
  goldenProductDelete(input: { id: $id }) {
    errors {
      field
      messages
    }
  }
}

Variables

{
	"id": "R29sZGVuUHJvZHVjdC04MQ=="
}

Query an individual Golden Product

This query enables you to delete an existing Golden Product.

Query

query GetGoldenProduct($id: ID!) {
	node(id: $id) {
		... on GoldenProduct {
			id
			legacyId
			title
			active
			goldenProductVariants {
				nodes {
					id
					active
					barcodes
					sku
				}
			}
			adverts {
				nodes {
					id
					title
					legacyId
					variants {
						nodes {
							id
							legacyId
							label
						}
					}
				}
			}
		}
	}
}

Variables

{
	"id": "R29sZGVuUHJvZHVjdC04Mg=="
}

Create a Golden Product Variant

This mutation enables you to create a new Golden Product Variant on an existing Golden Product.

Mutation

mutation goldenProductVariantCreate($attributes: GoldenProductVariantInput!) {
	goldenProductVariantCreate(input: { attributes: $attributes }) {
		goldenProductVariant {
			id
			notes
			description
			barcodes
			sku
			itemSize
			measurementItemUnit {
				id
			}
			optionValues {
				nodes {
					id
				}
			}
		}
		errors {
			field
			messages
		}
	}
}

Variables

{
	"attributes": {
		"goldenProductId": "R29sZGVuUHJvZHVjdC04Mg==",
		"description": "Variant Golden Product Description",
		"barcodes": [
			"978020137962"
		],
		"sku": "abc1234",
		"optionValues": [
			{
				"optionValueId": "T3B0aW9uVmFsdWUtNzMx"
			}
		]
	}
}

Update a Golden Product Variant

This mutation enables you to update an existing Golden Product Variant.

Mutation

mutation goldenProductVariantUpdate(
	$goldenProductVariantId: ID!
	$attributes: GoldenProductVariantUpdateInput!
) {
	goldenProductVariantUpdate(
		input: {
			goldenProductVariantId: $goldenProductVariantId
			attributes: $attributes
		}
	) {
		goldenProductVariant {
			id
			notes
			description
			barcodes
			sku
			optionValues {
				nodes {
					id
				}
			}
		}
		errors {
			field
			messages
		}
	}
}

Variables

{
	"goldenProductVariantId": "R29sZGVuUHJvZHVjdFZhcmlhbnQtNTk=",
	"attributes": {
		"goldenProductId": "R29sZGVuUHJvZHVjdC03OQ==",
		"description": "Variant Golden Product Description updated"
	}
}

Delete a Golden Product Variant

This mutation enables you to delete an existing Golden Product Variant.

Mutation

mutation goldenProductVariantDelete($id: ID!) {
	goldenProductVariantDelete(input: { id: $id }) {
		errors {
			field
			messages
		}
	}
}

Variables

{
	"id": "R29sZGVuUHJvZHVjdFZhcmlhbnQtNTk="
}

Activate a Golden Product Variant

This mutation enables you to set the active status of one or more existing Golden Product Variants to true

Mutation

mutation goldenProductVariantsActivate($goldenProductVariantIds: [ID!]!) {
	goldenProductVariantsActivate(
		input: { goldenProductVariantIds: $goldenProductVariantIds }
	) {
		goldenProductVariants {
			id
			active
		}
		errors {
			field
			messages
		}
	}
}

Variables

{
	"goldenProductVariantIds": [
		"R29sZGVuUHJvZHVjdFZhcmlhbnQtNjE="
	]
}

Deactivate a Golden Product Variant

This mutation enables you to set the active status of one or more existing Golden Product Variants to false

Mutation

mutation goldenProductVariantsDeactivate($goldenProductVariantIds: [ID!]!) {
	goldenProductVariantsDeactivate(
		input: { goldenProductVariantIds: $goldenProductVariantIds }
	) {
		goldenProductVariants {
			id
			active
		}
		errors {
			field
			messages
		}
	}
}

Variables

{
	"goldenProductVariantIds": [
		"R29sZGVuUHJvZHVjdFZhcmlhbnQtNjE="
	]
}

This mutation enables associate 1 or more seller variants directly to a Golden Product Variant

Mutation

mutation goldenProductVariantUnlinkVariants(
	$goldenProductVariantId: ID!
	$variantIds: [ID!]!
) {
	goldenProductVariantLinkVariants(
		input: {
			goldenProductVariantId: $goldenProductVariantId
			variantIds: $variantIds
		}
	) {
		goldenProductVariant {
			id
			variants {
				nodes {
					id
					advert {
						... on Advert {
							legacyId
						}
					}
				}
			}
		}
		errors {
			field
			messages
		}
	}
}

Variables

{
	"goldenProductVariantId": "R29sZGVuUHJvZHVjdFZhcmlhbnQtNjM=",
	"variantIds": [
		"VmFyaWFudC04NDkzNw=="
	]
}

This mutation enables unlink 1 or more seller variants from to a Golden Product Variant

Mutation

mutation goldenProductVariantUnlinkVariants(
	$goldenProductVariantId: ID!
	$variantIds: [ID!]!
) {
	goldenProductVariantLinkVariants(
		input: {
			goldenProductVariantId: $goldenProductVariantId
			variantIds: $variantIds
		}
	) {
		goldenProductVariant {
			id
			variants {
				nodes {
					id
					advert {
						... on Advert {
							legacyId
						}
					}
				}
			}
		}
		errors {
			field
			messages
		}
	}
}

Variables

{
	"goldenProductVariantId": "R29sZGVuUHJvZHVjdFZhcmlhbnQtNjM=",
	"variantIds": [
		"VmFyaWFudC04NDkzNw=="
	]
}