DocumentationAPI EndpointsFAQ'sSupplier Connect
Backoffice Login

JSON Data Format Details

The JSON Catalog format is a list of Objects and multiple arrays, with defining products details nested within. All "Critical" keys are mandatory, with proper formatting established for associated values.

Suggest Edits
[
   {
      "vendorSku":"12345-1058",
      "name":"TDF Pro Frameset",
      "variation":{
         "color":"Matte Black/Charcoal/Blue",
         "size":"58"
      },
      "isVisible":"Yes",
      "groupID":"106261",
      "language":"en",
      "description":"The TDF Pro Frameset has a race-specific geometry that's optimized for long-distance timed events on diverse terrain. With a carbon fiber fork, it's waiting to be built up exactly how you want it.",
      "additionaldescription":"<ul><li>Features the same carbon fiber seatpost found on our TDF-4</li><li>Geometry specially designed for long-distance races</li><li>The frame is constructed from carbon fiber, and it features a race-specific geometry</li></ul>",
      "msrp": 7.99,
      "defaultCost": 2.50,
      "brand":"TDF",
      "customCategories":[
         "Race"
      ],
      "gtin":"989676375934",
      "shippingDimensions":{
         "height":{
            "unit":"in",
            "value":30
         },
         "length":{
            "unit":"in",
            "value":39
         },
         "width":{
            "unit":"in",
            "value":6.9996
         }
      },
      "shippingWeight":{
         "unit":"lbs",
         "value":11.02
      },
      "images":[
         "https://c1.staticflickr.com/2/1368/5098190130_74c7f355bb_b.jpg",
         "https://s0.geograph.org.uk/geophotos/05/65/36/5653610_43500d35.jpg",
         "https://encrypted-tbn0.gstatic.com/images?q=tbn:ANd9GcTUXir1OMoonCHo4NHmA_nUBJy0gh_zyDhTbvNtcN3Xk39iDaGX"
      ]
   }
]

Single product

A single product is a product or service that is not offered in variations such as size or color. Product Examples

Product variation

Products are sometimes available in several options such as size or color. For example, you might offer a shirt available in 5 sizes and 3 colors.

Each combination of options represents a unique product variation. The above example of a shirt available in 5 sizes and 3 colors can result in 15 possible variations:

  • Shirt: X-small, White
  • Shirt: Small, White
  • Shirt: Medium, White
  • Shirt: Large, White
  • Shirt: X-Large, White
  • Shirt: X-small, Black
  • Shirt: Small, Black
  • and so on...

Product Examples

We treat each combination of options as a separate product to give you the flexibility to submit product information specific to a variation, such as images, dimensions, etc.

Use the groupID to display the variations together in the product catalog much like on any other online marketplace.

vendorSku: required

The vendorSku (stock keeping unit) is a non-standardized code used to identify a specific product or variant from a vendor or distributor. Retailers often use the vendorSku to find and order a specific product from a specific vendor.

Examples

  • APL-IPHONE-XS-BLK-256
  • 95418-7148

Minimum requirements

  • Every product and variant in your catalog must have a unique vendorSku.
  • vendorSku is case-insensitive: ABC123 = abc123

Code Example

{
  "vendorSku": "APL-IPHONE-XS-BLK-256",
  "name": "iPhone XS"
}

name: required

The name attribute is what retail staff, the shop owner, and end-consumers refer to the product as in everyday conversation. It is displayed to retailers in the product catalog and end-consumers shopping online.

Examples

  • iPhone XS
  • Men's Diverge E5 Sport

Minimum requirements

  • Every product and variant must have a name
  • Describe the name in a human readable way
  • Avoid using ALL CAPS or oDD-formATing that is not easy to read
  • Avoid describing the brand name and option values:
    *Ex. Apple iPhone XS - Black - 256MB

Code example 

{
  "vendorSku": "APL-IPHONE-XS-BLK-256",
  "name": "iPhone XS"
}

isVisible: Recommended

The isVisible Boolean field is used to mark whether an item in your Catalog is visible to all Retailers viewing your Catalog List. This is particularly useful when items become unavailable, but have a need to review historical data for those items marked "No".

