Skip to main content

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 items, item variations, and item groups. This endpoint can be useful if you want to sync the state of your entire catalog with Krestor.

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, item 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, 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, as shown below.

All files should be UTF-8 encoded CSVs.

Replace the catalog (sync)​

To replace all items, item 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 Krestor 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​

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

Form Parameters​

AttributeTypeRequired?Description
itemsCSV FileNoThe CSV file with all new items
variationsCSV FileNoThe CSV file with all new item 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, item 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, item 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.

URL Parameters​

AttributeTypeRequired?Description
sectionstringYesThe section that you want to update
notification_emailstringNoAn email address where you'd like to receive an email notification in case the task fails.
forcebooleanNoProcess the catalog even if it will invalidate a large number of existing items. Defaults to False.
patch_deltabooleanNoProcess updates as partial updates, meaning only provided fields will be updated in database. Fields not included in the upload or which are blank for a particular item will be ignored. More about patch update file format can be found at Patch Updates to Catalog Feed. Defaults to False.
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&patch_delta=True"

System Status​

To check the health of the system that processes the catalogs, you can issue a GET /status/ingestion, as shown below:

Check if the catalog-processing system is healthy
curl -X GET "https://ac.cnstrc.com/status/ingestion"

A healthy system will reply with {"message": "OK"}