Overview

The Merchstack export format looks quite similar to the import format except it includes additional data that has been added by the platform. In some cases your individual integration may include additional data or not contain all the data in the example because of the requirements of your system.

Categories

Categories that are flagged as "unmanaged" are categories that your system manages and only exist in the Merchstack platform for the purpose of building new Long Tail Categories. Your system is the "system of record". Therefore, these are not exported because they are redundant, with the exception of managed categories that have indexable facets or related items. Categories that are flagged as "managed" are categories created by Merchstack and should be imported as is. Merchstack is the "system" of record" for these categories. Exports you intake should only contain "managed" categories or categories with extra data.

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.

{
  "exportMetaData": {
    "formatVersion": "1.0",
    "exportId": "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"
    }
  ],
  "indexableFacets": [
    {
      "facetAttribute": "color",
      "details": [
        {
          "name": "red",
          "url": "<https://mywebsite.com/red/things>"
        },
        {
          "name": "green",
          "url": "<https://mywebsite.com/red/things>"
        }
      ]
    },
    {
      "facetAttribute": "season",
      "details": [
        {
          "name": "spring",
          "url": "<https://mywebsite.com/spring/things>"
        },
        {
          "name": "fall",
          "url": "<https://mywebsite.com/fall/things>"
        }
      ]
    }
  ],
  "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
Description
The unique identifier assigned to your tenant by Merchstack.
Name
storeId
Type
type: string
Required
Description
The unique identifier assigned to your store by Merchstack.
Name
externalSystemId
Type
type: string
Required
Description
The identifier assigned to a category in the integrated system.
Name
isPrivate
Type
type: boolean
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
Description
Indicates whether this category is the top-level category (e.g., "Mens").
Name
externalSystemParentId
Type
type: string
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
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
  Description
  The language code associated with this translation.
- Name
  name
  Type
  type: string
  Required
  Description
  The name of the category in this language.
- Name
  navName
  Type
  type: string
  Required
  Description
  The name of the category as displayed in the navigation for this language.
- Name
  slug
  Type
  type: string
  Required
  Description
  The slug for this category in the defined language.
- Name
  description
  Type
  type: string
  Required
  Description
  The banner copy for this category in the defined language.
- Name
  pageTitle
  Type
  type: string
  Required
  Description
  The page title of this category in the defined language.
- Name
  pageDescription
  Type
  type: string
  Required
  Description
  The meta description of this category in the defined translation.
Name
indexableFacets
Type
type: An array of links to internal categories linked to facets
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
  facetAttribute
  Type
  type: string
  Required
  Description
  The facet type that the attributes are linked to
- Name
  details
  Type
  type: string
  Required
  Description
  An array of objects describing the facet links
  Name
  name
  Type
  type: string
  Required
  Description
  The name of the facet attribute
  Name
  url
  Type
  type: string
  Required
  Description
  The link URL
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
  Description
  The identifier assigned by your system to this asset.
- Name
  name
  Type
  type: string
  Required
  Description
  The filename of the asset.
- Name
  type
  Type
  type: string
  Required
  Description
  The type of asset.
- Name
  mimeType
  Type
  type: string
  Required
  Description
  The MIME type of the asset.
- Name
  width
  Type
  type: string
  Required
  Description
  The width of the asset.
- Name
  height
  Type
  type: string
  Required
  Description
  The height of the asset.
- Name
  source
  Type
  type: string
  Required
  Description
  The location where the asset is available.
- Name
  focalPoint
  Type
  type: string
  Required
  Description
  The focal point of the asset.

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.

The operationType does not exist on product exports since we never create or delete products. We only update them.

{
  "exportMetaData": {
    "formatVersion": "1.0",
    "exportId": "123xyz",
    "recordNum": 12,
    "recordOf": 1300,
    "recordType": "product"
  },
  "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
Description
The unique identifier assigned to your tenant by Merchstack.
Name
storeId
Type
type: string
Required
Description
The unique identifier assigned to your store by Merchstack.
Name
externalSystemId
Type
type: string
Required
Description
The identifier assigned to a product in the integrated system.
Name
brand
Type
type: string
Required
Description
The normalized Brand name
Name
categoryIds
Type
type: array
Required
Description
An array of category IDs this product is assigned to
Name
translations
Type
type: array of translation objects
Required
Description
- Name
  languageCode
  Type
  type: string
  Required
  Description
  The language code associated with this translation.
- Name
  name
  Type
  type: string
  Required
  Description
  The name of the product in the defined language.
- Name
  slug
  Type
  type: string
  Required
  Description
  The slug for this product in the defined language.
- Name
  description
  Type
  type: string
  Required
  Description
  The description of the product in the defined language.
Name
enabled
Type
type: boolean
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
  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
  Description
  The identifier assigned by your system to this asset.
- Name
  name
  Type
  type: string
  Required
  Description
  The name of the asset, typically the filename.
- Name
  type
  Type
  type: string
  Required
  Description
  The type of asset.
- Name
  mimeType
  Type
  type: string
  Required
  Description
  The MIME type of the asset.
- Name
  width
  Type
  type: string
  Required
  Description
  The width of the asset.
- Name
  height
  Type
  type: string
  Required
  Description
  The height of the asset.
- Name
  source
  Type
  type: string
  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
Description
The ID of the asset that is used for the featured image.
Name
attributes
Type
type: array
Required
Description
An array of normalized key-value pairs that describe various aspects of the product.
Name
attribute
Type
type: object
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
Description
- Name
  enabled
  Type
  type: boolean
  Required
  Description
  Indicates whether this variant is publicly available to your end customers.
- Name
  sku
  Type
  type: string
  Required
  Description
  The stock keeping unit, or SKU, for this variant.
- Name
  externalSystemId
  Type
  type: string
  Required
  Description
  The identifier assigned by your system to this variant.
- Name
  price
  Type
  type: integer
  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
  Description
  The currency code indicating the currency in which the prices are specified.
- Name
  stockOnHand
  Type
  type: integer
  Required
  Description
  The quantity of this SKU currently in stock.
- Name
  outOfStockThreshold
  Type
  type: integer
  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.