Overview

This type of integration involves a much simpler dataset since we are only transmitted a small subset of information back to you. This includes just three pieces of information:

New Categories that have been created from Opportunities
Products that have been added to those categories
Indexable facets on your existing categories

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 unless they contain indexable facets. 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 plus categories with 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.

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

{
  "exportMetaData": {
    "formatVersion": "2.0",
    "exportId": "123xyz",
    "recordOf": 149,
    "recordType": "product",
    "operationType": "update",
    "recordNum": 1
  },
  "baseProductId": "248766",
  "productId": "248766",
  "categories": [
    "msk-shaving-foam-gels-long-category-banner"
  ]
}

Properties

Name
baseProductId
Type
type: string
Required
required
Description
The unique identifier in your system for the base product
Name
productId
Type
type: string
Required
required
Description
The unique identifier in your system for the variant
Name
categories
Type
type: arrat
Required
required
Description
An Array of Strings of category identifiers that the product is in