Order preview

Read-only price and fulfillment estimate before checkout.

POST /api/seller/v1/orders/preview is a read-only sibling of POST /api/seller/v1/orders. It tells you what a real order would cost and how it would be fulfilled, without claiming any keys.

Use it on your checkout summary screen so the buyer sees the final sale total before pressing "Pay" — no FOR UPDATE locks, no inventory holds, no transaction rows.

Which price is which#

Keep these money concepts separate — mixing them causes CATALOG_PRICE_MISMATCH / settlement drift:

ConceptWhat it isWhere it appears
Buyer retailWhat the end customer paid in your storeintegrationOrderContext on POST /orders — e.g. salesPriceGrossMinor, salesPriceNetMinor, currencyCode (audit / risk; not B2B settlement)
Catalog unit priceWhat Avrix validates per unit under the API business modelPreview unitPriceCents → echo as expectedUnitPriceCents (alias expectedWholesaleUnitPriceCents accepted; both must match if sent together)
Promo provenanceWhy unitPriceCents is below the list pricePreview initialUnitPriceCents (list) + promo (sourceType, sourceId, dates) + promoResolution. Your margin is the difference between the two integers
Advertised priceWhat the vendor asks you to show the buyer during a live list-price promotionPreview advertisedUnitPriceCents (list price with listPromo.discountPercent applied) + listPromo. Render was/now from initialUnitPriceCents vs advertisedUnitPriceCents; never recompute from discountPercent. API business model only — null on wholesale / revenue-share lines
Minor unitsInteger currency subunits (no decimals in JSON)All *Cents / *Minor fields. Use the currencyExponent next to each one (2 for USD/EUR, 0 for JPY, 3 for KWD) when formatting; see Money fields

Preview’s unitPriceCents / totalCents are the binding catalog figures for the next POST /orders, not your storefront MSRP. Declared retail belongs only in integrationOrderContext. See also Pricing view and BMA authority and Glossary.

Why#

Before this endpoint shipped, the only way a store could compute the checkout price for a cart was to:

  • call GET /products/:id/pricing for list prices — the catalog price list is authoritative under the API business model; or
  • (worse) call POST /orders "to see the price" and then call POST /orders/cancel if the buyer abandoned checkout — this both generated phantom transactions and burned pre-order capacity.

/orders/preview returns the binding unitPriceCents and currencyCode that POST /orders would charge, plus the fulfillmentType (fulfilled or pre-order) and an availability snapshot — all in one round-trip and one rate-limit budget hit on the orders class.

Sellability: Preview uses the same checkAvailabilityForSeller path as GET /availability — non-live products (draft/discontinued/archived) return 404 with PRODUCT_NOT_SELLABLE in readiness details. Authoritative sellability for catalog mirrors remains GET /allocations (sellable: true).

HTTP method: Preview uses POST with a JSON body because Next.js does not yet route the HTTP QUERY method (RFC 10008), which would be the semantically correct verb for this read-only operation. The endpoint is rate-limited as a read and successful responses are sampled in api_audit_log (not always-audited like mutating order writes).

API allocations: price comes from the catalog price list (resolve_sku_price) for the requested territory. countryCode is required (ISO 3166-1 alpha-2). Missing catalog pricing returns 422 CATALOG_PRICE_NOT_SET; omitting countryCode returns 422 SALES_COUNTRY_REQUIRED.

Before POST /orders, call preview and echo the returned unitPriceCents as expectedUnitPriceCents (the catalog list price under the API business model). The alias expectedWholesaleUnitPriceCents is accepted for the same echo — if both are sent they must match. If the price changed since preview, the order fails with 409 CATALOG_PRICE_MISMATCH unless you bind the preview price (see below).

Price binding (pick one):

  1. priceCommitment — the guaranteed binding path for every account, at every tier (no capability required). Every priced preview returns priceCommitment: { token, expiresAt } with a hard TTL of 15 minutes (priceCommitmentToken is a compatibility alias of priceCommitment.token). Pass the token on POST /orders; the previewed unitPriceCents is honoured until expiresAt even if the catalog price changes. Expired/forged tokens → 422 PRICE_COMMITMENT_EXPIRED / PRICE_COMMITMENT_INVALID — re-preview and re-quote.
  2. Checkout hold — the premium inventory + price lock. When whoami.capabilities.checkoutHoldEnabled is true, call POST /orders/hold after preview, then pass checkoutHoldId on POST /orders with the same expected price. Live catalog drift is ignored while the hold is valid.

