Bulk orders

POST /orders/bulk for a cart: strict and non-strict carts, refusals, and retries.

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 with GET /orders?orderReference=, read back with POST /orders/recover-keys, or refunded by reference.
  • Mint one Idempotency-Key for 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#

FieldTypeRequiredDescription
strictbooleanNotrue: all lines or none. false: each line on its own. Send it explicitly; the default depends on the contract date (below)
itemsarrayYes1 to 20 lines
items[].skuId / items[].skuCodestringOne ofThe SKU of the line
items[].quantityintegerYes1 to 1000
items[].orderReferencestringRecommendedThe line's own reference, unique per line
items[].expectedUnitPriceCentsintegerUsuallyThe line's unitPriceCents from preview; or send items[].priceCommitmentToken
items[].integrationOrderContextobjectSee belowThe line's declarations; merged over the cart-level context
items[].customerReference, items[].metadata, items[].consumerGeoAttestIdNoAs on POST /orders
integrationOrderContextobjectSee belowWhat every line shares. Each line's own context wins field by field
consumerGeoAttestIdstringNoA 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: truestrict: false
One line is refusedNothing is delivered. The request answers the refusing line's errorThe other lines are delivered. The refused line reads type: "failed" in a 200
Billing and webhooksOnly after every line is pulled; then order.fulfilled per linePer line, as each is delivered
Refund at your PSPThe whole cart, if you will not retryOnly 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.

JSON
{
  "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:

JSON
{
  "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 the requestId and 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:

JSON
{
  "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 backWhat a retry with the same key does
200, every line deliveredReturns 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_incompleteThe same, once support has the requestId
Timeout or 5xx with no answerRetry; 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.fulfilled arrives once per delivered line, keyed on the line's orderReference.
  • 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.

What links here

Published guides that link to this page.

Search docs

Search documentation…