Getting Your Data out of Merchstack

Our recommended approach for transferring large amounts of data as part of a custom integration with Merchstack is via file transfer. This can be coupled with our GraphQL Management APIs to enhance certain operations. Contact our integration team for more information

File Format

Merchstack uses the JSONL file format where each line in the file is a JSON record. Each file will have a maximum of 1000 records per file and export will be broken up over multiple files. Each file should be named using the data type and export ID (covered below) and a number such as product_export90100_1.jsonl.

Export Metadata

Each record of every file for every data-type should have an entry of meta-data that looks like this:

Example Export Metadata

"exportMetaData": {
    "formatVersion": "1.0",
    "exportId": "123xyz",
    "recordNum": 55,
    "recordOf": 300,
    "recordType": "category"
  },

Name
formatVersion
Type
type: string
Required
required
Description
This is the version of the file format you are using. This will allow us to make changes to the format version without every customer needing to upgrade at the same moment.
Name
exportId
Type
type: string
Required
required
Description
Every export should have a unique ID that identifies it to you and us so that we can track the progress and completeness of exports. This ID should span across all files of a particular export so that they can be tracked together. A time-date stamp string can be used here or a GUID.
Name
recordNum
Type
type: number
Required
required
Description
The is what number in the total number of records this particular export.
Name
recordOf
Type
type: number
Required
required
Description
This would be the total number of records across all files of a particular export.
Name
recordType
Type
type: string
Required
required
Description
What data type this file contains. The available data type are currently either category or product.

Data Types

End-to-End Integration

There are two types of export formats for the two types of integrations we do. The first is called a "end-to-end integration" where we are sending all of your data back when it's been modified in our system. This is for when Merchstack is powering your storefront. These are the formats we use for this:

Dataset	Required	Description
Category	Yes	Needed for all use cases
Product	Yes	Needed for all use cases

Long-Tail-Category Integration

These are the formats we use when we are integrating directly with your backend system, so it's only necessary to transfer a subset of information back and forth. These are the formats we use for this:

Dataset	Required	Description
Category	Yes	Includes new categories and indexable facets
Product	Yes	Includes new category assignments