Sending Magento 10,000 product updates as 10,000 synchronous API calls is slow, fragile, and hard to recover. The bulk API exists for exactly this: queue a batch of operations in one request, let consumers process them asynchronously, and poll for completion. Integrations that adopt it stop timing out; integrations that ignore it eventually hit a catalog size where they break.
How It Works
Any POST/PUT route accepting an array becomes bulk-capable via the /async/bulk prefix:
PUT /async/bulk/V1/products
with a body of product payloads. The response is a bulk UUID - not results. Each item becomes an operation message on the queue; consumers process them in the background. Status polling:
GET /V1/bulk/<bulk-uuid>/detailed-status
returns per-operation outcomes: complete, retriable failure, or error with a message. That per-operation granularity is the design win - 9,998 successes and 2 named failures, not one ambiguous timeout.
The Contract for Integrations
- Submit in chunks: batch payloads in the hundreds-to-thousands per bulk request - one giant payload is a queue flood, one-at-a-time is pointless
- Poll politely: exponential backoff on status checks; the work is asynchronous precisely because it takes time
- Handle per-operation failures: parse the detailed status and retry or escalate individual failures - a bulk that “mostly worked” needs item-level follow-up
- Idempotency matters: retries and resubmissions happen; operations keyed by natural keys (SKU) are safe to repeat
Infrastructure Requirements
The bulk API is only as alive as its consumers:
- RabbitMQ (or the DB queue) must be running
- The relevant consumers (
product_action_attribute.update,async.operations.all) must be supervised - viaconsumers_runnercron or systemd max_messagestuned so consumers recycle and releases deploy fresh code
A bulk endpoint returning 202 Accepted with dead consumers is an integration lying to you - monitor queue depth, not just API responses.
When to Use It
- Catalog syncs: price/stock/attribute deltas from ERP - the canonical use case
- Customer or order migrations: bulk creation with per-row error reporting
- Anything over ~100 entities: the overhead of the async contract pays for itself in reliability immediately
For interactive integrations (a customer-facing lookup), synchronous endpoints stay correct - async is for machine-to-machine volume, not user waiting.
The bulk API trades immediacy for resilience: queue, process, report. Adopt that shape and your integrations survive catalog growth, network blips and deploys - the three things that break naive sync loops every time.