Identifiers

Extended information on product and variant identifiers.

Overview​

Use the Product Identifier and Variant Identifier fields to clearly identify the product that you are selling. The identifiers won't be shown to customers who view your products online.

When to use​

Required for each product and variant

Format​

Follow these formatting guidelines to make sure that Axiom understands the data that you're submitting.

Identifiers must be unique across your live catalogue: a product_identifier already in use by one of your products is rejected, and so is a variant_identifier already in use by one of your variants.

Guidelines​

Follow these guidelines to make sure that you submit high-quality data for your products.

Minimum requirements​

These are the requirements that you'll need to meet to show your product. If you don't follow these requirements, we could reject your product.

• Submit a unique identifier for each different product.
• Use a stable identifier for each product. Once you've assigned an identifier to a product, don't change it. The identifier that you choose, identifies the product.
• Use the same identifier for the same product targeting different countries or different languages within the same country. You can create translations or pricing rules depending on the country, store and language.
  • If you target a multilingual country, like Switzerland, use the same identifier for a product shared in each supported language such as German, French and Italian.
  • If you target multiple countries, like the United States and Canada, use the same identifier for a product shared between countries.
• Don't use casing to make identifiers unique. Product identifiers are case-insensitive in the Axiom platform, there may be cases in which two products with product IDs that differ only by casing are interpreted as the same product. For example, if you submit identifier 'abc123' for one product and identifier 'ABC123' for another, these products may be confused. Instead of casing, use unique combinations of letters and numbers to differentiate products.
• Don't reuse or recycle the same identifier for different products. For example:
  • Don't reuse an identifier for different products in the same target country or language.
  • Don't reuse an identifier for products with variants. Each variant is a unique product and needs its unique identifier.
  • Don't recycle an identifier for new products. Even if you're not selling a product anymore or the product is out of stock, don't use that product's identifier for any other product.
• Avoid white space. White space before and after the identifier is removed automatically, but white space inside it is kept — ABC 123 and ABC 123 are two different identifiers.
• Don't submit invalid Unicode characters. These characters are generally added during your file's encoding process. To avoid them, use UTF-8 encoding. Examples of invalid Unicode characters include:
  • Control characters (e.g. U+200D)
  • Function characters
  • Private area characters
  • Surrogate pairs
  • Unassigned code points

Best practices​

These best practices can help you go beyond the basic requirements to optimise your product data for performance.

• Use internal system immutable identifiers where possible. As internal system identifiers can be guaranteed to be unique this can help prevent errors. Using SKUs as identifiers here is not recommended as they are generally not immutable and are often not a referenceable object in an e-commerce system.

Examples​

Products without variants​

A simple product carries one product_identifier and everything needed to order it: sku, unit_size, unit_label, and exactly one MPN and one UNSPSC code. manufacturer and brand are required; prices, categories, images, resources, properties and the product page URL are optional.

{
  "type": "simple",
  "product_identifier": "nzpkuuirhtia",
  "name": "BeeBlot Automated Immunoblot Processor",
  "brand": "BeeBlot",
  "manufacturer": "Gold Standard Diagnostics",
  "sku": "123",
  "unit_size": "1 x each",
  "unit_label": "EA",
  "description": "Automates the protocol for most strip-based assays, including line immunoassays and traditional Western blots.",
  "codes": [
    { "type": "MPN", "code": "13411862134" },
    { "type": "UNSPSC", "code": "41100000" }
  ],
  "prices": [
    { "price": "38467.37", "country": "GB", "currency": "GBP" }
  ],
  "categories": ["Home", "Blotting Apparatus"],
  "properties": {
    "Capacity": "50 strips per run",
    "Dimensions": "64 x 62 x 45 cm",
    "Power supply": "100-240V, 50-60Hz"
  },
  "image_urls": ["https://www.example.com/images/13411356.jpg"],
  "product_page_url": "https://www.example.com/products/13411864"
}

Products with variants​

A complex product is a parent that groups variants. The parent holds the shared descriptive information and its own product_identifier; each variant holds its own variant_identifier, plus the details that make it individually orderable.

Two rules catch people out here:

• codes are rejected on a complex parent. Put the MPN and UNSPSC on each variant instead.
• prices sent on a complex parent are ignored. Price each variant.

sku, unit_size and unit_label are optional on the parent and required on every variant, and each variant needs at least one option.

{
  "type": "complex",
  "product_identifier": "nzpkuuirhtia",
  "name": "BeeBlot Automated Immunoblot Processor",
  "brand": "BeeBlot",
  "manufacturer": "Gold Standard Diagnostics",
  "description": "Automates the protocol for most strip-based assays, including line immunoassays and traditional Western blots.",
  "categories": ["Home", "Blotting Apparatus"],
  "image_urls": ["https://www.example.com/images/13411356.jpg"],
  "product_page_url": "https://www.example.com/products/13411864",
  "variants": [
    {
      "variant_identifier": "nzpkuuirhtia-1",
      "name": "BeeBlot Automated Immunoblot Processor, 24 strip",
      "brand": "BeeBlot",
      "sku": "123-1",
      "unit_size": "1 x each",
      "unit_label": "EA",
      "options": [{ "name": "Capacity", "value": "24 strips" }],
      "codes": [
        { "type": "MPN", "code": "13411862134-1" },
        { "type": "UNSPSC", "code": "41100000" }
      ],
      "prices": [
        { "price": "38467.37", "country": "GB", "currency": "GBP" }
      ]
    },
    {
      "variant_identifier": "nzpkuuirhtia-2",
      "name": "BeeBlot Automated Immunoblot Processor, 48 strip",
      "brand": "BeeBlot",
      "sku": "123-2",
      "unit_size": "1 x each",
      "unit_label": "EA",
      "options": [{ "name": "Capacity", "value": "48 strips" }],
      "codes": [
        { "type": "MPN", "code": "13411862134-2" },
        { "type": "UNSPSC", "code": "41100000" }
      ],
      "prices": [
        { "price": "52140.00", "country": "GB", "currency": "GBP" }
      ]
    }
  ]
}

Note that manufacturer is not repeated on the variants. It belongs to the parent, and every variant reports the manufacturer of the product it belongs to. type and categories work the same way — they describe the product, not the variant.

Same product in multiple languages​

Send the product again with the same product_identifier — and the same variant_identifier for variants — and a different language_code. Matching identifiers are what tie the languages together, so a new identifier per language creates separate products rather than translations. See Multi-language support for what is stored per language and what is shared.