Full Catalog

In the sections above, we have introduced ways to interact with items, variations and item groups. Here we present a way to update or replace the entire catalog in a single API call. We define the catalog as the set of all your item groups, items and variations. This endpoint can be useful if you want to sync the state of your entire catalog with constructor.

The number of items/variations you can upload at once through the catalog endpoint is unlimited. In order to support any number of updates, we ask you to upload items, variations and item groups using CSV files instead of including them in the JSON body of the request.

Once we receive all the provided CSV files, we will return the id of an asynchronous task that will process the data and perform the update in the background. You can check the status of that task using 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. I.e: If there is an issue with data in the items file, we will not update any items, variations or item groups, even if the provided 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, as shown below.

All files should be UTF-8 encoded CSVs.

Replace the catalog (sync)#

To replace all items, variations and/or item groups, use the PUT /v1/catalog endpoint. In this endpoint you may upload up to 3 files in the form data under the following keys: items, variations, item_groups. If you do not wish to replace one of these types of resources, then simply omit it from the request. For example, if you only provide an items and a variations file, we will keep the existing item_groups. Every uploaded file will be treated as a SYNC request, meaning that any records that already exist in the Constructor backend will be deleted & replaced with the records that you provide in the file. Below you can find the expected format for each of these CSV files:

HTTP Request#

PUT https://ac.cnstrc.com/v1/catalog?key=[your API key]&section=[your section]&notification_email=[email]&force=True

URL Parameters#

sectionstringYesThe section that you want to update
notification_emailstringNoAn email address where you'd like to receive an email notifcation in case the task fails.
forcebooleanNoProcess the catalog even if it will invalidate a large number of existing items. Defaults to False.

Form Parameters#

itemsCSV FileNoThe CSV file with all new items
variationsCSV FileNoThe CSV file with all new variations
item_groupsCSV FileNoThe CSV file with all new item_groups

Response format#

"task_id": 1,
"task_status_path": "/v1/task/1"
Replace all items, variations and/or item groups.
curl -X PUT \
-F 'items=@path/to/items.csv' \
-F 'variations=@path/to/variations.csv' \
-F 'item_groups=@path/to/item_groups.csv' \
-u"[your token]:" "https://ac.cnstrc.com/v1/catalog?key=[your API key]&section=[your section]&notification_email=[email]&force=True"

Update the catalog (delta)#

To update specific items, variations and/or item groups, use the PATCH /v1/catalog endpoint. In this endpoint you may upload up to 3 files in the form data under the following keys: items, variations, item_groups. Each of these files must contain only the records that you want to update. Any other records that may exist in the backend will remain unaffected. This may be useful for example to send inventory updates, deactivate items that are out of stock, or introduce new categories. The expected file format is the same as the one in the Replace the catalog section. The response format is also the same.

Update some items, variations and/or item groups
curl -X PATCH \
-F 'items=@path/to/items.csv' \
-F 'variations=@path/to/variations.csv' \
-F 'item_groups=@path/to/item_groups.csv' \
-u"[your token]:" "https://ac.cnstrc.com/v1/catalog?key=[your API key]&section=[your section]&notification_email=[email]&force=True"