Order context

integrationOrderContext field matrix, production evidence, and validation layers.

integrationOrderContext attaches declared end-customer commerce data to checkout mutators for audit, disputes, and reporting. It does not replace wholesale settlement pricing.

Example#

curl -s -X POST "https://api.avrix.io/api/seller/v1/orders" \
  -H "Authorization: Bearer $AVRIX_API_KEY" \
  -H "Idempotency-Key: store-order-10432" \
  -H "Content-Type: application/json" \
  -d '{
  "skuCode": "SANDBOX-ALWAYS-001",
  "quantity": 1,
  "orderReference": "store-order-10432",
  "expectedUnitPriceCents": 5999,
  "countryCode": "NL",
  "deliveryMode": "key",
  "integrationOrderContext": {
    "schemaVersion": 1,
    "salesCountryCode": "NL",
    "currencyCode": "EUR",
    "salesPriceGrossMinor": 7999,
    "priceIncludesTax": true,
    "salesTaxRatePercent": 21,
    "salesChannel": "web",
    "salesTaxAmountMinor": 1388,
    "paymentProcessorReference": "pay_3QxK2mB9",
    "checkoutSessionId": "cs_sandbox_10432"
  }
}'

Use this page as the field reference. For call order and checkout patterns, see Integration recipes and Order lifecycle.

Where it applies#

OperationNotes
POST /ordersSingle-line checkout
POST /orders/bulkPer item; optional cart-level context merges (item overrides cart)
POST /orders/commitHot-drop commit
POST /keys/pullKey pull with commercial evidence
POST /keys/exportExport with commercial evidence

Top-level countryCode and integrationOrderContext.salesCountryCode are one declaration on POST /orders/preview, POST /orders/hold, POST /orders/reserve and POST /orders: send either. A top-level countryCode is promoted into the context when that field is absent; when both are sent they must agree, or the request is refused with 422 SALES_COUNTRY_MISMATCH. Neither value silently wins.

Schema version#

All requests use schemaVersion: 1. Unknown keys return 422. Serialized object max size: 8192 bytes.

Field matrix#

What a call refuses without, by key. GET /whoami returns exactly this for the calling key at data.requiredDeclarationsByOperation; integration presets remove the fields they fill, and a strict profile on the key adds its own.

CallsSandbox keyProduction key
POST /orders, POST /orders/bulk (each line, merged with the cart context), POST /orders/commit, POST /keys/pull, POST /keys/exportschemaVersion, salesCountryCode (or the top-level countryCode), salesPriceGrossMinor, salesTaxRatePercent, salesChannelThe same, plus currencyCode, salesPriceNetMinor, priceIncludesTax, salesTaxAmountMinor, paymentMethodFamily, paymentProcessorReference, checkoutSessionId and consumerIp
POST /orders/preview, POST /orders/holdsalesCountryCodesalesCountryCode and consumerIp (or a consumerGeoAttestId)
POST /orders/reservesalesCountryCodesalesCountryCode

The settlement declarations (country, gross, tax rate, channel) are enforced on orders against API-model allocations, in sandbox and production alike. Every sample on this site sends at least the sandbox set.

Core retail#

FieldTypeSandboxProduction keyNotes
schemaVersion1Required when context presentRequired when context present
salesCountryCodeISO 3166-1 alpha-2Required*Required*Territory and catalog price
consumerIpIPv4/IPv6OptionalRequiredPublic routable buyer IP; private ranges rejected
currencyCodeISO 4217OptionalRequiredRetail currency (may differ from wholesale)
salesPriceGrossMinorinteger ≥ 0Required*Required*Gross retail, minor units
salesPriceNetMinorinteger ≥ 0OptionalRequiredNet retail
priceIncludesTaxbooleanOptionalRequiredWhether gross includes tax
salesTaxAmountMinorinteger ≥ 0OptionalRequiredTax in minor units
salesTaxRatePercentnumber 0–100RequiredRequirede.g. 21; required for API catalog settlement
salesChannelstring ≤ 64RequiredRequirede.g. web, mobile_app, partner_embed, or marketplace:<slug>. Omitting it is refused with 422 SALES_CHANNEL_REQUIRED
paymentMethodFamilyenumOptionalRequiredNon-PCI family (see below)
paymentProcessorReferencestring ≤ 128OptionalRequiredYour PSP transaction id — never a card number
checkoutSessionIdstring ≤ 128OptionalRequiredBasket / checkout session correlation
appliedDiscountPercentagenumber 0–100OptionalOptional
appliedDiscountAmountMinorinteger ≥ 0OptionalOptionalSame minor unit as retail
immediateFulfilment / mustFulfilbooleanOptionalOptionalReserved; US spellings accepted as aliases