Item data persists in Lightspeed even when marked as "No", so simply updating with "Yes" at a later time will allow items to display again.

  • The default visibility for an item is set to "Yes" - this value is not required to upload items.
{
  "vendorSku": "95418-7148",
  "name": "S-Works",
  "description": "Un bin beau vélo",
  "isVisible": "Yes"/"No"
}

language: required

Use language to specify the language of the product information you're providing. You can also upload the same product in multiple languages.

Examples

  • fr
  • en
  • es

Minimum requirements

  • Must be a valid ISO 639-1 code.

Code Example

{
  "vendorSku": "95418-7148",
  "name": "S-Works",
  "description": "Un bin beau vélo",
  "language": "fr"
}
{
  "vendorSku": "95418-7148",
  "name": "S-Works",
  "description": "A very nice bike",
  "language": "en"
}

manufacturerSku

The manufacturerSku (stock keeping unit) is a non-standardized code used to identify a specific product or variant from a brand or manufacturer. Retailers often use the manufacturerSku to find and order a specific product from a brand.

Examples

  • APL-IPHONE-XS-BLK-256
  • 95418-7148

Minimum requirements

  • manufacturerSku is case-insensitive: ABC123 =/= abc123

Code example 

{
  "vendorSku": "APL-IPHONE-XS-BLK-256",
  "manufacturerSku": "APPLE-XS-BLACK",
  "name": "iPhone XS"
}

variation

A variation is a product that represents a specific combination of available options (such as size or color). A variation will always have an option name and an option value that describes the variation the customer is viewing.

Examples

  • name:value
  • Size: 256gb
  • Color: Black
  • Material: Carbon

Minimum requirements

A variant must always include the following fields:

  • option name
  • option value
  • groupID

Code Examples

{
  "variation": {
    "Option Name": "Option Value",
  },
}

{
  "vendorSku": "APL-IPHONE-XS-BLK-256",
  "name": "iPhone XS",
  "variation": {
    "Size": "256GB",
    "Color": "Black"
  },
  "groupID": "APL-IPHONE-XS",
}

attributes

The detailed specifications of a product. This describes the technical details of the product. Attributes are displayed as a list in the product details of the catalog. Attributes always have an attribute name and an attribute value that describes them.

Examples

  • name: value
  • Chainrings: 48/32T
  • Talk time (wireless): Up to 20 hours

Minimum requirements

  • Always include a name and value for each attribute.
  • List the attributes in the order you want them to appear.
{
  "attributes": {
    "Attribute name": "Attribute value",
  }
}

{
  "vendorSku": "95418-7148",
  "name": "Men's Diverge E5 Sport",
  "attributes": {
    "Chainrings": "48/32T",
    "Cassette": "Sunrace, 9-speed, 11-32t",
    "Rear derailleur": "Shimano Sora, long cage, 9-speed",
    "Shift levers": "Shimano Sora",
    "Crankset": "Praxis Alba 2d"
  }
}

groupID

groupID is used to display a group of variations together in the product catalog. All variations in your file that have the same group_id will display in the product catalog as a product with multiple options to choose from.

Examples

  • APL-IPHONE-XS
  • 95418

Minimum Requirements

  • groupID is case-insensitive: ABC123 = abc123****
  • A variant must always include the following fields:
    - option name
    - option value
    - groupID

Code Example 

{
"vendorSku":"APL-IPHONE-XS-BLK-256",
"name":"iPhone XS",
"variation":{
    "Size": "256GB",
    "Color": "Black",
    },
"groupID":"APL-IPHONE-XS",
}
{
"vendorSku":"APL-IPHONE-XS-BLK-512",
"name":"iPhone XS",
"variation":{
    "Size": "512GB",
    "Color": "Black",
    },
"groupID":"APL-IPHONE-XS",
}

description

Use description to explain basic details about what the product is.

Examples

  • "With the Diverge Sport, you'll be prepared for anything, from smooth tarmac to the loosest, roughest tracks out there. It's packed with all the same technologies as its pricier cousins, only its spec places an emphasis on reliable performance, not components so flashy you'll be eating nothing but top ramen for months."

