Formatting Your Data

Merchstack's import requires your data to be formatted a certain way for the import to work properly. If you're unable to send us your data in our preferred format, let us know and we'll work through the options with you.

Overview

The data you are required to send Merchstack can vary depending on your use case. At a minimum, Merchstack requires categories and products to create your catalog in our platform and allow you to start using the platform.

Dataset	Required	Description
Categories	Yes	Needed for all use cases
Products	Yes	Needed for all use cases
Pricing	No	Optionally required for certain calculated category strategies and storefront integrations
Inventory	No	Optionally required for certain calculated category strategies and storefront integrations

Categories

Categories are one of the core primitives of the Merchstack platform. To learn more about Categories in Merchstack, read the Category Concept documentation.

Managed and Unmanaged Categories

Categories created in Merchstack are called "managed" categories, meaning they are managed by the Merchstack system and we are the system of record. Categories imported from your system are called "unmanaged" and generally the only change we will make to an unmanaged category is to add extra data like indexable facets or related categories.

Example Category Record

This record would normally be on one line in the JSONL format but is formatted as a regular JSON document for clarity.

{
  "importMetaData": {
    "formatVersion": "1.0",
    "importId": "123xyz",
    "recordNum": 55,
    "recordOf": 300,
    "recordType": "category",
    "operationType": "create"
  },
  "tenantId": "ABC",
  "storeId": "123",
  "externalSystemId": "456",
  "enabled": false,
  "featuredExternalAssetId": "22314",
  "assignmentMethod": "Manual",
  "customFields": {
    "key": "value"
  },
  "isRoot": false,
  "externalSystemParentId": "123",
  "translations": [
    {
      "languageCode": "en",
      "name": "Men's Dress Shoes",
      "navName": "Dress Shoes",
      "slug": "dress-shoes",
      "description": "Shoes that Men love to wear when they're fancy",
      "pageTitle": "Men's Dress Shoes",
      "pageDescription": "Shoes that Men love to wear"
    }
  ],
  "assets": [
    {
      "externalSystemAssetId": "22314",
      "name": "clothing__95.jpg",
      "type": "IMAGE",
      "mimeType": "image/jpeg",
      "width": 159,
      "height": 235,
      "source": "cloudinary/path/to/image/clothing__95.jpg",
      "focalPoint": {
        "x": 23,
        "y": 45
      }
    }
  ]
}

Properties

Name
tenantId
Type
type: string
Required
required
Description
The unique identifier assigned to your tenant by Merchstack.
Name
storeId
Type
type: string
Required
required
Description
The unique identifier assigned to your store by Merchstack.
Name
externalSystemId
Type
type: string
Required
required
Description
The identifier assigned to a category in the integrated system.
Name
isPrivate
Type
type: boolean
Required
required
Description
Indicates whether this category is publicly available to your end customers (e.g., a sale category before or after a sale event).
Name
featuredAssetId
Type
type: string
Required
Description
The Asset ID of the image displayed on the Category page.
Name
assignmentMethod
Type
type: string
Required
Description
Whether products are either manually or automatically assigned to a category. Normally this will always be "Manual"
Name
customFields
Type
type: object
Required
Description
An object containing additional key-value pairs that provide extra information about the category.
Name
isRoot
Type
type: boolean
Required
required
Description
Indicates whether this category is the top-level category (e.g., "Mens").
Name
externalSystemParentId
Type
type: string
Required
required
Description
If the category is not a root category, this property represents the external system ID of its parent category.
Name
translations
Type
type: array of translation objects
Required
required
Description
An array containing translation objects that represent different language versions of the category's details. Each translation object includes the following properties:
- Name
  languageCode
  Type
  type: string
  Required
  required
  Description
  The language code associated with this translation.
- Name
  name
  Type
  type: string
  Required
  required
  Description
  The name of the category in this language.
- Name
  navName
  Type
  type: string
  Required
  required
  Description
  The name of the category as displayed in the navigation for this language.
- Name
  slug
  Type
  type: string
  Required
  required
  Description
  The slug for this category in the defined language.
- Name
  description
  Type
  type: string
  Required
  required
  Description
  The banner copy for this category in the defined language.
- Name
  pageTitle
  Type
  type: string
  Required
  required
  Description
  The page title of this category in the defined language.
- Name
  pageDescription
  Type
  type: string
  Required
  required
  Description
  The meta description of this category in the defined translation.
Name
assets
Type
type: array of objects
Required
Description
An array of objects describing the assets attached to this category.
- Name
  externalSystemAssetId
  Type
  type: string
  Required
  required
  Description
  The identifier assigned by your system to this asset.
