Order preview

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.

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

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.

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.

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).

{
  "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": "settlement_price",
          "startDate": "2026-09-01T00:00:00Z",
          "endDate": "2026-09-30T23:59:59Z"
        },
        "promoResolution": "applied"
      }
    ],
    "totalCents": 4797,
    "currencyCode": "EUR",
    "currencyExponent": 2,
    "estimateOnly": true
  }
}

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). promoResolution: "unavailable" means promotions could not be read at quote time: the price is the list price and a promo may still exist — re-preview before rendering a sale badge.

• 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:

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

• 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.
• 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.

• 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.

• Integration recipes — checkout call order, idempotency, and checkout holds
• Catalog sync & caching — why preview prices drift and when to refresh
• Webhooks — push-first fulfillment after POST /orders
• Error playbook — CATALOG_PRICE_MISMATCH, NO_AVAILABLE_KEYS, and validation-failed