*Every API catalog order must supply salesPriceGrossMinor, salesTaxRatePercent, salesCountryCode (the top-level countryCode alias is also accepted where documented), and salesChannel. Omitting the country is refused with 422 SALES_COUNTRY_REQUIRED; omitting gross or the tax rate with 422 TAX_DECLARATION_REQUIRED; omitting the channel with 422 SALES_CHANNEL_REQUIRED. Sandbox and production alike. Production commercial evidence additionally requires currencyCode, consumerIp, and the net/tax/PSP/checkout fields marked Required above.

Optional enterprise fields#

FieldTypeNotes
buyerLocaleBCP 47 string ≤ 35e.g. en-NL
customerVatNumberstring ≤ 32No spaces
purchaseOrderNumberstring ≤ 64B2B PO
customerTypeb2c | b2b
lineIndexinteger 0–999Aligns with bulk items[]; returned on orders and transactions
parentOrderReferencestring ≤ 255Your cart id for a bulk cart; GET /orders?parentOrderReference= lists its lines
externalNetworkOrderIdstring ≤ 255Marketplace / network order id

Input aliases (normalized server-side): externalMarketplaceOrderId → externalNetworkOrderId; channel → salesChannel; storefrontId → checkoutSessionId; US spellings immediateFulfillment / mustFulfill.

Reading a cart back#

Send your cart id as parentOrderReference on a bulk cart (cart-level integrationOrderContext) and each line's position as lineIndex. Then:

  • GET /orders?parentOrderReference=<cart id> returns every line as an order aggregate, in line order, with meta.parentOrderReference and meta.count (at most 100 lines);
  • GET /orders, GET /orders/{orderId} and GET /keys/pulls (older path GET /transactions) carry parentOrderReference and lineIndex on each line (null for an order placed on its own);
  • GET /keys/pulls?parentOrderReference=<cart id> lists the cart's pulls.

Refunds stay per line: refund each line by its own orderReference. There is no cart-level refund, because each line is billed and settled on its own.

paymentMethodFamily values#

card, wallet, paypal, ideal, bancontact, sepa_debit, invoice, store_credit, gift_card, crypto, other

Validation layers#

LayerWhenRequired fields
Schema (Zod)Whenever context is presentschemaVersion: 1; unknown keys → 422
Global strict modeDeployment policy enabledcurrencyCode, salesPriceGrossMinor, salesCountryCode or consumerIp
Production-key commercial evidenceKey environment = productionGlobal set plus net, tax, paymentMethodFamily, paymentProcessorReference, checkoutSessionId
Per-key profileintegration_context_strict_profile on the keyAdditional listed paths

Sandbox keys skip the production commercial evidence but not the settlement declarations (salesCountryCode, salesPriceGrossMinor, salesTaxRatePercent, salesChannel). Send the full production set in sandbox before go-live.

Example (production-shaped)#

Consistent with the docs scenario: SKU SANDBOX-ALWAYS-001, order reference store-order-10432.

JSON
{
  "skuCode": "SANDBOX-ALWAYS-001",
  "quantity": 1,
  "orderReference": "store-order-10432",
  "countryCode": "US",
  "expectedUnitPriceCents": 5999,
  "integrationOrderContext": {
    "schemaVersion": 1,
    "salesCountryCode": "US",
    "currencyCode": "USD",
    "salesPriceGrossMinor": 1999,
    "salesPriceNetMinor": 1999,
    "priceIncludesTax": true,
    "salesTaxAmountMinor": 0,
    "salesTaxRatePercent": 0,
    "consumerIp": "203.0.113.42",
    "paymentMethodFamily": "card",
    "paymentProcessorReference": "psp_txn_10432",
    "checkoutSessionId": "cs_store_10432",
    "salesChannel": "web",
    "customerType": "b2c"
  }
}

Webhooks and privacy#

Order webhooks may include integrationOrderContextRedacted (allowlisted declared retail fields only — no consumer IP, VAT id, or PSP references). Full context is not replayed on the wire. See Webhooks and the privacy guide for retention and DSAR.

Common mistakes#

MistakeResult
Sending only what a sandbox key requires422 on production keys at cutover
Sending your load-balancer IP as consumerIpCONSUMER_IP_INVALID
Putting money fields only in metadataNot validated; not used for reporting
Leaving sandbox_pay_* in production codeSANDBOX_MAGIC_VALUE_REJECTED

What links here

Published guides that link to this page.

Search docs

Search documentation…