- Name
  name
  Type
  type: string
  Required
  required
  Description
  The filename of the asset.
- Name
  type
  Type
  type: string
  Required
  required
  Description
  The type of asset.
- Name
  mimeType
  Type
  type: string
  Required
  required
  Description
  The MIME type of the asset.
- Name
  width
  Type
  type: string
  Required
  required
  Description
  The width of the asset.
- Name
  height
  Type
  type: string
  Required
  required
  Description
  The height of the asset.
- Name
  source
  Type
  type: string
  Required
  required
  Description
  The location where the asset is available.
- Name
  focalPoint
  Type
  type: string
  Required
  Description
  The focal point of the asset.

Category JSON Schema

You can use this JSON schema to validate your data

Products

Products are the other core primitive of the Merchstack platform. Product models come in various shapes across platforms. In order for us to process different types of products, we normalize products into a common format on import. The product model comprises products, options, and variants, although you may not use all of these elements. Merchstack is not the system of record for product data, so we expect to receive updates when product or variant data changes.

Example Product Record

This record would normally be on one line in the JSONL format but is formatted as a regular JSON document for clarity.

{
  "importMetaData": {
    "formatVersion": "1.0",
    "importId": "123xyz",
    "recordNum": 12,
    "recordOf": 1300,
    "recordType": "product",
    "operationType": "create"
  },
  "tenantId": "ABC",
  "storeId": "123",
  "externalSystemId": "456",
  "brand": "Nike",
  "categoryIds": [
    "456"
  ],
  "translations": [
    {
      "languageCode": "en",
      "name": "Nike Air Force Ones",
      "slug": "nike-air-force-ones",
      "description": "World Famous Air Force Ones"
    }
  ],
  "enabled": true,
  "assets": [
    {
      "externalSystemAssetId": "22314",
      "name": "clothing__95.jpg",
      "type": "IMAGE",
      "mimeType": "image/jpeg",
      "width": 159,
      "height": 159,
      "source": "cloudinary/path/to/image/clothing__95.jpg",
      "focalPoint": {
        "x": 25,
        "y": 55
      }
    }
  ],
  "featuredAssetId": "22314",
  "attributes": [
    {
      "gender": [
        "male"
      ],
      "color": [
        "black",
        "blue"
      ],
      "country of origin": [
        "UK"
      ]
    }
  ],
  "variants": [
    {
      "enabled": true,
      "sku": "661595-01",
      "externalSystemID": "101101",
      "price": 3999,
      "compareAtPrice": 2999,
      "currencyCode": "USD",
      "stockOnHand": 22,
      "outOfStockThreshold": 2,
      "featuredAssetId": "22314",
      "attributes": [
        {
          "Paint Finish": "Flat",
          "Dept": "Home Furnishings"
        }
      ]
    }
  ]
}

Properties

Name
tenantId
Type
type: string
Required
required
Description
The unique identifier assigned to your tenant by Merchstack.
Name
storeId
Type
type: string
Required
required
Description
The unique identifier assigned to your store by Merchstack.
Name
externalSystemId
Type
type: string
Required
required
Description
The identifier assigned to a product in the integrated system.
Name
brand
Type
type: string
Required
required
Description
The normalized Brand name
Name
categoryIds
Type
type: array
Required
required
Description
An array of category IDs this product is assigned to
Name
translations
Type
type: array of translation objects
Required
required
Description
- Name
  languageCode
  Type
  type: string
  Required
  required
  Description
  The language code associated with this translation.
- Name
  name
  Type
  type: string
  Required
  required
  Description
  The name of the product in the defined language.
- Name
  slug
  Type
  type: string
  Required
  required
  Description
  The slug for this product in the defined language.
- Name
  description
  Type
  type: string
  Required
  required
  Description
  The description of the product in the defined language.
Name
enabled
Type
type: boolean
Required
required
Description
Indicates whether this product is publicly available to your end customers.
Name
assets
Type
type: array of asset types
Required
Description
An array of objects describing the assets attached to this product.
- Name
  operation
  Type
  type: string
  Required
  required
  Description
  The operation you want to perform on the asset for update records. Options include: `addAsset`, `updateAsset` or `deleteAsset`.
- Name
  externalSystemAssetId
  Type
  type: string
  Required
  required
  Description
  The identifier assigned by your system to this asset.
- Name
  name
  Type
  type: string
  Required
  required
  Description
  The name of the asset, typically the filename.
