Constructor customers can keep their product catalogs up-to-date by uploading catalog files via HTTP or FTPS.

Constructor accepts JSON, JSONL, and CSV files for catalog uploads at intervals convenient for customers (e.g., daily, bi-weekly, etc.).

Upload frequency will depend on the upload operation (i.e., a full sync versus a delta). For a full sync, the recommendation is once per day, and for a delta, the recommendation is to batch updates based on how often product attributes change, and send one delta upload every five (5) minutes.

Which catalog upload operation should I use?

Wondering which upload operation is right for you? Use the table below to determine the best fit and follow the links to learn more about the operation.

How do I specify my upload operation?

The method your company uses to send the file to Constructor will determine how you specify your chosen upload operation.

FTPS

When sending a file via FTPS, the filename should contain four pieces of information, each separated by an underscore:

1. The index API key (e.g., key_abCDeFGhiJ1234)
2. The section name (e.g., “Products”)
3. The operation name (e.g., sync, delta, patchdelta, patchdeltacreate, patchdeltaignore, or delete)
4. A timestamp (i.e., to ensure older files are not overwritten)

Here is an example of a filename with all four pieces of information: key_abCDeFGhiJ1234_Products_patchdelta_2024-02-10-16-18-00.csv

If you are uploading a single catalog file, you can follow the naming convention above with a .csv, .json or .jsonl extension.

If you are uploading multiple files, you should group the files together and compress them as a .tar.gz file. Learn how here.

Learn more about Constructor’s FTPS connection here.

HTTP

When sending catalog files via the catalog API, you must specify the request that corresponds to the desired upload operation.

• PUT: Supports a full catalog sync
• PATCH: Supports a delta (partial) upload and a patch_delta (patch) upload.

⚠️ Note: To send a patch upload, you must define the patch_delta (where patch_delta=true) and on_missing query parameters. Learn more about the on_missing options (e.g., create and ignore) here.

Learn more about sending catalog files via HTTP here.

Catalog upload operations

Full sync

Update the entire catalog

A full sync upload will replace your current catalog with a new catalog. It is the default method for keeping a catalog up-to-date. This file should contain your entire catalog (i.e., all data for items, variations, and item_groups).

This operation allows companies to add new items, update existing item data, and remove items.

If you choose to remove items from the catalog by not including them in a file you will upload, you will also remove their associated learnings.

Alternatively, if the items are items you plan to add back in the near future, you can retain associated learnings by simply deactivating the items. This is done by including an active field in the CSV file (where active=false for an item) or JSON/JSONL file (where "active": false for an item).

⚠️ Please note:

• There is a failsafe threshold for sync uploads. If your update will deactivate or remove more than 50% of your current catalog, Constructor will reject the upload. This prevents companies from accidentally deleting their entire catalog.
• This threshold is calculated for each part of your catalog (e.g., items, variations, and item_group). The entire upload will fail if at least one part of the catalog exceeds the 50% threshold.

Delta (partial)

Update one or more item records or variation records

A delta (or partial) upload updates your current catalog with information specified in the file. It does not require that you upload the entire catalog file, but it does require that you provide the entire item or variation record for each item you wish to update.

Why? The data you provide will completely replace the existing item record in the current catalog. If data for an item is left out, such as attributes like price or description, it will be removed from the index.

The delta operation can also add items to your current catalog. For example, a company realizes its latest upload did not contain items from a new brand they now carry. They want to add these new items to the Constructor catalog. Rather than uploading the entire catalog again, they can use the delta operation to upload a file containing data for the new items.

⚠️ Please note:

• There is a failsafe threshold for delta uploads. If your update will deactivate more than 50% of your current catalog, Constructor will reject the upload.
• This threshold is calculated for each part of your catalog (e.g., items, variations, and item_group). The entire upload will fail if at least one part of the catalog exceeds the 50% threshold.

Patch

Update one or more item attributes or variation attributes

There are three types of patch operations: patch delta, patch delta create, and patch delta ignore.

Patch delta

A patch delta upload will update specific data in your current catalog. It’s a "quick update" that does not require uploading the entire catalog—just the information you need to update. If the file you’re uploading contains any new items, Constructor will reject it.

For example, a retailer wants to send regular updates on item pricing and inventory levels throughout the day. To do so, they would use the patch delta operation to upload a file that contains only the id and the updated price and instock fields.