Minimum requirements

  • description is optional for every product and variation
  • HTML markup is not accepted in the description field

Code Example

{
  "vendorSku": "APL-IPHONE-XS-BLK-256",
  "name": "iPhone XS",
  "description": "Super Retina in two sizes — including the largest display ever on an iPhone. Even faster Face ID. The smartest, most powerful chip in a smartphone. And a breakthrough dual‑camera system with Depth Control. iPhone XS is everything you love about iPhone. Taken to the extreme."
}

LINE BREAK EXAMPLE:

{
"vendorSku": "APL-IPHONE-XS-BLK-256",
  "name": "iPhone XS",
  "description": "<div>Hello,</div><div><p>This is</p><p>another line!</p></div>"
}

additionalDescription

Use additionalDescription to explain specific details about your product.

Examples

  • Our Premium E5 aluminum frameset features our comfortable, yet confidence-inspiring, Open Road Geometry. Front & rear thru-axles are also included, making this Diverge the ultimate tool for your next adventure.
  • The lightweight FACT carbon fork is plenty stiff, aiding in handling, rigidity, and an overall light weight.
  • The Praxis Alba 2D is an incredibly stiff crankset with supreme ramping for precise shifts between the rings.

This is displayed in the catalog as

  • Our Premium E5 aluminum frameset features our comfortable, yet confidence-inspiring, Open Road Geometry. Front & rear thru-axles are also included, making this Diverge the ultimate tool for your next adventure.
    -The lightweight FACT carbon fork is plenty stiff, aiding in handling, rigidity, and an overall light weight.
  • The Praxis Alba 2D is an incredibly stiff crankset with supreme ramping for precise shifts between the rings.

Minimum requirements

  • additionalDescription is an optional field
  • Supported HTML tags:
strong, em, ul, ol, li, br, sub, sup, div, span, dl, dt, dd, table, tbody, thead, tr, th, td, img

Code Example

{
  "vendorSku": "APL-IPHONE-XS-BLK-256",
  "name": "iPhone XS",
  "additionalDescription": "<ul><li>Super Retina HD display</li><li>5.8‑inch (diagonal) all‑screen OLED Multi‑Touch display</li><li>HDR display</li></ul>"
}

LINE BREAK EXAMPLE:

{
"vendorSku": "APL-IPHONE-XS-BLK-256",
  "name": "iPhone XS",
  "additionalDescription": "<div>Hello,</div><div><p>This is</p><p>another line!</p></div>"
}

msrp

The "Manufacturer Suggested Retail Price" is the recommended selling price defined by the Vendor. This gives a baseline price for Retailers to sell the products they order from you.

Examples

  • 100.00
  • 10,000.00
  • 54.99
  • 0.00

Minimum Requirements

  • No currency symbols ($, £, €)
  • Numbers and Periods(.) only
  • If no MSRP is to be specified, you must place 0.00

Code Example

{
  "vendorSku": "95418-7148",
  "msrp": 100.00
}

defaultCost:Required**

The price Retailers pay you, the Vendor, for your products.

Examples

  • 24.70
  • 30.00
  • 1200.00

Minimum Requirements

  • no Currency Symbols ($, £, €)
  • numbers and periods(.) only

Code Example

{
  "vendorSku": "95418-7148",
  "defaultCost": 54.00
}

gtin

Global trade identification number (GTIN), is a standardized identification code used in barcodes to identify a specific product or variation. The standardization of GTIN allows vendors and retailers to identify a unique product sold anywhere on earth. No two products have the same GTIN.

GTIN variations

GTIN type Description

UPC Used in North America, UPC is a 12-digit number like 323456789012. 8-digit UPC-E codes should be converted to 12-digit codes

EAN Used in Europe, EAN is a 13-digit number like 3001234567892

ISBN Used for books, ISBN is a 10 or 13-digit number like 1455582344 or 978-1455582341. If you have both, only include the 13-digit number. ISBN-10 are deprecated and should be converted to ISBN-13

ITF-14 Used for multipacks, GTIN-14 is a 14-digit number like 10856435001702

Examples

  • 10856435001702
  • 323456789012