Either binding locks the price, not the offer itself. If the publisher removes the sale country from the catalog between preview and commit (the country's price-list entry disappears, or the territory is excluded), the bound commit still fails closed — 422 CATALOG_PRICE_NOT_SET or the territory rejection — rather than settling into a de-listed country.

Request#

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

You must supply either skuId or skuCode. quantity is 1..1000 (same caps as POST /orders).

Response (200)#

JSON
{
  "data": {
    "type": "order_preview",
    "fulfillmentType": "fulfilled",
    "allocationId": "f8b1…",
    "allocationRemaining": 942,
    "inventoryAvailable": 942,
    "maxFulfillableQuantity": 942,
    "canFulfill": true,
    "partialFulfillmentExpected": false,
    "cannotFullyFulfill": false,
    "allOrNothingWillFail": false,
    "lines": [
      {
        "skuId": "8b9d…",
        "skuCode": "WITCHER3-WIN-EU",
        "quantity": 3,
        "unitPriceCents": 1599,
        "lineTotalCents": 4797,
        "currencyCode": "EUR",
        "initialUnitPriceCents": 1999,
        "promo": {
          "sourceType": "event",
          "sourceId": "3f6c…",
          "discountPercent": 20,
          "priceEffect": "both",
          "startDate": "2026-09-01T00:00:00Z",
          "endDate": "2026-09-30T23:59:59Z"
        },
        "promoResolution": "applied",
        "listPromo": {
          "sourceType": "event",
          "sourceId": "3f6c…",
          "discountPercent": 20,
          "priceEffect": "both",
          "startDate": "2026-09-01T00:00:00Z",
          "endDate": "2026-09-30T23:59:59Z"
        },
        "advertisedUnitPriceCents": 1599
      }
    ],
    "totalCents": 4797,
    "currencyCode": "EUR",
    "currencyExponent": 2,
    "commitRequirements": { "missing": [] },
    "estimateOnly": true
  }
}

What the commit still needs. commitRequirements.missing lists every integrationOrderContext field POST /orders will refuse without, for this key and allocation, that the preview body did not carry: the payment-time fields a quote cannot demand (the charged amounts, the tax split, the payment method and processor reference, the checkout session) and, on API-model allocations, the settlement declarations. When it is not empty, warnings includes COMMIT_FIELDS_MISSING. A preview whose list is empty commits with the same body plus the price echo. Fields the store already knows at quote time are refused by the preview itself instead: on a production key a preview without the buyer IP (consumerIp, or a consumerGeoAttestId) is 422 VALIDATION_FAILED naming integrationOrderContext.consumerIp, exactly as POST /orders answers.

unitPriceCents already includes any settlement-affecting promotion. initialUnitPriceCents is the catalog list price it came from and promo names the share or deal that discounted it (sourceId is the same shareId / responseId you read under Promotions). listPromo is the live promotion the vendor asks you to advertise and advertisedUnitPriceCents is the list price with it applied. Every promotion is both by default, so on an API-model line an approved promotion lowers unitPriceCents, promo and listPromo name the same source, and unitPriceCents equals advertisedUnitPriceCents. A list_price promotion, still a supported value, leaves unitPriceCents and promo untouched and shows up only in listPromo, so a sale badge comes from listPromo and advertisedUnitPriceCents, not from promo. On Wholesale, Traditional Revenue Share and Buy-In Wholesale lines promo is always null: promotions never change an agreed per-key price. promoResolution: "unavailable" means promotions could not be read at quote time: the price is the list price, listPromo is null, and a promo may still exist, so re-preview before rendering a sale badge. The per-priceEffect matrix is on Promotions.

Scope and rate limits#

  • Scope: seller:orders:preview or seller:keys:pull (keys with pull scope may preview without a separate scope).
  • Rate class: orders (same bucket as POST /orders), not catalog read / read-cached. Cache preview results until the cart changes — do not call on every UI tick (Catalog sync & caching).

For pre-order SKUs the response also includes a preorder block:

JSON
"preorder": {
  "releaseDate": "2026-12-12T00:00:00Z",
  "preorderStart": "2026-10-01T00:00:00Z",
  "preorderEnd":   "2026-12-11T23:59:59Z",
  "preorderUnlocked": false
}

Important#

  • estimateOnly: true is set on every preview response. The price reflects live catalog or allocation pricing at the time of preview — the binding price is whatever POST /orders sees on the next request. Price list rows and allocations can change; do not cache the preview total beyond the lifetime of the open cart.
  • API allocations without a catalog price return 422 CATALOG_PRICE_NOT_SET instead of null totals.
  • maxFulfillableQuantity is the same as available (min of allocation headroom and inventory). Use it with canFulfill to gate checkout.
  • canFulfill is true when the requested quantity can be satisfied for the estimated fulfillmentType (fulfilled or pre-order).
  • partialFulfillmentExpected is true when fulfillmentType is fulfilled and available < quantity. POST /orders does not partially deliver keys — it returns 409 NO_AVAILABLE_KEYS with zero keys pulled. Disable pay / reduce quantity when this is true. For pre-order, it is always false until pre-order capacity is exhausted (then POST /orders may return INSUFFICIENT_PREORDER_CAPACITY).
  • Prefer the clearer aliases cannotFullyFulfill and allOrNothingWillFail (same boolean). partialFulfillmentExpected remains for backward compatibility — it does not mean partial key delivery.
  • Money fields include currencyExponent (ISO-4217 minor-unit digits: 0 for JPY/KRW, 2 for EUR/USD, 3 for KWD/BHD) next to currencyCode: on every line, on the total, and inside settlement next to currency. See Money fields.
  • The endpoint is rate-limited under the orders class (same bucket as POST /orders), but it is an operation: "read" so it does not consume the write budget.

Capacity and holds#

maxFulfillableQuantity and canFulfill are net of live checkout holds: the response carries heldQuantity (keys other shoppers' holds cover right now, null if the hold ledger was unreadable) and sellableNow (min(allocationRemaining, inventoryAvailable) − heldQuantity). Gate Pay on canFulfill, which uses sellableNow.

Errors#

Preview runs the same order admission POST /orders runs, on the integrationOrderContext you send: sale country, currencyCode, salesChannel, your selling footprint, the agreement's currency and channel terms, region locks and the price echo when you send one; the buyer-network confirmation (consumerGeoAttestId) is checked after those and before the geo verdict, so CONSUMER_GEO_ATTEST_REQUIRED never hides a refusal you can fix in the request. A preview that answers 200 is therefore never refused by POST /orders or POST /orders/hold for any of the codes below; the settlement declarations (salesPriceGrossMinor, salesTaxRatePercent, salesChannel itself) are still required only where keys move. Send the same context to preview that you will send to commit.

HTTPcodewhen
404NOT_FOUNDSKU is not in your allocations or allocation is not active
422VALIDATION_FAILEDMissing skuId/skuCode, bad quantity; on a production key, no buyer IP (integrationOrderContext.consumerIp or consumerGeoAttestId)
422CONSUMER_GEO_MISMATCH_POLICY_REFUSEDThe agreement's geo-mismatch policy is refuse and the checkout attest or the IP lookup points at another country than the declared one (Territory enforcement)
422SALES_COUNTRY_REQUIREDAPI allocation without countryCode / salesCountryCode
422SALES_COUNTRY_MISMATCHcountryCode and integrationOrderContext.salesCountryCode both sent and different
422CATALOG_PRICE_NOT_SETNo list price for the sale country
422TERRITORY_*, COUNTRY_RESTRICTED, REGION_LOCKED_FOR_SKU, REGION_LOCKED_FOR_CONTRACTThe country is outside what the SKU, the release or the agreement allows
422FOOTPRINT_COUNTRY_NOT_DECLARED, FOOTPRINT_CURRENCY_NOT_DECLAREDYour selling footprint does not declare the country or the currencyCode you sent
422CURRENCY_NOT_PERMITTED_BY_TERM, CURRENCY_NOT_PRICED_FOR_COUNTRYThe agreement does not permit the currencyCode you sent, or the country is priced in another currency
422SALES_CHANNEL_NOT_PERMITTEDThe agreement does not permit the salesChannel you sent
422CONSUMER_*Buyer network checks — see Territory enforcement
503PREORDER_STATE_UNAVAILABLEPre-order RPC timed out — retry after Retry-After seconds (5s)
429RATE_LIMIT_EXCEEDEDStandard orders class rate limit — wait for Retry-After

Forbidden anti-patterns#

  • Calling POST /orders followed by POST /orders/cancel to display a price. Use /orders/preview instead.
  • Caching the preview total in your storefront DB beyond the open cart. The price changes whenever the publisher repriced the allocation; always refresh on the final "Pay" click.
  • Treating estimateOnly: true as advisory. Stores that bill the buyer based on a stale preview total will see settlement discrepancies and chargebacks.
  • Charging when canFulfill is false. Disable Pay (or reduce quantity) when preview or GET /availability?quantity= says the line cannot be fulfilled. POST /orders will not partially deliver keys — expect 409 NO_AVAILABLE_KEYS and refund at your PSP. See Getting started and Integration recipes.

What links here

Published guides that link to this page.

Search docs

Search documentation…