As opposed to the items, variations and item groups APIs which utilize JSON, the catalog API allows for updating of an entire or partial catalog with a single API call utilizing CSV files. We define the catalog as the set of all your items, item variations, and item groups.
API endpoints
The number of items / variations that can be uploaded at once through the catalog endpoint is unlimited utilizing the catalog APIs.
Once Constructor receives all the provided CSV files, we will return an id of an asynchronous task that will process the data and perform the update in the background. The status of that task may be checked via the tasks API.
In order to avoid data inconsistencies, if the update fails for any of the provided resources, none of them will be updated. For example, If there is an issue with data in the items.csv file, we will not update any items, item variations or item groups, even if the provided item variations and/or item groups are themselves correct.
Should a catalog upload result in substantial changes to the existing items (defined for now as deleting more than 50% of items), it will be rejected. It's possible to override this behavior using the force parameter.
All files should be UTF-8 encoded CSVs. A full CSV feed update may consist of the following components:
- CSV feed format - items (products) - defined within an
items.csvfile
Products shown as results on product listing pages (search, browse) - CSV feed format - variations - optionally defined within a
variations.csvfile
Not all product catalogs have variations. Variations refer to child items that can be shown as swatches of top level results on product listing pages - CSV feed format - item groups (categories) - defined within an
item_groups.csvfile
Hierarchy definition of groups for organizing products
Rate limiting
To provide a better user experience with catalog update operations, Constructor utilizes a queuing mechanism. Every catalog request creates a task to process.
The default queue limit is 1,000. After exceeding the limit of 1,000 tasks, rate limiting will be applied.
To understand the remaining quota, please refer to the X-RateLimit-Tasks-Remaining header, which will show how many tasks can be submitted.