The Public API offers two ways to load many records at once. Picking the right one keeps your integration simple and your latency low.Documentation Index
Fetch the complete documentation index at: https://docs.retailgrid.io/llms.txt
Use this file to discover all available pages before exploring further.
Side by side
POST /v1/imports/* | POST /v1/<entity>/bulk | |
|---|---|---|
| Transport | Multipart CSV | JSON |
| Mode | Async - returns a job_id | Sync - returns results in the response |
| Typical size | Hundreds of thousands to millions of rows | Hundreds to a few thousand rows |
| Per-row error reporting | After the job completes | Immediately, in BulkResponse.results |
| Retry semantics | Retry the upload; fix CSV and re-submit if the job fails | Idempotent per item |
| Rate limit footprint | One request per file | One request per batch |
Use imports/* when…
- You are doing a full-catalog refresh from your ERP or PIM.
- The data already lives in a CSV (or your pipeline can produce one cheaply).
- Wall-clock latency does not matter - you can poll status.
- You want minimal request overhead per row.
Use /bulk when…
- You are syncing deltas from your source system on an event-driven schedule.
- You want a single round trip and an immediate per-row outcome.
- You can shape the payload as JSON (the records do not naturally come from a file).
- Batch size is in the hundreds to low thousands.
POST /v1/products/bulkPOST /v1/product_variants/bulkPOST /v1/transactions/bulkPOST /v1/competitor_prices/bulk
Use single-record POST /v1/<entity>/{entity_id} when…
- You are reacting to a single change in your source system (one product updated, one transaction posted).
- You want strong per-call status semantics (
201vs422directly). - You need the full response body for the row you just wrote.
A pragmatic pattern
Most production integrations end up using two of the three:- Daily full-catalog
imports/productsto absorb all upstream changes. - Event-driven
products/bulkorPOST /v1/products/{entity_id}for low-latency updates between full syncs.