API Reference
Proof Scheduleâ„¢UI LibrariesClient LibrariesBlogMain Site

Introduction

To upload catalog data to Constructor via the API, there are multiple methods available - each suited to different types of catalog updates.

Updating catalog data is an asynchronous process, meaning that changes are not applied instantly after processing the request and receiving the response, but may take some time. In the response a task ID will be returned, which can be used to retrieve information about task's status via the retrieve task endpoint.

Items, variations and item groups APIs

JSON data can be transmitted via individual HTTP requests against Constructor's items, variations and item groups API endpoints. This method allows you to batch upload or modify product information but is generally limited to operations on batches of 10,000 products at a time. This might require multiple network requests to complete an operation, especially for large catalogs.

Catalog APIs

For bulk updates or full catalog uploads, CSV files can be used. This method is ideal for large-scale data uploads where you're setting or updating your entire product catalog within Constructor, though it can certainly be used to make incremental (delta) changes. The process involves sending CSV files through an HTTP network request to the Constructor's catalog API endpoint. There are two main operations you can perform:

  • Sync: this operation replaces the entire product catalog with the data within the CSV files. It's used for full catalog updates.
  • Delta: This operation updates specific items defined within the CSV files, rather than the entire catalog. It's useful for making incremental updates to your catalog.

The CSV files typically include items.csv (for root level products), variations.csv (for product variations), and item_groups.csv (for group hierarchies). For information on the expected format of these files, please refer to the CSV transfer via API resource.

Choosing the right method

For large-scale updates, the CSV method via HTTP (Catalog APIs) is recommended for almost all integrations, especially when updating the entire catalog or a large portion of it. This is due to the ease of audibility.

For real-time or granular updates, the JSON-based items, variations and item groups APIs are suitable for making one-off changes to specific products or attributes. Due to potential complexities with managing large volumes of updates, it's recommended to use this method for smaller, more targeted updates.

It is possible and common to "mix and match" methods. For example, using the catalog APIs to send full syncs to Constructor on a regular interval and send small updates via the JSON based APIs as product attributes change.