Constructor will locate each item using the id and update the price and instock fields for those items. Pre-existing item data, such as item name, size, price, colors, etc., would remain unchanged.

⚠️ Please note:

• There is a failsafe threshold for patch delta uploads. If your update will deactivate more than 50% of your current catalog, Constructor will reject the upload.
• This threshold is calculated for each part of your catalog (e.g., items, variations, and item_group). If at least one part of the catalog exceeds the 50% threshold, the entire upload will fail.

Patch delta create

A patch delta create upload operation will update specific data in your current catalog and add new items (or data points) to the catalog. It’s a "quick update" that does not require uploading the entire catalog—just the information you need to update and add.

For example, a company wants to accomplish the following:

• Update specific data: Update the price for specific items.
• Add new items (or data points): Add the new attribute eco-friendly to a group of items.

To do so, the company would use the patch delta create operation to upload a file that contains only:

• The item id and the updated price for each item that needs updating, and
• The item id and the new attribute eco-friendly for each item that needs the attribute added.

Because the eco-friendly attribute is new and the company is using the patch delta create operation, Constructor will both update item pricing for the items specified and add the new attribute to the corresponding items in the file.

⚠️ Please note:

• This operation does not support updates to item_group data.
• There is a failsafe threshold for patch delta create uploads. If your update will deactivate more than 50% of your current catalog, Constructor will reject the upload.
• This threshold is calculated for each part of your catalog (e.g., items, variations, and item_group). If at least one part of the catalog exceeds the 50% threshold, the entire upload will fail.

Patch delta ignore

A patch delta ignore upload operation will update specific data in your current catalog. It’s a "quick update" that does not require uploading the entire catalog—just the information you need to update.

For example, a company wants to update inventory levels for all items. Their file lists all item ids and the updated instock status. However, the file also contains other new items that haven’t previously been uploaded to Constructor.

The company can still update inventory levels by uploading the file using the patch delta ignore operation. Constructor will locate each item using the id and update the instock fields. Since the remaining items contained in the file are new, they’ll be ignored and not added to the catalog.

⚠️ Please note:

• This operation does not support updates to item_group data.
• There is a failsafe threshold for patch delta ignore uploads. If your update will deactivate more than 50% of your current catalog, Constructor will reject the upload.
• This threshold is calculated for each part of your catalog (e.g., items, variations, and item_group). If at least one part of the catalog exceeds the 50% threshold, the entire upload will fail.

Delete

Delete specific data and behavioral learnings from the catalog

A delete upload operation will delete specific data from your catalog. A delete operation will remove not only items but all behavioral learnings associated with the items.

If deleting items via HTTPS, there is a limit to how many items you can include in the request. To reduce the number of calls made, uploading the full catalog via sync may make more sense. Constructor will delete all items not included in that file.

💡 Wait, I don’t want to delete items. Can I make them inactive instead? If you plan to add back certain items in the near future, you can retain associated learnings by simply deactivating the items. This is done by including an active field in the CSV (where active=false for an item) or JSON/JSONL (where "active": false for an item).

⚠️ Please note:

• There is a failsafe threshold for delete uploads. If your update will delete more than 50% of your current catalog, Constructor will reject the upload.
• This threshold is calculated for each part of your catalog (e.g., items, variations, and item_group). If at least one part of the catalog exceeds the 50% threshold, the entire upload will fail.

🛑 Using “force” upload operation

Each upload method has a force option, which allows a company to override the 50% failsafe threshold in place for the operation.

If using FTPS, you can specify a force operation as part of the filename (e.g., forcesync, forcedelta, etc.). If using HTTPS, you can set the force query parameter to true.

⚠️ Please note: You should only use a force operation when absolutely necessary to manually override the 50% failsafe threshold.

Force operations should not be used as part of an automated process, in production indexes, or as a default sync method.

Overriding the failsafe may result in significant changes to your catalog.

View catalog uploads via the Constructor dashboard

Companies can view previous catalog uploads by operation (e.g., full, delta (partial), and patch delta) in their Constructor dashboard.

1. Select Integration in the side menu of the Constructor dashboard, then select Catalog Uploads.
2. Scroll to view past catalog uploads.
3. To filter by catalog upload operation, select Filters on the far right side of the page.
4. Choose the desired operation from the drop-down, then select Update filters in the bottom-right corner of the pop-up.
5. To view details about a particular upload, select the filename.