- Name
  type
  Type
  type: string
  Required
  required
  Description
  The type of asset.
- Name
  mimeType
  Type
  type: string
  Required
  required
  Description
  The MIME type of the asset.
- Name
  width
  Type
  type: string
  Required
  required
  Description
  The width of the asset.
- Name
  height
  Type
  type: string
  Required
  required
  Description
  The height of the asset.
- Name
  source
  Type
  type: string
  Required
  required
  Description
  The location where the asset is available.
- Name
  forcalPoint
  Type
  type: string
  Required
  Description
  The focal point of the asset.
Name
featuredAsset
Type
type: string
Required
required
Description
The ID of the asset that is used for the featured image.
Name
attributes
Type
type: array
Required
required
Description
An array of normalized key-value pairs that describe various aspects of the product.
Name
attribute
Type
type: object
Required
required
Description
A key-value pair that provides specific information about the product. This is specified as an array fo string but it can have a single value
Name
variants
Type
type: array of variant objects
Required
required
Description
- Name
  enabled
  Type
  type: boolean
  Required
  required
  Description
  Indicates whether this variant is publicly available to your end customers.
- Name
  sku
  Type
  type: string
  Required
  required
  Description
  The stock keeping unit, or SKU, for this variant.
- Name
  externalSystemId
  Type
  type: string
  Required
  required
  Description
  The identifier assigned by your system to this variant.
- Name
  price
  Type
  type: integer
  Required
  required
  Description
  The current price of the variant you are updating, specified in a decimal-less format.
- Name
  compareAtPrice
  Type
  type: integer
  Required
  Description
  The price at which this product is typically sold. Used to display an original price when there is a discounted price available. Specified in a decimal-less format.
- Name
  currencyCode
  Type
  type: integer
  Required
  required
  Description
  The currency code indicating the currency in which the prices are specified.
- Name
  stockOnHand
  Type
  type: integer
  Required
  required
  Description
  The quantity of this SKU currently in stock.
- Name
  outOfStockThreshold
  Type
  type: integer
  Required
  required
  Description
  The quantity threshold below which the system should consider the product as out of stock.
- Name
  featuredExternalAsset
  Type
  type: string
  Required
  Description
  The ID of the asset to be used when displaying this variant.

Product JSON Schema

You can use this JSON schema to validate your data

Pricing

Price data is not fundamentally required to use Merchstack, but is recommended to get the most out of our capaibilities. If you are integrating Merchstack directly with your storefront, then pricing data will be needed to power your PLP experiences. Outside of this, Merchstack uses price data to automatically manage the products that should be assigned and unassigned to your price-based categories (e.g. Sale and Clearance categories).

Example Pricing Record

This record would normally be on one line in the JSONL format but is formatted as a regular JSON document for clarity.

{
  "importMetaData": {
    "formatVersion": "1.0",
    "importId": "123xyz",
    "recordNum": 12,
    "recordOf": 450,
    "recordType": "pricing",
    "operationType": "update"
  },
  "externalVariantId": "1234",
  "price": 1200,
  "compareAtPrice": 2400
}

Properties

Name
externalVariantId
Type
type: string
Required
required
Description
The ID of the variant you are updating
Name
price
Type
type: string
Required
required
Description
The current price of the variant you are updating, specified in a decimal-less format.
Name
compareAtPrice
Type
type: string
Required
Description
The price at which this product is typically sold. Used to display an original price when there is a discounted price available. Specified in a decimal-less format.

Pricing JSON Schema

You can use this JSON schema to validate your data

Inventory

Inventory data is not fundamentally required to use Merchstack, but is recommended to get the most out of our capaibilities. If you are integrating Merchstack directly with your storefront, then inventory data will be needed to ensure you can implement appropriate controls around out-of-stock experiences. Equally, our calculated categories and opportunity engine use your stock data to build categories that have an appropriate number of products in them.

Example Inventory Record

This record would normally be on one line in the JSONL format but is formatted as a regular JSON document for clarity.

{
  "importMetaData": {
    "formatVersion": "1.0",
    "importId": "123xyz",
    "recordNum": 120,
    "recordOf": 45000,
    "recordType": "inventory",
    "operationType": "update"
  },
  "externalVariantId": "1234",
  "stockOnHand": 120
}

Properties

Name
externalVariantId
Type
type: string
Required
required
Description
The ID of the variant you are updating
Name
stockOnHand
Type
type: integer
Required
required
Description
The quantity of this SKU currently in stock.

Inventory JSON Schema

You can use this JSON schema to validate your data