Use case: Integrate with external product and inventory data

In many enterprise architectures, Product data originates from multiple external systems of record. Zen Electron's setup is a classic example: they need to source core Product data from a Product Information Management (PIM) system and inventory levels from an Enterprise Resource Planning (ERP).

The synchronous HTTP API and the asynchronous Import API are the two primary ways to send data to the Project.

A key best practice for any data import is to define unique keys for all resources. Keys make your import operations idempotent (safe to re-run) and provide a stable way to reference resources across different import jobs. Notice how each CSV file below includes a unique key for the primary resource it defines.

Assume the data is formatted into the following CSV files:

sku,quantityOnStock,restockableInDays
WM-001,150, 3
WM-001,85, 5
BK-001,200, 2
UCH-001,92, 3

key,name_en_US,slug_en_US,product_type_key,variant_sku,variant_key,price_key,price_cent_amount,price_currency,tax_category_key
product-001,Wireless Mouse,wireless-mouse,electronics,WM-001,wm-001,wm-001-us-price,2999,USD,standard-tax
product-002,Bluetooth Keyboard,bluetooth-keyboard,electronics,BK-001,bk-001,bk-001-us-price,1232,USD,standard-tax
product-003,USB-C Hub,usb-c-hub,electronics,UCH-001,uch-001,uch-001-us-price,3999,USD,standard-tax

Solution A: The Import API

1. Create an Import Container that acts as a staging area for your import operations. Do not specify the resourceType so the container can handle both inventory and product data.
2. Submit inventory data from the ERP: Import InventoryEntry resources before the associated Products exist. The Import API's automatic dependency resolution links inventory to the correct Product Variants using the sku field when the Products are created later.
3. Submit product data from the PIM: Reuse the same Import Container. The Import API resolves references to Product Types, Tax Categories, and other dependencies automatically.
4. Poll the Import Container status to monitor progress. The Import API holds unresolved operations for up to 48 hours while waiting for dependencies to arrive.

Key considerations for the Import API

• Idempotency and keys: Providing a unique key for every resource (Products, Product Variants, Prices, Images, etc.) is a crucial best practice. This key, which you define in your source system (PIM/DAM), allows the Import API to either create a new resource or update an existing one with the same key. This ensures your import scripts are idempotent, allowing them to run repeatedly without producing duplicate data.
• Asynchronous operation: The Import API is asynchronous. You submit a request and then poll for status updates.
• Data orchestration: The Import API excels at handling complex data relationships. For example, if the ERP data includes supplyChannels that reference Channel keys that don't exist yet, the API will hold those operations in an unresolved state until the corresponding Channels are imported or created, at which point it automatically links them. This dependency resolution works as long as all related data is sent within 48 hours.

The Import API handles both create and update scenarios with the same request structure and intelligently manages dependencies, simplifying the integration of data from multiple systems like a PIM and a DAM.

Solution B: The HTTP API

The HTTP API is synchronous and provides immediate feedback on whether an operation succeeded or failed. While this approach offers more control, it also requires managing backoff responses, resource dependencies, and error handling within your client.

The core pattern is an "upsert" (update or insert) operation:

1. Attempt to fetch each resource (InventoryEntry or Product) by its key.
2. If the resource is not found (404 response), create it with a POST request.
3. If the resource exists, get its current version and update it with the appropriate update actions.

Results are nearly instantaneous, provided all dependencies (like Product Types) are in place. However, you are responsible for building a resilient client that ramps up request load gradually, retries transient errors with exponential backoff, and manages concurrency to avoid triggering back-pressure responses.

Choosing the right API

The Import API is designed for asynchronous bulk operations and excels at initial migrations, scheduled batch syncs from multiple systems, and automatic dependency management. The HTTP API is designed for synchronous, real-time operations where immediate feedback and precise control over individual requests are required.

Test your knowledge