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

  11 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 a supplied 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
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 linking of 1 or more seller variants directly to a Golden Product Variant

Mutation

mutation goldenProductVariantLinkVariants(
	$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 unlinking of 1 or more seller variants from a Golden Product Variant

Mutation

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

Variables

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

Merge Golden Products

When multiple instances of a Golden Product occur, you will most likely want to merge into 1 Golden Product; the following mutation enables this.


Mutation

mutation GoldenProductsMerge($ids: [ID!]!) {
  goldenProductsMerge(input: { goldenProductIds: $ids }) {
    goldenProduct {
      id
      title
    }
    errors {
      field
      messages
    }
  }
}

Variables

{
  "ids": [
    "R29sZGVuUHJvZHVjdC00",
    "R29sZGVuUHJvZHVjdC03",
    "R29sZGVuUHJvZHVjdC0yMA=="
  ]
}

Merge Rules

  • Retained product: Chosen based on highest variant count, or oldest if tied
  • Removed product: Deleted after merge
  • Variants & adverts: Reassigned to the retained product
  • Product Details: Preserved from the retained product; differences in product data are not resolved/combined automatically

Create Advert using variantUpsertFromBarcode

Using this mutation does not require that the ProductDB Backfill Policy is set, and will create products with backfilled data immediately upon a successful barcode match.

Mutation

mutation createProductFromBarcodeImmediate(
  $input: VariantUpsertFromBarcodeMutationInput!
) {
  variantUpsertFromBarcode(input: $input) {
    variant {
      countOnHand
      advert {
        ... on Advert {
          id
          title
        }
        ... on UnpublishedAdvert {
          id
          details {
            title
          }
        }
      }
    }
    errors {
      field
      messages
    }
  }
}

Variables

{
  "input": {
    "sellerId": "U2VsbGVyLTY2MDE3MQ==",
    "barcode": "5054990132277",
    "attemptPublish": true,
    "attributes": {
      "price": 20,
      "salePrice": 10,
      "countOnHand": 100
    }
  }
}

How it works

Scenario 1 - New Advert & Variant Created
  • The mutation is called with a valid barcode (and there is an existing golden variant with a matching barcode in the CPD).
  • A new advert & variant is created under the seller with the same attributes as the matched barcode.
  • If “Offer Attributes” are provided (e.g. price, count on hand), the new seller variant is created with those attributes.
Scenario 2 - Update an existing variant
  • The mutation is called with a valid barcode and it matches a variant that already belongs to the seller
  • If offer attributes are provided (e.g. price, count on hand), the existing seller variant is updated with those attributes.
Scenario 3 - Create a new variant but assign to existing advert
  • The seller has one advert with one variant having barcode X. One golden record exists with two variants, with one having barcode X and another barcode Y.
  • The mutation is called with barcode: Y
  • Instead of creating a new advert & new variant under the seller, the mutation creates a new variant under the existing advert.

NOTE: this behavior exists because we want the grouping of seller products to respect that of the golden products. Variants should belong under the correct advert as specified in the CPD.

 

Create Advert using advertUpsert

Assuming that you have the ProductDB Backfill Policy set accordingly (and the Golden Products feature is enabled), you can use advertUpsert to create products using a supplied barcode.

NOTE: This method will backfill product detail using a scheduled batch process. So while the Advert will be created immediately, the backfilling of product data will take up to 1 hour.


Mutation

mutation createProductFromBarcode($input: AdvertUpsertMutationInput!) {
  advertUpsert(input: $input) {
    advert {
      id
    }
    errors {
      field
      messages
    }
  }
}

Variables

{
  "input": {
    "sellerId": "U2VsbGVyLTY2MDExOQ==",
    "attributes": {
      "title": "title will be backfilled from CPD data",
      "description": "description will be backfilled from CPD data",
      "attemptAutoPublish": true,
      "variants": [
        {
          "countOnHand": 999,
          "barcode": "1232131232121"
        }
      ]
    }
  }
}

How it works

advertUpsert is designed to work across a range of product creation methods, the majority of which relate to supplying a full data set.

From a data backfill perspective, it works as follows:

  • Unless a valid existing product identifier is supplied in the payload - a new product will be created every time this mutation is called (it is non-idempotent in this scenario).

Note that in this context, a barcode is not considered a valid product identifier.

  • Product data will then be backfilled in-line with the configured Backfill Policy which occurs on a scheduled basis.