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",
"consumerIp": "198.51.100.42"
}
}'Use this page as the field reference. For call order and checkout patterns, see Integration recipes and Order lifecycle.
Where it applies#
| Operation | Notes |
|---|---|
| POST /orders | Single-line checkout |
| POST /orders/bulk | Per item; optional cart-level context merges (item overrides cart) |
| POST /orders/commit | Hot-drop commit |
| POST /keys/pull | Key pull with commercial evidence |
| POST /keys/export | Export with commercial evidence |
Top-level countryCode on POST /orders promotes into
integrationOrderContext.salesCountryCode when that field is absent.
Schema version#
All requests use schemaVersion: 1. Unknown keys return 422. Serialized object max size:
8192 bytes.
Field matrix#
Core retail#
| Field | Type | Sandbox | Production key | Notes |
|---|---|---|---|---|
schemaVersion | 1 | Required when context present | Required when context present | |
salesCountryCode | ISO 3166-1 alpha-2 | Required* | Required* | Territory and catalog price |
consumerIp | IPv4/IPv6 | Alternative* | Required* | Public routable buyer IP; private ranges rejected |
currencyCode | ISO 4217 | Required* | Required* | Retail currency (may differ from wholesale) |
salesPriceGrossMinor | integer ≥ 0 | Required* | Required* | Gross retail, minor units |
salesPriceNetMinor | integer ≥ 0 | Optional | Required | Net retail |
priceIncludesTax | boolean | Optional | Required | Whether gross includes tax |
salesTaxAmountMinor | integer ≥ 0 | Optional | Required | Tax in minor units |
salesTaxRatePercent | number 0–100 | Required | Required | e.g. 21; required for API catalog settlement |
salesChannel | string ≤ 64 | Required | Required | e.g. web, mobile_app, partner_embed, or marketplace:<slug>. Omitting it is refused with 422 SALES_CHANNEL_REQUIRED |
paymentMethodFamily | enum | Optional | Required | Non-PCI family (see below) |
paymentProcessorReference | string ≤ 128 | Optional | Required | Your PSP transaction id — never a card number |
checkoutSessionId | string ≤ 128 | Optional | Required | Basket / checkout session correlation |
appliedDiscountPercentage | number 0–100 | Optional | Optional | |
appliedDiscountAmountMinor | integer ≥ 0 | Optional | Optional | Same minor unit as retail |
immediateFulfilment / mustFulfil | boolean | Optional | Optional | Reserved; 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#
| Field | Type | Notes |
|---|---|---|
buyerLocale | BCP 47 string ≤ 35 | e.g. en-NL |
customerVatNumber | string ≤ 32 | No spaces |
purchaseOrderNumber | string ≤ 64 | B2B PO |
customerType | b2c | b2b | |
lineIndex | integer 0–999 | Aligns with bulk items[] |
parentOrderReference | string ≤ 255 | Split / child line parent |
externalNetworkOrderId | string ≤ 255 | Marketplace / network order id |
Input aliases (normalized server-side): externalMarketplaceOrderId → externalNetworkOrderId;
channel → salesChannel; storefrontId → checkoutSessionId; US spellings
immediateFulfillment / mustFulfill.
paymentMethodFamily values#
card, wallet, paypal, ideal, bancontact, sepa_debit, invoice, store_credit,
gift_card, crypto, other
Validation layers#
| Layer | When | Required fields |
|---|---|---|
| Schema (Zod) | Whenever context is present | schemaVersion: 1; unknown keys → 422 |
| Global strict mode | Deployment policy enabled | currencyCode, salesPriceGrossMinor, salesCountryCode or consumerIp |
| Production-key commercial evidence | Key environment = production | Global set plus net, tax, paymentMethodFamily, paymentProcessorReference, checkoutSessionId |
| Per-key profile | integration_context_strict_profile on the key | Additional listed paths |
Sandbox keys skip production commercial evidence. Match production validation in sandbox before go-live.
Example (production-shaped)#
Consistent with the docs scenario: SKU SANDBOX-ALWAYS-001, order reference store-order-10432.
{
"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#
| Mistake | Result |
|---|---|
| Implementing only the sandbox-minimal set | 422 on production keys at cutover |
Sending your load-balancer IP as consumerIp | CONSUMER_IP_INVALID |
Putting money fields only in metadata | Not validated; not used for reporting |
Leaving sandbox_pay_* in production code | SANDBOX_MAGIC_VALUE_REJECTED |