Backfill Product Data

What you’ll learn

• Comparative methods of product creation
• How you can use backfill data to create your own products

Product creation methods

There are 2 high level ways that you can create products (Adverts) in Marketplacer using our APIs:

1. Method 1: Supply all the data that is needed to create a valid product
2. Method 2: Use centrally managed “backfill” data

Method 1 - Supply all required data

Method 1 is described in detail here. In a nutshell this method requires that you provide all mandatory data required to ensure that the product is considered valid by the marketplace operator. Depending on the attributes, catalog and vetting rules required by the operator this can be a relatively onerous task.

NOTE: Assuming you have been granted access to use the Seller API, this method is generally available for use.

Method 2 - Use pre-created backfill data

Method 2 allows you to leverage “Golden Product” data stored in the Marketplacer Central Product Database (CPD). This is a data set of “approved” product descriptions managed by the Operator (Sellers cannot directly create or update this information).

For a full overview of what Golden Products are, and how they are managed, you can read the Operator Guide on the subject, once again noting that direct Golden Product data manipulation is not available to Sellers.

How it works

1. Golden Product data is created and managed by the operator and stored in the CPD
2. Sellers then use 1 of the supported product mutations (described below) to supply:

• A barcode (hopefully matching a stored Golden Product)
• “Offer Attributes” not stored in the CPD, e.g. stock position, price etc.

3. Depending on the mutation used, barcode matching is performed either:

• Immediately
• On a schedule

4. Assuming a successful match, Golden Product data is backfilled on to your product

Examples

The following examples demonstrate 2 different mutations that you can use to create products using backfilled data.

variantUpsertFromBarcode

The variantUpsertFromBarcode mutation will allow you to immediately create products using a barcode for a product held in the CPD. An example can be found below:

NOTE: You do not need to have the Backfill Policy for the seller enabled for this mutation to work - adverts and variants will be created immediately with backfilled data.

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": {
    "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.

advertUpsert

The advertUpsert mutation will allow you to create products using a barcode for a product held in the CPD. While a product entity will be created immediately, it will not be backfilled with matching CPD data until the Backfill Scheduler runs. An example can be found below:

NOTE: You need to have the Backfill Policy enabled for the seller in order that product data is backfilled.

Mutation

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

Variables

{
  "input": {
    "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 the supply a full data set (see Method 1 above).

From a data backfill perspective (Method 2), 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.