Minimum requirements

  • All gtin types are an optional field
  • A gtin must be unique for every product and variation in your catalog (two different products cannot have the same gtin)
  • A gtin must be included for any physical products that will be sold in-store or shipped to customers
  • If you sell the exact same product that another vendor also sells, make sure you are using the same gtin.
  • gtinUpc must be between 8 and 12 characters
  • gtinEan must be 13 characters
  • gtinItf14 must be 14 characters
  • gtinIsbn must be between 10 and 13 characters (not including the dashes)

Code Example 

{
  "vendorSku": "APL-IPHONE-XS-BLK-256",
  "name": "iPhone XS",
  "gtinUpc": "323456789012",
  "gtinEan": "3001234567892",
  "gtinItf14": "10856435001702",
  "gtinIsbn": "978-3-16-148410-0",
}

customCategories

Used primarily for navigation and ease of discovery within the product catalog, customCategories classifies a group of similar products together. A product or variation will be placed in each category you list in your file. Navigating on the front-end, this results in the customer being able to find your product in each of those categories.

Examples

  • Women's
    Jackets
    Pants
    Accessories
  • Snowboard
    Boots
    Bindings
    Boards

Minimum requirements

  • customCategory is an optional field
  • List them in the order of navigation (like a website) from top to bottom.

Code Example 

{
  "vendorSku": "95418-7148",
  "name": "Men's Diverge E5 Sport",
  "customCategories": [
    "Bikes",
    "Road Bikes",
    "Adventure & Gravel Bikes",
    "Men's Diverge"
  ]
}

brand: required

The brand or sub-brand to which this item is sold under.

Examples

  • Apple
  • Specialized
  • Nike
  • Nike SB
  • NikeLab

Minimum requirements

  • brand is a required field for all products and variations.

Code Example 

{
  "vendorSku": "95418-7148",
  "name": "Men's Diverge E5 Sport",
  "brand": "Specialized"
}

image

Use image to upload the photograph, image or graphic that represents this product or variation.

Examples

Minimum requirements

  • Minimum 1 image per product/variation
  • Maximum 12 images per product/variation
  • Upload high quality images
  • If your product is available in several colors, upload a specific image for each color variation so that each color has its own image.
  • Include the http or https in your image URL
  • Be consistent with the dimensions of your images to create a uniform experience

Code example 

{
  "vendorSku": "95418-7148",
  "name": "Men's Diverge E5 Sport",
  "images": [
    "https://media.specialized.com/mixed_media/BRD-3528_PDP_Hero_1440x810.jpg",
    "https://media.specialized.com/mixed_media/BRD-3528_PDP_Hero_1040x600.jpg"
  ]
}

Note

Images are cached, but only after the first time the image URL(s) provided is requested. It is thereby possible that if you remove the image at the URL(s) provided, and it is not requested before being removed, it will be inaccessible.

shippingDimensions

Use shippingDimensions to help retailers determine the shipping costs for the product during checkout. This is typically the height, length and width of the product in its shipping form, often within a package. We currently only accept cm and in for dimensional units.

Examples

  • 21 in
  • 39 cm

Minimum requirements

  • Submit units of measurement in cm or in
  • Minimum value = 0
  • Maximum value = 500

Code Example 

{
  "vendorSku": "95418-7148",
  "name": "Men's Diverge E5 Sport",
  "shippingDimensions": {
    "height": {
      "unit": "in",
      "value": 222
    },
    "length": {
      "unit": "in",
      "value": 298
    },
  }
}

shippingWeight

Use shippingWeight to help retailers determine the shipping costs for the product during checkout. This is typically the weight of the product in its shipping form, often within a package. We currently only accept g (grams), kg(kilograms), oz (ounces), and lbs (pounds) for measurement units.

Examples

  • 191 g
  • 19 oz

Minimum requirements

  • Submit units of measurement in g, kg, oz, or lbs only

Code Example 

{
  "vendorSku": "95418-7148",
  "name": "Men's Diverge E5 Sport",
  "shippingWeight": {
    "unit": "g",
    "value": 4567
  }
}

Updated over 3 years ago

What’s Next