POST /api/seller/v1/orders/bulk
Places a cart of up to 20 lines in one request. Each line is its own order: it has its own
orderReference, orderId, keys, settlement and refunds. The request decides whether the cart is
all or nothing (strict: true) or whether each line succeeds on its own (strict: false).
Use it when one buyer pays for several SKUs at once. For a single SKU, use
POST /orders.
Before you send it#
- Preview every line with POST /orders/preview and keep each line's
unitPriceCents. - Charge the buyer once, for the whole cart.
- Give every line an
orderReference. The schema lets you leave it out, but a line without one cannot be looked up withGET /orders?orderReference=, read back with POST /orders/recover-keys, or refunded by reference. - Mint one
Idempotency-Keyfor the cart and keep it with the payment.
Scope: seller:orders:write (the legacy seller:keys:pull also works). Headers:
Authorization, Content-Type: application/json, and Idempotency-Key (required).
Request#
| Field | Type | Required | Description |
|---|---|---|---|
strict | boolean | No | true: all lines or none. false: each line on its own. Send it explicitly; the default depends on the contract date (below) |
items | array | Yes | 1 to 20 lines |
items[].skuId / items[].skuCode | string | One of | The SKU of the line |
items[].quantity | integer | Yes | 1 to 1000 |
items[].orderReference | string | Recommended | The line's own reference, unique per line |
items[].expectedUnitPriceCents | integer | Usually | The line's unitPriceCents from preview; or send items[].priceCommitmentToken |
items[].integrationOrderContext | object | See below | The line's declarations; merged over the cart-level context |
items[].customerReference, items[].metadata, items[].consumerGeoAttestId | No | As on POST /orders | |
integrationOrderContext | object | See below | What every line shares. Each line's own context wins field by field |
consumerGeoAttestId | string | No | A buyer-network confirmation for the whole cart; spent only when a line is delivered |
Each line must end up with the declarations a committing call needs once the cart context is merged
in: schemaVersion, salesCountryCode, salesPriceGrossMinor, salesTaxRatePercent and
salesChannel on every key, plus the commercial evidence on a production key
(Order context). salesPriceGrossMinor is the line's gross, not
the cart total.
A line does not read countryCode, backorderOnUnavailable, checkoutHoldId, deliveryMode or
immediateFulfilment: declare the country in integrationOrderContext.salesCountryCode. A bulk line
cannot become a backorder; a line short of stock is refused with NO_AVAILABLE_KEYS.
To read the cart back later, put your cart id in the cart-level parentOrderReference and each
line's position in its lineIndex (see reading a cart back).
Example (sandbox)#
A two-line cart on a sandbox key. It runs as written.
curl -s -X POST "https://api.avrix.io/api/seller/v1/orders/bulk" \
-H "Authorization: Bearer $AVRIX_API_KEY" \
-H "Idempotency-Key: cart-10432" \
-H "Content-Type: application/json" \
-d '{
"strict": true,
"integrationOrderContext": {
"schemaVersion": 1,
"salesCountryCode": "NL",
"currencyCode": "EUR",
"priceIncludesTax": true,
"salesTaxRatePercent": 21,
"salesChannel": "web",
"paymentProcessorReference": "pay_3QxK2mB9",
"checkoutSessionId": "cs_sandbox_10432",
"parentOrderReference": "cart-10432"
},
"items": [
{
"skuCode": "SANDBOX-ALWAYS-001",
"quantity": 2,
"orderReference": "cart-10432-1",
"expectedUnitPriceCents": 5999,
"integrationOrderContext": {
"salesPriceGrossMinor": 15998,
"salesTaxAmountMinor": 2776,
"lineIndex": 0
}
},
{
"skuCode": "SANDBOX-EUR1-001",
"quantity": 1,
"orderReference": "cart-10432-2",
"expectedUnitPriceCents": 100,
"integrationOrderContext": {
"salesPriceGrossMinor": 149,
"salesTaxAmountMinor": 26,
"lineIndex": 1
}
}
]
}'Strict or not#
strict: true | strict: false | |
|---|---|---|
| One line is refused | Nothing is delivered. The request answers the refusing line's error | The other lines are delivered. The refused line reads type: "failed" in a 200 |
| Billing and webhooks | Only after every line is pulled; then order.fulfilled per line | Per line, as each is delivered |
| Refund at your PSP | The whole cart, if you will not retry | Only the failed lines |
An omitted strict is true on contract date 2026-09-01 and later, which every unpinned request
uses. A request pinned to X-Avrix-Api-Version: 2026-04-29 defaults to false. meta.strict on the
response says which mode ran.
Success#
Every line delivered, in either mode, answers 200. Persist each line's keys, keyIds and
orderId before you show the buyer anything.
{
"data": {
"items": [
{
"skuCode": "SANDBOX-ALWAYS-001",
"quantity": 2,
"orderReference": "cart-10432-1",
"orderId": "ord_6rfz4y3b",
"type": "fulfilled",
"pulled": 2,
"keys": ["AAAA-BBBB-CCCC-DDDD", "EEEE-FFFF-GGGG-HHHH"],
"keyIds": ["8f21a9b0-1234-5678-9abc-def012345678", "9a02c7d1-2345-6789-abcd-ef0123456789"]
},
{
"skuCode": "SANDBOX-EUR1-001",
"quantity": 1,
"orderReference": "cart-10432-2",
"orderId": "ord_7tgk5z4c",
"type": "fulfilled",
"pulled": 1,
"keys": ["JJJJ-KKKK-LLLL-MMMM"],
"keyIds": ["0b13d8e2-3456-789a-bcde-f01234567890"]
}
]
},
"meta": { "contractDate": "2026-09-01", "strict": true }
}
Lines carry the same fields as a POST /orders response (allocationId, activation,
transactionIds, fulfilledAt, economics and so on), shortened here. A line on a pre-order SKU
reads type: "pre-order" with reserved and no keys: bulk pre-orders lock their keys and are
delivered automatically at release (pre-orders).
A strict cart is refused#
First every line is checked as a preview would check it. If any line fails, the answer is
422 VALIDATION_FAILED with every problem in details.issues, and nothing was pulled.
Then every line is pulled before any line is billed. If a line is refused at that point, for example two lines of one SKU that each fit the stock alone but not together, the keys the earlier lines took go back to stock and the request answers the refusing line's own code and status:
{
"code": "NO_AVAILABLE_KEYS",
"message": "No available keys in inventory",
"details": {
"strictCart": {
"outcome": "rolled_back",
"failedItemIndex": 1,
"items": [
{ "index": 0, "orderReference": "cart-10432-1", "status": "rolled_back" },
{ "index": 1, "orderReference": "cart-10432-2", "status": "failed" }
]
}
},
"requestId": "req_01J8XYZ"
}
Each line's status is failed, rolled_back or not_attempted. outcome is:
rolled_back: every earlier line was released. Nothing of the cart was delivered or billed.rollback_incomplete: at least one earlier line could not be released automatically. The cart still did not go through and the response carries no keys, but the keys that line took may stay held. Keep therequestIdand send it to support before you retry.
A line can also fail while being billed (503 BILLING_RECORD_FAILED or KEY_DECRYPT_FAILED).
The lines already billed are then reversed as a refund and the rest released, with the same
strictCart report; again nothing of the cart was delivered.
A non-strict cart with a refused line#
The request answers 200. A refused line reads type: "failed" with code, error and the
httpStatus it would have had on its own:
{
"data": {
"items": [
{
"skuCode": "SANDBOX-ALWAYS-001",
"quantity": 2,
"orderReference": "cart-10432-1",
"orderId": "ord_6rfz4y3b",
"type": "fulfilled",
"pulled": 2,
"keys": ["AAAA-BBBB-CCCC-DDDD", "EEEE-FFFF-GGGG-HHHH"],
"keyIds": ["8f21a9b0-1234-5678-9abc-def012345678", "9a02c7d1-2345-6789-abcd-ef0123456789"]
},
{
"skuCode": "SANDBOX-LOWSTOCK-001",
"quantity": 4,
"orderReference": "cart-10432-2",
"type": "failed",
"pulled": 0,
"keys": [],
"code": "NO_AVAILABLE_KEYS",
"error": "No available keys in inventory",
"httpStatus": 409
}
]
},
"meta": { "contractDate": "2026-09-01", "strict": false }
}
Deliver the fulfilled lines and refund the failed ones at your PSP, or retry them.
Retrying#
Retry with the same Idempotency-Key and the same body: the same lines in the same order.
Avrix replays each line by the cart's key and the line's position, so a changed line order is a
different request (IDEMPOTENCY_KEY_MISMATCH).
| What came back | What a retry with the same key does |
|---|---|
200, every line delivered | Returns the same response, with the same keys |
200 with failed lines (non-strict) | Returns the delivered lines with their keys again, and runs the failed lines again |
Strict refusal (422, rolled_back) | Runs the whole cart again: nothing of it was stored. Fix the cause first |
rollback_incomplete | The same, once support has the requestId |
Timeout or 5xx with no answer | Retry; you end with exactly one delivery per line |
Never retry a cart with a new Idempotency-Key after you charged the buyer: that is a new cart and
pulls new keys. If retries keep failing, look each line up with
GET /orders?orderReference=<line reference> or the whole cart with
GET /orders?parentOrderReference=<cart id>.
After the cart#
- Webhooks.
order.fulfilledarrives once per delivered line, keyed on the line'sorderReference. - Refunds are per line: POST /refunds with the line's
orderReference. There is no cart-level refund, because each line is billed and settled on its own. - Finance lists each line as its own sale.