{"openapi":"3.1.0","info":{"title":"Avrix Seller API","description":"External API for **seller companies** (including **digital game stores** and other retailers) to browse catalogs from connected publishers, place orders, pull keys from allocations, and subscribe to webhooks. Use a Bearer token (seller API key) from Settings → API Keys.\n\n**Finance routes** use **`/api/seller/v1/finance/...`** (unversioned `/api/seller/finance/...` redirects to `/v1/`). Scope: `seller:finance:read`. See `https://docs.avrix.io/seller-api/scopes`.\n\n**Tax posture:** All prices are **tax-exclusive** integer minor units. Retail VAT/GST on the storefront price is the seller's responsibility — Avrix is not a tax engine.\n\n**Start here:** `https://docs.avrix.io/seller-api/quickstart` — golden path to first order. **Index:** `https://docs.avrix.io/guides/getting-started`.\n\n**Publishers (content owners):** use the Avrix console for supply-side workflows; a Vendor HTTP API is in development and not publicly exposed.\n\nAll responses include `X-Api-Version: 1` (major API family) and `X-Avrix-Api-Version` (date-based contract revision for generated clients and partner compatibility checks). Supported request contract dates: `2026-04-29` (default) and `2026-09-01` (bulk orders default to `strict: true`); responses echo the effective date.\n\n**Response shape:** Paginated and list endpoints expose rows in **`data`** (and **`meta`** for cursors). Catalog cold-start snapshot uses **`meta` + `data`** (array of products with expansions).\n\n**Idempotency:** Mutating endpoints that accept `Idempotency-Key` may return header `Idempotency-Replayed: true` when the response body is replayed from storage (same key as a prior completed request within 24h), not a fresh execution.\n\n**Integration recipes** (scopes, call order, idempotency): see `https://docs.avrix.io/seller-api/integration-recipes`.\n\n**Sandbox / test connection** (base URL, scopes, 401/403 triage, IP allowlist): see `https://docs.avrix.io/seller-api/sandbox`.\n\n**HTTP conventions** — **Authentication:** `Authorization: Bearer <API key>`. **Request correlation:** response header `X-Request-Id`; error bodies may include `requestId` (include in support tickets). **Pagination:** list routes use `cursor` and `meta` (see each operation). **Rate limits:** there are no plans or tiers. **Production keys are not rate limited** (the IP allowlist is the gate). **Sandbox keys** share one flat abuse cap per company: 600 writes / 1,200 reads / 12,000 cached reads per minute, split by route class. On **429** (sandbox only), back off; `Retry-After` is present (seconds). **Throughput:** see `https://docs.avrix.io/seller-api/partner-runbook` and `https://docs.avrix.io/seller-api/partner-runbook`.\n\n**Standard errors:** Unless an operation lists only specific codes, endpoints may return **401** (`UNAUTHORIZED`), **403** (`FORBIDDEN`), **429** (`RATE_LIMIT_EXCEEDED`), and **500** (`INTERNAL_ERROR`) with JSON body `ApiError`. See `https://docs.avrix.io/seller-api/errors`. Reusable response components: `#/components/responses/SellerApiUnauthorized`, `SellerApiForbidden`, `SellerApiRateLimited`, `SellerApiInternalError`.\n\n**Privacy / telemetry:** Seller API handlers see **your egress IP** for **allowlist checks** and abuse controls only — **not** as buyer PII on orders. The buyer IP you declare in `integrationOrderContext.consumerIp` is resolved at request time and **not stored**: sale and pull rows keep the resolved country plus a peppered, truncated hash (`consumerIpHash`). **GET /api/seller/v1/whoami-ip** echoes your IP for allowlist onboarding (key-free). Do **not** embed secrets in URLs. See `https://docs.avrix.io/seller-api/partner-runbook`.","version":"2026-09-08","contact":{"name":"Avrix Seller API Support","url":"https://docs.avrix.io/seller-api/partner-runbook","email":"support@avrix.io"},"license":{"name":"Proprietary","url":"https://avrix.io/legal"}},"servers":[{"url":"https://api.avrix.io","description":"Production (sandbox keys use the same host)"}],"security":[{"bearerAuth":[]}],"paths":{"/api/seller/v1/products":{"get":{"summary":"List products","description":"Products available from connected partners. Paginated. Filter by q (search name/slug), partner (publisher company ID), or status.\n\n**Pagination:** Stable keyset order by creation time then id (newest first). The `cursor` is a versioned token (v2 encodes created time + id); legacy id-only cursors are still accepted. See `https://docs.avrix.io/seller-api/catalog-and-allocations`.\n\n**Incremental sync:** Optional `updatedSince` (ISO 8601) returns rows whose latest update (or creation) time is on or after that instant. Combine with **`product.updated`** webhooks and a stored watermark for efficient deltas.\n\n**Store copy language:** `shortDescription` follows the `locale` query parameter if set (`xx` or `xx-YY`), else `Accept-Language`, else English. `meta.localePreference` echoes the resolved preference chain.\n\nEach item includes **store-facing catalog fields** (cover, short description, platforms/regions, **US list price** where resolvable) so you can build browse pages and compare **SRP / MSRP** (`listPriceFromCents`) with **wholesale contract pricing** on `GET /api/seller/v1/allocations` (`pricePerKeyCents`, `businessModel`).","parameters":[{"name":"limit","in":"query","schema":{"type":"integer","default":50,"minimum":1,"maximum":100}},{"name":"cursor","in":"query","schema":{"type":"string"}},{"name":"q","in":"query","schema":{"type":"string"},"description":"Search by product name or slug"},{"name":"partner","in":"query","schema":{"type":"string","maxLength":32,"pattern":"^[a-zA-Z0-9_-]+$"},"description":"Filter by publisher company ID — slug-safe identifier (alphanumeric, hyphen, underscore), max 32 chars (alias: publisherCompanyId)"},{"name":"status","in":"query","deprecated":true,"schema":{"type":"string","enum":["draft","active","discontinued","archived"]},"description":"Deprecated: filter by the legacy lifecycle rollup (matched against the derived value). Visible products always carry status=active; prefer the launchPhase / tradingState / isArchived response fields."},{"name":"slug","in":"query","schema":{"type":"string","maxLength":512},"description":"Exact catalog product slug (per vendor); narrows list to a single product when shared"},{"name":"publisherCompanyId","in":"query","schema":{"type":"string","maxLength":32,"pattern":"^[a-zA-Z0-9_-]+$"},"description":"Alias of `partner`"},{"name":"locale","in":"query","schema":{"type":"string","pattern":"^[a-zA-Z]{2}(-[a-zA-Z]{2})?$"},"description":"BCP 47 language tag for vendor `shortDescription` (overrides Accept-Language)"},{"name":"updatedSince","in":"query","schema":{"type":"string","format":"date-time"},"description":"ISO 8601 — only products updated on or after this instant (incremental sync)"},{"name":"expand","in":"query","schema":{"type":"string"},"description":"Comma-separated list of optional list-level expansions: `availability` adds a per-row `availability` summary (`available`, `allocationRemaining`, `inventoryAvailable`, `skuCount`); `pricing` adds a per-row `pricing` summary (`wholesaleFromCents` from your seller allocation + `listPriceFromCents` from the publisher list price band). **Use this to bundle browse data and avoid the N+1 pattern of one list call followed by 100 detail/availability/pricing calls.** The `availability` field is advisory — call `/availability` for commit-time accuracy. CDN-cacheable per `Authorization`+`Accept-Language`+`expand`."},{"name":"Accept-Language","in":"header","schema":{"type":"string"},"description":"Preferred languages for store copy (q-values supported); used when `locale` is omitted"},{"name":"filters","in":"query","required":false,"schema":{"type":"string"},"description":"Optional JSON array filter DSL `[{ \"field\", \"op\", \"value\" }, …]` augmenting named params; unknown fields → **422**. Whitelist is route-specific."}],"responses":{"200":{"description":"Products list","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/PartnerProductWithExpansions"}},"meta":{"$ref":"#/components/schemas/PaginationMeta"}}}}}},"401":{"$ref":"#/components/responses/SellerApiUnauthorized"},"403":{"$ref":"#/components/responses/SellerApiForbidden"},"422":{"description":"Invalid query parameters (e.g. limit, locale, partner company ID)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"429":{"$ref":"#/components/responses/SellerApiRateLimited"},"500":{"$ref":"#/components/responses/SellerApiInternalError"}},"x-avrix-scopes":["seller:products:read"],"x-avrix-tier":"catalog","x-avrix-store-profile":"catalog","tags":["Catalog"],"operationId":"listProducts"}},"/api/seller/v1/products/{productId}":{"get":{"summary":"Get product detail","description":"Full product detail with editions, releases, SKUs, pricing. Use expand=base for minimal (product base only). **Store copy:** `shortDescription` uses `locale` or `Accept-Language` with English fallback (same rules as list products).","parameters":[{"name":"productId","in":"path","required":true,"schema":{"type":"string","format":"uuid"}},{"name":"expand","in":"query","schema":{"type":"string","description":"base = product base only; default = full with editions,pricing"}},{"name":"locale","in":"query","schema":{"type":"string","pattern":"^[a-zA-Z]{2}(-[a-zA-Z]{2})?$"},"description":"BCP 47 language tag for vendor shortDescription"},{"name":"Accept-Language","in":"header","schema":{"type":"string"},"description":"Preferred languages when locale is omitted"}],"responses":{"200":{"description":"Product detail","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/SellerProductDetail"},"relatedProducts":{"type":"array","description":"Relationship edges — only targets visible to your seller account are exposed. `requires` = DLC/expansion needs the base game; `includes` = bundle contents; `edition_of` = edition of a base product.","items":{"type":"object","required":["type","productId"],"properties":{"type":{"type":"string","enum":["requires","includes","upgrades","edition_of"]},"productId":{"type":"string","format":"uuid"}}}}}}}}},"401":{"$ref":"#/components/responses/SellerApiUnauthorized"},"403":{"$ref":"#/components/responses/SellerApiForbidden"},"404":{"description":"Resource not found or not visible to this seller key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"code":"NOT_FOUND","message":"Product not found","requestId":"req_01EXAMPLE","doc_url":"https://docs.avrix.io/seller-api/errors#not-found"}}}},"429":{"$ref":"#/components/responses/SellerApiRateLimited"},"500":{"$ref":"#/components/responses/SellerApiInternalError"}},"x-avrix-scopes":["seller:products:read"],"x-avrix-tier":"catalog","tags":["Catalog"],"operationId":"getProduct"}},"/api/seller/v1/products/{productId}/pricing":{"get":{"summary":"Get product pricing","description":"Pricing per release and country. Use expand=product to include product { id, name, slug } in one request.","parameters":[{"name":"productId","in":"path","required":true,"schema":{"type":"string","format":"uuid"}},{"name":"country","in":"query","schema":{"type":"string","description":"Comma-separated country codes (e.g. US,DE,GB)"}},{"name":"expand","in":"query","schema":{"type":"string","description":"product = include product base in response"}}],"responses":{"200":{"description":"Pricing data","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/PricingRelease"}}}}}}},"401":{"$ref":"#/components/responses/SellerApiUnauthorized"},"403":{"$ref":"#/components/responses/SellerApiForbidden"},"404":{"description":"Resource not found or not visible to this seller key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"code":"NOT_FOUND","message":"Product not found","requestId":"req_01EXAMPLE","doc_url":"https://docs.avrix.io/seller-api/errors#not-found"}}}},"429":{"$ref":"#/components/responses/SellerApiRateLimited"},"500":{"$ref":"#/components/responses/SellerApiInternalError"}},"x-avrix-scopes":["seller:products:read"],"x-avrix-tier":"catalog","tags":["Catalog"],"operationId":"listProductsPricing"}},"/api/seller/v1/catalog/checksum":{"get":{"summary":"Catalog integrity digest","description":"Deterministic lowercase hex SHA-256 fingerprint of visible catalog rows (**product id** + **product `updatedAt`**) sorted canonically (`digestAlgorithm`: `sha256-sorted-product-rows-v1`). Use between full `/catalog/snapshot` pulls to detect drift without downloading the snapshot body. Optional `partner` / `publisherCompanyId` matches `/products` publisher scoping.","tags":["Catalog"],"security":[{"bearerAuth":[]}],"parameters":[{"name":"partner","in":"query","schema":{"type":"string","maxLength":32,"pattern":"^[a-zA-Z0-9_-]+$"},"description":"Filter digest to a single publisher company ID (slug-safe identifier)"},{"name":"publisherCompanyId","in":"query","schema":{"type":"string","maxLength":32,"pattern":"^[a-zA-Z0-9_-]+$"},"description":"Alias of `partner`"}],"responses":{"200":{"description":"Integrity digest","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/CatalogIntegrityDigest"}},"required":["data"]}}}},"401":{"$ref":"#/components/responses/SellerApiUnauthorized"},"403":{"$ref":"#/components/responses/SellerApiForbidden"},"422":{"description":"Invalid query parameters (e.g. conflicting partner + publisherCompanyId)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"429":{"$ref":"#/components/responses/SellerApiRateLimited"},"500":{"$ref":"#/components/responses/SellerApiInternalError"}},"x-avrix-scopes":["seller:products:read"],"x-avrix-tier":"catalog","operationId":"listCatalogChecksum"}},"/api/seller/v1/catalog/changes":{"get":{"summary":"Catalog visibility delta","description":"Per-seller feed of catalog visibility transitions (`added`, `updated`, `removed` tombstones). Use with `/catalog/snapshot` or `/products` for mirror correctness when products leave the catalog.\n\n**Retention SLA:** delta events are retained for **at least 30 days**. A store offline for up to a month catches up via deltas alone; beyond retention (or on `GET /catalog/checksum` drift), cold-start with `GET /catalog/snapshot`.","tags":["Catalog"],"security":[{"bearerAuth":[]}],"parameters":[{"name":"since","in":"query","schema":{"type":"string","format":"date-time"},"description":"ISO-8601 cursor — return events after this timestamp"},{"name":"limit","in":"query","schema":{"type":"integer","minimum":1,"maximum":5000,"default":500},"description":"Maximum events to return (default 500, max 5000)"},{"name":"cursor","in":"query","required":false,"schema":{"type":"string"},"description":"Opaque sequence cursor from `meta.nextCursor` — the preferred paging mode (tie- and clock-skew-safe). When both `cursor` and `since` are sent, the cursor wins."}],"responses":{"200":{"description":"Visibility changes","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"changes":{"type":"array","items":{"type":"object","properties":{"productId":{"type":"string","format":"uuid"},"type":{"type":"string","enum":["added","updated","removed"]},"occurredAt":{"type":"string","format":"date-time"},"changedFields":{"type":"array","items":{"type":"string","enum":["pricing","availability","metadata","territory","relationships"]},"description":"Which facets changed — refetch only those surfaces. Empty array = unknown (pre-cursor rows); refetch the whole product."}},"required":["productId","type","occurredAt"]}}},"required":["changes"]}},"required":["data"]}}}},"401":{"$ref":"#/components/responses/SellerApiUnauthorized"},"403":{"$ref":"#/components/responses/SellerApiForbidden"},"422":{"description":"Invalid query parameters","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"429":{"$ref":"#/components/responses/SellerApiRateLimited"},"500":{"$ref":"#/components/responses/SellerApiInternalError"}},"x-avrix-scopes":["seller:products:read"],"x-avrix-tier":"catalog","operationId":"listCatalogChanges"}},"/api/seller/v1/catalog/snapshot":{"get":{"summary":"Cold-start catalog snapshot","description":"Returns the seller's **entire** visible catalog (every product across every connected publisher) in a single denormalised JSON payload, plus per-row `availability` and `pricing` expansions. Recommended for seeding a new store instead of crawling 50k rows through `/products`. Subsequent syncs should use `meta.maxUpdatedAt` as a watermark for `GET /products?updatedSince=` and webhook subscriptions.\n\n**Caching:** Short-lived origin cache per `(sellerCompanyId, locale)`, plus CDN edge cache segmented per `Authorization`+`Accept-Language` with `stale-while-revalidate=600`. Stable weak ETag derived from `(maxUpdatedAt, totalProducts)` — CDN revalidations against origin return 304 with no JSON serialization.\n\n**Compression:** when `Accept-Encoding: gzip` is set, the response body is gzipped and `Content-Encoding: gzip` is returned.\n\n**Rate-limit:** participates in the cheap `read-cached` bucket; only true origin work debits the regular `read` bucket. A daily snapshot pull costs ~zero rate budget.","tags":["Catalog"],"security":[{"bearerAuth":[]}],"parameters":[{"name":"Accept-Language","in":"header","schema":{"type":"string"},"description":"Preferred languages for store copy (q-values supported)"},{"name":"Accept-Encoding","in":"header","schema":{"type":"string"},"description":"Set to `gzip` (or include `gzip` in the list) to receive a gzipped body"},{"name":"If-None-Match","in":"header","schema":{"type":"string"},"description":"Conditional GET: send the previous response's `ETag` to receive `304 Not Modified` when the catalog hasn't changed"},{"name":"format","in":"query","required":false,"description":"`json` (default) returns one document; `ndjson` streams the same snapshot as newline-delimited JSON for very large stores (100k+ SKUs) — line 1 is the meta object (stamped format: \"ndjson\"), each following line is one product row. Identical ETag semantics: send If-None-Match and get 304 when unchanged.","schema":{"type":"string","enum":["json","ndjson"],"default":"json"}}],"responses":{"200":{"description":"Full seller catalog snapshot","headers":{"ETag":{"schema":{"type":"string"},"description":"Weak ETag, e.g. `W/\"abc123...\"` — derived from `(maxUpdatedAt, totalProducts)`"},"Cache-Control":{"schema":{"type":"string"},"description":"`private, max-age=300, s-maxage=300, stale-while-revalidate=600`"},"Vary":{"schema":{"type":"string"},"description":"`Authorization, Accept-Language, Accept-Encoding`"},"Content-Encoding":{"schema":{"type":"string"},"description":"`gzip` when the client accepted gzip"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CatalogSnapshot"}},"application/x-ndjson":{"schema":{"type":"string","description":"Newline-delimited JSON: meta line first, then one product per line."}}}},"304":{"description":"Not modified — the catalog hasn't changed since the supplied `If-None-Match`"},"401":{"$ref":"#/components/responses/SellerApiUnauthorized"},"403":{"$ref":"#/components/responses/SellerApiForbidden"},"429":{"$ref":"#/components/responses/SellerApiRateLimited"},"500":{"$ref":"#/components/responses/SellerApiInternalError"}},"x-avrix-scopes":["seller:products:read"],"x-avrix-tier":"catalog","operationId":"getCatalogSnapshot"}},"/api/seller/v1/partners":{"get":{"summary":"List partners","description":"Connected partners (publishers). Each item includes the **connection** id and timestamps, invoicing flags, public-style **publisher** fields (`website`, `country`, `description`, `logo`) from IAM, and a read-only **`contracts`** summary (`activeBmaTypes`, `mcaStatus`, `catalogShareMode`, `sharesSuspended`) for pre-pull diagnostics.","responses":{"200":{"description":"Partners list","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/SellerPartner"}}}}}}},"401":{"$ref":"#/components/responses/SellerApiUnauthorized"},"403":{"$ref":"#/components/responses/SellerApiForbidden"},"429":{"$ref":"#/components/responses/SellerApiRateLimited"},"500":{"$ref":"#/components/responses/SellerApiInternalError"}},"x-avrix-scopes":["seller:products:read"],"x-avrix-tier":"catalog","tags":["Catalog"],"operationId":"listPartners"}},"/api/seller/v1/allocations":{"get":{"summary":"List allocations","description":"Allocations (quantity limits from publishers) with **commercial terms** for API checkout: `businessModel`, `pricePerKeyCents`, `currencyCode`, `paymentStatus`, and `productId` (links to `GET /products/{productId}` for full SKU/pricing detail). **List/catalog prices** (SRP) come from product list/detail and `.../pricing` routes; **per-key wholesale** is on each allocation. When `businessModel` is `api` and `pricePerKeyCents` &gt; 0, fulfilled pulls record per-key rows for finance (`https://docs.avrix.io/seller-api/store-profiles`).\n\nDelta polling: pass `updatedSince` with your last-seen max `updatedAt` to fetch only changed grants instead of a full refetch. Sellability embedded in catalog responses (`sharedSkus[].sellable`) is computed from these same grant rows, and grant mutations invalidate the cached catalog surfaces, so allocations and catalog readiness cannot drift apart for longer than one poll.","parameters":[{"name":"sellableOnly","in":"query","required":false,"schema":{"type":"boolean","default":false},"description":"When true, return only allocations currently sellable for checkout (share, allocation, product, and pricing gates satisfied)."},{"name":"limit","in":"query","required":false,"schema":{"type":"integer","minimum":1,"maximum":100,"default":50},"description":"Page size (1–100, default 50)."},{"name":"cursor","in":"query","required":false,"schema":{"type":"string"},"description":"Opaque keyset cursor from `meta.nextCursor` of the previous page. Omit for the first page."},{"name":"updatedSince","in":"query","required":false,"description":"Delta polling: only grants mutated at/after this ISO 8601 instant. Use the max `updatedAt` you have stored as the next `updatedSince`; overlap by a few seconds to be safe. Full refetches are only needed on cold start.","schema":{"type":"string","format":"date-time"}}],"responses":{"200":{"description":"Allocations list","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"readableId":{"type":"string","description":"Prefixed ID (e.g. alc_abc12345)"},"createdAt":{"type":["string","null"],"format":"date-time"},"publisherCompanyId":{"type":"string"},"publisherCompanyName":{"type":"string"},"productId":{"type":["string","null"],"format":"uuid","description":"Catalog product id; use with GET /products/{productId}"},"skuId":{"type":"string"},"skuCode":{"type":"string"},"productName":{"type":"string"},"quantityLimit":{"type":"integer"},"quantityPulled":{"type":"integer"},"remaining":{"type":"integer"},"status":{"type":"string"},"businessModel":{"type":"string","description":"e.g. api — drives commercial recording when priced"},"paymentStatus":{"type":"string"},"pricePerKeyCents":{"type":["integer","null"],"description":"Wholesale / contract price per key in currencyCode"},"currencyCode":{"type":["string","null"]},"currencyExponent":{"type":["integer","null"],"description":"ISO 4217 minor-unit exponent for currencyCode (0 for JPY, 2 for USD, 3 for KWD)."},"shareActive":{"type":"boolean","description":"True when the SKU is in catalog scope (share, share_mode=all, or full-catalog BMA)."},"catalogVisible":{"type":"boolean","description":"Alias of shareActive for catalog feed visibility."},"territoryPricingSet":{"type":"boolean","description":"True when API territory catalog pricing or wholesale allocation price is configured."},"sellable":{"type":"boolean","description":"True when share, allocation, and pricing gates are satisfied for checkout."},"readinessBlockers":{"type":"array","items":{"type":"string"},"description":"Blocking codes such as NO_SKU_SHARE, NO_TERRITORY_PRICING."},"recommendedAction":{"type":["string","null"],"description":"Integrator remediation hint (e.g. request_publisher_sku_share)."},"updatedAt":{"type":"string","format":"date-time","description":"Last grant mutation (resize, status change, rebalance). Pair with ?updatedSince= for cheap delta polls."},"activation":{"$ref":"#/components/schemas/SkuActivation"},"refundPolicy":{"$ref":"#/components/schemas/RefundPolicy"},"consumerGeoAttestRequired":{"type":"boolean","description":"True when this Content Owner requires confirming the buyer’s network from the checkout page before commercial orders."}}}},"meta":{"type":"object","description":"Pagination envelope. Page with `cursor` until `nextCursor` is null.","properties":{"limit":{"type":"integer","description":"Echo of the requested page size."},"count":{"type":"integer","description":"Rows in this page (after `sellableOnly` filtering)."},"nextCursor":{"type":["string","null"],"description":"Opaque cursor for the next page; null on the last page."},"nextUrl":{"type":["string","null"],"description":"Convenience absolute URL for the next page; null on the last page."},"hasMore":{"type":"boolean"},"warnings":{"type":"array","description":"Commercial readiness warnings (e.g. missing catalog prices) when present.","items":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"}}}}}}}}}}},"401":{"$ref":"#/components/responses/SellerApiUnauthorized"},"403":{"$ref":"#/components/responses/SellerApiForbidden"},"429":{"$ref":"#/components/responses/SellerApiRateLimited"},"500":{"$ref":"#/components/responses/SellerApiInternalError"}},"x-avrix-scopes":["seller:products:read"],"x-avrix-tier":"catalog","tags":["Catalog"],"operationId":"listAllocations"}},"/api/seller/v1/allocations/requests":{"get":{"summary":"List allocation requests","description":"Allocation increase requests submitted by the seller.","responses":{"200":{"description":"Request list"},"401":{"$ref":"#/components/responses/SellerApiUnauthorized"},"403":{"$ref":"#/components/responses/SellerApiForbidden"},"429":{"$ref":"#/components/responses/SellerApiRateLimited"},"500":{"$ref":"#/components/responses/SellerApiInternalError"}},"x-avrix-scopes":["seller:products:read"],"x-avrix-tier":"catalog","tags":["Catalog"],"operationId":"listAllocationsRequests"},"post":{"summary":"Create allocation request","description":"Request more keys when a grant ceiling is exhausted.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["grantId","requestedQuantity"],"properties":{"grantId":{"type":"string","format":"uuid"},"requestedQuantity":{"type":"integer","minimum":1},"declaredForecast":{"type":"integer","minimum":0},"publisherAvailableKeys":{"type":"integer","minimum":0}}},"example":{"skuCode":"SANDBOX-ALWAYS-001","quantity":100,"note":"Pilot allocation request"}}}},"responses":{"200":{"description":"Request created or auto-resolved"},"400":{"description":"Invalid grantId or requestedQuantity","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"401":{"$ref":"#/components/responses/SellerApiUnauthorized"},"403":{"$ref":"#/components/responses/SellerApiForbidden"},"429":{"$ref":"#/components/responses/SellerApiRateLimited"},"500":{"$ref":"#/components/responses/SellerApiInternalError"}},"x-avrix-scopes":["seller:keys:pull"],"x-avrix-tier":"catalog","tags":["Catalog"],"operationId":"createRequest"}},"/api/seller/v1/availability":{"get":{"summary":"Check availability","description":"Stock availability for a SKU or multiple SKUs. Single: use skuCode or skuId. Bulk: use skuCodes (comma-separated, max 50). Returns available (pullable), allocationRemaining, inventoryAvailable (sum of dedicatedAvailable + sharedPoolAvailable), and backorderEligible.","parameters":[{"name":"skuCode","in":"query","schema":{"type":"string"},"description":"Single SKU code"},{"name":"skuId","in":"query","schema":{"type":"string","format":"uuid"},"description":"Single SKU ID"},{"name":"skuCodes","in":"query","schema":{"type":"string"},"description":"Comma-separated SKU codes for bulk check (max 50)"},{"name":"quantity","in":"query","schema":{"type":"integer","minimum":1,"maximum":1000},"description":"Single-mode only: when set, response includes `canFulfill` and `partialFulfillmentExpected` for this quantity"},{"name":"countryCode","in":"query","required":false,"description":"Optional single ISO 3166-1 alpha-2 code (e.g. `DE`) — the canonical spelling, matching the checkout field name. When present, each availability item also carries `country`, `sellableInCountry`, and `blockedReason` (`COUNTRY_RESTRICTED`, `TERRITORY_NOT_ALLOWED_FOR_SKU`, `TERRITORY_EXCLUDED_FOR_RELEASE`, `SKU_REGION_UNRESOLVED`, or `CATALOG_PRICE_NOT_SET`) evaluated with the same territory predicate as `POST /orders/preview`.","schema":{"type":"string","pattern":"^[A-Za-z]{2}$"}},{"name":"country","in":"query","required":false,"description":"Alias of `countryCode` (the original availability spelling, kept for compatibility). Sending both with different values fails validation.","schema":{"type":"string","pattern":"^[A-Za-z]{2}$"}}],"responses":{"200":{"description":"Availability data (single object or array for bulk)","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"oneOf":[{"type":"object","properties":{"available":{"type":"integer"},"allocationRemaining":{"type":"integer"},"inventoryAvailable":{"type":"integer","description":"Keys fulfillable for this allocation: the publisher's shared available pool plus any stock the publisher has dedicated to your allocation."},"allocationId":{"type":"string"},"allocationReadableId":{"type":"string","description":"Readable ID alc_xxx for allocation"},"skuId":{"type":"string"},"skuCode":{"type":"string"},"maxFulfillableQuantity":{"type":"integer","description":"Same as `available` (min of allocation headroom and inventory)"},"canFulfill":{"type":"boolean","description":"Present when `quantity` query is set — true if requested quantity can be satisfied"},"partialFulfillmentExpected":{"type":"boolean","deprecated":true,"description":"Deprecated alias of `cannotFullyFulfill` (kept for backward compatibility; removal planned for v2). True when immediate fulfillment cannot satisfy the requested quantity — POST /orders is all-or-nothing and returns 409 NO_AVAILABLE_KEYS with zero keys pulled. Despite the name it never means partial key delivery. Migrate to `cannotFullyFulfill` / `allOrNothingWillFail`."},"cannotFullyFulfill":{"type":"boolean","description":"True when immediate fulfillment cannot satisfy the requested quantity and all-or-nothing checkout will fail (expect 409 NO_AVAILABLE_KEYS, not partial keys). Disable Pay or reduce quantity. Same boolean as `allOrNothingWillFail`; supersedes the deprecated `partialFulfillmentExpected`."},"allOrNothingWillFail":{"type":"boolean","description":"True when POST /orders will fail all-or-nothing (409 NO_AVAILABLE_KEYS, zero keys) for this quantity. Same boolean as `cannotFullyFulfill`."},"requestable":{"type":"boolean","description":"True when allocation is exhausted but publisher policy allows requesting more capacity"},"backordered":{"type":"boolean","description":"True when seller has an open backorder row for this SKU"},"country":{"type":"string","description":"Echo of the `country` query when provided."},"sellableInCountry":{"type":"boolean","description":"Present only when `country` was requested. True when the SKU can be sold to a buyer in that country: territory allowlist + exclusions, plus the catalog price gate for API-model allocations — the same predicate POST /orders/preview enforces."},"blockedReason":{"type":["string","null"],"enum":["COUNTRY_RESTRICTED","TERRITORY_NOT_ALLOWED_FOR_SKU","TERRITORY_EXCLUDED_FOR_RELEASE","REGION_LOCKED_FOR_CONTRACT","REGION_LOCKED_FOR_SKU","SKU_REGION_UNRESOLVED","CATALOG_PRICE_NOT_SET",null],"description":"Why `sellableInCountry` is false; null when sellable. Present only when `country` was requested."},"dedicatedAvailable":{"type":"integer","description":"Keys the publisher dedicated to this allocation (reserved + grant-scoped)."},"sharedPoolAvailable":{"type":"integer","description":"Keys in the publisher shared pool (`status=available`) for this SKU."},"backorderEligible":{"type":"boolean","description":"True when durable backorders are enabled and this grant policy allows requestModeBackorder."},"backorderIneligibleReason":{"type":["string","null"],"enum":["BACKORDER_FLAG_OFF","BACKORDER_POLICY_OFF",null],"description":"Why backorderEligible is false; null when eligible."}}},{"type":"array","items":{"type":"object","properties":{"available":{"type":"integer"},"allocationRemaining":{"type":"integer"},"inventoryAvailable":{"type":"integer","description":"Keys fulfillable for this allocation: the publisher's shared available pool plus any stock the publisher has dedicated to your allocation."},"allocationId":{"type":"string"},"allocationReadableId":{"type":"string"},"skuId":{"type":"string"},"skuCode":{"type":"string"},"country":{"type":"string","description":"Echo of the `country` query when provided."},"sellableInCountry":{"type":"boolean","description":"Present only when `country` was requested. True when the SKU can be sold to a buyer in that country: territory allowlist + exclusions, plus the catalog price gate for API-model allocations — the same predicate POST /orders/preview enforces."},"blockedReason":{"type":["string","null"],"enum":["COUNTRY_RESTRICTED","TERRITORY_NOT_ALLOWED_FOR_SKU","TERRITORY_EXCLUDED_FOR_RELEASE","REGION_LOCKED_FOR_CONTRACT","REGION_LOCKED_FOR_SKU","SKU_REGION_UNRESOLVED","CATALOG_PRICE_NOT_SET",null],"description":"Why `sellableInCountry` is false; null when sellable. Present only when `country` was requested."},"dedicatedAvailable":{"type":"integer","description":"Keys the publisher dedicated to this allocation (reserved + grant-scoped)."},"sharedPoolAvailable":{"type":"integer","description":"Keys in the publisher shared pool (`status=available`) for this SKU."},"backorderEligible":{"type":"boolean","description":"True when durable backorders are enabled and this grant policy allows requestModeBackorder."},"backorderIneligibleReason":{"type":["string","null"],"enum":["BACKORDER_FLAG_OFF","BACKORDER_POLICY_OFF",null],"description":"Why backorderEligible is false; null when eligible."}}}}]}}}}}},"401":{"$ref":"#/components/responses/SellerApiUnauthorized"},"403":{"$ref":"#/components/responses/SellerApiForbidden"},"404":{"description":"SKU not found for this seller, allocation missing, or allocation exists without catalog share. When share is missing, `details.readiness` includes `NO_SKU_SHARE`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"422":{"description":"Invalid query parameters (e.g. skuId/skuCode conflict, skuCodes count)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"429":{"$ref":"#/components/responses/SellerApiRateLimited"},"500":{"$ref":"#/components/responses/SellerApiInternalError"}},"x-avrix-scopes":["seller:products:read"],"x-avrix-tier":"catalog","x-avrix-store-profile":"checkout-read","tags":["Catalog"],"operationId":"listAvailability"}},"/api/seller/v1/transactions":{"get":{"summary":"List transactions","description":"Key pull history. Paginated. Filter by from/to (ISO 8601 date range) for analytics and reporting. When `meta.hasMore` is true, `meta.nextUrl` is the full URL for the next page (same filters; cursor updated).","parameters":[{"name":"limit","in":"query","schema":{"type":"integer","default":50,"minimum":1,"maximum":100}},{"name":"cursor","in":"query","schema":{"type":"string"}},{"name":"orderReference","in":"query","schema":{"type":"string"}},{"name":"from","in":"query","schema":{"type":"string","format":"date-time"},"description":"Filter transactions from this date (ISO 8601)"},{"name":"to","in":"query","schema":{"type":"string","format":"date-time"},"description":"Filter transactions until this date (ISO 8601)"},{"name":"filters","in":"query","required":false,"schema":{"type":"string"},"description":"Optional JSON array filter DSL `[{ \"field\", \"op\", \"value\" }, …]` augmenting named params; unknown fields → **422**. Whitelist is route-specific."}],"responses":{"200":{"description":"Transactions list","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/SellerTransaction"}},"meta":{"$ref":"#/components/schemas/PaginationMeta"}}}}}},"401":{"$ref":"#/components/responses/SellerApiUnauthorized"},"403":{"$ref":"#/components/responses/SellerApiForbidden"},"422":{"description":"Invalid query parameters (limit, cursor, date range)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"429":{"$ref":"#/components/responses/SellerApiRateLimited"},"500":{"$ref":"#/components/responses/SellerApiInternalError"}},"x-avrix-scopes":["seller:products:read"],"x-avrix-tier":"catalog","tags":["Catalog"],"operationId":"listTransactions"}},"/api/seller/v1/keys":{"get":{"summary":"List seller API keys","description":"List API keys for the authenticated company (masked identifiers only; full secrets are never returned). Requires `seller:keys:write` scope.","responses":{"200":{"description":"Masked keys","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/SellerApiKeyMasked"}}}}}}},"401":{"$ref":"#/components/responses/SellerApiUnauthorized"},"403":{"$ref":"#/components/responses/SellerApiForbidden"},"429":{"$ref":"#/components/responses/SellerApiRateLimited"},"500":{"$ref":"#/components/responses/SellerApiInternalError"}},"x-avrix-scopes":["seller:keys:write"],"x-avrix-tier":"keys","tags":["Keys"],"operationId":"listKeys"},"post":{"summary":"Create seller API key","description":"Create a new API key. The raw secret is returned **once** in `data.key`; store it securely. **The new key can never exceed the calling key's ceiling**: its scopes are the server's default set intersected with the calling key's scopes, it inherits the calling key's environment (sandbox keys mint sandbox keys) and expiry, and when the calling key is IP-restricted the new key inherits that allowlist (omit `allowed_ips`) or must supply a non-empty subset of it — widening attempts are rejected with `403`. Production child keys additionally require a signed API Revenue Share Channel Terms addendum on the key-owning company (`403 API_MODEL_AGREEMENT_REQUIRED` otherwise). `includeFinanceScope: true` adds `seller:finance:read` only when the calling key holds it (`403 INSUFFICIENT_SCOPE` otherwise). To obtain keys with broader scopes, create them in the console. **`allowed_ips` is optional** (0–50 IPv4/IPv6 literals or CIDR ranges) — when configured, requests from other source IPs are rejected with `403 IP_NOT_ALLOWED`. Strongly recommended; see `https://docs.avrix.io/seller-api/ip-allowlist`. Requires `seller:keys:write` on the **calling** key.","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/SellerApiKeyCreateRequest"},"example":{"name":"checkout-service-sandbox","environment":"sandbox","scopes":["seller:products:read","seller:keys:pull","seller:orders:preview"]}}}},"responses":{"201":{"description":"Key created","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/SellerApiKeyCreated"}}}}}},"401":{"$ref":"#/components/responses/SellerApiUnauthorized"},"403":{"$ref":"#/components/responses/SellerApiForbidden"},"422":{"description":"Validation failed (e.g. missing name)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"429":{"$ref":"#/components/responses/SellerApiRateLimited"},"500":{"$ref":"#/components/responses/SellerApiInternalError"}},"x-avrix-scopes":["seller:keys:write"],"x-avrix-tier":"keys","tags":["Keys"],"operationId":"createKey"}},"/api/seller/v1/keys/{id}":{"delete":{"summary":"Revoke seller API key","description":"Soft-revoke an API key by UUID. The key immediately stops authenticating but the record is retained for audit (not hard-deleted). This path is for key lifecycle only; `POST /keys/pull` and `POST /keys/export` are separate routes. Requires `seller:keys:write` scope.","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"responses":{"204":{"description":"Key revoked"},"401":{"$ref":"#/components/responses/SellerApiUnauthorized"},"403":{"$ref":"#/components/responses/SellerApiForbidden"},"404":{"description":"Key not found or already revoked","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"429":{"$ref":"#/components/responses/SellerApiRateLimited"},"500":{"$ref":"#/components/responses/SellerApiInternalError"}},"x-avrix-scopes":["seller:keys:write"],"x-avrix-tier":"keys","tags":["Keys"],"operationId":"deleteKey"}},"/api/seller/v1/keys/{id}/allowed-ips":{"patch":{"summary":"Update seller API key IP allowlist","description":"Replace the IP allowlist on an existing key **without rotating the secret**. Use this when your servers move egress IPs (cloud region migration, NAT gateway IP rotation). The PATCH is a full replacement: the new array completely overwrites the old one. Requires `seller:keys:write` scope. See `https://docs.avrix.io/seller-api/ip-allowlist`.","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/SellerApiKeyAllowedIpsUpdateRequest"},"example":{"allowedIps":["203.0.113.10"]}}}},"responses":{"204":{"description":"Allowlist updated. Changes propagate within ~60s as cached entries refresh."},"401":{"$ref":"#/components/responses/SellerApiUnauthorized"},"403":{"$ref":"#/components/responses/SellerApiForbidden"},"404":{"description":"Key not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"422":{"description":"Validation failed — `allowed_ips` empty, exceeds 50 entries, contains an invalid literal/CIDR, or contains a reserved/private range","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"429":{"$ref":"#/components/responses/SellerApiRateLimited"},"500":{"$ref":"#/components/responses/SellerApiInternalError"}},"x-avrix-scopes":["seller:keys:write"],"x-avrix-tier":"keys","tags":["Keys"],"operationId":"updateAllowedIp"}},"/api/seller/v1/keys/{id}/rotate":{"post":{"summary":"Rotate seller API key secret","description":"In-place rotation of an API key secret. Returns the new raw secret once. Requires `seller:keys:write`.","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"Key rotated","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/SellerApiKeyCreated"}}}}}},"401":{"$ref":"#/components/responses/SellerApiUnauthorized"},"403":{"$ref":"#/components/responses/SellerApiForbidden"},"404":{"description":"Key not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"422":{"description":"Invalid path id","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"429":{"$ref":"#/components/responses/SellerApiRateLimited"},"500":{"$ref":"#/components/responses/SellerApiInternalError"}},"x-avrix-scopes":["seller:keys:write"],"x-avrix-tier":"keys","tags":["Keys"],"operationId":"createRotate"}},"/api/seller/v1/whoami-ip":{"get":{"summary":"Echo the request's normalized client IP","description":"**Public, unauthenticated.** Returns the client IP that Avrix would evaluate for the IP allowlist if this request were authenticated. Use it to:\n\n- Confirm your server's egress IP from `curl` before adding it to a key's `allowed_ips`.\n- Power the dashboard's *Detect my IP* button during key onboarding.\n\nIP precedence: `x-vercel-forwarded-for` → `x-real-ip` → leftmost `x-forwarded-for`. The endpoint never echoes any other request signal. No rate limit is applied and no `X-RateLimit-*` headers are returned; the `401`/`403`/`429` entries below are the shared response set every operation declares and are not produced by this route in practice.","security":[],"responses":{"200":{"description":"Client IP resolved (or `null` when no header parsed)","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"clientIp":{"type":["string","null"],"example":"203.0.113.5"}}},"meta":{"type":"object","properties":{"requestId":{"type":"string","example":"req_01J9..."}}}}}}}},"401":{"$ref":"#/components/responses/SellerApiUnauthorized"},"403":{"$ref":"#/components/responses/SellerApiForbidden"},"429":{"$ref":"#/components/responses/SellerApiRateLimited"},"500":{"$ref":"#/components/responses/SellerApiInternalError"}},"x-avrix-scopes":[],"x-avrix-tier":"meta","tags":["Seller meta"],"operationId":"getWhoamiIp"}},"/api/seller/v1/keys/export":{"post":{"summary":"Export keys as ZIP","description":"Pull keys and return as a ZIP file (keys.txt inside) when keys are delivered immediately. **Pre-order** SKUs return JSON (`application/json`) with reserved counts instead of a ZIP (pre-order purchasing is capability-gated — `whoami.capabilities.preorderEnabled`, default false). Same contract checks as POST /orders. Use **Idempotency-Key** header (same canonical body for replay). API catalog exports require **integrationOrderContext** with `salesCountryCode`, `salesPriceGrossMinor`, and `salesTaxRatePercent`.\n\n**Route error codes** (prefix hints for monitoring; canonical `code` unchanged):\n\n| Prefix | Typical `code` values |\n|---|---|\n| KEY_* | Export windows, decrypt failures, `NO_AVAILABLE_KEYS` |\n| ORD_* | Pull parity / allocation enforcement |\n| | AUTH_* | `UNAUTHORIZED`, `FORBIDDEN`, `KEY_ENVIRONMENT_MISMATCH`, `IP_NOT_ALLOWED`, `IP_NOT_RESOLVABLE` |\n| RATE_* | `RATE_LIMIT_EXCEEDED` |\n\nSee `https://docs.avrix.io/seller-api/errors`.\n\n**Commercial enforcement (API allocations, production keys):** Territory allowlists, catalog list-price parity (`expectedUnitPriceCents` from preview), and buyer IP geo cross-check. Error codes: CATALOG_PRICE_NOT_SET, CATALOG_PRICE_MISMATCH, INVALID_CATALOG_PRICE, TERRITORY_NOT_ALLOWED_FOR_SKU, TERRITORY_EXCLUDED_FOR_RELEASE, SKU_REGION_UNRESOLVED, CONSUMER_IP_REQUIRED, CONSUMER_IP_INVALID, CONSUMER_GEO_MISMATCH, CONSUMER_IP_HIGH_RISK, CONSUMER_GEO_UNAVAILABLE, SALES_COUNTRY_REQUIRED, TAX_DECLARATION_REQUIRED. See `https://docs.avrix.io/seller-api/territory` and `https://docs.avrix.io/seller-api/store-profiles`.","parameters":[{"name":"Idempotency-Key","in":"header","required":true,"schema":{"type":"string"},"description":"Same key returns the cached successful response within 24h when the request body matches; failed responses are never cached, so a retry after fixing the cause re-executes"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["quantity"],"properties":{"skuId":{"type":"string","format":"uuid"},"skuCode":{"type":"string"},"quantity":{"type":"integer","minimum":1,"maximum":1000},"orderReference":{"type":"string","maxLength":255},"customerReference":{"type":"string","maxLength":255},"metadata":{"type":"object"},"integrationOrderContext":{"$ref":"#/components/schemas/IntegrationOrderContext"},"expectedUnitPriceCents":{"type":"integer","minimum":1,"description":"Required for API allocations on production keys. Must exactly match unitPriceCents from POST /orders/preview for the same SKU, quantity, countryCode, and integrationOrderContext."},"expectedWholesaleUnitPriceCents":{"type":"integer","minimum":1,"description":"Deprecated alias of expectedUnitPriceCents (removal planned for v2). When both are sent they must be equal. Preferred alias for wholesale/RS allocation price echo (minor units). Same semantics as expectedUnitPriceCents for wholesale commits. When both are sent they must match.","deprecated":true},"priceCommitmentToken":{"type":"string","minLength":16,"maxLength":2048,"description":"Short-lived price commitment from POST /orders/preview (when price-commitment binding is enabled on the deployment). Binds unitPriceCents across PSP charge → order. Prefer this or checkoutHoldId over re-reading live catalog."},"consumerGeoAttestId":{"type":"string","format":"uuid","description":"Optional checkout-page buyer network confirmation from POST /geo/attest. Required when GET /allocations.consumerGeoAttestRequired is true for that publisher. The attested IP must not equal the API caller or the key allowlist."}},"anyOf":[{"required":["skuId"]},{"required":["skuCode"]}]},"example":{"skuCode":"SANDBOX-ALWAYS-001","quantity":1,"orderReference":"store-order-10432"}}}},"responses":{"200":{"description":"ZIP file with keys.txt, or JSON body for pre-order (no ZIP)","content":{"application/zip":{"schema":{"type":"string","format":"binary"}},"application/json":{"schema":{"type":"object","required":["data"],"properties":{"data":{"type":"object","properties":{"type":{"type":"string","enum":["pre-order"]},"skuId":{"type":"string","format":"uuid"},"skuCode":{"type":["string","null"]},"orderReference":{"type":["string","null"]},"reserved":{"type":"integer"},"allocationId":{"type":"string","format":"uuid"},"releaseDate":{"type":["string","null"],"format":"date-time","description":"Release go-live instant (ISO 8601 date-time, UTC). Releases created before time-aware scheduling hold midnight UTC of their original calendar date."},"preorderStart":{"type":["string","null"]},"preorderEnd":{"type":["string","null"]},"exportUnavailableReason":{"type":"string","enum":["PRE_ORDER"]}}}}}}},"headers":{"Content-Disposition":{"schema":{"type":"string"},"description":"Present for ZIP responses"},"X-Key-Count":{"schema":{"type":"integer"},"description":"Number of keys in the ZIP (fulfilled only)"}}},"400":{"description":"Client error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"401":{"$ref":"#/components/responses/SellerApiUnauthorized"},"402":{"description":"Payment not cleared","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"403":{"description":"Insufficient API scope, client IP not in key allowlist, or inactive contract/share (`CONTRACT_NOT_ACTIVE`)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"409":{"description":"Insufficient keys or idempotency body mismatch","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"422":{"description":"Validation / minimum order","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"examples":{"VALIDATION_FAILED":{"summary":"VALIDATION_FAILED","value":{"code":"VALIDATION_FAILED","message":"SKU could not be resolved","error":"SKU could not be resolved","timestamp":"2026-07-20T12:00:00.000Z","recoverable":true,"hint":"See https://docs.avrix.io/seller-api/errors","requestId":"req_p1_details_example","details":{"stage":"skuResolve","skuCode":"UNKNOWN-SKU"}}}}}}},"429":{"$ref":"#/components/responses/SellerApiRateLimited"},"500":{"$ref":"#/components/responses/SellerApiInternalError"},"503":{"description":"Pre-order state unavailable","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}},"x-avrix-scopes":["seller:keys:pull"],"x-avrix-tier":"keys","tags":["Keys"],"operationId":"exportKey"}},"/api/seller/v1/keys/pull":{"post":{"summary":"Pull keys","description":"Pull keys from an allocation. Provide allocationId, or (skuId | skuCode) with quantity. **Scopes:** `seller:keys:pull`. Use **Idempotency-Key** header for retries (same canonical body). API catalog pulls require **integrationOrderContext** with `salesCountryCode`, `salesPriceGrossMinor`, and `salesTaxRatePercent`.\n\n**Route error codes** (prefix hints for monitoring; canonical `code` unchanged):\n\n| Prefix | Typical `code` values |\n|---|---|\n| KEY_* | `NO_AVAILABLE_KEYS`, decrypt/export failures, environment mismatch |\n| ORD_* | Contract / allocation denials merged into `pullError` |\n| CAT_* | SKU not entitled |\n| | AUTH_* | `UNAUTHORIZED`, `FORBIDDEN`, `KEY_ENVIRONMENT_MISMATCH`, `IP_NOT_ALLOWED`, `IP_NOT_RESOLVABLE` |\n| RATE_* | `RATE_LIMIT_EXCEEDED` |\n\nSee `https://docs.avrix.io/seller-api/errors`.\n\n**Commercial enforcement (API allocations, production keys):** Territory allowlists, catalog list-price parity (`expectedUnitPriceCents` from preview), and buyer IP geo cross-check. Error codes: CATALOG_PRICE_NOT_SET, CATALOG_PRICE_MISMATCH, INVALID_CATALOG_PRICE, TERRITORY_NOT_ALLOWED_FOR_SKU, TERRITORY_EXCLUDED_FOR_RELEASE, SKU_REGION_UNRESOLVED, CONSUMER_IP_REQUIRED, CONSUMER_IP_INVALID, CONSUMER_GEO_MISMATCH, CONSUMER_IP_HIGH_RISK, CONSUMER_GEO_UNAVAILABLE, SALES_COUNTRY_REQUIRED, TAX_DECLARATION_REQUIRED. See `https://docs.avrix.io/seller-api/territory` and `https://docs.avrix.io/seller-api/store-profiles`.","parameters":[{"name":"Idempotency-Key","in":"header","required":true,"schema":{"type":"string"},"description":"Same key returns the cached successful response within 24h when the request body matches; failed responses are never cached, so a retry after fixing the cause re-executes"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["quantity"],"properties":{"allocationId":{"type":"string","format":"uuid"},"skuId":{"type":"string","format":"uuid"},"skuCode":{"type":"string"},"quantity":{"type":"integer","minimum":1,"maximum":1000},"orderReference":{"type":"string"},"customerReference":{"type":"string","maxLength":255},"metadata":{"type":"object"},"integrationOrderContext":{"$ref":"#/components/schemas/IntegrationOrderContext"},"expectedUnitPriceCents":{"type":"integer","minimum":1,"description":"Required for API allocations on production keys. Must exactly match unitPriceCents from POST /orders/preview for the same SKU, quantity, countryCode, and integrationOrderContext."},"expectedWholesaleUnitPriceCents":{"type":"integer","minimum":1,"description":"Deprecated alias of expectedUnitPriceCents (removal planned for v2). When both are sent they must be equal. Preferred alias for wholesale/RS allocation price echo (minor units). Same semantics as expectedUnitPriceCents for wholesale commits. When both are sent they must match.","deprecated":true},"priceCommitmentToken":{"type":"string","minLength":16,"maxLength":2048,"description":"Short-lived price commitment from POST /orders/preview (when price-commitment binding is enabled on the deployment). Binds unitPriceCents across PSP charge → order. Prefer this or checkoutHoldId over re-reading live catalog."},"consumerGeoAttestId":{"type":"string","format":"uuid","description":"Optional checkout-page buyer network confirmation from POST /geo/attest. Required when GET /allocations.consumerGeoAttestRequired is true for that publisher. The attested IP must not equal the API caller or the key allowlist."}}},"example":{"skuCode":"SANDBOX-ALWAYS-001","quantity":1,"orderReference":"store-order-10432"}}}},"responses":{"200":{"description":"Keys pulled or pre-order reserved","content":{"application/json":{"schema":{"type":"object","required":["data"],"properties":{"data":{"oneOf":[{"type":"object","properties":{"type":{"type":"string","enum":["fulfilled"]},"skuId":{"type":"string","format":"uuid"},"skuCode":{"type":["string","null"]},"orderReference":{"type":["string","null"]},"keys":{"type":"array","items":{"type":"string"}},"pulled":{"type":"integer"},"allocationId":{"type":"string","format":"uuid"},"fulfilledAt":{"type":"string","format":"date-time"},"orderReadableId":{"type":"string","description":"Prefixed order ID (e.g. ord_abc12345)"},"activation":{"$ref":"#/components/schemas/SkuActivation","description":"Where the delivered key can be activated — the guaranteed intersection across the SKU's inventory batches, not the specific batch this key came from. Same object as GET /allocations and POST /orders/preview lines. Show it as \"activates in\" at delivery time without a second lookup."}}},{"type":"object","properties":{"type":{"type":"string","enum":["pre-order"]},"skuId":{"type":"string","format":"uuid"},"skuCode":{"type":["string","null"]},"orderReference":{"type":["string","null"]},"reserved":{"type":"integer"},"allocationId":{"type":"string","format":"uuid"},"releaseDate":{"type":["string","null"],"format":"date-time","description":"Release go-live instant (ISO 8601 date-time, UTC). Releases created before time-aware scheduling hold midnight UTC of their original calendar date."},"preorderStart":{"type":["string","null"]},"preorderEnd":{"type":["string","null"]},"activation":{"$ref":"#/components/schemas/SkuActivation","description":"Where the delivered key can be activated — the guaranteed intersection across the SKU's inventory batches, not the specific batch this key came from. Same object as GET /allocations and POST /orders/preview lines. Show it as \"activates in\" at delivery time without a second lookup."}},"x-avrix-capability":"preorder"}]},"contractTermId":{"type":"string","format":"uuid","description":"Active BMA term id from the atomic pull (response root; see SellerContractTermStamp)"},"contractTermVersion":{"type":"integer","minimum":1,"description":"BMA term version at pull time"}}}}}},"400":{"description":"Client error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"401":{"$ref":"#/components/responses/SellerApiUnauthorized"},"402":{"description":"Payment not cleared","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"403":{"description":"Insufficient API scope, client IP not in key allowlist, or inactive contract/share (`CONTRACT_NOT_ACTIVE`)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"409":{"description":"Insufficient vendor stock (`NO_AVAILABLE_KEYS`), allocation cap reached (`ALLOCATION_EXCEEDED`, with `details.remainingInAllocation`), or idempotency body mismatch","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"examples":{"NO_AVAILABLE_KEYS":{"summary":"NO_AVAILABLE_KEYS","value":{"code":"NO_AVAILABLE_KEYS","message":"No available keys in inventory","error":"No available keys in inventory","timestamp":"2026-07-20T12:00:00.000Z","recoverable":true,"hint":"See https://docs.avrix.io/seller-api/errors","requestId":"req_p1_details_example","details":{"pullError":"NO_AVAILABLE_KEYS","allocationId":"00000000-0000-4000-8000-000000000001","skuId":"00000000-0000-4000-8000-000000000002"}}},"ALLOCATION_EXCEEDED":{"summary":"Allocation cap reached (request more headroom)","value":{"code":"ALLOCATION_EXCEEDED","message":"Only 7 keys remaining in allocation","error":"Only 7 keys remaining in allocation","timestamp":"2026-07-20T12:00:00.000Z","recoverable":false,"hint":"Your allocation cap is reached (details.remainingInAllocation shows headroom) — request a larger allocation from the publisher","doc_url":"https://docs.avrix.io/seller-api/errors#allocation-exceeded","requestId":"req_p1_details_example","details":{"pullError":"ALLOCATION_EXCEEDED","recommendedAction":"request_allocation_increase","remainingInAllocation":7,"allocationId":"00000000-0000-4000-8000-000000000001","skuId":"00000000-0000-4000-8000-000000000002"}}}}}}},"422":{"description":"Validation / minimum order","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"examples":{"CONSUMER_IP_REQUIRED":{"value":{"code":"CONSUMER_IP_REQUIRED","message":"consumerIp is required for production API keys","error":"consumerIp is required for production API keys","timestamp":"2026-05-26T12:00:00.000Z","recoverable":true,"hint":"Re-run POST /orders/preview and align country, price, and consumerIp before POST /orders","requestId":"req_commercial_enforcement_example","details":{"pullError":"CONSUMER_IP_REQUIRED"}}}}}}},"429":{"description":"Rate limit","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"500":{"$ref":"#/components/responses/SellerApiInternalError"},"503":{"description":"Pre-order state unavailable","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}},"x-avrix-scopes":["seller:keys:pull"],"x-avrix-tier":"keys","tags":["Keys"],"operationId":"pullKey"}},"/api/seller/v1/keys/return":{"post":{"summary":"Return keys after fulfillment","description":"Return keys that were pulled for your seller company (`revealed` state). Returned keys are **quarantined** — they do **not** re-enter the available pool and are never automatically re-issued to any seller. Operators review quarantined keys out-of-band and decide whether to write off, re-issue, or refund. Allocation headroom is restored accordingly. Use after refunds or chargebacks when keys must not remain with the buyer. Requires `seller:refunds:write`; legacy `seller:keys:pull` remains accepted during the deprecation window. Use **Idempotency-Key** for safe retries. Emits webhook `order.keys_returned`. See https://docs.avrix.io/seller-api/refunds-returns.\n\n**Route error codes** (prefix hints for monitoring; canonical `code` unchanged):\n\n| Prefix | Typical `code` values |\n|---|---|\n| KEY_* | Return eligibility, unknown pull batch, idempotency replay |\n| ORD_* | Post-commit guardrails |\n| | AUTH_* | `UNAUTHORIZED`, `FORBIDDEN`, `KEY_ENVIRONMENT_MISMATCH`, `IP_NOT_ALLOWED`, `IP_NOT_RESOLVABLE` |\n| RATE_* | `RATE_LIMIT_EXCEEDED` |\n\nSee `https://docs.avrix.io/seller-api/errors`.","parameters":[{"name":"Idempotency-Key","in":"header","required":true,"schema":{"type":"string"},"description":"Required for safe retries (same rules as POST /orders)"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["keyIds"],"properties":{"keyIds":{"type":"array","items":{"type":"string","format":"uuid"},"minItems":1,"maxItems":100,"description":"Key UUIDs previously delivered to your integration (from seller_key_pulls)"},"reason":{"type":"string","maxLength":500,"description":"Optional audit reason (e.g. refund id)"}}},"example":{"keyIds":["key_01EXAMPLE"],"reason":"customer_refund"}}}},"responses":{"200":{"description":"Keys quarantined and allocation headroom restored","content":{"application/json":{"schema":{"type":"object","required":["data"],"properties":{"data":{"type":"object","properties":{"returned":{"type":"integer","description":"Number of keys quarantined"}},"required":["returned"]}}}}}},"400":{"description":"Keys not returnable or not owned by this seller","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"401":{"$ref":"#/components/responses/SellerApiUnauthorized"},"403":{"$ref":"#/components/responses/SellerApiForbidden"},"422":{"description":"Validation failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"429":{"$ref":"#/components/responses/SellerApiRateLimited"},"500":{"$ref":"#/components/responses/SellerApiInternalError"}},"x-avrix-scopes":["seller:refunds:write"],"x-avrix-tier":"keys","tags":["Keys"],"operationId":"returnKey"}},"/api/seller/v1/refunds":{"post":{"summary":"External refund or chargeback callback","description":"Notify Avrix that a storefront refund or chargeback has occurred and quarantine already delivered keys. This endpoint reuses the key-return quarantine flow, restores allocation headroom, and emits both `order.keys_returned` and `refund.completed`. Requires `seller:refunds:write` (or legacy `seller:keys:pull`). Use `Idempotency-Key` for safe retries.\n\nRequest `reason` is accepted for compatibility but ignored. Inventory stores a canonical code (`api_refund` or `chargeback` from `type`). Partner text belongs on `refundReference` or `chargebackReference`.\n\n**Route error codes** (prefix hints for monitoring; canonical `code` unchanged):\n\n| Prefix | Typical `code` values |\n|---|---|\n| KEY_* | Keys already consumed / cannot quarantine |\n| ORD_* | Unknown order reference, duplicate refund notification |\n| | AUTH_* | `UNAUTHORIZED`, `FORBIDDEN`, `KEY_ENVIRONMENT_MISMATCH`, `IP_NOT_ALLOWED`, `IP_NOT_RESOLVABLE` |\n| RATE_* | `RATE_LIMIT_EXCEEDED` |\n\nSee `https://docs.avrix.io/seller-api/errors`.","parameters":[{"name":"Idempotency-Key","in":"header","required":true,"schema":{"type":"string"},"description":"Required for safe retries"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["type"],"properties":{"type":{"type":"string","enum":["refund","chargeback"]},"keyIds":{"type":"array","items":{"type":"string","format":"uuid"},"minItems":1,"maxItems":100,"description":"Explicit key UUIDs from the fulfilment response. Optional when `quantity` + `orderReference` select the keys instead; one of the two forms is required."},"quantity":{"type":"integer","minimum":1,"maximum":100,"description":"Partial refund by count: quarantines the newest `quantity` live keys sold under `orderReference` (no need to track key ids by position). Requires `orderReference`."},"refundReference":{"type":"string","maxLength":128,"description":"Required when type is refund"},"chargebackReference":{"type":"string","maxLength":128,"description":"Required when type is chargeback"},"orderReference":{"type":"string","maxLength":255},"reason":{"type":"string","maxLength":500,"description":"Accepted for compatibility and ignored. Inventory reason is `api_refund` or `chargeback` from `type`. Put partner text on `refundReference` or `chargebackReference`."},"occurredAt":{"type":"string","format":"date-time"}}},"example":{"type":"refund","keyIds":["key_01EXAMPLE"],"refundReference":"psp_refund_10432"}}}},"responses":{"200":{"description":"Refund or chargeback accepted and keys quarantined","content":{"application/json":{"schema":{"type":"object","required":["data"],"properties":{"data":{"type":"object","properties":{"type":{"type":"string"},"returned":{"type":"integer"},"refundReference":{"type":["string","null"]},"chargebackReference":{"type":["string","null"]},"orderReference":{"type":["string","null"]},"occurredAt":{"type":["string","null"],"format":"date-time"}},"required":["type","returned"]}}}}}},"400":{"description":"Keys not returnable or not owned by this seller","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"401":{"$ref":"#/components/responses/SellerApiUnauthorized"},"403":{"$ref":"#/components/responses/SellerApiForbidden"},"422":{"description":"Validation failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"examples":{"MISSING_TYPE":{"summary":"type omitted","value":{"code":"VALIDATION_FAILED","message":"Invalid request body field \"type\": type is required: \"refund\" or \"chargeback\"","error":"Invalid request body field \"type\": type is required: \"refund\" or \"chargeback\"","timestamp":"2026-09-07T00:00:00.000Z","recoverable":true,"hint":"Use details.issues for machine-readable corrections (field + message).","doc_url":"https://docs.avrix.io/seller-api/errors#validation-failed","requestId":"req_refund_422_type","details":{"validationTarget":"json_body","issues":[{"field":"type","message":"type is required: \"refund\" or \"chargeback\""}]}}},"MISSING_REFUND_REFERENCE":{"summary":"refund without refundReference","value":{"code":"VALIDATION_FAILED","message":"Invalid request body field \"refundReference\": refundReference is required when type is refund","error":"Invalid request body field \"refundReference\": refundReference is required when type is refund","timestamp":"2026-09-07T00:00:00.000Z","recoverable":true,"hint":"Use details.issues for machine-readable corrections (field + message).","doc_url":"https://docs.avrix.io/seller-api/errors#validation-failed","requestId":"req_refund_422_ref","details":{"validationTarget":"json_body","issues":[{"field":"refundReference","message":"refundReference is required when type is refund"}]}}}}}}},"429":{"$ref":"#/components/responses/SellerApiRateLimited"},"500":{"$ref":"#/components/responses/SellerApiInternalError"}},"x-avrix-scopes":["seller:refunds:write"],"x-avrix-tier":"orders","tags":["Orders"],"operationId":"createRefund"},"get":{"summary":"List refunds and chargebacks","description":"Paginated refund/chargeback status for quarantined sales. **Avrix never refunds your PSP** — refund the buyer first, then POST /refunds. Scopes: `seller:refunds:read` (also `seller:refunds:write`, `seller:finance:read`, or legacy `seller:keys:pull`).","x-avrix-scopes":["seller:refunds:read"],"x-avrix-tier":"standard","parameters":[{"name":"limit","in":"query","schema":{"type":"integer","minimum":1,"maximum":100,"default":50}},{"name":"cursor","in":"query","schema":{"type":"string"},"description":"Opaque keyset cursor from meta.nextCursor. Do not construct or parse — echo it back verbatim. Legacy integer offset cursors from before 2026-08 remain accepted during transition."},{"name":"orderReference","in":"query","schema":{"type":"string"},"description":"Filter by store orderReference"}],"responses":{"200":{"description":"Refund list","content":{"application/json":{"schema":{"type":"object","required":["data","meta"],"properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/SellerRefund"}},"meta":{"type":"object","properties":{"limit":{"type":"integer"},"nextCursor":{"type":["string","null"]},"nextUrl":{"type":["string","null"]}}}}}}}},"401":{"$ref":"#/components/responses/SellerApiUnauthorized"},"403":{"$ref":"#/components/responses/SellerApiForbidden"},"429":{"$ref":"#/components/responses/SellerApiRateLimited"},"500":{"$ref":"#/components/responses/SellerApiInternalError"}},"operationId":"listRefunds","tags":["Orders"]}},"/api/seller/v1/promotions/summary":{"get":{"summary":"Get promotions summary","description":"Counts of platform event shares and custom deals (pending, accepted/approved, declined/rejected). Requires seller:promotions:read scope.","responses":{"200":{"description":"Summary counts","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"shares":{"type":"object","properties":{"pending":{"type":"integer"},"accepted":{"type":"integer"},"declined":{"type":"integer"},"total":{"type":"integer"}}},"deals":{"type":"object","properties":{"pending":{"type":"integer"},"approved":{"type":"integer"},"rejected":{"type":"integer"},"total":{"type":"integer"}}}}}}}}}},"401":{"$ref":"#/components/responses/SellerApiUnauthorized"},"403":{"$ref":"#/components/responses/SellerApiForbidden"},"429":{"$ref":"#/components/responses/SellerApiRateLimited"},"500":{"$ref":"#/components/responses/SellerApiInternalError"}},"x-avrix-scopes":["seller:promotions:read"],"x-avrix-tier":"promotions","tags":["Promotions"],"operationId":"getPromotionsSummary"}},"/api/seller/v1/promotions/shares":{"get":{"summary":"List platform event shares","description":"Platform event promotions shared by vendors with your company. Filter by status (pending, accepted, declined, expired). Requires seller:promotions:read scope.","parameters":[{"name":"status","in":"query","schema":{"type":"string"},"description":"Comma-separated: pending, accepted, declined, expired"}],"responses":{"200":{"description":"Shares list","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"type":"object","properties":{"share_id":{"type":"string"},"participation_id":{"type":"string"},"status":{"type":"string"},"vendor_company_id":{"type":"string"},"vendor_company_name":{"type":"string"},"event_id":{"type":"string"},"event_name":{"type":"string"},"event_starts_at":{"type":["string","null"]},"event_ends_at":{"type":["string","null"]},"platform_name":{"type":"string"},"product_count":{"type":"integer"},"shared_at":{"type":"string"}}}}}}}}},"401":{"$ref":"#/components/responses/SellerApiUnauthorized"},"403":{"$ref":"#/components/responses/SellerApiForbidden"},"429":{"$ref":"#/components/responses/SellerApiRateLimited"},"500":{"$ref":"#/components/responses/SellerApiInternalError"}},"x-avrix-scopes":["seller:promotions:read"],"x-avrix-tier":"promotions","tags":["Promotions"],"operationId":"listPromotionsShares"}},"/api/seller/v1/promotions/shares/{shareId}":{"get":{"summary":"Get share detail","description":"Platform event share detail with products (SKU, discount, etc.). Requires seller:promotions:read scope.","parameters":[{"name":"shareId","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"Share detail with products","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"share_id":{"type":"string"},"status":{"type":"string"},"vendor_company_id":{"type":"string"},"event_name":{"type":"string"},"platform_name":{"type":"string"},"products":{"type":"array","items":{"type":"object","properties":{"sku_id":{"type":"string"},"sku_code":{"type":"string"},"product_name":{"type":"string"},"discount_percent":{"type":"integer"},"base_price_cents":{"type":["integer","null"]}}}}}}}}}}},"401":{"$ref":"#/components/responses/SellerApiUnauthorized"},"403":{"$ref":"#/components/responses/SellerApiForbidden"},"404":{"description":"Share not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"429":{"$ref":"#/components/responses/SellerApiRateLimited"},"500":{"$ref":"#/components/responses/SellerApiInternalError"}},"x-avrix-scopes":["seller:promotions:read"],"x-avrix-tier":"promotions","tags":["Promotions"],"operationId":"getShare"}},"/api/seller/v1/promotions/shares/{shareId}/accept":{"post":{"summary":"Accept share","description":"Accept a platform event share. Requires seller:promotions:respond scope.","parameters":[{"name":"shareId","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"sellerNotes":{"type":"string","description":"Optional notes"}}},"example":{}}}},"responses":{"200":{"description":"Share accepted","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"shareId":{"type":"string"}}}}}}}},"400":{"description":"Already responded or expired","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"401":{"$ref":"#/components/responses/SellerApiUnauthorized"},"403":{"$ref":"#/components/responses/SellerApiForbidden"},"429":{"$ref":"#/components/responses/SellerApiRateLimited"},"500":{"$ref":"#/components/responses/SellerApiInternalError"}},"x-avrix-scopes":["seller:promotions:respond"],"x-avrix-tier":"promotions","tags":["Promotions"],"operationId":"acceptShare"}},"/api/seller/v1/promotions/shares/{shareId}/decline":{"post":{"summary":"Decline share","description":"Decline a platform event share. Requires seller:promotions:respond scope.","parameters":[{"name":"shareId","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"notes":{"type":"string","description":"Optional decline reason"}}},"example":{}}}},"responses":{"200":{"description":"Share declined","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"shareId":{"type":"string"}}}}}}}},"400":{"description":"Already responded or expired","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"401":{"$ref":"#/components/responses/SellerApiUnauthorized"},"403":{"$ref":"#/components/responses/SellerApiForbidden"},"429":{"$ref":"#/components/responses/SellerApiRateLimited"},"500":{"$ref":"#/components/responses/SellerApiInternalError"}},"x-avrix-scopes":["seller:promotions:respond"],"x-avrix-tier":"promotions","tags":["Promotions"],"operationId":"declineShare"}},"/api/seller/v1/promotions/deals":{"get":{"summary":"List received custom deals","description":"Custom promotions shared by vendors with your company. Filter by vendor (publisher company ID) or status (pending, approved, rejected, expired). Requires seller:promotions:read scope.","parameters":[{"name":"vendor","in":"query","schema":{"type":"string","maxLength":32,"pattern":"^[a-zA-Z0-9_-]+$"},"description":"Filter by vendor company ID — slug-safe identifier (alphanumeric, hyphen, underscore), max 32 chars"},{"name":"status","in":"query","schema":{"type":"string"},"description":"Comma-separated: pending, approved, rejected, expired"}],"responses":{"200":{"description":"Deals list","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","description":"Response ID"},"promotion_id":{"type":"string"},"promotion_name":{"type":"string"},"vendor_company_id":{"type":"string"},"vendor_company_name":{"type":"string"},"start_date":{"type":"string"},"end_date":{"type":"string"},"response_status":{"type":"string"},"product_count":{"type":"integer"}}}}}}}}},"401":{"$ref":"#/components/responses/SellerApiUnauthorized"},"403":{"$ref":"#/components/responses/SellerApiForbidden"},"429":{"$ref":"#/components/responses/SellerApiRateLimited"},"500":{"$ref":"#/components/responses/SellerApiInternalError"}},"x-avrix-scopes":["seller:promotions:read"],"x-avrix-tier":"promotions","tags":["Promotions"],"operationId":"listPromotionsDeals"}},"/api/seller/v1/promotions/deals/{responseId}":{"get":{"summary":"Get deal detail","description":"Custom deal detail with products. Requires seller:promotions:read scope.","parameters":[{"name":"responseId","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"Deal detail with products","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"id":{"type":"string"},"promotion_id":{"type":"string"},"promotion_name":{"type":"string"},"vendor_company_id":{"type":"string"},"start_date":{"type":"string"},"end_date":{"type":"string"},"response_status":{"type":"string"},"products":{"type":"array","items":{"type":"object","properties":{"sku_id":{"type":"string"},"sku_code":{"type":"string"},"product_name":{"type":"string"},"discount_percent":{"type":"integer"},"base_price_cents":{"type":["integer","null"]}}}}}}}}}}},"401":{"$ref":"#/components/responses/SellerApiUnauthorized"},"403":{"$ref":"#/components/responses/SellerApiForbidden"},"404":{"description":"Deal not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"429":{"$ref":"#/components/responses/SellerApiRateLimited"},"500":{"$ref":"#/components/responses/SellerApiInternalError"}},"x-avrix-scopes":["seller:promotions:read"],"x-avrix-tier":"promotions","tags":["Promotions"],"operationId":"getDeal"}},"/api/seller/v1/promotions/deals/{responseId}/respond":{"post":{"summary":"Respond to deal","description":"Accept or decline a custom deal. Body: { decision: 'approved' | 'rejected', note?: string }. Requires seller:promotions:respond scope.","parameters":[{"name":"responseId","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["decision"],"properties":{"decision":{"type":"string","enum":["approved","rejected"]},"note":{"type":"string","description":"Optional note"}}},"example":{"decision":"accepted"}}}},"responses":{"200":{"description":"Response recorded","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"responseId":{"type":"string"}}}}}}}},"400":{"description":"Already responded, withdrawn, or deadline passed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"401":{"$ref":"#/components/responses/SellerApiUnauthorized"},"403":{"$ref":"#/components/responses/SellerApiForbidden"},"404":{"description":"Deal not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"429":{"$ref":"#/components/responses/SellerApiRateLimited"},"500":{"$ref":"#/components/responses/SellerApiInternalError"}},"x-avrix-scopes":["seller:promotions:respond"],"x-avrix-tier":"promotions","tags":["Promotions"],"operationId":"respondDeal"}},"/api/seller/v1/health":{"get":{"summary":"Health check (with sub-component status)","description":"Uptime + per-component status. Auth optional. Returns 200 when the **db** probe succeeds; 503 when the db probe is degraded. The `components` object reports `db`, `redis`, `qstash`, and `catalogIndex` independently with `status` (`ok` / `degraded` / `unconfigured`), `latencyMs`, and an optional `message` field. `qstash` and `catalogIndex` never downgrade the top-level status — they have safe fallbacks (cron delivery + read-through cache). The legacy `redisConfigured` boolean is preserved for backwards compatibility. Note: Unlike other endpoints, health does not wrap the response in a `data` object.","security":[],"responses":{"200":{"description":"API is operational","content":{"application/json":{"schema":{"type":"object","properties":{"status":{"type":"string","enum":["ok","degraded"]},"timestamp":{"type":"string","format":"date-time"},"version":{"type":"string","example":"1"},"redisConfigured":{"type":"boolean","description":"Legacy flag — true when the rate-limit/cache backend is configured. Prefer `components.redis.status`."},"checkDurationMs":{"type":"integer"},"components":{"type":"object","properties":{"db":{"$ref":"#/components/schemas/SellerHealthComponent"},"redis":{"$ref":"#/components/schemas/SellerHealthComponent"},"qstash":{"$ref":"#/components/schemas/SellerHealthComponent"},"catalogIndex":{"$ref":"#/components/schemas/SellerHealthComponent"}}}}}}}},"401":{"$ref":"#/components/responses/SellerApiUnauthorized"},"403":{"$ref":"#/components/responses/SellerApiForbidden"},"429":{"$ref":"#/components/responses/SellerApiRateLimited"},"500":{"$ref":"#/components/responses/SellerApiInternalError"},"503":{"description":"Required component (db) is degraded.","content":{"application/json":{"schema":{"type":"object","properties":{"status":{"type":"string","enum":["degraded"]},"components":{"type":"object"}}}}}}},"x-avrix-scopes":[],"x-avrix-tier":"meta","tags":["Seller meta"],"operationId":"getHealth"}},"/api/seller/v1/webhooks/event-types":{"get":{"summary":"List webhook event types","description":"Catalog of webhook event names and short descriptions for subscription discovery. Canonical list: GET /api/seller/v1/webhooks/event-types.","responses":{"200":{"description":"Webhook event type catalog","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"type":"object","required":["name","description"],"properties":{"name":{"type":"string","enum":["test.ping","order.fulfilled","order.failed","order.activated","order.reserved","order.ready","order.preorder_fulfilled","order.returned","order.keys_returned","refund.completed","chargeback.resolved","redemption.expiring","redemption.expired","catalog.export_ready","keys.pulled","allocation.updated","allocation.depleted","allocation.low_stock","product.updated","product.announced","product.delisted","product.delisting_scheduled","release.available","release.date_changed","sku.pricing_updated","sku.sellability_changed","contract.activated","contract.superseded","contract.amendment_accepted","invoice.created","report.ready","system.webhook_endpoint_disabled"]},"description":{"type":"string"}}}}}}}}},"401":{"$ref":"#/components/responses/SellerApiUnauthorized"},"403":{"$ref":"#/components/responses/SellerApiForbidden"},"429":{"$ref":"#/components/responses/SellerApiRateLimited"},"500":{"$ref":"#/components/responses/SellerApiInternalError"}},"x-avrix-scopes":["seller:webhooks:read"],"x-avrix-tier":"webhooks","tags":["Webhooks"],"operationId":"listWebhooksEventTypes"}},"/api/seller/v1/webhooks":{"get":{"summary":"List webhook endpoints","description":"List registered webhook endpoints for your company.","responses":{"200":{"description":"Webhook endpoints list","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"url":{"type":"string"},"events":{"type":"array","items":{"type":"string"}},"status":{"type":"string"},"createdAt":{"type":"string","format":"date-time"},"bufferedDeliveries":{"type":"integer","description":"Deliveries parked for this endpoint while it is disabled (buffered, flushed on re-enable). Company admins are alerted when a disabled endpoint crosses 50/80/100% of bufferCapacity; at the cap new events are dropped and must be recovered by polling."},"bufferCapacity":{"type":"integer","description":"Per-endpoint buffer cap (10,000 by default)."}}}}}}}}},"401":{"$ref":"#/components/responses/SellerApiUnauthorized"},"403":{"$ref":"#/components/responses/SellerApiForbidden"},"429":{"$ref":"#/components/responses/SellerApiRateLimited"},"500":{"$ref":"#/components/responses/SellerApiInternalError"}},"x-avrix-scopes":["seller:webhooks:read"],"x-avrix-tier":"webhooks","tags":["Webhooks"],"operationId":"listWebhooks"},"post":{"summary":"Create webhook endpoint","description":"Register a webhook endpoint. Returns the signing secret ONCE - store it securely.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["url","events"],"properties":{"url":{"type":"string","format":"uri"},"events":{"type":"array","items":{"type":"string","enum":["test.ping","order.fulfilled","order.failed","order.activated","order.reserved","order.ready","order.preorder_fulfilled","order.returned","order.keys_returned","refund.completed","chargeback.resolved","redemption.expiring","redemption.expired","catalog.export_ready","keys.pulled","allocation.updated","allocation.depleted","allocation.low_stock","product.updated","product.announced","product.delisted","product.delisting_scheduled","release.available","release.date_changed","sku.pricing_updated","sku.sellability_changed","contract.activated","contract.superseded","contract.amendment_accepted","invoice.created","report.ready","system.webhook_endpoint_disabled"]}}}},"example":{"url":"https://merchant.example/webhooks/avrix","events":["order.fulfilled","order.failed","test.ping"]}}}},"responses":{"201":{"description":"Webhook created","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"id":{"type":"string"},"url":{"type":"string"},"events":{"type":"array","items":{"type":"string"}},"secret":{"type":"string","description":"Signing secret - shown only once"}}}}}}}},"401":{"$ref":"#/components/responses/SellerApiUnauthorized"},"403":{"$ref":"#/components/responses/SellerApiForbidden"},"429":{"$ref":"#/components/responses/SellerApiRateLimited"},"500":{"$ref":"#/components/responses/SellerApiInternalError"}},"x-avrix-scopes":["seller:webhooks:write"],"x-avrix-tier":"webhooks","tags":["Webhooks"],"operationId":"createWebhook","parameters":[{"name":"Idempotency-Key","in":"header","required":true,"schema":{"type":"string","minLength":1,"maxLength":64,"pattern":"^[a-zA-Z0-9_-]+$"},"description":"Stable key for this logical mutation (1–64 chars, `[a-zA-Z0-9_-]`). Reuse the same key and canonical JSON body on retries. Mismatch returns 409 `IDEMPOTENCY_KEY_MISMATCH`."}]}},"/api/seller/v1/webhooks/{id}":{"patch":{"summary":"Update webhook endpoint","description":"Update URL and/or events, or rotate the signing secret (`rotateSecret: true`).","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"url":{"type":"string","format":"uri"},"events":{"type":"array","items":{"type":"string"}},"rotateSecret":{"type":"boolean"}}},"example":{"events":["order.fulfilled","order.failed","order.reserved","test.ping"]}}}},"responses":{"200":{"description":"Updated","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"id":{"type":"string"},"url":{"type":"string"},"events":{"type":"array","items":{"type":"string"}},"secret":{"type":"string","description":"Present only when rotateSecret was true"}}}}}}}},"401":{"$ref":"#/components/responses/SellerApiUnauthorized"},"403":{"$ref":"#/components/responses/SellerApiForbidden"},"422":{"description":"Invalid path `id` (UUID) or JSON body (unknown keys rejected; at least one of url, events, rotateSecret: true required; events must be known event names)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"429":{"$ref":"#/components/responses/SellerApiRateLimited"},"500":{"$ref":"#/components/responses/SellerApiInternalError"}},"x-avrix-scopes":["seller:webhooks:write"],"x-avrix-tier":"webhooks","tags":["Webhooks"],"operationId":"updateWebhook"},"delete":{"summary":"Delete webhook endpoint","description":"Remove a webhook endpoint. Stops sending events.","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"responses":{"204":{"description":"Webhook deleted"},"401":{"$ref":"#/components/responses/SellerApiUnauthorized"},"403":{"$ref":"#/components/responses/SellerApiForbidden"},"422":{"description":"Invalid path parameter `id` (UUID)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"429":{"$ref":"#/components/responses/SellerApiRateLimited"},"500":{"$ref":"#/components/responses/SellerApiInternalError"}},"x-avrix-scopes":["seller:webhooks:write"],"x-avrix-tier":"webhooks","tags":["Webhooks"],"operationId":"deleteWebhook"}},"/api/seller/v1/webhooks/{id}/test":{"post":{"summary":"Send test webhook","description":"Queues a `test.ping` delivery to verify URL and HMAC verification.","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"responses":{"202":{"description":"Test delivery queued","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"deliveryId":{"type":"string"},"eventId":{"type":"string"},"message":{"type":"string"}}}}}}}},"401":{"$ref":"#/components/responses/SellerApiUnauthorized"},"403":{"$ref":"#/components/responses/SellerApiForbidden"},"429":{"$ref":"#/components/responses/SellerApiRateLimited"},"500":{"$ref":"#/components/responses/SellerApiInternalError"}},"x-avrix-scopes":["seller:webhooks:write"],"x-avrix-tier":"webhooks","tags":["Webhooks"],"operationId":"createTest"}},"/api/seller/v1/webhooks/{id}/enable":{"post":{"summary":"Re-enable webhook endpoint","description":"Sets status to active after circuit-breaker disable; resets failure counters.\n\n**Buffered events:** deliveries queued while the endpoint was disabled are flushed automatically on re-enable (`flushedBufferedDeliveries` reports the count).","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"Re-enabled","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"id":{"type":"string"},"status":{"type":"string"},"message":{"type":"string"},"flushedBufferedDeliveries":{"type":"integer","description":"Deliveries buffered while the endpoint was disabled, now queued for delivery."}}}}}}}},"401":{"$ref":"#/components/responses/SellerApiUnauthorized"},"403":{"$ref":"#/components/responses/SellerApiForbidden"},"429":{"$ref":"#/components/responses/SellerApiRateLimited"},"500":{"$ref":"#/components/responses/SellerApiInternalError"}},"x-avrix-scopes":["seller:webhooks:write"],"x-avrix-tier":"webhooks","tags":["Webhooks"],"operationId":"createEnable"}},"/api/seller/v1/webhooks/{id}/deliveries/{deliveryId}/retry":{"post":{"summary":"Retry failed webhook delivery","description":"Re-queues a failed delivery with attempts reset.","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}},{"name":"deliveryId","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"responses":{"202":{"description":"Delivery re-queued"},"401":{"$ref":"#/components/responses/SellerApiUnauthorized"},"403":{"$ref":"#/components/responses/SellerApiForbidden"},"429":{"$ref":"#/components/responses/SellerApiRateLimited"},"500":{"$ref":"#/components/responses/SellerApiInternalError"}},"x-avrix-scopes":["seller:webhooks:write"],"x-avrix-tier":"webhooks","tags":["Webhooks"],"operationId":"createRetry"}},"/api/seller/v1/webhooks/{id}/deliveries/replay":{"post":{"summary":"Bulk replay webhook deliveries (Phase 3.3)","description":"Re-enqueues a window of past deliveries for an endpoint. Each replay inserts a **new** `event_id` (global uniqueness); the outbound JSON duplicates the original envelope and adds **`replay.sourceDeliveryId`** and **`replay.originalEventId`** so receivers can correlate with idempotency keyed on `event_id` / `X-Avrix-Event-Id`. Use to recover from partner-side outages without manual ticket-driven resyncs. Window is capped at 7 days back; up to 1000 deliveries per call.","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["since"],"additionalProperties":false,"properties":{"since":{"type":"string","format":"date-time","description":"Inclusive lower bound on delivery `created_at`. Max 7 days back."},"until":{"type":"string","format":"date-time","description":"Inclusive upper bound on delivery `created_at`. Defaults to now."},"sourceStatus":{"type":"string","enum":["failed","succeeded","all"],"default":"failed","description":"Which source deliveries to replay. Defaults to `failed`."},"eventTypes":{"type":"array","items":{"type":"string"},"minItems":1,"description":"Restrict replay to specific event types (e.g. [\"order.fulfilled\"])."},"limit":{"type":"integer","minimum":1,"maximum":1000,"default":200,"description":"Hard cap on rows enqueued in this call."}}},"example":{"since":"2026-08-01T00:00:00.000Z"}}}},"responses":{"202":{"description":"Replay enqueued","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"enqueued":{"type":"integer"},"deliveryIds":{"type":"array","items":{"type":"string","format":"uuid"},"description":"Newly created replay rows."},"sourceDeliveryIds":{"type":"array","items":{"type":"string","format":"uuid"},"description":"Original deliveries that were cloned."}}}}}}}},"400":{"description":"Invalid window or input","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"401":{"$ref":"#/components/responses/SellerApiUnauthorized"},"403":{"$ref":"#/components/responses/SellerApiForbidden"},"404":{"description":"Webhook endpoint not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"409":{"description":"Webhook endpoint is not active; re-enable first.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"422":{"description":"Validation failed (invalid `since`/`until` or window > 7 days)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"429":{"$ref":"#/components/responses/SellerApiRateLimited"},"500":{"$ref":"#/components/responses/SellerApiInternalError"}},"x-avrix-scopes":["seller:webhooks:write"],"x-avrix-tier":"webhooks","tags":["Webhooks"],"operationId":"createReplay"}},"/api/seller/v1/usage":{"get":{"summary":"API usage summary","description":"Aggregates `api_audit_log` rows for the authenticated seller (UTC window). Default: last 7 days.","parameters":[{"name":"from","in":"query","schema":{"type":"string","format":"date-time"},"description":"Range start (ISO 8601)"},{"name":"to","in":"query","schema":{"type":"string","format":"date-time"},"description":"Range end (ISO 8601)"}],"responses":{"200":{"description":"Usage aggregates","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"from":{"type":"string"},"to":{"type":"string"},"totalRequests":{"type":"integer"},"totalErrors":{"type":"integer","description":"Responses >= 400, excluding lookup misses."},"totalLookupMisses":{"type":"integer","description":"404s on GET lookups (e.g. `GET /orders?orderReference=` before a commit). Expected integration behaviour, not failures."},"byEndpoint":{"type":"array","description":"One bucket per method + endpoint; a GET lookup and a POST commit on the same path are separate buckets.","items":{"type":"object","properties":{"endpoint":{"type":"string"},"method":{"type":"string","description":"HTTP method (uppercase)."},"requests":{"type":"integer"},"errors":{"type":"integer","description":"Responses >= 400, excluding lookup misses."},"lookupMisses":{"type":"integer","description":"404s on GET requests in this bucket."}}}}}}}}}}},"401":{"$ref":"#/components/responses/SellerApiUnauthorized"},"403":{"$ref":"#/components/responses/SellerApiForbidden"},"422":{"description":"Invalid query parameters (from/to or range)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"429":{"$ref":"#/components/responses/SellerApiRateLimited"},"500":{"$ref":"#/components/responses/SellerApiInternalError"}},"x-avrix-scopes":["seller:products:read"],"x-avrix-tier":"meta","tags":["Seller meta"],"operationId":"getUsage"}},"/api/seller/v1/requests/{requestId}":{"get":{"summary":"Inspect a Seller API request by X-Request-Id","description":"Returns a redacted, seller-scoped trace from `distribution.api_audit_log`. Raw keys, webhook secrets, PSP tokens, and free-form metadata are never returned.","parameters":[{"name":"requestId","in":"path","required":true,"schema":{"type":"string","minLength":8,"maxLength":128},"description":"The X-Request-Id value from a Seller API response."}],"responses":{"200":{"description":"Redacted request trace","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"requestId":{"type":"string"},"traces":{"type":"array","items":{"type":"object","properties":{"endpoint":{"type":"string"},"method":{"type":"string"},"statusCode":{"type":["integer","null"]},"responseTimeMs":{"type":["integer","null"]},"errorMessage":{"type":["string","null"]},"apiKeyId":{"type":["string","null"],"format":"uuid"},"integrationContextBytes":{"type":["integer","null"]},"pulledCount":{"type":["integer","null"]},"allocationId":{"type":["string","null"],"format":"uuid"},"skuId":{"type":["string","null"],"format":"uuid"},"keyPullId":{"type":["string","null"],"format":"uuid"},"createdAt":{"type":"string","format":"date-time"}}}}}}}}}}},"401":{"$ref":"#/components/responses/SellerApiUnauthorized"},"403":{"$ref":"#/components/responses/SellerApiForbidden"},"422":{"description":"Invalid request id"},"429":{"$ref":"#/components/responses/SellerApiRateLimited"},"500":{"$ref":"#/components/responses/SellerApiInternalError"}},"x-avrix-scopes":["seller:products:read"],"x-avrix-tier":"meta","tags":["Seller meta"],"operationId":"getRequest"}},"/api/seller/v1/orders":{"get":{"summary":"Get order aggregate","description":"Reconcile key pulls and active pre-order reservations by **orderReference** (your store order id) or **orderReadableId** (`ord_…` from create-order responses). Provide exactly one. Requires scope `seller:products:read`. Does not return key plaintext.\n\n**Listing mode:** when neither `orderReference` nor `orderReadableId` is given, the endpoint lists the seller's order tuples keyset-paginated over `(fulfilledAt, orderReference)` — `?from&to&status&cursor&limit`. Built for full-ledger reconciliation and disaster recovery: after a total store-DB loss, page from your launch date to now and rebuild the complete ledger. Responses never include key plaintext.","parameters":[{"name":"orderReference","in":"query","required":false,"schema":{"type":"string","minLength":1,"maxLength":512},"description":"Your store order id (same value passed when creating the order). Mutually exclusive with orderReadableId."},{"name":"orderReadableId","in":"query","required":false,"schema":{"type":"string","minLength":1,"maxLength":128},"description":"Avrix readable order id from POST /orders or POST /keys/pull (`ord_…`). Mutually exclusive with orderReference."},{"name":"filters","in":"query","required":false,"schema":{"type":"string"},"description":"Optional JSON array filter DSL `[{ \"field\", \"op\", \"value\" }, …]` augmenting named params; unknown fields → **422**. Whitelist is route-specific."},{"name":"from","in":"query","required":false,"schema":{"type":"string","format":"date-time"},"description":"Listing mode: inclusive lower bound on `fulfilledAt` (ISO-8601). Used only when neither `orderReference` nor `orderReadableId` is given."},{"name":"to","in":"query","required":false,"schema":{"type":"string","format":"date-time"},"description":"Listing mode: inclusive upper bound on `fulfilledAt` (ISO-8601)."},{"name":"status","in":"query","required":false,"schema":{"type":"string","enum":["preordered","awaiting_release","awaiting_stock","ready","partially_fulfilled","fulfilled","cancelled","returned","refunded","failed"]},"description":"Listing mode: filter by derived order status. Applied per page after derivation — a filtered page can carry fewer than `limit` items while more pages remain."},{"name":"cursor","in":"query","required":false,"schema":{"type":"string"},"description":"Listing mode: opaque keyset cursor from `meta.nextCursor` of the previous page."},{"name":"limit","in":"query","required":false,"schema":{"type":"integer","minimum":1,"maximum":100,"default":50},"description":"Listing mode: page size (1–100, default 50)."}],"responses":{"200":{"description":"Order aggregate for the given orderReference or orderReadableId (fulfilled pulls + active pre-orders). No plaintext keys.","content":{"application/json":{"schema":{"oneOf":[{"type":"object","required":["data"],"properties":{"data":{"$ref":"#/components/schemas/SellerOrderAggregate"}},"description":"Lookup mode (orderReference / orderReadableId given)."},{"$ref":"#/components/schemas/SellerOrderListPage"}]},"example":{"data":{"orderReference":"store-order-10432","fulfilled":[{"skuCode":"SANDBOX-ALWAYS-001","allocationId":"00000000-0000-4000-8000-000000000001","fulfilledQuantity":1,"firstKeyPullId":"00000000-0000-4000-8000-0000000000aa","orderReadableId":"ord_abc12345"}],"preOrderActive":[]}}}}},"401":{"$ref":"#/components/responses/SellerApiUnauthorized"},"403":{"$ref":"#/components/responses/SellerApiForbidden"},"404":{"description":"No pulls or active reservations for this orderReference or orderReadableId","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"422":{"description":"Missing, conflicting, or invalid query parameters (provide exactly one of orderReference, orderReadableId; max lengths enforced)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"429":{"$ref":"#/components/responses/SellerApiRateLimited"},"500":{"$ref":"#/components/responses/SellerApiInternalError"}},"x-avrix-scopes":["seller:products:read"],"x-avrix-tier":"orders","tags":["Orders"],"operationId":"listOrders"},"post":{"summary":"Create order","description":"Create order and pull keys (or reserve for pre-order). Provide **skuId or skuCode** with **quantity** as a JSON **integer** (1–1000). **Scopes:** `seller:keys:pull`. Use **Idempotency-Key** header for retries; replays require the **same canonical JSON body** (sorted keys, SHA-256 — see https://docs.avrix.io/seller-api/integration-recipes); mismatch returns **409** `IDEMPOTENCY_KEY_MISMATCH` with **`details.requestBodyHash`**. API catalog orders require **integrationOrderContext** with `salesTaxRatePercent`, `salesPriceGrossMinor`, and `salesCountryCode` (422 `TAX_DECLARATION_REQUIRED` / `SALES_COUNTRY_REQUIRED` if omitted). Other context fields are declared retail evidence and do not replace wholesale settlement. Optional **metadata** — see https://docs.avrix.io/seller-api/integration-recipes. **Pre-order**: If the product has a future release date, keys are reserved (not delivered) and the response `type` is `pre-order`. When the deployment requires integration order context, responses include **`X-Seller-Api-Strict-Integration-Context: true`**.\n\n**Route error codes** (prefix hints for monitoring; canonical `code` unchanged):\n\n| Prefix | Typical `code` values |\n|---|---|\n| ORD_* | `VALIDATION_FAILED`, `INSUFFICIENT_INVENTORY`, `CONFLICT`, `IDEMPOTENCY_KEY_MISMATCH`, `KYB_NOT_VERIFIED`, `TREASURY_CAPABILITY_MISSING`, preorder / fulfilment denials |\n| CAT_* | Visibility / BMA denials, unknown SKU or product for company |\n| KEY_* | `NO_AVAILABLE_KEYS` when immediate fulfilment cannot allocate |\n| | AUTH_* | `UNAUTHORIZED`, `FORBIDDEN`, `KEY_ENVIRONMENT_MISMATCH`, `IP_NOT_ALLOWED`, `IP_NOT_RESOLVABLE` |\n| RATE_* | `RATE_LIMIT_EXCEEDED` |\n\nSee `https://docs.avrix.io/seller-api/errors`.\n\n**Commercial enforcement (API allocations, production keys):** Territory allowlists, catalog list-price parity (`expectedUnitPriceCents` from preview), and buyer IP geo cross-check. Error codes: CATALOG_PRICE_NOT_SET, CATALOG_PRICE_MISMATCH, INVALID_CATALOG_PRICE, TERRITORY_NOT_ALLOWED_FOR_SKU, TERRITORY_EXCLUDED_FOR_RELEASE, SKU_REGION_UNRESOLVED, CONSUMER_IP_REQUIRED, CONSUMER_IP_INVALID, CONSUMER_GEO_MISMATCH, CONSUMER_IP_HIGH_RISK, CONSUMER_GEO_UNAVAILABLE, SALES_COUNTRY_REQUIRED, TAX_DECLARATION_REQUIRED. See `https://docs.avrix.io/seller-api/territory` and `https://docs.avrix.io/seller-api/store-profiles`.\n\n**Pre-orders (capability `preorder`):** purchasing `launchPhase: pre_order` products requires `whoami.capabilities.preorderEnabled: true` (default **false**). Without the capability, pre-order-phase SKUs fail with **`PRODUCT_NOT_SELLABLE`** (`recoverable: false`) — check the capability up front instead of retrying.","parameters":[{"name":"Idempotency-Key","in":"header","required":true,"schema":{"type":"string"},"description":"Same key returns the cached successful response within 24h when the request body matches (SHA-256 of canonical JSON). Failed (4xx/5xx) responses are never cached: retrying the same key after fixing the cause re-executes against live state."}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["quantity","orderReference"],"properties":{"skuId":{"type":"string","format":"uuid","description":"SKU UUID. Provide `skuId` or `skuCode`."},"skuCode":{"type":"string","description":"Human-readable SKU code. Provide `skuId` or `skuCode`."},"quantity":{"type":"integer","minimum":1,"maximum":1000,"description":"Units to fulfil (integer 1–1000)."},"orderReference":{"type":"string","minLength":1,"maxLength":255,"description":"Required. Your store order ID for correlation, and the key the platform uses to detect duplicate orders and scope replay."},"customerReference":{"type":"string","maxLength":255,"description":"End customer reference (e.g. customer email or ID)"},"metadata":{"type":"object","description":"Opaque string-keyed metadata (not validated). Examples: lineItemId, channel, cartId — see https://docs.avrix.io/seller-api/integration-recipes"},"integrationOrderContext":{"$ref":"#/components/schemas/IntegrationOrderContext"},"countryCode":{"type":"string","minLength":2,"maxLength":2,"description":"ISO 3166-1 alpha-2 sales territory. Promoted into integrationOrderContext.salesCountryCode when that field is omitted (same semantics as POST /orders/preview and POST /orders/reserve). `country` is accepted as a request alias of this field (the availability spelling); sending both with different values fails with 422 VALIDATION_FAILED."},"checkoutHoldId":{"type":"string","format":"uuid","description":"Optional hold from POST /orders/hold (must match sku, quantity, orderReference)"},"expectedUnitPriceCents":{"type":"integer","minimum":1,"description":"Required for API allocations on production keys. Must exactly match unitPriceCents from POST /orders/preview for the same SKU, quantity, countryCode, and integrationOrderContext."},"deliveryMode":{"type":"string","enum":["key","keyless"],"default":"key","description":"Defaults to key (plaintext codes). The keyless value is not generally available; when disabled the API returns 403 FEATURE_DISABLED."},"keylessProvider":{"type":"string","enum":["hosted_redemption","steam_gift","epic_entitlement","gog_connect"],"description":"Optional explicit keyless provider; auto-selected by platform when omitted."},"expectedWholesaleUnitPriceCents":{"type":"integer","minimum":1,"description":"Deprecated alias of expectedUnitPriceCents (removal planned for v2). When both are sent they must be equal. Preferred alias for wholesale/RS allocation price echo (minor units). Same semantics as expectedUnitPriceCents for wholesale commits. When both are sent they must match.","deprecated":true},"priceCommitmentToken":{"type":"string","minLength":16,"maxLength":2048,"description":"Short-lived price commitment from POST /orders/preview (when price-commitment binding is enabled on the deployment). Binds unitPriceCents across PSP charge → order. Prefer this or checkoutHoldId over re-reading live catalog."},"backorderOnUnavailable":{"type":"boolean","description":"When true, request a durable customer-order backorder if immediate fulfilment cannot allocate. Rejected with 403 FEATURE_DISABLED unless GET /whoami capabilities.backorderEnabled is true. When that capability is on, the vendor grant must allow request_mode_backorder or the API returns 403 BACKORDER_NOT_ALLOWED. Accepted orders are awaiting_stock until order.ready, then POST /orders/{orderId}/fulfill.","x-avrix-capability":"backorder"},"immediateFulfilment":{"type":"boolean","description":"When false, keys are provisioned but plaintext omitted from HTTP response (deferredReveal)."},"consumerGeoAttestId":{"type":"string","format":"uuid","description":"Optional checkout-page buyer network confirmation from POST /geo/attest. Required when GET /allocations.consumerGeoAttestRequired is true for that publisher. The attested IP must not equal the API caller or the key allowlist."}},"anyOf":[{"required":["skuId"]},{"required":["skuCode"]}]},"example":{"skuCode":"SANDBOX-ALWAYS-001","quantity":1,"orderReference":"store-order-10432","countryCode":"NL","expectedUnitPriceCents":5999,"integrationOrderContext":{"schemaVersion":1,"salesCountryCode":"NL","currencyCode":"EUR","salesPriceGrossMinor":5999,"salesPriceNetMinor":4958,"priceIncludesTax":true,"salesTaxAmountMinor":1041,"salesTaxRatePercent":21,"consumerIp":"8.8.8.8","paymentMethodFamily":"card","paymentProcessorReference":"psp_txn_10432","checkoutSessionId":"cs_store_10432","salesChannel":"web"}}}}},"responses":{"200":{"description":"Order created (fulfilled or pre-order). **Discriminate on `data.type`.**","content":{"application/json":{"schema":{"type":"object","required":["data"],"properties":{"data":{"discriminator":{"propertyName":"type","mapping":{"fulfilled":"#/components/schemas/SellerOrderFulfilledData","pre-order":"#/components/schemas/SellerOrderPreorderData"}},"oneOf":[{"$ref":"#/components/schemas/SellerOrderFulfilledData"},{"$ref":"#/components/schemas/SellerOrderPreorderData"}],"properties":{"warnings":{"type":"array","items":{"type":"string"},"description":"What the settlement noticed but did not refuse over: a declared tax rate that disagreed with your own amounts, or a consumer country whose evidence was weaker than the platform's bar. Additive, and never a reason for a non-200: the sale happened and the key was delivered."}}},"contractTermId":{"type":"string","format":"uuid","description":"Active BMA term id from the atomic pull (response root; see SellerContractTermStamp)"},"contractTermVersion":{"type":"integer","minimum":1,"description":"BMA term version at pull time"}}},"examples":{"fulfilled":{"summary":"Fulfilled (key-based)","value":{"data":{"type":"fulfilled","skuId":"00000000-0000-4000-8000-000000000002","skuCode":"SANDBOX-ALWAYS-001","orderReference":"store-order-10432","keys":["XXXXX-XXXXX-XXXXX-XXXXX"],"keyIds":["00000000-0000-4000-8000-0000000000bb"],"pulled":1,"allocationId":"00000000-0000-4000-8000-000000000001","orderReadableId":"ord_abc12345","fulfilledAt":"2026-08-07T12:00:00.000Z"},"contractTermId":"00000000-0000-4000-8000-000000000099","contractTermVersion":1}},"fulfilledKeyless":{"summary":"Fulfilled (keyless)","value":{"data":{"type":"fulfilled","deliveryMode":"keyless","skuId":"00000000-0000-0000-0000-000000000002","pulled":1,"allocationId":"00000000-0000-0000-0000-000000000001","delivery":{"provider":"hosted_redemption","redemptionUrl":"https://app.avrix.io/redeem/v1.example","fulfillmentId":"00000000-0000-0000-0000-000000000003","expiresAt":"2026-07-25T12:00:00.000Z"},"orderReference":"store-order-123"}}}},"example":{"data":{"type":"fulfilled","skuId":"00000000-0000-4000-8000-000000000002","skuCode":"SANDBOX-ALWAYS-001","orderReference":"store-order-10432","keys":["XXXXX-XXXXX-XXXXX-XXXXX"],"keyIds":["00000000-0000-4000-8000-0000000000bb"],"pulled":1,"allocationId":"00000000-0000-4000-8000-000000000001","orderReadableId":"ord_abc12345","fulfilledAt":"2026-08-07T12:00:00.000Z"},"contractTermId":"00000000-0000-4000-8000-000000000099","contractTermVersion":1}}}},"400":{"description":"Default client error (`BAD_REQUEST` and other codes mapped to 400)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"401":{"$ref":"#/components/responses/SellerApiUnauthorized"},"402":{"description":"Payment not cleared (`PAYMENT_NOT_CLEARED`)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"403":{"description":"Insufficient API scope, client IP not in key allowlist, inactive contract/share, or seller account readiness (`CONTRACT_NOT_ACTIVE`, `KYB_NOT_VERIFIED`, `TREASURY_CAPABILITY_MISSING`)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"404":{"description":"SKU not found in allocations (`NOT_FOUND`)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"409":{"description":"Insufficient vendor stock (`NO_AVAILABLE_KEYS`), allocation cap reached (`ALLOCATION_EXCEEDED`, with `details.remainingInAllocation`), idempotency body mismatch (`IDEMPOTENCY_KEY_MISMATCH`), or partial duplicate `orderReference` (`ORDER_REFERENCE_CONFLICT`). For idempotency mismatch, **`details.requestBodyHash`** is the SHA-256 (hex) of the **current** request body after canonical key sorting. A fully fulfilled `orderReference` on the same allocation replays the original keys instead of returning 409.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"examples":{"noAvailableKeys":{"summary":"Stock exhausted after payment (refund at PSP)","value":{"code":"NO_AVAILABLE_KEYS","message":"No keys available for this allocation","details":{"recommendedAction":"refund_customer","skuCode":"SKU-EXAMPLE","quantity":1}}},"idempotencyMismatch":{"summary":"Same Idempotency-Key, different JSON body","value":{"code":"IDEMPOTENCY_KEY_MISMATCH","message":"Request body does not match the stored idempotency record","details":{"recommendedAction":"fix_request_body_or_new_key","requestBodyHash":"a1b2c3d4e5f6789012345678901234567890abcdef1234567890abcdef123456"}}},"orderReferenceConflict":{"summary":"Partial prior fulfillment under the same orderReference","value":{"code":"ORDER_REFERENCE_CONFLICT","message":"orderReference already fulfilled 1 key(s); requested 3. Use a new orderReference for a new sale.","details":{"recommendedAction":"fix_request_body_or_new_key","pullError":"ORDER_REFERENCE_CONFLICT"}}},"CATALOG_PRICE_MISMATCH":{"value":{"code":"CATALOG_PRICE_MISMATCH","message":"expectedUnitPriceCents does not match catalog list price","error":"expectedUnitPriceCents does not match catalog list price","timestamp":"2026-05-26T12:00:00.000Z","recoverable":true,"hint":"Re-run POST /orders/preview and align country, price, and consumerIp before POST /orders","requestId":"req_commercial_enforcement_example","details":{"pullError":"CATALOG_PRICE_MISMATCH","expectedUnitPriceCents":1999}}},"NO_AVAILABLE_KEYS":{"summary":"NO_AVAILABLE_KEYS","value":{"code":"NO_AVAILABLE_KEYS","message":"No available keys in inventory","error":"No available keys in inventory","timestamp":"2026-07-20T12:00:00.000Z","recoverable":true,"hint":"See https://docs.avrix.io/seller-api/errors","requestId":"req_p1_details_example","details":{"pullError":"NO_AVAILABLE_KEYS","allocationId":"00000000-0000-4000-8000-000000000001","skuId":"00000000-0000-4000-8000-000000000002"}}},"ALLOCATION_EXCEEDED":{"summary":"Allocation cap reached (request more headroom)","value":{"code":"ALLOCATION_EXCEEDED","message":"Only 7 keys remaining in allocation","error":"Only 7 keys remaining in allocation","timestamp":"2026-07-20T12:00:00.000Z","recoverable":false,"hint":"Your allocation cap is reached (details.remainingInAllocation shows headroom) — request a larger allocation from the publisher","doc_url":"https://docs.avrix.io/seller-api/errors#allocation-exceeded","requestId":"req_p1_details_example","details":{"pullError":"ALLOCATION_EXCEEDED","recommendedAction":"request_allocation_increase","remainingInAllocation":7,"allocationId":"00000000-0000-4000-8000-000000000001","skuId":"00000000-0000-4000-8000-000000000002"}}}}}}},"422":{"description":"Validation failed or minimum order (`MINIMUM_ORDER_VIOLATION` / `VALIDATION_FAILED`)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"examples":{"CONSUMER_GEO_MISMATCH":{"value":{"code":"CONSUMER_GEO_MISMATCH","message":"IP country does not match salesCountryCode","error":"IP country does not match salesCountryCode","timestamp":"2026-05-26T12:00:00.000Z","recoverable":true,"hint":"Re-run POST /orders/preview and align country, price, and consumerIp before POST /orders","requestId":"req_commercial_enforcement_example","details":{"pullError":"CONSUMER_GEO_MISMATCH","salesCountryCode":"US","consumerIpCountry":"DE"}}}}}}},"429":{"description":"Rate limit exceeded","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"500":{"$ref":"#/components/responses/SellerApiInternalError"},"503":{"description":"Pre-order state unavailable (`PREORDER_STATE_UNAVAILABLE`)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"examples":{"CONSUMER_GEO_UNAVAILABLE":{"value":{"code":"CONSUMER_GEO_UNAVAILABLE","message":"Consumer geo data is temporarily unavailable","error":"Consumer geo data is temporarily unavailable","timestamp":"2026-05-26T12:00:00.000Z","recoverable":true,"hint":"Re-run POST /orders/preview and align country, price, and consumerIp before POST /orders","requestId":"req_commercial_enforcement_example","details":{"pullError":"CONSUMER_GEO_UNAVAILABLE","retriable":true}}}}}}}},"x-avrix-scopes":["seller:keys:pull"],"x-avrix-tier":"orders","x-avrix-store-profile":"checkout-write","tags":["Orders"],"operationId":"createOrder","x-codeSamples":[{"lang":"curl","label":"Create order","source":"curl -s -X POST \"https://api.avrix.io/api/seller/v1/orders\" \\\n  -H \"Authorization: Bearer avrix_sk_sbx_your_key_here\" \\\n  -H \"Content-Type: application/json\" \\\n  -H \"Idempotency-Key: ik_store_10432\" \\\n  -d '{\"skuCode\":\"SANDBOX-ALWAYS-001\",\"quantity\":1,\"orderReference\":\"store-order-10432\",\"countryCode\":\"NL\",\"expectedUnitPriceCents\":5999,\"integrationOrderContext\":{\"schemaVersion\":1,\"salesCountryCode\":\"NL\",\"currencyCode\":\"EUR\",\"salesPriceGrossMinor\":5999,\"salesPriceNetMinor\":4958,\"priceIncludesTax\":true,\"salesTaxAmountMinor\":1041,\"salesTaxRatePercent\":21,\"consumerIp\":\"8.8.8.8\",\"paymentMethodFamily\":\"card\",\"paymentProcessorReference\":\"psp_txn_10432\",\"checkoutSessionId\":\"cs_store_10432\"}}'"}]}},"/api/seller/v1/orders/reserve":{"post":{"summary":"Reserve hot-drop inventory (short-TTL hold)","description":"Reserve `quantity` slots against a **hot-drop** allocation without yet consuming any keys. Intended for high-contention launches where stores need to lock availability for a buyer in-flight and then finalise the purchase with `POST /orders/commit` before the reservation expires.\n\nThe reservation expires after a short TTL (a handful of seconds). If the client does not call `/orders/commit` in time, the slot is released automatically and becomes available to other buyers.\n\nSpecify the allocation by `allocationId` or resolve it from `skuId` / `skuCode`. The route is a **no-op for allocations that are not in hot-drop mode** — in that case use `POST /orders` instead; this endpoint returns **412 HOT_DROP_NOT_ENABLED** so clients can fall back automatically. Counts against the **`orders` rate-limit class**.\n\n**Route error codes** (prefix hints for monitoring; canonical `code` unchanged):\n\n| Prefix | Typical `code` values |\n|---|---|\n| ORD_* | `VALIDATION_FAILED`, reservation conflicts, TTL / capacity denials (`reserveError` details) |\n| CAT_* | `HOT_DROP_UNAVAILABLE`, not eligible SKU |\n| | AUTH_* | `UNAUTHORIZED`, `FORBIDDEN`, `KEY_ENVIRONMENT_MISMATCH`, `IP_NOT_ALLOWED`, `IP_NOT_RESOLVABLE` |\n| RATE_* | `RATE_LIMIT_EXCEEDED` |\n\nSee `https://docs.avrix.io/seller-api/errors`.\n\n**Commercial enforcement (API allocations, production keys):** Territory allowlists, catalog list-price parity (`expectedUnitPriceCents` from preview), and buyer IP validation. Geo/VPN cross-check runs when `whoami.capabilities.consumerGeoEnforcementEnabled` is true. Error codes: CATALOG_PRICE_NOT_SET, CATALOG_PRICE_MISMATCH, INVALID_CATALOG_PRICE, TERRITORY_NOT_ALLOWED_FOR_SKU, TERRITORY_EXCLUDED_FOR_RELEASE, SKU_REGION_UNRESOLVED, CONSUMER_IP_REQUIRED, CONSUMER_IP_INVALID, CONSUMER_GEO_MISMATCH, CONSUMER_IP_HIGH_RISK, CONSUMER_GEO_UNAVAILABLE, SALES_COUNTRY_REQUIRED, TAX_DECLARATION_REQUIRED. See `https://docs.avrix.io/seller-api/territory` and `https://docs.avrix.io/seller-api/creating-orders`.","parameters":[{"name":"Idempotency-Key","in":"header","required":true,"schema":{"type":"string"},"description":"Required for safe retries; same key returns the cached successful response when the request body matches (failed responses are never cached)"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["quantity"],"properties":{"skuId":{"type":"string","format":"uuid"},"skuCode":{"type":"string","minLength":1},"allocationId":{"type":"string","format":"uuid"},"quantity":{"type":"integer","minimum":1,"maximum":1000},"orderReference":{"type":["string","null"],"maxLength":255,"description":"Your order/cart identifier. Echoed back on `/orders/commit`."},"customerReference":{"type":["string","null"],"maxLength":255,"description":"Opaque buyer identifier for your records."},"countryCode":{"type":"string","minLength":2,"maxLength":2,"description":"ISO 3166-1 alpha-2 sales territory. Required for API allocations (catalog list price resolution). `country` is accepted as a request alias of this field (the availability spelling); sending both with different values fails with 422 VALIDATION_FAILED."}},"description":"Provide either `allocationId`, `skuId`, or `skuCode`."},"example":{"skuCode":"SANDBOX-ALWAYS-001","quantity":1,"orderReference":"store-order-10432","countryCode":"US"}}}},"responses":{"200":{"description":"Reservation created; call `POST /orders/commit` with `reservationId` before `expiresAt`.","content":{"application/json":{"schema":{"type":"object","required":["data"],"properties":{"data":{"type":"object","required":["type","reservationId","allocationId","quantity","expiresAt","expiresInSeconds","remainingSlots"],"properties":{"type":{"type":"string","enum":["reservation"]},"reservationId":{"type":"string","format":"uuid"},"allocationId":{"type":"string","format":"uuid"},"quantity":{"type":"integer","minimum":1},"expiresAt":{"type":"string","format":"date-time"},"expiresInSeconds":{"type":"integer","description":"TTL from `HOT_DROP_RESERVATION_TTL_SECONDS`."},"remainingSlots":{"type":"integer","description":"Approximate remaining hot-drop slots after this reservation."},"orderReference":{"type":["string","null"]}}}}}}}},"400":{"description":"Request missing `skuId`/`skuCode`/`allocationId`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"401":{"$ref":"#/components/responses/SellerApiUnauthorized"},"403":{"$ref":"#/components/responses/SellerApiForbidden"},"404":{"description":"SKU or active allocation not found for this seller.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"409":{"description":"`SOLD_OUT` — no remaining hot-drop slots.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"examples":{"SOLD_OUT":{"summary":"SOLD_OUT","value":{"code":"SOLD_OUT","message":"Hot-drop reservation sold out","error":"Hot-drop reservation sold out","timestamp":"2026-07-20T12:00:00.000Z","recoverable":true,"hint":"See https://docs.avrix.io/seller-api/errors","requestId":"req_p1_details_example","details":{"hotDropError":"SOLD_OUT","remaining":0}}}}}}},"412":{"description":"`HOT_DROP_NOT_ENABLED` — allocation is not in hot-drop mode; use `POST /orders` instead.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"422":{"description":"Validation failed (malformed body or invalid `quantity`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"429":{"$ref":"#/components/responses/SellerApiRateLimited"},"500":{"$ref":"#/components/responses/SellerApiInternalError"},"503":{"description":"`STORE_UNAVAILABLE` — reservation store temporarily unavailable. Retry after `Retry-After` seconds.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}},"x-avrix-scopes":["seller:keys:pull"],"x-avrix-tier":"orders","tags":["Orders"],"operationId":"reserveOrder"}},"/api/seller/v1/orders/commit":{"post":{"summary":"Commit a hot-drop reservation","description":"Finalise a reservation previously returned by `POST /orders/reserve`. Runs the full contract chain (gating, pricing, pre-order flags) and either returns real keys (`fulfillmentType: fulfilled`) or records the pre-order (`fulfillmentType: pre-order`). On any downstream failure the reservation is **released** back into the available pool automatically.\n\nThe reservation is bounded by the TTL returned from `/orders/reserve`. Commits for expired reservations fail with **410 RESERVATION_GONE** — in that case the client should re-reserve. Counts against the **`orders` rate-limit class**.\n\n**Route error codes** (prefix hints for monitoring; canonical `code` unchanged):\n\n| Prefix | Typical `code` values |\n|---|---|\n| ORD_* | `VALIDATION_FAILED`, stale reservation, insufficient inventory at commit, `pullError` allocations |\n| CAT_* | Hot-drop / visibility denials |\n| KEY_* | Pull-path shortages surfaced with SKU/allocation hints |\n| | AUTH_* | `UNAUTHORIZED`, `FORBIDDEN`, `KEY_ENVIRONMENT_MISMATCH`, `IP_NOT_ALLOWED`, `IP_NOT_RESOLVABLE` |\n| RATE_* | `RATE_LIMIT_EXCEEDED` |\n\nSee `https://docs.avrix.io/seller-api/errors`.","parameters":[{"name":"Idempotency-Key","in":"header","required":true,"schema":{"type":"string"},"description":"Required for safe retries; same key returns the cached successful response when the request body matches (failed responses are never cached)"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["reservationId"],"properties":{"reservationId":{"type":"string","format":"uuid","description":"The `reservationId` returned by `POST /orders/reserve`."},"metadata":{"type":"object","additionalProperties":true,"description":"Free-form metadata persisted on the order (same shape as `POST /orders`)."},"integrationOrderContext":{"type":"object","additionalProperties":true,"description":"Optional integration order context (e.g. upstream cart / tax receipt). Subject to size limits and optional strict profile validation per key."},"consumerGeoAttestId":{"type":"string","format":"uuid","description":"Optional checkout-page buyer network confirmation from POST /geo/attest. Required when GET /allocations.consumerGeoAttestRequired is true for that publisher. The attested IP must not equal the API caller or the key allowlist."}}},"example":{"reservationId":"rsv_01EXAMPLE","orderReference":"store-order-10432","expectedUnitPriceCents":999}}}},"responses":{"200":{"description":"Reservation committed. Shape depends on `type`: `fulfilled` returns real keys, `pre-order` returns reserved counts with release window.","content":{"application/json":{"schema":{"type":"object","required":["data"],"properties":{"data":{"oneOf":[{"type":"object","required":["type","allocationId","keys","pulled"],"properties":{"type":{"type":"string","enum":["fulfilled"]},"allocationId":{"type":"string","format":"uuid"},"orderReference":{"type":["string","null"]},"keys":{"type":"array","items":{"type":"string"}},"keyIds":{"type":"array","items":{"type":"string","format":"uuid"},"description":"Key UUIDs (not plaintext), one per delivered key, same order as `keys` — pass them to POST /refunds or POST /keys/return. Parity with POST /orders."},"pulled":{"type":"integer","minimum":0},"fulfilledAt":{"type":"string","format":"date-time"},"orderReadableId":{"type":"string","description":"Short human-readable order ID (e.g. `ord_...`)."}}},{"type":"object","required":["type","allocationId","reserved"],"properties":{"type":{"type":"string","enum":["pre-order"]},"allocationId":{"type":"string","format":"uuid"},"orderReference":{"type":["string","null"]},"reserved":{"type":"integer","minimum":0},"releaseDate":{"type":["string","null"],"format":"date-time"},"preorderStart":{"type":["string","null"],"format":"date-time"},"preorderEnd":{"type":["string","null"],"format":"date-time"}},"x-avrix-capability":"preorder"}]},"contractTermId":{"type":"string","format":"uuid","description":"Active BMA term id from the atomic pull (response root; see SellerContractTermStamp)"},"contractTermVersion":{"type":"integer","minimum":1,"description":"BMA term version at pull time"}}}}}},"401":{"$ref":"#/components/responses/SellerApiUnauthorized"},"403":{"$ref":"#/components/responses/SellerApiForbidden"},"409":{"description":"`ALLOCATION_NOT_AVAILABLE` — the underlying allocation is no longer active or no longer in hot-drop mode. The reservation is released.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"410":{"description":"`RESERVATION_GONE` — reservation not found or TTL expired. Call `POST /orders/reserve` again.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"422":{"description":"Validation failed (malformed body or `integrationOrderContext`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"429":{"$ref":"#/components/responses/SellerApiRateLimited"},"500":{"$ref":"#/components/responses/SellerApiInternalError"}},"x-avrix-scopes":["seller:keys:pull"],"x-avrix-tier":"orders","tags":["Orders"],"operationId":"commitOrder"}},"/api/seller/v1/orders/preview":{"post":{"summary":"Preview order (price + fulfillment estimate)","description":"**Scopes:** `seller:orders:preview` or `seller:keys:pull`. Non-binding estimate; debits the **`orders`** rate-limit class.\n\nRead-only preview of what `POST /orders` would do. Returns the wholesale unit price from the seller's allocation, the per-line and total cost, and the expected fulfillment type (`fulfilled` for ready-to-deliver keys or `pre-order` for unreleased SKUs). Does **not** acquire any inventory locks, does **not** record a transaction, and does **not** charge against pre-order capacity. Stores call this from their checkout summary to display the final cost to the buyer; the binding price is the one that comes back from `POST /orders`. Counts against the **`orders` rate-limit class**.\n\n**Route error codes** (prefix hints for monitoring; canonical `code` unchanged):\n\n| Prefix | Typical `code` values |\n|---|---|\n| ORD_* | `VALIDATION_FAILED`, estimate denied, pricing headroom errors surfaced as `previewError` details |\n| CAT_* | Product/SKU not visible under BMA |\n| | AUTH_* | `UNAUTHORIZED`, `FORBIDDEN`, `KEY_ENVIRONMENT_MISMATCH`, `IP_NOT_ALLOWED`, `IP_NOT_RESOLVABLE` |\n| RATE_* | `RATE_LIMIT_EXCEEDED` |\n\nSee `https://docs.avrix.io/seller-api/errors`.\n\n**Commercial enforcement (API allocations, production keys):** Territory allowlists, catalog list-price parity (`expectedUnitPriceCents` from preview), and buyer IP geo cross-check. Error codes: CATALOG_PRICE_NOT_SET, CATALOG_PRICE_MISMATCH, INVALID_CATALOG_PRICE, TERRITORY_NOT_ALLOWED_FOR_SKU, TERRITORY_EXCLUDED_FOR_RELEASE, SKU_REGION_UNRESOLVED, CONSUMER_IP_REQUIRED, CONSUMER_IP_INVALID, CONSUMER_GEO_MISMATCH, CONSUMER_IP_HIGH_RISK, CONSUMER_GEO_UNAVAILABLE, SALES_COUNTRY_REQUIRED, TAX_DECLARATION_REQUIRED. See `https://docs.avrix.io/seller-api/territory` and `https://docs.avrix.io/seller-api/store-profiles`.\n\n**Pre-orders (capability `preorder`):** purchasing `launchPhase: pre_order` products requires `whoami.capabilities.preorderEnabled: true` (default **false**). Without the capability, pre-order-phase SKUs fail with **`PRODUCT_NOT_SELLABLE`** (`recoverable: false`) — check the capability up front instead of retrying.\n\n**Price binding:** every priced preview returns `priceCommitment: { token, expiresAt }` (hard TTL 15 minutes) — a capability-independent way to commit the previewed price on POST /orders. Production deployments fail closed at boot when price signing is unconfigured, so in production the field is always present on priced previews. In sandbox/local environments presence is signalled by `whoami.capabilities.priceCommitmentConfigured`; when `false` the field is omitted — send `expectedUnitPriceCents` on commit instead. Expired tokens fail with **`PRICE_COMMITMENT_EXPIRED`** (re-preview).","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["quantity"],"properties":{"skuId":{"type":"string","format":"uuid"},"skuCode":{"type":"string","minLength":1},"quantity":{"type":"integer","minimum":1,"maximum":1000},"countryCode":{"type":"string","minLength":2,"maxLength":2,"description":"ISO 3166-1 alpha-2 sales territory. Required for API allocations (catalog list price resolution). `country` is accepted as a request alias of this field (the availability spelling); sending both with different values fails with 422 VALIDATION_FAILED."},"integrationOrderContext":{"$ref":"#/components/schemas/IntegrationOrderContext"},"consumerIp":{"type":"string","description":"Optional buyer IPv4/IPv6 (same semantics as integrationOrderContext.consumerIp). When `whoami.capabilities.consumerGeoEnforcementEnabled` is true, buyer IP must match `salesCountryCode` and VPN/hosting/Tor are rejected (422). `CONSUMER_GEO_UNAVAILABLE` is 503 + Retry-After. During monitor (`consumerGeoMonitorEnabled`) the same checks emit additive `geoWarning` on 200 instead of blocking. Otherwise only IP shape is validated."},"orderReference":{"type":"string","minLength":1,"maxLength":255,"description":"Optional store order / cart reference for correlation with a later POST /orders (not required for preview)."},"consumerGeoAttestId":{"type":"string","format":"uuid","description":"Optional checkout-page buyer network confirmation from POST /geo/attest. Required when GET /allocations.consumerGeoAttestRequired is true for that publisher. The attested IP must not equal the API caller or the key allowlist."}},"description":"Provide either `skuId` or `skuCode`."},"example":{"skuCode":"SANDBOX-ALWAYS-001","quantity":1,"countryCode":"NL","integrationOrderContext":{"schemaVersion":1,"salesCountryCode":"NL","currencyCode":"EUR","salesPriceGrossMinor":7999,"priceIncludesTax":true,"salesTaxAmountMinor":1388,"salesTaxRatePercent":21,"salesChannel":"web"}}}}},"responses":{"200":{"description":"Preview successful","content":{"application/json":{"schema":{"type":"object","required":["data"],"properties":{"data":{"type":"object","required":["type","fulfillmentType","allocationId","allocationRemaining","inventoryAvailable","partialFulfillmentExpected","maxFulfillableQuantity","canFulfill","lines","estimateOnly"],"properties":{"type":{"type":"string","enum":["order_preview"]},"fulfillmentType":{"type":"string","enum":["fulfilled","pre-order"]},"allocationId":{"type":"string","format":"uuid"},"allocationRemaining":{"type":"integer"},"inventoryAvailable":{"type":"integer","description":"Keys fulfillable for this allocation: the publisher's shared available pool plus any stock the publisher has dedicated to your allocation."},"partialFulfillmentExpected":{"type":"boolean","deprecated":true,"description":"Deprecated alias of `cannotFullyFulfill` (kept for backward compatibility; removal planned for v2). True when immediate fulfillment cannot satisfy the requested quantity — POST /orders is all-or-nothing and returns 409 NO_AVAILABLE_KEYS with zero keys pulled. Despite the name it never means partial key delivery. Migrate to `cannotFullyFulfill` / `allOrNothingWillFail`."},"cannotFullyFulfill":{"type":"boolean","description":"True when immediate fulfillment cannot satisfy the requested quantity and all-or-nothing checkout will fail (expect 409 NO_AVAILABLE_KEYS, not partial keys). Disable Pay or reduce quantity. Same boolean as `allOrNothingWillFail`; supersedes the deprecated `partialFulfillmentExpected`."},"allOrNothingWillFail":{"type":"boolean","description":"True when POST /orders will fail all-or-nothing (409 NO_AVAILABLE_KEYS, zero keys) for this quantity. Same boolean as `cannotFullyFulfill`."},"maxFulfillableQuantity":{"type":"integer","description":"Maximum quantity fulfillable now (same as available for immediate fulfillment)"},"canFulfill":{"type":"boolean","description":"True when the requested quantity can be satisfied for the estimated fulfillmentType"},"lines":{"type":"array","items":{"type":"object","required":["skuId","skuCode","quantity"],"properties":{"skuId":{"type":"string","format":"uuid"},"skuCode":{"type":"string"},"quantity":{"type":"integer"},"unitPriceCents":{"type":["integer","null"],"description":"Effective unit price to echo as `expectedUnitPriceCents`. Already includes any settlement promo (see `promo`)."},"lineTotalCents":{"type":["integer","null"]},"currencyCode":{"type":["string","null"]},"initialUnitPriceCents":{"type":["integer","null"],"description":"Catalog list unit price before any settlement promo. Equal to `unitPriceCents` when no promo applies."},"promo":{"anyOf":[{"$ref":"#/components/schemas/SettlementPromoRef"},{"type":"null"}]},"promoResolution":{"type":"string","enum":["applied","none","unavailable"],"description":"`applied` = a settlement promo discounted the price; `none` = list price, no active settlement promo; `unavailable` = promotions could not be read at quote time, so the price is the list price and a promo may still exist (fail-open)."},"activation":{"$ref":"#/components/schemas/SkuActivation"}}}},"totalCents":{"type":["integer","null"]},"currencyCode":{"type":["string","null"]},"preorder":{"type":["object","null"],"properties":{"releaseDate":{"type":["string","null"],"format":"date-time"},"preorderStart":{"type":["string","null"],"format":"date-time"},"preorderEnd":{"type":["string","null"],"format":"date-time"},"preorderUnlocked":{"type":"boolean"}},"x-avrix-capability":"preorder"},"estimateOnly":{"type":"boolean","description":"Always `true`. Stores must re-call /orders/preview on every cart change rather than caching the price."},"priceCommitmentToken":{"type":["string","null"],"description":"Alias of `priceCommitment.token` (kept for compatibility). Short-lived HMAC token binding unitPriceCents. Pass on POST /orders as priceCommitmentToken. Always present on priced previews in production; in sandbox/local omitted when `whoami.capabilities.priceCommitmentConfigured` is `false`."},"priceCommitment":{"type":["object","null"],"description":"The capability-independent price-binding path. Always present on priced previews in production (deployments fail closed at boot without price signing); in sandbox/local environments presence is signalled by `whoami.capabilities.priceCommitmentConfigured` — when it is `false` the field is omitted and `expectedUnitPriceCents` on POST /orders is the fallback. Pass `token` on POST /orders as `priceCommitmentToken` to lock the previewed unitPriceCents until `expiresAt` (hard TTL: 15 minutes). Checkout holds remain the premium inventory + price lock.","properties":{"token":{"type":"string","description":"Short-lived HMAC price commitment (pct1.*)."},"expiresAt":{"type":"string","format":"date-time","description":"Hard expiry — a commit after this fails with PRICE_COMMITMENT_EXPIRED."}}},"warnings":{"type":"array","items":{"type":"string","enum":["REQUIRES_BASE_GAME","ACTIVATION_REGION_MISMATCH"]},"description":"Advisory warnings when activationPolicy is warn (the default). `REQUIRES_BASE_GAME` — the SKU's product is DLC/expansion and the buyer must own the base game (see relatedProducts on the product detail). Fulfilment is not blocked. `ACTIVATION_REGION_MISMATCH` — the request countryCode is outside the SKU's guaranteed activation set. When activationPolicy is enforce_known or enforce_strict this condition is a 422 instead of a warning. enforce_strict also returns 422 ACTIVATION_REGION_UNKNOWN when coverage is absent."},"settlement":{"type":"object","description":"What this sale would settle at if committed now. Computed by the same calculator the commit path uses, on the same inputs. Absent when the platform cannot yet say: no VAT rate on file for the country, or the agreement states no VAT basis.","properties":{"basis":{"type":["string","null"],"example":"purchaser_country_capped"},"grossMinor":{"type":"integer","example":5999},"currency":{"type":["string","null"],"example":"EUR"},"appliedRatePercent":{"type":["number","null"],"example":21},"rateReason":{"type":["string","null"],"example":"corroborated","description":"Why that rate applied. `fallback_store_country` means the declared consumer country was not corroborated, so the sale settles at your own registered country's rate."},"evidenceRank":{"type":["integer","null"],"example":2,"description":"1 checkout attestation, 2 consumer IP, 3 your declaration alone. Preview runs no IP lookup, so a committed sale may land at a better rank than the preview showed, never a worse one."},"vatMinor":{"type":["integer","null"],"example":1041},"netMinor":{"type":["integer","null"],"example":4958},"sellerShareMinor":{"type":["integer","null"],"example":null,"description":"Unknown until commit locks the governing share. Preview returns null."},"publisherShareMinor":{"type":["integer","null"],"example":null,"description":"Unknown until commit locks the governing share. Preview returns null."},"warnings":{"type":"array","items":{"type":"string"}}}}}}}},"example":{"data":{"type":"order_preview","fulfillmentType":"fulfilled","allocationId":"00000000-0000-4000-8000-000000000001","allocationRemaining":942,"inventoryAvailable":942,"partialFulfillmentExpected":false,"maxFulfillableQuantity":942,"canFulfill":true,"lines":[{"skuId":"00000000-0000-4000-8000-000000000002","skuCode":"SANDBOX-ALWAYS-001","quantity":1,"unitPriceCents":999,"lineTotalCents":999,"currencyCode":"USD"}],"totalCents":999,"currencyCode":"USD","currencyExponent":2,"estimateOnly":true}}}}},"401":{"$ref":"#/components/responses/SellerApiUnauthorized"},"403":{"$ref":"#/components/responses/SellerApiForbidden"},"404":{"description":"SKU unknown to the seller account, no active allocation row, or allocation row missing after resolution. Body is `ApiError`; use **`details.previewError`** to distinguish `SKU_NOT_FOUND` vs allocation-related codes (`ALLOCATION_NOT_FOUND`, `ALLOCATION_INACTIVE`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"422":{"description":"Zod schema validation on the body, or **`VALIDATION_FAILED`** from the preview service for domain rules (e.g. missing `skuId`/`skuCode`, bad `quantity`) with **`details.validationTarget`** `json_body` and **`details.issues`**.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"examples":{"TERRITORY_NOT_ALLOWED_FOR_SKU":{"value":{"code":"TERRITORY_NOT_ALLOWED_FOR_SKU","message":"Country not in SKU region pack","error":"Country not in SKU region pack","timestamp":"2026-05-26T12:00:00.000Z","recoverable":true,"hint":"Re-run POST /orders/preview and align country, price, and consumerIp before POST /orders","requestId":"req_commercial_enforcement_example","details":{"previewError":"TERRITORY_NOT_ALLOWED_FOR_SKU","salesCountryCode":"RU"}}},"CATALOG_PRICE_NOT_SET":{"summary":"CATALOG_PRICE_NOT_SET","value":{"code":"CATALOG_PRICE_NOT_SET","message":"No catalog list price for country","error":"No catalog list price for country","timestamp":"2026-07-20T12:00:00.000Z","recoverable":true,"hint":"See https://docs.avrix.io/seller-api/errors","requestId":"req_p1_details_example","details":{"previewError":"CATALOG_PRICE_NOT_SET","salesCountryCode":"US"}}}}}}},"429":{"$ref":"#/components/responses/SellerApiRateLimited"},"500":{"$ref":"#/components/responses/SellerApiInternalError"},"503":{"description":"Pre-order state lookup temporarily unavailable. Retry after `Retry-After` seconds. Body is `ApiError` with **`details.previewError`** = `PREORDER_STATE_UNAVAILABLE` when returned from the preview service.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}},"x-avrix-scopes":["seller:orders:preview","seller:keys:pull"],"x-avrix-tier":"orders","x-avrix-store-profile":"checkout-read","tags":["Orders"],"operationId":"previewOrder","x-codeSamples":[{"lang":"curl","label":"Preview order","source":"curl -s -X POST \"https://api.avrix.io/api/seller/v1/orders/preview\" \\\n  -H \"Authorization: Bearer avrix_sk_sbx_your_key_here\" \\\n  -H \"Content-Type: application/json\" \\\n  -d '{\"skuCode\":\"SANDBOX-ALWAYS-001\",\"quantity\":1,\"countryCode\":\"US\"}'"}]}},"/api/seller/v1/orders/hold":{"post":{"summary":"Create checkout soft-hold","description":"Optional short-lived checkout slot hold between preview and `POST /orders` (when enabled on the deployment — see `whoami.capabilities.checkoutHoldEnabled`). Authority remains `POST /orders`. Returns **412** `CHECKOUT_HOLD_DISABLED` when off. See `https://docs.avrix.io/seller-api/order-preview`.\n\n**Commercial enforcement (API allocations, production keys):** Territory allowlists, catalog list-price parity (`expectedUnitPriceCents` from preview), and buyer IP validation. Geo/VPN cross-check runs when `whoami.capabilities.consumerGeoEnforcementEnabled` is true. Error codes: CATALOG_PRICE_NOT_SET, CATALOG_PRICE_MISMATCH, INVALID_CATALOG_PRICE, TERRITORY_NOT_ALLOWED_FOR_SKU, TERRITORY_EXCLUDED_FOR_RELEASE, SKU_REGION_UNRESOLVED, CONSUMER_IP_REQUIRED, CONSUMER_IP_INVALID, CONSUMER_GEO_MISMATCH, CONSUMER_IP_HIGH_RISK, CONSUMER_GEO_UNAVAILABLE, SALES_COUNTRY_REQUIRED, TAX_DECLARATION_REQUIRED. See `https://docs.avrix.io/seller-api/territory` and `https://docs.avrix.io/seller-api/creating-orders`.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["quantity","orderReference"],"properties":{"skuId":{"type":"string","format":"uuid"},"skuCode":{"type":"string","minLength":1},"quantity":{"type":"integer","minimum":1,"maximum":1000},"orderReference":{"type":"string","maxLength":255},"customerReference":{"type":["string","null"],"maxLength":255},"countryCode":{"type":"string","minLength":2,"maxLength":2,"description":"ISO 3166-1 alpha-2 sales territory. Required for API allocations (catalog list price resolution). `country` is accepted as a request alias of this field (the availability spelling); sending both with different values fails with 422 VALIDATION_FAILED."},"expectedUnitPriceCents":{"type":"integer","minimum":1,"description":"Optional echo from POST /orders/preview; must match catalog list price when provided. Partner echo of preview unitPriceCents. Prefer expectedWholesaleUnitPriceCents for wholesale/RS."},"expectedWholesaleUnitPriceCents":{"type":"integer","minimum":1,"description":"Deprecated alias of expectedUnitPriceCents (removal planned for v2). When both are sent they must be equal. Preferred alias for wholesale/RS allocation price echo (minor units). Same semantics as expectedUnitPriceCents for wholesale commits. When both are sent they must match.","deprecated":true},"integrationOrderContext":{"$ref":"#/components/schemas/IntegrationOrderContext"},"consumerGeoAttestId":{"type":"string","format":"uuid","description":"Optional checkout-page buyer network confirmation from POST /geo/attest. Required when GET /allocations.consumerGeoAttestRequired is true for that publisher. The attested IP must not equal the API caller or the key allowlist."}},"description":"Provide either `skuId` or `skuCode`."},"example":{"skuCode":"SANDBOX-ALWAYS-001","quantity":1,"countryCode":"US","holdSeconds":300}}}},"responses":{"200":{"description":"Hold created","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","required":["type","holdId","expiresAt","expiresInSeconds","allocationId"],"properties":{"type":{"type":"string","enum":["checkout_hold"]},"holdId":{"type":"string","format":"uuid"},"expiresAt":{"type":"string","format":"date-time"},"expiresInSeconds":{"type":"integer"},"allocationId":{"type":"string","format":"uuid"},"maxFulfillableQuantity":{"type":"integer"},"unitPriceCents":{"type":"integer","description":"Bound effective unit price for API allocations (settlement promo already applied; honored on POST /orders while the hold is valid). Echo it as `expectedUnitPriceCents`."},"initialUnitPriceCents":{"type":"integer","description":"Catalog list unit price before any settlement promo. Equal to `unitPriceCents` when no promo applies."},"promo":{"anyOf":[{"$ref":"#/components/schemas/SettlementPromoRef"},{"type":"null"}]},"promoResolution":{"type":"string","enum":["applied","none","unavailable"],"description":"`applied` = a settlement promo discounted the price; `none` = list price, no active settlement promo; `unavailable` = promotions could not be read at quote time, so the price is the list price and a promo may still exist (fail-open)."},"currencyCode":{"type":["string","null"]},"salesCountryCode":{"type":["string","null"]},"priceBoundAt":{"type":["string","null"],"format":"date-time"}}}}}}}},"401":{"$ref":"#/components/responses/SellerApiUnauthorized"},"403":{"$ref":"#/components/responses/SellerApiForbidden"},"409":{"description":"Insufficient headroom for hold (`SOLD_OUT`)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"412":{"description":"Checkout hold disabled on deployment","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"422":{"description":"Validation failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"429":{"$ref":"#/components/responses/SellerApiRateLimited"},"500":{"$ref":"#/components/responses/SellerApiInternalError"},"503":{"description":"Hold service unavailable (`STORE_UNAVAILABLE`)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}},"x-avrix-scopes":["seller:keys:pull"],"x-avrix-tier":"orders","tags":["Orders"],"operationId":"holdOrder","parameters":[{"name":"Idempotency-Key","in":"header","required":true,"schema":{"type":"string","minLength":1,"maxLength":64,"pattern":"^[a-zA-Z0-9_-]+$"},"description":"Stable key for this logical mutation (1–64 chars, `[a-zA-Z0-9_-]`). Reuse the same key and canonical JSON body on retries. Mismatch returns 409 `IDEMPOTENCY_KEY_MISMATCH`."}]},"delete":{"summary":"Release checkout soft-hold","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["holdId"],"properties":{"holdId":{"type":"string","format":"uuid"}}},"example":{"holdId":"hold_01EXAMPLE"}}}},"responses":{"200":{"description":"Hold released (or already gone)"},"401":{"$ref":"#/components/responses/SellerApiUnauthorized"},"403":{"$ref":"#/components/responses/SellerApiForbidden"},"404":{"description":"Hold not found for this seller","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"422":{"description":"Validation failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"429":{"$ref":"#/components/responses/SellerApiRateLimited"},"500":{"$ref":"#/components/responses/SellerApiInternalError"}},"x-avrix-scopes":["seller:keys:pull"],"x-avrix-tier":"orders","tags":["Orders"],"operationId":"deleteHold","parameters":[{"name":"Idempotency-Key","in":"header","required":true,"schema":{"type":"string","minLength":1,"maxLength":64,"pattern":"^[a-zA-Z0-9_-]+$"},"description":"Stable key for this logical mutation (1–64 chars, `[a-zA-Z0-9_-]`). Reuse the same key and canonical JSON body on retries. Mismatch returns 409 `IDEMPOTENCY_KEY_MISMATCH`."}],"description":"Release a checkout hold early. Requires `Idempotency-Key`. Scope: `seller:keys:pull` (or orders write). Capability: `whoami.capabilities.checkoutHoldEnabled`."}},"/api/seller/v1/orders/recover-keys":{"post":{"summary":"Recover the keys already sold under an orderReference","description":"**Scope:** `seller:keys:pull` (or `seller:orders:write`). Debits the **`orders`** rate-limit class (sandbox keys only — production keys are not rate limited).\n\nRe-reads the keys that were already fulfilled for an `orderReference` — for the case where your store lost the `POST /orders` response (a crash between the pull and your own database write). Returns only keys that are still live for that reference (`revealed` / `assigned` / `redeemed`, the same filter the orderReference replay uses); returned or refunded keys are excluded. **Never pulls new inventory** and never creates a sale. Every call is audited as a key reveal.\n\nThis is the only read of key plaintext outside `POST /orders` / pull / export: `GET /orders` keeps never returning plaintext (certification case 16).\n\n**Route error codes:** `NOT_FOUND` (no live keys under the reference), `VALIDATION_FAILED`, `UNAUTHORIZED`, `FORBIDDEN`, `RATE_LIMIT_EXCEEDED`, `INTERNAL_ERROR`. See `https://docs.avrix.io/seller-api/errors`.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["orderReference"],"properties":{"orderReference":{"type":"string","maxLength":128,"description":"The order reference used when placing the order"}}},"example":{"orderReference":"store-order-10432"}}}},"responses":{"200":{"description":"Live keys for the reference","content":{"application/json":{"schema":{"type":"object","required":["data"],"properties":{"data":{"type":"object","required":["orderReference","recovered","keyIds","keys"],"properties":{"orderReference":{"type":"string"},"recovered":{"type":"integer","description":"Number of live keys returned"},"keyIds":{"type":"array","items":{"type":"string","format":"uuid"},"description":"Key UUIDs — the same ids `POST /orders` returned; use them for `POST /refunds` / `POST /keys/return`."},"keys":{"type":"array","items":{"type":"string"},"description":"Key plaintext, in the same order as `keyIds`."},"skuIds":{"type":"array","items":{"type":"string","format":"uuid"}}}}}},"example":{"data":{"orderReference":"store-order-10432","recovered":1,"keyIds":["00000000-0000-4000-8000-0000000000aa"],"keys":["AAAAA-BBBBB-CCCCC"],"skuIds":["00000000-0000-4000-8000-0000000000bb"]}}}}},"401":{"$ref":"#/components/responses/SellerApiUnauthorized"},"403":{"$ref":"#/components/responses/SellerApiForbidden"},"404":{"description":"No live keys under this reference","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"422":{"description":"Validation failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"429":{"$ref":"#/components/responses/SellerApiRateLimited"},"500":{"$ref":"#/components/responses/SellerApiInternalError"}},"tags":["Orders"],"x-avrix-scopes":["seller:keys:pull"],"x-avrix-tier":"keys","operationId":"recoverOrderKeys"}},"/api/seller/v1/orders/cancel":{"post":{"summary":"Cancel pre-order","description":"**Capability-gated (`preorder`):** pre-order cancellation applies only to accounts with `whoami.capabilities.preorderEnabled: true`. With the capability off (the default), pre-order-phase products are not transactable and there is nothing to cancel.\n\nCancel active pre-order reservations by orderReference. Keys are returned to available inventory. Use **Idempotency-Key** for safe retries (caches 200 and 404).\n\n**Route error codes** (prefix hints for monitoring; canonical `code` unchanged):\n\n| Prefix | Typical `code` values |\n|---|---|\n| ORD_* | `NOT_FOUND`, `CONFLICT` / invalid lifecycle transition |\n| CAT_* | Reservation/order kind mismatches |\n| | AUTH_* | `UNAUTHORIZED`, `FORBIDDEN`, `KEY_ENVIRONMENT_MISMATCH`, `IP_NOT_ALLOWED`, `IP_NOT_RESOLVABLE` |\n| RATE_* | `RATE_LIMIT_EXCEEDED` |\n\nSee `https://docs.avrix.io/seller-api/errors`.","parameters":[{"name":"Idempotency-Key","in":"header","required":true,"schema":{"type":"string"},"description":"Same key returns the cached successful response within 24h; failed responses are never cached"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["orderReference"],"properties":{"orderReference":{"type":"string","description":"The order reference used when placing the pre-order"},"reason":{"type":"string","maxLength":500,"description":"Optional cancellation reason"}}},"example":{"orderReference":"store-order-10432"}}}},"responses":{"200":{"description":"Reservations cancelled","content":{"application/json":{"schema":{"type":"object","required":["data"],"properties":{"data":{"type":"object","properties":{"orderReference":{"type":"string"},"cancelled":{"type":"integer","description":"Number of reservations cancelled"}},"required":["orderReference","cancelled"]}}}}}},"401":{"$ref":"#/components/responses/SellerApiUnauthorized"},"403":{"$ref":"#/components/responses/SellerApiForbidden"},"404":{"description":"No active reservations found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"examples":{"NOT_FOUND":{"summary":"NOT_FOUND","value":{"code":"NOT_FOUND","message":"No cancellable order for this reference","error":"No cancellable order for this reference","timestamp":"2026-07-20T12:00:00.000Z","recoverable":true,"hint":"See https://docs.avrix.io/seller-api/errors","requestId":"req_p1_details_example","details":{"orderReference":"store-order-123"}}}}}}},"429":{"$ref":"#/components/responses/SellerApiRateLimited"},"500":{"$ref":"#/components/responses/SellerApiInternalError"}},"x-avrix-scopes":["seller:keys:pull"],"x-avrix-tier":"orders","tags":["Orders"],"operationId":"cancelOrder","x-avrix-capability":"preorder"}},"/api/seller/v1/orders/bulk":{"post":{"summary":"Create bulk order (multi-SKU cart)","description":"Create order for multiple SKUs in one request (e.g. cart checkout or wholesale). On the launch contract (2026-04-29, the stamped default for unpinned requests **before 2026-09-01 UTC**) each item is processed independently and **partial success** is allowed (HTTP 200 with mixed line outcomes). Set **`strict: true`** to run read-only validation on every line first; any failure yields **422** `VALIDATION_FAILED` with aggregated `details.issues` and **no** inventory mutation / webhooks. **From 2026-09-01 (UTC) the stamped default becomes the 2026-09-01 contract and an omitted `strict` defaults to `true`** — the cutover happens automatically; pin `X-Avrix-Api-Version: 2026-04-29` or send `strict: false` explicitly to keep partial success. The response `meta` echoes the effective `contractDate` and `strict` mode. Recommendation: always send `strict` explicitly so defaults never surprise you. Items for unreleased products are automatically reserved as pre-orders when strict checks pass and the fulfillment path chooses pre-order. Optional **integrationOrderContext** at root (cart-level) merges with each item's **integrationOrderContext** (item wins). Use Idempotency-Key for the whole batch; body must match for replay.\n\n**Route error codes** (prefix hints for monitoring; canonical `code` unchanged):\n\n| Prefix | Typical `code` values |\n|---|---|\n| ORD_* | `VALIDATION_FAILED` (per-line `details.issues`), `INSUFFICIENT_INVENTORY`, `CONFLICT`, `IDEMPOTENCY_KEY_MISMATCH`, cart minimum errors |\n| CAT_* | Company visibility / BMA denials |\n| KEY_* | `NO_AVAILABLE_KEYS` on fulfilment paths |\n| | AUTH_* | `UNAUTHORIZED`, `FORBIDDEN`, `KEY_ENVIRONMENT_MISMATCH`, `IP_NOT_ALLOWED`, `IP_NOT_RESOLVABLE` |\n| RATE_* | `RATE_LIMIT_EXCEEDED` |\n\nSee `https://docs.avrix.io/seller-api/errors`.\n\n**Commercial enforcement (API allocations, production keys):** Territory allowlists, catalog list-price parity (`expectedUnitPriceCents` from preview), and buyer IP geo cross-check. Error codes: CATALOG_PRICE_NOT_SET, CATALOG_PRICE_MISMATCH, INVALID_CATALOG_PRICE, TERRITORY_NOT_ALLOWED_FOR_SKU, TERRITORY_EXCLUDED_FOR_RELEASE, SKU_REGION_UNRESOLVED, CONSUMER_IP_REQUIRED, CONSUMER_IP_INVALID, CONSUMER_GEO_MISMATCH, CONSUMER_IP_HIGH_RISK, CONSUMER_GEO_UNAVAILABLE, SALES_COUNTRY_REQUIRED, TAX_DECLARATION_REQUIRED. See `https://docs.avrix.io/seller-api/territory` and `https://docs.avrix.io/seller-api/store-profiles`.","parameters":[{"name":"Idempotency-Key","in":"header","required":true,"schema":{"type":"string"},"description":"Same key returns the cached successful response within 24h when the request body matches; failed responses are never cached, so a retry after fixing the cause re-executes"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["items"],"properties":{"strict":{"type":"boolean","description":"Cart atomicity control. When true, rejects the entire cart with 422 if any line fails validation, preview checks, or would only partially satisfy immediate inventory — no keys allocated. **Default depends on your contract date:** omitted `strict` behaves as `false` (partial success) on the 2026-04-29 contract, and as `true` on contract dates >= 2026-09-01 (send `X-Avrix-Api-Version: 2026-09-01` or `next`). RECOMMENDED: send `strict: true` explicitly, or pin the 2026-09-01 contract."},"integrationOrderContext":{"$ref":"#/components/schemas/IntegrationOrderContext"},"items":{"type":"array","minItems":1,"maxItems":20,"items":{"type":"object","properties":{"skuId":{"type":"string","format":"uuid"},"skuCode":{"type":"string"},"quantity":{"type":"integer","minimum":1,"maximum":1000},"orderReference":{"type":"string","maxLength":255},"customerReference":{"type":"string","maxLength":255},"metadata":{"type":"object"},"integrationOrderContext":{"$ref":"#/components/schemas/IntegrationOrderContext"},"expectedUnitPriceCents":{"type":"integer","minimum":1,"description":"Required for API allocations on production keys. Must exactly match unitPriceCents from POST /orders/preview for the same SKU, quantity, countryCode, and integrationOrderContext."},"expectedWholesaleUnitPriceCents":{"type":"integer","minimum":1,"description":"Deprecated alias of expectedUnitPriceCents (removal planned for v2). When both are sent they must be equal. Preferred alias for wholesale/RS allocation price echo (minor units). Same semantics as expectedUnitPriceCents for wholesale commits. When both are sent they must match.","deprecated":true},"priceCommitmentToken":{"type":"string","minLength":16,"maxLength":2048,"description":"Short-lived price commitment from POST /orders/preview (when price-commitment binding is enabled on the deployment). Binds unitPriceCents across PSP charge → order. Prefer this or checkoutHoldId over re-reading live catalog."}}}},"expectedUnitPriceCents":{"type":"integer","minimum":1,"description":"Required for API allocations on production keys. Must exactly match unitPriceCents from POST /orders/preview for the same SKU, quantity, countryCode, and integrationOrderContext."},"expectedWholesaleUnitPriceCents":{"type":"integer","minimum":1,"description":"Deprecated alias of expectedUnitPriceCents (removal planned for v2). When both are sent they must be equal. Preferred alias for wholesale/RS allocation price echo (minor units). Same semantics as expectedUnitPriceCents for wholesale commits. When both are sent they must match.","deprecated":true},"consumerGeoAttestId":{"type":"string","format":"uuid","description":"Optional checkout-page buyer network confirmation from POST /geo/attest. Required when GET /allocations.consumerGeoAttestRequired is true for that publisher. The attested IP must not equal the API caller or the key allowlist."}}},"example":{"strict":true,"items":[{"skuCode":"SANDBOX-ALWAYS-001","quantity":1,"orderReference":"store-order-10432-line-0"}]}}}},"responses":{"200":{"description":"Bulk order result (partial success; mix of fulfilled and pre-order items)","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"items":{"type":"array","items":{"type":"object","properties":{"skuCode":{"type":"string"},"skuId":{"type":"string"},"quantity":{"type":"integer"},"orderReference":{"type":["string","null"]},"type":{"type":"string","enum":["fulfilled","pre-order"],"description":"Whether keys were delivered or reserved"},"keys":{"type":"array","items":{"type":"string"},"description":"Delivered keys (empty for pre-order)"},"pulled":{"type":"integer"},"reserved":{"type":"integer","description":"Number of keys reserved (pre-order only)"},"allocationId":{"type":"string"},"orderReadableId":{"type":"string"},"fulfilledAt":{"type":"string","format":"date-time"},"contractTermId":{"type":"string","format":"uuid","description":"Active BMA term for this line when fulfilled or pre-order reserved"},"contractTermVersion":{"type":"integer","minimum":1,"description":"BMA term version at pull time for this line"},"releaseDate":{"type":["string","null"],"format":"date-time","description":"Expected release go-live instant (pre-order only, ISO 8601 date-time)"},"error":{"type":"string","description":"Human-readable error if this line item failed"},"code":{"type":"string","description":"Canonical error code when `error` is set (same vocabulary as single-order responses)"},"httpStatus":{"type":"integer","description":"HTTP status that would apply if this line were requested alone"},"issues":{"type":"array","description":"Optional field-level issues when `error` is set (same shape as ApiError.details.issues)","items":{"type":"object","properties":{"field":{"type":"string"},"message":{"type":"string"}}}}}}}}},"meta":{"type":"object","description":"Behavior profile that served this cart — detect the strict-default cutover from the payload instead of inferring it from dates.","properties":{"contractDate":{"type":"string","description":"Effective X-Avrix-Api-Version contract date for this request (also echoed as a response header)."},"strict":{"type":"boolean","description":"Effective strict mode after applying the contract-date default."}}}}}}}},"401":{"$ref":"#/components/responses/SellerApiUnauthorized"},"403":{"$ref":"#/components/responses/SellerApiForbidden"},"409":{"description":"Idempotency-Key reused with different request body (`IDEMPOTENCY_KEY_MISMATCH`)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"422":{"description":"Validation failed (`VALIDATION_FAILED`) — malformed body, cart schema failure, or **strict** bulk pre-flight when any line is invalid","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"examples":{"VALIDATION_FAILED":{"summary":"VALIDATION_FAILED","value":{"code":"VALIDATION_FAILED","message":"Strict cart validation failed","error":"Strict cart validation failed","timestamp":"2026-07-20T12:00:00.000Z","recoverable":true,"hint":"See https://docs.avrix.io/seller-api/errors","requestId":"req_p1_details_example","details":{"issues":[{"field":"items[0]","message":"Insufficient inventory for strict cart (requested 5, available 2)"}]}}}}}}},"429":{"$ref":"#/components/responses/SellerApiRateLimited"},"500":{"$ref":"#/components/responses/SellerApiInternalError"}},"x-avrix-scopes":["seller:keys:pull"],"x-avrix-tier":"orders","tags":["Orders"],"operationId":"bulkOrder"}},"/api/seller/v1/webhooks/{id}/deliveries":{"get":{"summary":"List webhook deliveries","description":"List delivery status for a webhook endpoint. Use for debugging failed deliveries. Filter by status (pending, succeeded, failed).","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","format":"uuid"},"description":"Webhook endpoint ID"},{"name":"limit","in":"query","schema":{"type":"integer","default":50,"minimum":1,"maximum":100}},{"name":"status","in":"query","schema":{"type":"string","enum":["pending","succeeded","failed"]}}],"responses":{"200":{"description":"Delivery list","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"endpointId":{"type":"string"},"eventId":{"type":"string","description":"Use for idempotent handling; also in X-Avrix-Event-Id and payload.eventId"},"eventType":{"type":"string"},"status":{"type":"string"},"attempts":{"type":"integer"},"responseStatus":{"type":["integer","null"]},"createdAt":{"type":"string","format":"date-time"},"lastAttemptAt":{"type":["string","null"],"format":"date-time"},"nextRetryAt":{"type":["string","null"],"format":"date-time"}}}}}}}}},"401":{"$ref":"#/components/responses/SellerApiUnauthorized"},"403":{"$ref":"#/components/responses/SellerApiForbidden"},"422":{"description":"Invalid query parameters (limit, status)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"429":{"$ref":"#/components/responses/SellerApiRateLimited"},"500":{"$ref":"#/components/responses/SellerApiInternalError"}},"x-avrix-scopes":["seller:webhooks:read"],"x-avrix-tier":"webhooks","tags":["Webhooks"],"operationId":"listWebhooksDeliveries"}},"/api/seller/v1/geo/attest":{"post":{"summary":"Create a buyer network confirmation","description":"Mints a short-lived confirmation the storefront loads in the buyer browser. Requires any seller scope. Sandbox keys never require this on orders.","tags":["Seller meta"],"responses":{"201":{"description":"Attest created","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","required":["attestId","expiresAt","pixelUrl"],"properties":{"attestId":{"type":"string","format":"uuid"},"expiresAt":{"type":"string","format":"date-time"},"pixelUrl":{"type":"string","format":"uri","description":"Load this URL in the buyer browser (img or fetch). No API key."}}},"meta":{"type":"object"}}}}}},"401":{"$ref":"#/components/responses/SellerApiUnauthorized"},"403":{"$ref":"#/components/responses/SellerApiForbidden"},"429":{"$ref":"#/components/responses/SellerApiRateLimited"},"500":{"$ref":"#/components/responses/SellerApiInternalError"}},"x-avrix-scopes":[],"x-avrix-tier":"meta","operationId":"createGeoAttest"}},"/api/seller/v1/geo/attest/{attestId}/pixel":{"get":{"summary":"Complete buyer network confirmation (pixel)","description":"No API key. Intended for the buyer browser. Returns a 1×1 GIF. CORS `*`. Completing from the store server is rejected later as CONSUMER_IP_INVALID.","security":[],"tags":["Seller meta"],"parameters":[{"name":"attestId","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"1×1 GIF (completion is best-effort)","content":{"image/gif":{"schema":{"type":"string","format":"binary"}}}},"401":{"$ref":"#/components/responses/SellerApiUnauthorized"},"403":{"$ref":"#/components/responses/SellerApiForbidden"},"429":{"$ref":"#/components/responses/SellerApiRateLimited"},"500":{"$ref":"#/components/responses/SellerApiInternalError"}},"x-avrix-scopes":[],"x-avrix-tier":"meta","operationId":"getGeoAttestPixel"}},"/api/seller/v1/geo/attest/{attestId}/complete":{"post":{"summary":"Complete buyer network confirmation (JSON)","description":"No API key. Same effect as the pixel, with a JSON body. CORS `*`.","security":[],"tags":["Seller meta"],"parameters":[{"name":"attestId","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"Completed","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"completed":{"type":"boolean"}}}}}}}},"401":{"$ref":"#/components/responses/SellerApiUnauthorized"},"403":{"$ref":"#/components/responses/SellerApiForbidden"},"404":{"description":"Attest not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"422":{"description":"Attest expired or incomplete","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"429":{"$ref":"#/components/responses/SellerApiRateLimited"},"500":{"$ref":"#/components/responses/SellerApiInternalError"}},"x-avrix-scopes":[],"x-avrix-tier":"meta","operationId":"completeGeoAttest"}},"/api/seller/v1/whoami":{"get":{"summary":"Who am I","description":"Identity echo for the calling API key: company, key metadata (scopes, environment), sandbox flag, and normalized allowlist IPs (masked consistently with keys list). Requires **any** seller scope on the key.\n\n**IP privacy:** Response fields describe **your integration egress**, not buyers.\n\n**Contract posture:** Response includes `data.hasActiveBma` and `data.warnings` (e.g. `NO_ACTIVE_BMA`, `API_SKU_MISSING_CATALOG_PRICE`, `PRICE_COMMITMENT_NOT_CONFIGURED`). Header `X-Avrix-Warning: no_active_bma` when no BMA is signed.\n\n**Capabilities:** `data.capabilities` reports deployment features (`preorderEnabled` (pre-order purchase flows for this company; default false), `backorderEnabled` (durable customer-order backorders; default false — `backorderOnUnavailable` is rejected until this is true), `activationPolicy` (`warn` | `enforce_known` | `enforce_strict`), `priceCommitmentConfigured`, `checkoutHoldEnabled`, `checkoutHoldConfigured`, `hotDropRedisConfigured`, `idempotencyBackend`, `territoryEnforcementEnabled`, `consumerGeoEnforcementEnabled`, `catalogPriceStrictMode`) — see `https://docs.avrix.io/seller-api/store-profiles` and `https://docs.avrix.io/seller-api/territory`.\n\n**Capability details:** `data.capabilityDetails` splits keyless, preorder, activationEnforcement and priceCommitment into `available` (shipped), `enabled` (feature flag or per-company gate) and `verifiedAt` (first live proof, null until the capability has worked in a real request) — use it to distinguish shipped vs flagged vs proven; the flat booleans stay for compatibility.","tags":["Seller meta"],"parameters":[{"name":"diagnostics","in":"query","required":false,"description":"When `1` or `true`, run full integrator diagnostics (publisher warnings, commercial catalog-price warnings, and territory-pricing readiness). Omit for the default fast path.","schema":{"type":"string","enum":["1","true","yes"]}}],"responses":{"200":{"description":"Identity payload","headers":{"X-Avrix-Warning":{"description":"Present when `data.hasActiveBma` is false (`no_active_bma`) or when API catalog pricing is incomplete (`api_allocation_missing_price`).","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/SellerWhoamiResponse"},"example":{"data":{"persona":"seller","sandbox":true,"requestEnvironment":"sandbox","hasActiveBma":true,"warnings":[],"capabilities":{"checkoutHoldEnabled":true,"checkoutHoldConfigured":true,"hotDropRedisConfigured":true,"idempotencyBackend":"redis","territoryEnforcementEnabled":true,"consumerGeoEnforcementEnabled":false,"catalogPriceStrictMode":true,"keylessEnabled":false,"backorderEnabled":false,"activationPolicy":"warn","activationEnforceOptIn":false,"priceCommitmentConfigured":true,"consumerGeoAttestEnabled":true,"consumerGeoAttestRequired":false},"capabilityDetails":{"keyless":{"available":true,"enabled":false,"certified":false,"verifiedAt":null},"preorder":{"available":true,"enabled":false,"certified":false,"verifiedAt":null},"activationEnforcement":{"available":true,"enabled":false,"verifiedAt":null},"priceCommitment":{"available":true,"enabled":true,"verifiedAt":"2026-08-14T09:12:00Z"}},"company":{"id":"00000000-0000-4000-8000-000000000010","name":"Sandbox Seller"},"key":{"id":"00000000-0000-4000-8000-000000000011","name":"sandbox-checkout","environment":"sandbox","scopes":["seller:products:read","seller:keys:pull","seller:orders:preview"]},"integrationReadiness":{"sellableSkuCount":1,"sharedSkuCount":1,"allocatedSkuCount":1,"allocatedWithoutShareCount":0,"sharedWithoutAllocationCount":0,"missingTerritoryPricingCount":0}},"meta":{"requestId":"req_01EXAMPLE","diagnostics":false}}}}},"401":{"$ref":"#/components/responses/SellerApiUnauthorized"},"403":{"$ref":"#/components/responses/SellerApiForbidden"},"429":{"$ref":"#/components/responses/SellerApiRateLimited"},"500":{"$ref":"#/components/responses/SellerApiInternalError"}},"x-avrix-scopes":["seller:products:read"],"x-avrix-tier":"meta","operationId":"getWhoami","x-codeSamples":[{"lang":"curl","label":"Whoami","source":"curl -s \"https://api.avrix.io/api/seller/v1/whoami\" \\\n  -H \"Authorization: Bearer avrix_sk_sbx_your_key_here\""}]}},"/api/seller/oauth/token":{"post":{"summary":"OAuth2 client_credentials token","description":"Mint a short-lived Bearer (`avrix_oat_*`) mapped to a **seller API key** row (token TTL ~3600s). Authenticate with JSON body `grant_type=client_credentials`, `client_id` (**API key uuid**), `client_secret` (**plaintext key once**). Disabled when OAuth token minting is not enabled on the deployment (**501**).\n\n**Privacy:** treat `client_secret` like a password — never log or persist.","tags":["Seller auth"],"security":[],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["grant_type","client_id","client_secret"],"properties":{"grant_type":{"type":"string","enum":["client_credentials"]},"client_id":{"type":"string","format":"uuid"},"client_secret":{"type":"string"}}},"example":{"grant_type":"client_credentials","client_id":"example_client","client_secret":"example_secret"}}}},"responses":{"200":{"description":"access_token issued","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"401":{"$ref":"#/components/responses/SellerApiUnauthorized"},"403":{"$ref":"#/components/responses/SellerApiForbidden"},"422":{"description":"Validation failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"429":{"$ref":"#/components/responses/SellerApiRateLimited"},"500":{"$ref":"#/components/responses/SellerApiInternalError"},"501":{"description":"OAuth issuance disabled","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}},"x-avrix-scopes":[],"x-avrix-tier":"auth","operationId":"tokenOauth"}},"/api/seller/v1/orders/{orderId}":{"get":{"summary":"Fetch order by readable id","description":"Returns aggregate fulfillment state for a single store order reference bundle identified by Avrix readable id (`ord_…`).","tags":["Orders"],"security":[{"bearerAuth":[]}],"parameters":[{"name":"orderId","in":"path","required":true,"schema":{"type":"string","pattern":"^ord_"},"description":"Avrix order readable id (`ord_…`)"}],"responses":{"200":{"description":"Order aggregate for the given readable id (`ord_…`). No plaintext keys.","content":{"application/json":{"schema":{"type":"object","required":["data"],"properties":{"data":{"$ref":"#/components/schemas/SellerOrderAggregate"}}}}}},"401":{"$ref":"#/components/responses/SellerApiUnauthorized"},"403":{"$ref":"#/components/responses/SellerApiForbidden"},"404":{"description":"Order not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"422":{"description":"Invalid orderId","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"429":{"$ref":"#/components/responses/SellerApiRateLimited"},"500":{"$ref":"#/components/responses/SellerApiInternalError"}},"x-avrix-scopes":["seller:products:read"],"x-avrix-tier":"orders","operationId":"getOrder"}},"/api/seller/v1/orders/{orderId}/extend":{"post":{"summary":"Extend hot-drop reservation TTL","description":"**Hot-drop only.** Extends an outstanding reservation TTL (idempotent; capped per reservation — **409** `RESERVATION_EXTEND_EXHAUSTED` when exhausted). `orderId` path parameter is the **hot-drop reservation UUID**.\n\n**Route error codes** (prefix hints for monitoring; canonical `code` unchanged):\n\n| Prefix | Typical `code` values |\n|---|---|\n| ORD_* | `NOT_FOUND`, `RESERVATION_EXTEND_EXHAUSTED`, invalid reservation state |\n| CAT_* | `HOT_DROP_UNAVAILABLE` |\n| | AUTH_* | `UNAUTHORIZED`, `FORBIDDEN`, `KEY_ENVIRONMENT_MISMATCH`, `IP_NOT_ALLOWED`, `IP_NOT_RESOLVABLE` |\n| RATE_* | `RATE_LIMIT_EXCEEDED` |\n\nSee `https://docs.avrix.io/seller-api/errors`.","tags":["Orders"],"parameters":[{"name":"orderId","in":"path","required":true,"schema":{"type":"string","format":"uuid"},"description":"Hot-drop reservation UUID"}],"responses":{"200":{"description":"Hot-drop reservation TTL extended once (`data.reservationId`, `expiresAt`, `ttlSeconds`, `extendedOnce: true`).","content":{"application/json":{"schema":{"type":"object","required":["data","meta"],"properties":{"data":{"$ref":"#/components/schemas/SellerHotDropExtendData"},"meta":{"type":"object","properties":{"requestId":{"type":"string"}}}}}}}},"401":{"$ref":"#/components/responses/SellerApiUnauthorized"},"403":{"$ref":"#/components/responses/SellerApiForbidden"},"409":{"description":"Conflict / exhausted extend","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"429":{"$ref":"#/components/responses/SellerApiRateLimited"},"500":{"$ref":"#/components/responses/SellerApiInternalError"},"503":{"description":"Coordination service unavailable","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}},"x-avrix-scopes":["seller:keys:pull"],"x-avrix-tier":"orders","operationId":"extendOrder"}},"/api/seller/v1/orders/fulfillments/{fulfillmentId}/revoke":{"post":{"summary":"Revoke keyless fulfillment","description":"**Capability-gated (`keyless`, not GA):** keyless fulfilment requires the keyless capability — check `whoami.capabilityDetails.keyless`; without it keyless flows fail with `403 FEATURE_DISABLED`.\n\nInvalidates a keyless redemption link for the seller company. Idempotent when the fulfillment is already terminal (`revoked`, `redeemed`, or `activated`). Does not return keys to inventory.\n\nRequires `seller:orders:manage`.","tags":["Orders"],"parameters":[{"name":"fulfillmentId","in":"path","required":true,"schema":{"type":"string","format":"uuid"},"description":"Keyless fulfillment UUID from order `delivery.fulfillmentId`"}],"responses":{"200":{"description":"Revoked (or already terminal)","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/SellerKeylessFulfillmentRevokeResult"},"meta":{"type":"object","properties":{"requestId":{"type":"string"}}}}}}}},"401":{"$ref":"#/components/responses/SellerApiUnauthorized"},"403":{"$ref":"#/components/responses/SellerApiForbidden"},"404":{"description":"Fulfillment not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"422":{"description":"Validation error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"429":{"$ref":"#/components/responses/SellerApiRateLimited"},"500":{"$ref":"#/components/responses/SellerApiInternalError"}},"x-avrix-scopes":["seller:orders:manage"],"x-avrix-tier":"orders","operationId":"createRevoke"}},"/api/seller/v1/orders/fulfillments/{fulfillmentId}/regenerate":{"post":{"summary":"Regenerate keyless fulfillment","description":"**Capability-gated (`keyless`, not GA):** keyless fulfilment requires the keyless capability — check `whoami.capabilityDetails.keyless`; without it keyless flows fail with `403 FEATURE_DISABLED`.\n\nRevokes the existing hosted redemption link and issues a new fulfillment with a fresh URL. Returns a **new** `fulfillmentId`. Not allowed after buyer activation (`409` `ALREADY_ACTIVATED`).\n\nRequires `seller:orders:manage`. Currently supported for `hosted_redemption` only.","tags":["Orders"],"parameters":[{"name":"fulfillmentId","in":"path","required":true,"schema":{"type":"string","format":"uuid"},"description":"Existing keyless fulfillment UUID"}],"responses":{"200":{"description":"New keyless delivery reference","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"allOf":[{"$ref":"#/components/schemas/SellerOrderKeylessDelivery"},{"type":"object","properties":{"status":{"type":"string","enum":["issued","viewed","activated","redeemed","expired","revoked","failed"]}}}]},"meta":{"type":"object","properties":{"requestId":{"type":"string"}}}}}}}},"401":{"$ref":"#/components/responses/SellerApiUnauthorized"},"403":{"$ref":"#/components/responses/SellerApiForbidden"},"404":{"description":"Fulfillment not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"409":{"description":"Already activated","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"422":{"description":"Provider does not support regenerate","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"429":{"$ref":"#/components/responses/SellerApiRateLimited"},"500":{"$ref":"#/components/responses/SellerApiInternalError"}},"x-avrix-scopes":["seller:orders:manage"],"x-avrix-tier":"orders","operationId":"createRegenerate"}},"/api/seller/v1/availability/{skuCode}":{"get":{"summary":"Availability by SKU code","description":"CDN-friendly single-SKU alias over `GET /availability`. Company-cacheable via `Authorization` + `Accept-Language`. Returns allocation + inventory headroom.\n\n**Bundles:** includes `skuType` + `bundleItems` when configured.","tags":["Catalog"],"parameters":[{"name":"skuCode","in":"path","required":true,"schema":{"type":"string"},"description":"SKU code (URL-encoded)"},{"name":"countryCode","in":"query","required":false,"description":"Optional single ISO 3166-1 alpha-2 code (e.g. `DE`) — the canonical spelling, matching the checkout field name. When present, each availability item also carries `country`, `sellableInCountry`, and `blockedReason` (`COUNTRY_RESTRICTED`, `TERRITORY_NOT_ALLOWED_FOR_SKU`, `TERRITORY_EXCLUDED_FOR_RELEASE`, `SKU_REGION_UNRESOLVED`, or `CATALOG_PRICE_NOT_SET`) evaluated with the same territory predicate as `POST /orders/preview`.","schema":{"type":"string","pattern":"^[A-Za-z]{2}$"}},{"name":"country","in":"query","required":false,"description":"Alias of `countryCode` (the original availability spelling, kept for compatibility). Sending both with different values fails validation.","schema":{"type":"string","pattern":"^[A-Za-z]{2}$"}}],"responses":{"200":{"description":"Availability row","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"401":{"$ref":"#/components/responses/SellerApiUnauthorized"},"403":{"$ref":"#/components/responses/SellerApiForbidden"},"404":{"description":"SKU not allocated","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"429":{"$ref":"#/components/responses/SellerApiRateLimited"},"500":{"$ref":"#/components/responses/SellerApiInternalError"}},"x-avrix-scopes":["seller:products:read"],"x-avrix-tier":"catalog","operationId":"getAvailability"}},"/api/seller/v1/promotions/shares/{shareId}/discounts":{"get":{"summary":"Promotion share SKU discounts","description":"SKU-level discount table for an **accepted** promotion share (`shareId`). Rows are gated to the promotion's **effective time window** (the same predicate that prices settlement): outside the window — before the event starts or after it ends — `data` is empty and `meta.active` is `false`, with `meta.window` carrying the event's `startsAt`/`endsAt`. Do not apply a share's discounts to your storefront unless `meta.active` is `true`.","tags":["Promotions"],"parameters":[{"name":"shareId","in":"path","required":true,"schema":{"type":"string","format":"uuid"}},{"name":"limit","in":"query","schema":{"type":"integer","default":50,"minimum":1,"maximum":100}},{"name":"cursor","in":"query","schema":{"type":"string"}}],"responses":{"200":{"description":"Rows (empty with meta.active=false outside the effective window)","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"type":"object","properties":{"productId":{"type":"string"},"sku":{"type":"string"},"discountPct":{"type":"number"}}}},"meta":{"type":["object","null"],"description":"Effective-window gate: rows are served only while active is true.","properties":{"window":{"type":"object","properties":{"startsAt":{"type":["string","null"],"format":"date-time"},"endsAt":{"type":["string","null"],"format":"date-time"}}},"active":{"type":"boolean"}}}}}}}},"401":{"$ref":"#/components/responses/SellerApiUnauthorized"},"403":{"$ref":"#/components/responses/SellerApiForbidden"},"404":{"description":"Share not visible","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"429":{"$ref":"#/components/responses/SellerApiRateLimited"},"500":{"$ref":"#/components/responses/SellerApiInternalError"}},"x-avrix-scopes":["seller:promotions:read"],"x-avrix-tier":"promotions","operationId":"listPromotionsSharesDiscounts"}},"/api/seller/v1/regions":{"get":{"summary":"List regions visible to seller","description":"Regions intersecting **your visible publisher catalog**. Supports cursor pagination.\n\n**Commercial enforcement (API allocations, production keys):** Territory allowlists, catalog list-price parity (`expectedUnitPriceCents` from preview), and buyer IP geo cross-check. Error codes: CATALOG_PRICE_NOT_SET, CATALOG_PRICE_MISMATCH, INVALID_CATALOG_PRICE, TERRITORY_NOT_ALLOWED_FOR_SKU, TERRITORY_EXCLUDED_FOR_RELEASE, SKU_REGION_UNRESOLVED, CONSUMER_IP_REQUIRED, CONSUMER_IP_INVALID, CONSUMER_GEO_MISMATCH, CONSUMER_IP_HIGH_RISK, CONSUMER_GEO_UNAVAILABLE, SALES_COUNTRY_REQUIRED, TAX_DECLARATION_REQUIRED. See `https://docs.avrix.io/seller-api/territory` and `https://docs.avrix.io/seller-api/store-profiles`.","tags":["Catalog"],"parameters":[{"name":"limit","in":"query","schema":{"type":"integer","default":50,"minimum":1,"maximum":100}},{"name":"cursor","in":"query","schema":{"type":"string"}},{"name":"partner","in":"query","schema":{"type":"string","maxLength":32,"pattern":"^[a-zA-Z0-9_-]+$"}}],"responses":{"200":{"description":"Regions visible via active allocations (`{ data: SellerRegionSummary[] }`).","content":{"application/json":{"schema":{"type":"object","required":["data"],"properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/SellerRegionSummary"}}}}}}},"401":{"$ref":"#/components/responses/SellerApiUnauthorized"},"403":{"$ref":"#/components/responses/SellerApiForbidden"},"429":{"$ref":"#/components/responses/SellerApiRateLimited"},"500":{"$ref":"#/components/responses/SellerApiInternalError"}},"x-avrix-scopes":["seller:products:read"],"x-avrix-tier":"catalog","operationId":"listRegions"}},"/api/seller/v1/regions/{code}":{"get":{"summary":"Region detail","description":"Single region by **AUM region code** when visible via your publisher connections.\n\n**Commercial enforcement (API allocations, production keys):** Territory allowlists, catalog list-price parity (`expectedUnitPriceCents` from preview), and buyer IP geo cross-check. Error codes: CATALOG_PRICE_NOT_SET, CATALOG_PRICE_MISMATCH, INVALID_CATALOG_PRICE, TERRITORY_NOT_ALLOWED_FOR_SKU, TERRITORY_EXCLUDED_FOR_RELEASE, SKU_REGION_UNRESOLVED, CONSUMER_IP_REQUIRED, CONSUMER_IP_INVALID, CONSUMER_GEO_MISMATCH, CONSUMER_IP_HIGH_RISK, CONSUMER_GEO_UNAVAILABLE, SALES_COUNTRY_REQUIRED, TAX_DECLARATION_REQUIRED. See `https://docs.avrix.io/seller-api/territory` and `https://docs.avrix.io/seller-api/store-profiles`.","tags":["Catalog"],"parameters":[{"name":"code","in":"path","required":true,"schema":{"type":"string"},"description":"Region code (case-insensitive)"},{"name":"partner","in":"query","schema":{"type":"string","maxLength":32,"pattern":"^[a-zA-Z0-9_-]+$"}}],"responses":{"200":{"description":"Region detail","content":{"application/json":{"schema":{"type":"object"}}}},"401":{"$ref":"#/components/responses/SellerApiUnauthorized"},"403":{"$ref":"#/components/responses/SellerApiForbidden"},"404":{"description":"Unknown / not visible","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"429":{"$ref":"#/components/responses/SellerApiRateLimited"},"500":{"$ref":"#/components/responses/SellerApiInternalError"}},"x-avrix-scopes":["seller:products:read"],"x-avrix-tier":"catalog","operationId":"getRegion"}},"/api/seller/v1/activity":{"get":{"summary":"Settlement activity feed","description":"One keyset-pageable settlement feed at sale grain: `sale` (+1), `refund` / `chargeback` (-1), custody-only `pull` (+1) and keyless `reveal` (0) entries with counterparty, promo reference, buyer-country evidence and economics. Reconcile against this cursor instead of joining `/finance/api-sales`, `/transactions` and `/refunds`. `format=csv` renders the same rows (the next cursor is returned in `X-Next-Cursor`). Passing `kinds=transaction` or `kinds=webhook_delivery` returns the legacy merged shape for one release; webhook deliveries live on `GET /events` and `GET /webhooks/{id}/deliveries`.","tags":["Seller meta"],"parameters":[{"name":"limit","in":"query","schema":{"type":"integer","default":50,"minimum":1,"maximum":100}},{"name":"cursor","in":"query","schema":{"type":"string"},"description":"Opaque keyset cursor from `meta.nextCursor`."},{"name":"kinds","in":"query","schema":{"type":"string"},"description":"Comma-separated `sale`, `refund`, `chargeback`, `pull`, `reveal` (default: all). Legacy: `transaction`, `webhook_delivery`."},{"name":"from","in":"query","schema":{"type":"string","format":"date-time"},"description":"Inclusive lower bound on `occurredAt` (ISO-8601)."},{"name":"to","in":"query","schema":{"type":"string","format":"date-time"},"description":"Inclusive upper bound on `occurredAt` (ISO-8601)."},{"name":"promoId","in":"query","schema":{"type":"string","format":"uuid"},"description":"Only entries discounted by this share / deal id."},{"name":"counterparty","in":"query","schema":{"type":"string"},"description":"Only entries settled with this publisher company id."},{"name":"orderReference","in":"query","schema":{"type":"string"},"description":"Only entries for this order reference."},{"name":"format","in":"query","schema":{"type":"string","enum":["json","csv"],"default":"json"}}],"responses":{"200":{"description":"Settlement entries (or legacy rows when `kinds` is limited to legacy kinds).","content":{"application/json":{"schema":{"type":"object","required":["data"],"properties":{"data":{"type":"array","items":{"oneOf":[{"$ref":"#/components/schemas/SellerSettlementActivityEntry"},{"$ref":"#/components/schemas/SellerActivityItem"}]}},"meta":{"type":"object","properties":{"limit":{"type":"integer"},"nextCursor":{"type":["string","null"]}}}}}},"text/csv":{"schema":{"type":"string"}}}},"401":{"$ref":"#/components/responses/SellerApiUnauthorized"},"403":{"$ref":"#/components/responses/SellerApiForbidden"},"429":{"$ref":"#/components/responses/SellerApiRateLimited"},"500":{"$ref":"#/components/responses/SellerApiInternalError"}},"x-avrix-scopes":["seller:products:read"],"x-avrix-tier":"catalog","operationId":"listActivity"}},"/api/seller/v1/events":{"get":{"summary":"Webhook delivery cursor feed","description":"Immutable forward cursor over **webhook deliveries**. Start from a `since` ISO watermark, then follow `meta.nextCursor` (keyset on `createdAt`,`id`) until it is null: a burst of events sharing one timestamp pages through without loss or repetition, which `since` alone cannot guarantee. `meta.nextSince` remains for older clients. Requires `seller:webhooks:read`. Complements per-endpoint delivery listings.","tags":["Webhooks"],"parameters":[{"name":"limit","in":"query","schema":{"type":"integer","default":50,"minimum":1,"maximum":100}},{"name":"cursor","in":"query","description":"Opaque keyset position from a previous page's `meta.nextCursor`. Takes precedence over `since`. 422 when malformed.","schema":{"type":"string"}},{"name":"since","in":"query","description":"Rows created strictly after this instant (full timestamp precision is honoured). Use for the first page or a time-based watermark.","schema":{"type":"string","format":"date-time"}}],"responses":{"200":{"description":"Forward-only webhook delivery cursor across all endpoints for this key (`data[]` + `meta.nextCursor` / `meta.nextSince`).","content":{"application/json":{"schema":{"type":"object","required":["data","meta"],"properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/SellerWebhookDeliveryCursorItem"}},"meta":{"type":"object","required":["requestId"],"properties":{"requestId":{"type":"string"},"nextSince":{"type":["string","null"],"format":"date-time","description":"Pass as `since` on the next page when more rows exist; null when exhausted. Prefer `nextCursor`: `since` alone cannot page across more than one page of rows sharing a timestamp."},"nextCursor":{"type":["string","null"],"description":"Opaque keyset cursor (createdAt, id) for the next page; null when exhausted. Loss-free across bursts of rows sharing one timestamp."}}}}}}}},"401":{"$ref":"#/components/responses/SellerApiUnauthorized"},"403":{"$ref":"#/components/responses/SellerApiForbidden"},"422":{"description":"Invalid since / pagination","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"429":{"$ref":"#/components/responses/SellerApiRateLimited"},"500":{"$ref":"#/components/responses/SellerApiInternalError"}},"x-avrix-scopes":["seller:webhooks:read"],"x-avrix-tier":"webhooks","operationId":"listEvents"}},"/api/seller/v1/finance/summary":{"get":{"summary":"Finance summary (seller)","description":"Outstanding balances per publisher relationship, draft sales report count, and recent monthly reports. **Not** key-pull history — use `/api/seller/v1/transactions` for pulls. Requires scope `seller:finance:read`.","responses":{"200":{"description":"Seller finance overview payload","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","description":"See fetchSellerFinanceOverview in platform code"}}}}}},"401":{"$ref":"#/components/responses/SellerApiUnauthorized"},"403":{"$ref":"#/components/responses/SellerApiForbidden"},"429":{"$ref":"#/components/responses/SellerApiRateLimited"},"500":{"$ref":"#/components/responses/SellerApiInternalError"}},"x-avrix-scopes":["seller:finance:read"],"x-avrix-tier":"finance","tags":["Finance"],"operationId":"getFinanceSummary"}},"/api/seller/v1/finance/api-sales":{"get":{"summary":"API sale transactions (seller)","description":"Per-key `sales.api_sale_transactions` rows for the authenticated seller. Paginated; `cursor` is a numeric offset string. Optional `from` / `to` ISO 8601 filters on `sale_timestamp`. Requires `seller:finance:read`.\n\nCSV export (`format=csv`) columns: id, publisherCompanyId, keyPullId, keyId, skuId, productId, salePriceCents, currencyCode, currencyExponent, publisherShareCents, sellerShareCents, platformFeeCents, saleTimestamp, aggregationStatus, reportId, orderReference, adjustmentStatus, customerRegionCode, detectedCountryCode, warning (`COUNTRY_MISMATCH` when the buyer IP country disagreed with the declared sales country; empty otherwise).","parameters":[{"name":"limit","in":"query","schema":{"type":"integer","default":50,"minimum":1,"maximum":100}},{"name":"cursor","in":"query","schema":{"type":"string"},"description":"Opaque keyset cursor from meta.nextCursor. Do not construct or parse — echo it back verbatim. Legacy integer offset cursors from before 2026-08 remain accepted during transition."},{"name":"from","in":"query","schema":{"type":"string","format":"date-time"}},{"name":"to","in":"query","schema":{"type":"string","format":"date-time"}},{"name":"format","in":"query","required":false,"schema":{"type":"string","enum":["json","csv"],"default":"json"},"description":"Response format. `csv` streams the same rows as text/csv for finance tooling."}],"responses":{"200":{"description":"Rows and pagination meta","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/SellerApiSaleTransaction"}},"meta":{"$ref":"#/components/schemas/PaginationMeta"}}}}}},"401":{"$ref":"#/components/responses/SellerApiUnauthorized"},"403":{"$ref":"#/components/responses/SellerApiForbidden"},"422":{"description":"Invalid query parameters","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"429":{"$ref":"#/components/responses/SellerApiRateLimited"},"500":{"$ref":"#/components/responses/SellerApiInternalError"}},"x-avrix-scopes":["seller:finance:read"],"x-avrix-tier":"finance","tags":["Finance"],"operationId":"listFinanceApiSales"}},"/api/seller/v1/finance/invoices":{"get":{"summary":"Seller invoices (platform billing)","description":"Paginated `sales.invoices` where the seller is the authenticated company. Requires `seller:finance:read`.","parameters":[{"name":"limit","in":"query","schema":{"type":"integer","default":50,"minimum":1,"maximum":100}},{"name":"cursor","in":"query","schema":{"type":"string"},"description":"Opaque keyset cursor from meta.nextCursor. Do not construct or parse — echo it back verbatim. Legacy integer offset cursors from before 2026-08 remain accepted during transition."}],"responses":{"200":{"description":"Invoices and pagination meta","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"type":"object"}},"meta":{"$ref":"#/components/schemas/PaginationMeta"}}}}}},"401":{"$ref":"#/components/responses/SellerApiUnauthorized"},"403":{"$ref":"#/components/responses/SellerApiForbidden"},"422":{"description":"Invalid query parameters","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"429":{"$ref":"#/components/responses/SellerApiRateLimited"},"500":{"$ref":"#/components/responses/SellerApiInternalError"}},"x-avrix-scopes":["seller:finance:read"],"x-avrix-tier":"finance","tags":["Finance"],"operationId":"listFinanceInvoices"}},"/api/seller/v1/refunds/{refundId}":{"get":{"summary":"Get refund by id","description":"Single refund/chargeback status row. `refundId` is the sale transaction id from GET /refunds. Scopes: same as GET /refunds.","x-avrix-scopes":["seller:refunds:read"],"x-avrix-tier":"standard","parameters":[{"name":"refundId","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"Refund detail","content":{"application/json":{"schema":{"type":"object","required":["data"],"properties":{"data":{"$ref":"#/components/schemas/SellerRefund"}}}}}},"401":{"$ref":"#/components/responses/SellerApiUnauthorized"},"403":{"$ref":"#/components/responses/SellerApiForbidden"},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"429":{"$ref":"#/components/responses/SellerApiRateLimited"},"500":{"$ref":"#/components/responses/SellerApiInternalError"}},"operationId":"getRefund","tags":["Orders"]}},"/api/seller/v1/chargebacks/resolve":{"post":{"summary":"Resolve a chargeback dispute","description":"Report the outcome of a payment-provider dispute for a chargeback previously declared via `POST /refunds` with `type: \"chargeback\"`. Resolves the whole group sharing the same `chargebackReference` in a single atomic update. Winning means you kept the buyer's money, so the sale stands again and the content owner's share plus the platform commission are restored on a later settlement; losing confirms the reversal already applied when the chargeback was declared. Requires `seller:refunds:write`. Use `Idempotency-Key` for safe retries.\n\nReturns `404` when `chargebackReference` is not found for your company, and `409` (with the current `adjustmentStatus` in the message) when the chargeback is not in the `chargeback_open` state.","parameters":[{"name":"Idempotency-Key","in":"header","required":true,"schema":{"type":"string"},"description":"Required for safe retries"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["chargebackReference","outcome"],"properties":{"chargebackReference":{"type":"string","minLength":1,"maxLength":128},"outcome":{"type":"string","enum":["won","lost"]},"occurredAt":{"type":"string","format":"date-time"}}},"example":{"chargebackReference":"psp_dispute_10432","outcome":"won"}}}},"responses":{"200":{"description":"Chargeback resolved","content":{"application/json":{"schema":{"type":"object","required":["data"],"properties":{"data":{"type":"object","required":["chargebackReference","outcome","resolved"],"properties":{"chargebackReference":{"type":"string"},"outcome":{"type":"string","enum":["won","lost"]},"resolved":{"type":"integer","description":"Number of sale transactions resolved in this group."}}}}}}}},"401":{"$ref":"#/components/responses/SellerApiUnauthorized"},"403":{"$ref":"#/components/responses/SellerApiForbidden"},"404":{"description":"Chargeback reference not found for this seller","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"409":{"description":"Chargeback is not in the chargeback_open state","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"422":{"description":"Validation failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"429":{"$ref":"#/components/responses/SellerApiRateLimited"},"500":{"$ref":"#/components/responses/SellerApiInternalError"}},"x-avrix-scopes":["seller:refunds:write"],"x-avrix-tier":"orders","tags":["Orders"],"operationId":"resolveChargeback"}},"/api/seller/v1/products/{productId}/media/download":{"get":{"tags":["Catalog"],"summary":"Download product media ZIP","description":"Streams a ZIP archive of screenshots, trailers, and capsule art for a seller-visible product. Requires `seller:products:read`. Console session downloads (cookie + `?company=`) remain supported for the seller UI but are outside this Bearer contract.","operationId":"downloadProductMedia","x-avrix-scopes":["seller:products:read"],"x-avrix-tier":"catalog","parameters":[{"name":"productId","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"ZIP archive of product media","content":{"application/zip":{"schema":{"type":"string","format":"binary"}}},"headers":{"Content-Disposition":{"description":"attachment; filename=\"{slug}-media-{timestamp}.zip\"","schema":{"type":"string"}}}},"401":{"$ref":"#/components/responses/SellerApiUnauthorized"},"403":{"$ref":"#/components/responses/SellerApiForbidden"},"404":{"description":"Product not found or no downloadable media","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"422":{"description":"Invalid productId path parameter","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"429":{"$ref":"#/components/responses/SellerApiRateLimited"},"500":{"$ref":"#/components/responses/SellerApiInternalError"}}}},"/api/seller/v1/platforms":{"get":{"summary":"Platform registry","description":"Reference list of platform codes (`steam`, `ps5`, …) with display names and platform families, so integrators can validate `platformCode` values offline instead of treating them as open strings. Mirrors `GET /regions`; safe to cache for an hour.","operationId":"listPlatforms","tags":["Catalog"],"x-avrix-scopes":["seller:products:read"],"x-avrix-tier":"catalog","responses":{"200":{"description":"Active platforms","content":{"application/json":{"schema":{"type":"object","required":["data"],"properties":{"data":{"type":"array","items":{"type":"object","required":["code","name"],"properties":{"code":{"type":"string","description":"Stable machine code, e.g. `steam`."},"name":{"type":"string"},"platformFamily":{"type":["string","null"],"description":"Family grouping, e.g. `playstation`."}}}},"version":{"type":"string","description":"Stable hex digest of active platform codes + updatedAt. Poll and compare."},"updatedAt":{"type":["string","null"],"format":"date-time","description":"max(updated_at) among active registry rows."}}}}}},"401":{"$ref":"#/components/responses/SellerApiUnauthorized"},"403":{"$ref":"#/components/responses/SellerApiForbidden"},"429":{"$ref":"#/components/responses/SellerApiRateLimited"},"500":{"$ref":"#/components/responses/SellerApiInternalError"}}}},"/api/seller/v1/webhooks/egress-ips":{"get":{"summary":"Webhook egress identity","description":"The source-IP identity of webhook deliveries, for firewall teams. Key-free. When `pinned` is false (the current default — egress is not pinned on this infrastructure), do NOT build source-IP allowlists; signature verification is the authoritative control. When pinned, address changes are announced at least 30 days ahead.","operationId":"getWebhookEgressIps","tags":["webhooks"],"security":[],"x-avrix-scopes":[],"x-avrix-tier":"public","responses":{"200":{"description":"Egress identity","content":{"application/json":{"schema":{"type":"object","required":["data"],"properties":{"data":{"type":"object","required":["egressIps","pinned","verificationRequired"],"properties":{"egressIps":{"type":"array","items":{"type":"string"},"description":"Static egress IPs/CIDRs; empty when unpinned."},"pinned":{"type":"boolean"},"verificationRequired":{"type":"boolean","const":true},"docUrl":{"type":"string"}}}}}}}},"401":{"$ref":"#/components/responses/SellerApiUnauthorized"},"403":{"$ref":"#/components/responses/SellerApiForbidden"},"429":{"$ref":"#/components/responses/SellerApiRateLimited"},"500":{"$ref":"#/components/responses/SellerApiInternalError"}}}},"/api/seller/v1/finance/statements":{"get":{"summary":"Monthly finance statement","description":"Reconcile monthly transaction activity with approved settlements and outstanding balances. Legacy totals cover the returned lines; activityTotals covers the entire month, including pending and quarantined entries. These are different financial views and must not be added together. Results are frozen for 30 minutes. Follow nextCursor with the same period to retrieve subsequent pages; an expired cursor returns 422 and requires restarting without a cursor. format=csv downloads one page and returns pagination metadata in X-Avrix-Statement-Total-Lines, X-Avrix-Statement-Truncated and X-Avrix-Statement-Next-Cursor headers. Invoicing remains a separate action following report approval.","operationId":"getFinanceStatement","tags":["Finance"],"x-avrix-scopes":["seller:finance:read"],"x-avrix-tier":"finance","parameters":[{"name":"period","in":"query","required":true,"description":"Calendar month, `YYYY-MM` (UTC).","schema":{"type":"string","pattern":"^\\d{4}-\\d{2}$","example":"2026-07"}},{"name":"format","in":"query","required":false,"description":"`json` (default) or `csv` (transaction lines only).","schema":{"type":"string","enum":["json","csv"],"default":"json"}},{"name":"cursor","in":"query","required":false,"description":"Opaque nextCursor from the preceding page. Keep the same period.","schema":{"type":"string"}},{"name":"limit","in":"query","required":false,"description":"Maximum returned lines per page; activityTotals always covers the full period.","schema":{"type":"integer","minimum":1,"maximum":5000,"default":5000}}],"responses":{"200":{"description":"Statement for the period","content":{"application/json":{"schema":{"type":"object","required":["data"],"properties":{"data":{"$ref":"#/components/schemas/SellerFinanceStatement"}}}},"text/csv":{"schema":{"type":"string","description":"One row per transaction line."}}}},"401":{"$ref":"#/components/responses/SellerApiUnauthorized"},"403":{"$ref":"#/components/responses/SellerApiForbidden"},"422":{"description":"`period` missing or not `YYYY-MM`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"429":{"$ref":"#/components/responses/SellerApiRateLimited"},"500":{"$ref":"#/components/responses/SellerApiInternalError"}}}},"/api/seller/v1/integration/status":{"get":{"summary":"Integration status","description":"Consolidated onboarding progress — one machine-readable answer to \"why can't I sell yet?\". Each gate (BMA, catalog share, allocation, territory pricing, webhook, signed test ping, first order) reports `satisfied` plus an actionable `hint`. `readyToSell` is true when every commerce-critical gate passes. Diagnostics-grade endpoint: poll during onboarding, not on the hot path.","operationId":"getIntegrationStatus","tags":["Seller meta"],"x-avrix-scopes":["seller:products:read"],"x-avrix-tier":"general","responses":{"200":{"description":"Consolidated integration gates","content":{"application/json":{"schema":{"type":"object","required":["data"],"properties":{"data":{"$ref":"#/components/schemas/SellerIntegrationStatus"}}}}}},"401":{"$ref":"#/components/responses/SellerApiUnauthorized"},"403":{"$ref":"#/components/responses/SellerApiForbidden"},"429":{"$ref":"#/components/responses/SellerApiRateLimited"},"500":{"$ref":"#/components/responses/SellerApiInternalError"}}}},"/api/seller/v1/orders/{orderId}/fulfill":{"post":{"summary":"Fulfill a ready deferred order","description":"Assigns and reveals keys for a durable preorder or backorder. Pre-orders and backorders are **capability-gated** (`whoami.capabilities.preorderEnabled` / `backorderEnabled`, both default false) — without the grant no durable rows reach a revealable state. Allowed when status is `ready`, or `awaiting_release` / `awaiting_stock` if keys are already available. All-or-nothing: the full pending quantity is revealed or the call fails with `409 ORDER_NOT_READY` and no partial fulfillment. Idempotency-Key required. Scope: `seller:orders:fulfill` (v1 also accepts `seller:keys:pull` and `seller:orders:write`). Plaintext keys appear only in this response.","tags":["Orders"],"security":[{"bearerAuth":[]}],"parameters":[{"name":"orderId","in":"path","required":true,"schema":{"type":"string","pattern":"^ord_"},"description":"Avrix order readable id (`ord_…`)"}],"responses":{"200":{"description":"Keys revealed. Order is fulfilled.","content":{"application/json":{"schema":{"type":"object","required":["data"],"properties":{"data":{"$ref":"#/components/schemas/SellerOrderFulfillData"}}}}}},"401":{"$ref":"#/components/responses/SellerApiUnauthorized"},"403":{"$ref":"#/components/responses/SellerApiForbidden"},"404":{"description":"Order not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"409":{"description":"ORDER_NOT_READY or order is not fulfillable","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"422":{"description":"Invalid orderId","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"429":{"$ref":"#/components/responses/SellerApiRateLimited"},"500":{"$ref":"#/components/responses/SellerApiInternalError"}},"x-avrix-scopes":["seller:orders:fulfill"],"x-avrix-tier":"orders","operationId":"fulfillOrder"}},"/api/seller/v1/promotions/calendar":{"get":{"summary":"List live and upcoming promotion windows","description":"Live and upcoming accepted shares and approved deals with `priceEffect` (`list_price`, `settlement_price`, or `both`). Catalog `/products/{id}/pricing` stays undiscounted. Settlement-affecting windows change preview/commit unit price. Requires seller:promotions:read.","tags":["Promotions"],"responses":{"200":{"description":"Promotion calendar","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/SellerPromotionCalendarEntry"}}}}}}},"401":{"$ref":"#/components/responses/SellerApiUnauthorized"},"403":{"$ref":"#/components/responses/SellerApiForbidden"},"429":{"$ref":"#/components/responses/SellerApiRateLimited"},"500":{"$ref":"#/components/responses/SellerApiInternalError"}},"x-avrix-scopes":["seller:promotions:read"],"x-avrix-tier":"promotions","operationId":"getPromotionsCalendar"}},"/api/seller/v1/catalog/exports":{"post":{"summary":"Enqueue a catalog export","description":"Starts an async job that builds an immutable gzip NDJSON catalog artifact (same payload as GET /catalog/snapshot?format=ndjson). Poll GET /catalog/exports/{exportId} or subscribe to catalog.export_ready. Synchronous snapshot remains available.","operationId":"createCatalogExport","tags":["Catalog"],"x-avrix-scopes":["seller:products:read"],"x-avrix-tier":"catalog","responses":{"202":{"description":"Export accepted","content":{"application/json":{"schema":{"type":"object","required":["data"],"properties":{"data":{"type":"object","required":["exportId","status"],"properties":{"exportId":{"type":"string","format":"uuid"},"status":{"type":"string","enum":["pending"]}}}}}}}},"401":{"$ref":"#/components/responses/SellerApiUnauthorized"},"403":{"$ref":"#/components/responses/SellerApiForbidden"},"429":{"$ref":"#/components/responses/SellerApiRateLimited"},"500":{"$ref":"#/components/responses/SellerApiInternalError"}}}},"/api/seller/v1/catalog/exports/{exportId}":{"get":{"summary":"Catalog export status","description":"Job status plus a short-lived signed download URL when the gzip NDJSON artifact is ready. 410 EXPORT_EXPIRED when the artifact TTL has elapsed.","operationId":"getCatalogExport","tags":["Catalog"],"x-avrix-scopes":["seller:products:read"],"x-avrix-tier":"catalog","parameters":[{"name":"exportId","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"Export status","content":{"application/json":{"schema":{"type":"object","required":["data"],"properties":{"data":{"type":"object","required":["exportId","status"],"properties":{"exportId":{"type":"string","format":"uuid"},"status":{"type":"string","enum":["pending","processing","completed","failed","expired"]},"checksum":{"type":"string","description":"SHA-256 hex of the gzip NDJSON artifact."},"bytes":{"type":"integer"},"expiresAt":{"type":"string","format":"date-time"},"downloadUrl":{"type":"string","format":"uri","description":"Short-lived signed URL. Present only when status is completed."},"totalProducts":{"type":"integer"}}}}}}}},"401":{"$ref":"#/components/responses/SellerApiUnauthorized"},"403":{"$ref":"#/components/responses/SellerApiForbidden"},"404":{"description":"Export not found or not owned by this seller.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"410":{"description":"Artifact expired","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"429":{"$ref":"#/components/responses/SellerApiRateLimited"},"500":{"$ref":"#/components/responses/SellerApiInternalError"}}}},"/api/seller/v1/me/footprint":{"get":{"tags":["Finance"],"summary":"Read your selling footprint","description":"Your selling footprint: the countries and currencies you sell in. The same record the Commercial configuration screen edits and the order path checks, so an order into a country not listed here is refused with FOOTPRINT_COUNTRY_NOT_DECLARED, and one in a currency not listed with FOOTPRINT_CURRENCY_NOT_DECLARED.\n\nA footprint narrows and never grants. Declaring a country does not obtain the right to sell there: your agreement does that, and this states which part of the granted territory you actually operate in.","operationId":"getMeFootprint","security":null,"responses":{"200":{"description":"Your declared footprint.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","required":["countries","currencies"],"properties":{"countries":{"type":"array","items":{"type":"string","example":"NL"},"description":"ISO 3166-1 alpha-2 countries you sell into."},"currencies":{"type":"array","items":{"type":"string","example":"EUR"},"description":"ISO 4217 currencies you sell in."}}}}}}}},"401":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"403":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"429":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"500":{"$ref":"#/components/responses/SellerApiInternalError"},"503":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}},"x-avrix-scopes":["seller:account:manage"],"x-avrix-tier":"meta"},"put":{"tags":["Finance"],"summary":"Replace your selling footprint","description":"Your selling footprint: the countries and currencies you sell in. The same record the Commercial configuration screen edits and the order path checks, so an order into a country not listed here is refused with FOOTPRINT_COUNTRY_NOT_DECLARED, and one in a currency not listed with FOOTPRINT_CURRENCY_NOT_DECLARED.\n\nA footprint narrows and never grants. Declaring a country does not obtain the right to sell there: your agreement does that, and this states which part of the granted territory you actually operate in.\n\nA replace, not a merge: send the complete set of countries and currencies. An omitted key would leave you unable to express \"I no longer sell here\", and makes a retry mean something different from the first call. Requires `seller:account:manage`, which legacy keys do not hold.","operationId":"putMeFootprint","security":null,"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["countries","currencies"],"properties":{"countries":{"type":"array","items":{"type":"string","example":"NL"},"description":"ISO 3166-1 alpha-2 countries you sell into. At least one: an empty footprint would refuse every order, so the API refuses to store one.","minItems":1},"currencies":{"type":"array","items":{"type":"string","example":"EUR"},"description":"ISO 4217 currencies you sell in. At least one, for the same reason.","minItems":1}}}}}},"responses":{"200":{"description":"The footprint as stored.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","required":["countries","currencies"],"properties":{"countries":{"type":"array","items":{"type":"string","example":"NL"},"description":"ISO 3166-1 alpha-2 countries you sell into."},"currencies":{"type":"array","items":{"type":"string","example":"EUR"},"description":"ISO 4217 currencies you sell in."}}}}}}}},"401":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"403":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"422":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"429":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"500":{"$ref":"#/components/responses/SellerApiInternalError"},"503":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}},"x-avrix-scopes":["seller:account:manage"],"x-avrix-tier":"meta"}},"/api/seller/v1/finance/api-sales/{transactionId}":{"get":{"tags":["Finance"],"summary":"Read one API sale transaction","description":"One sale as the ledger recorded it: what it settled at, which entry type it is, and, for a reversal, which sale it reverses. The list endpoint answers what happened this period; this answers why a statement line says what it does.\n\nA transaction id belonging to another seller returns 404 rather than 403, because a 403 would confirm the row exists.","operationId":"getFinanceApiSaleTransaction","security":null,"parameters":[{"name":"transactionId","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"The transaction as recorded.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object"}}}}}},"401":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"403":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"404":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"429":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"500":{"$ref":"#/components/responses/SellerApiInternalError"},"503":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}},"x-avrix-scopes":["seller:finance:read"],"x-avrix-tier":"finance"}}},"components":{"headers":{"IdempotencyReplayed":{"description":"Present with value `true` when the response is replayed from idempotency storage (same `Idempotency-Key` as a prior successful request; failed responses are never stored). Absent on first execution.","schema":{"type":"string","enum":["true"]}},"XRateLimitReset":{"description":"Unix timestamp in seconds when the current rate-limit window resets.","schema":{"type":"integer","format":"int64"}}},"securitySchemes":{"bearerAuth":{"type":"http","scheme":"bearer","bearerFormat":"API Key"}},"responses":{"SellerApiUnauthorized":{"description":"Missing or invalid `Authorization` Bearer token, expired key, or invalid company.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"SellerApiForbidden":{"description":"Valid auth but insufficient API scope, client IP not in key allowlist, or access is not available from the caller location (`LOCATION_BLOCKED`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"SellerApiRateLimited":{"description":"Per-company rate limit exceeded. See `Retry-After` (seconds) when present and `X-RateLimit-Reset` (Unix seconds) for the current window reset.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}},"headers":{"X-RateLimit-Reset":{"$ref":"#/components/headers/XRateLimitReset"}}},"SellerApiInternalError":{"description":"Unexpected server error.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}},"schemas":{"SellerHealthComponent":{"type":"object","description":"Per-component health probe result. `unconfigured` means the feature is opt-in and not enabled in this environment (e.g. local development without optional backends) — it is not an error.","required":["status"],"properties":{"status":{"type":"string","enum":["ok","degraded","unconfigured"]},"latencyMs":{"type":"integer","description":"Round-trip probe latency in ms (omitted when unconfigured)."},"message":{"type":"string","description":"Short error message (only when status === 'degraded')."},"lastUpdated":{"type":"string","format":"date-time","description":"Catalog index: timestamp of the most recently updated product row."},"ageSeconds":{"type":"integer","description":"Catalog index: seconds since the most recent product update."},"publisher":{"type":"boolean","description":"Whether near-real-time webhook push is configured."},"receiver":{"type":"boolean","description":"Whether near-real-time webhook push verification is configured."}}},"SellerPartner":{"type":"object","description":"Publisher–seller connection (same lifecycle as Marketplace → Partners: `active`, `suspended`, `terminated`) plus safe publisher profile fields. `connectionId` is `distribution.company_connections.id`. Avatar URLs use the same resolution as the console (icon → light/dark logos → legacy `logo_url`).","required":["connectionId","sellerCompanyId","publisherCompanyId","publisherCompanyName","status","connectionCreatedAt","connectionUpdatedAt","automatedSalesReportInvoicing","contracts"],"properties":{"connectionId":{"type":"string","format":"uuid"},"sellerCompanyId":{"type":"string","maxLength":32,"description":"Company id (slug-safe identifier, max 32 chars)"},"publisherCompanyId":{"type":"string","maxLength":32,"description":"Company id (slug-safe identifier, max 32 chars)"},"publisherCompanyName":{"type":"string"},"status":{"type":"string","description":"Connection status","enum":["active","suspended","terminated"]},"connectionCreatedAt":{"type":"string","format":"date-time"},"connectionUpdatedAt":{"type":"string","format":"date-time"},"automatedSalesReportInvoicing":{"type":"boolean"},"offboardingStatus":{"type":["string","null"]},"terminationReason":{"type":["string","null"]},"terminationEffectiveAt":{"type":["string","null"],"format":"date-time"},"terminationInitiatedAt":{"type":["string","null"],"format":"date-time"},"terminatedBy":{"type":["string","null"],"description":"User id when recorded"},"publisherWebsite":{"type":["string","null"],"format":"uri"},"publisherCountry":{"type":["string","null"]},"publisherDescription":{"type":["string","null"],"description":"Company public bio from company profile (not store short copy)"},"publisherIndustry":{"type":["string","null"]},"publisherCompanySize":{"type":["string","null"]},"publisherRankingTier":{"type":["string","null"]},"publisherSellerSubType":{"type":["string","null"]},"publisherCompanyTypeCode":{"type":["string","null"]},"publisherCompanyImageUrl":{"type":["string","null"],"format":"uri","description":"Resolved display avatar URL (same pipeline as the console)."},"publisherLogoUrl":{"type":["string","null"],"format":"uri","description":"Same value as `publisherCompanyImageUrl` (legacy name)."},"contracts":{"$ref":"#/components/schemas/SellerPartnerContractsSummary"}}},"SellerWhoamiWarning":{"type":"object","required":["code","message"],"properties":{"code":{"type":"string","description":"Machine code, e.g. NO_ACTIVE_BMA, API_SKU_MISSING_CATALOG_PRICE, API_SKU_MISSING_TERRITORY_PRICING, PRICE_COMMITMENT_NOT_CONFIGURED"},"message":{"type":"string"}}},"SellerPublisherWhoamiWarning":{"type":"object","required":["publisherCompanyId","publisherCompanyName","code","message"],"properties":{"publisherCompanyId":{"type":"string","maxLength":32},"publisherCompanyName":{"type":"string"},"code":{"type":"string","description":"e.g. NO_ACTIVE_BMA, SHARES_SUSPENDED, API_SKU_MISSING_TERRITORY_PRICING"},"message":{"type":"string"}}},"SellerCapabilityDetail":{"type":"object","description":"One capability's shipped/flagged/proven split (see capabilityDetails).","properties":{"available":{"type":"boolean","description":"The capability's code path is shipped in this deployment."},"enabled":{"type":"boolean","description":"The feature flag or per-company gate is on for this company."},"certified":{"type":"boolean","description":"Present on capabilities that require certification (keyless, preorder): Avrix flips the grant only after the integration is certified for this company / deployment. Until then the capability is not available to you regardless of what the docs describe, and commits reject with FEATURE_DISABLED / PRODUCT_NOT_SELLABLE."},"verifiedAt":{"type":["string","null"],"format":"date-time","description":"First live proof for this company; null until the capability has demonstrably worked in a real request."}}},"SellerWhoamiCapabilities":{"type":"object","properties":{"checkoutHoldEnabled":{"type":"boolean"},"checkoutHoldConfigured":{"type":"boolean"},"hotDropRedisConfigured":{"type":"boolean"},"idempotencyBackend":{"type":"string","enum":["redis","postgres","memory"]},"integrationProfilesDoc":{"type":"string"},"territoryEnforcementEnabled":{"type":"boolean","description":"True when production API orders enforce SKU territory allowlists"},"consumerGeoEnforcementEnabled":{"type":"boolean","description":"True for production keys when consumer geo enforcement is active. When false, buyer IP is shape-checked only unless monitor is on."},"consumerGeoMonitorEnabled":{"type":"boolean","description":"True for production keys when consumer geo is in monitor mode. Would-be denials appear as geoWarning on 200 responses."},"catalogPriceStrictMode":{"type":"boolean","description":"True when API allocations require expectedUnitPriceCents from preview"},"keylessEnabled":{"type":"boolean","description":"True when seller-api-keyless is enabled (hosted_redemption; quantity must be 1)."},"preorderEnabled":{"type":"boolean","description":"True when this company may purchase launchPhase pre_order products. Default false."},"backorderEnabled":{"type":"boolean","description":"True when durable customer-order backorders are enabled. Default false: backorderOnUnavailable is rejected with 403 FEATURE_DISABLED (details.reason BACKORDER_NOT_ENABLED). When true, POST /orders may accept awaiting_stock against headroom if the vendor policy allows request_mode_backorder; otherwise BACKORDER_NOT_ALLOWED."},"activationPolicy":{"type":"string","enum":["warn","enforce_known","enforce_strict"],"description":"EFFECTIVE activation-territory posture for this company (platform posture, upgraded to enforce_known when activationEnforceOptIn is true). warn (default) adds an advisory preview warning. enforce_known returns 422 ACTIVATION_REGION_MISMATCH for a known locked-set miss. enforce_strict also returns 422 ACTIVATION_REGION_UNKNOWN when batch activation coverage is absent. Enforcement 422s carry details: skuId, countryCode, activationType, allowedCountries."},"activationEnforceOptIn":{"type":"boolean","description":"True when this company opted in to activation-territory enforcement (enforce_known) ahead of the platform default flip. Contact support to opt in."},"priceCommitmentConfigured":{"type":"boolean","description":"True when this deployment can mint signed preview price-commitment tokens. Production deployments fail closed at boot without the signing key, so this is always true in production; when false (sandbox/local), expectedUnitPriceCents remains mandatory on commit."},"consumerGeoAttestEnabled":{"type":"boolean","description":"True when POST /geo/attest and related complete/pixel routes exist."},"consumerGeoAttestRequired":{"type":"boolean","description":"True when any active Content Owner connection requires checkout-page buyer network confirmation. Always false for sandbox keys."}}},"SellerWhoamiData":{"type":"object","required":["persona","sandbox","requestEnvironment","hasActiveBma","warnings","capabilities","company","key","settlement"],"properties":{"persona":{"type":"string","enum":["seller"]},"sandbox":{"type":"boolean"},"requestEnvironment":{"type":"string","enum":["sandbox","production"]},"hasActiveBma":{"type":"boolean","description":"True when the seller company has at least one active BMA term with any publisher."},"warnings":{"type":"array","items":{"$ref":"#/components/schemas/SellerWhoamiWarning"}},"publisherWarnings":{"type":"array","description":"Per-publisher diagnostic warnings for integrator routing.","items":{"$ref":"#/components/schemas/SellerPublisherWhoamiWarning"}},"integrationReadiness":{"type":"object","description":"Aggregate SKU readiness counts and blockers for store onboarding. Default whoami uses a lightweight summary (`diagnostics=false`, `missingTerritoryPricingCount` is 0). Full territory-pricing walks require `?diagnostics=1`. Under a full-catalog BMA scope no per-SKU share rows exist by design; allocated SKUs count as shared/sellable and NO_SKU_SHARE is not raised.","properties":{"sellableSkuCount":{"type":"integer"},"sharedSkuCount":{"type":"integer"},"allocatedSkuCount":{"type":"integer"},"allocatedWithoutShareCount":{"type":"integer"},"sharedWithoutAllocationCount":{"type":"integer"},"missingTerritoryPricingCount":{"type":"integer","description":"Only populated on `?diagnostics=1`; otherwise 0 on the fast path."},"settlementHint":{"type":"string","enum":["prepaid_wallet","invoice_report_only"],"description":"Coarse checkout UI hint (wallet vs invoice path)."},"settlementMode":{"type":"string","enum":["prepaid_wallet","automated_invoice","report_only"],"description":"Finer settlement posture from Airwallex B2B flag and automated_sales_report_invoicing on an active connection."},"diagnostics":{"type":"boolean","description":"True when this response used the full diagnostics path (`?diagnostics=1`)."},"blockers":{"type":"array","description":"What stands between this key and a settled sale. Catalog blockers (`NO_SKU_SHARE`, `NO_ALLOCATION`, `NO_TERRITORY_PRICING`, `NO_ACTIVE_BMA`) resolve through your vendor relationship. `STORE_COUNTRY_MISSING` is the seller's own: the company has no registered country on file, so a sale whose buyer country cannot be confirmed is held out of settlement until one is recorded in the console (Company settings, addresses). `REGION_LOCKED` names, in `countries`, the countries you declare that a Content Owner has locked under an in-force agreement; orders into them are refused until the owner lifts the lock.","items":{"type":"object","properties":{"code":{"type":"string","description":"e.g. NO_ACTIVE_BMA, NO_SKU_SHARE, NO_ALLOCATION, NO_TERRITORY_PRICING, STORE_COUNTRY_MISSING, REGION_LOCKED"},"count":{"type":"integer"},"recommendedAction":{"type":"string"},"countries":{"type":"array","items":{"type":"string"},"description":"Only on REGION_LOCKED: ISO 3166-1 alpha-2 codes of the declared countries an owner has locked."}}}}}},"capabilities":{"$ref":"#/components/schemas/SellerWhoamiCapabilities"},"capabilityDetails":{"type":"object","description":"Shipped vs flagged vs proven, per capability: `available` = the code path exists in this deployment; `enabled` = the feature flag or per-company gate is on for THIS company; `verifiedAt` = first live proof (first request where the capability demonstrably worked), null until then. The flat `capabilities` booleans remain the compatibility surface.","properties":{"keyless":{"$ref":"#/components/schemas/SellerCapabilityDetail"},"preorder":{"$ref":"#/components/schemas/SellerCapabilityDetail"},"activationEnforcement":{"$ref":"#/components/schemas/SellerCapabilityDetail"},"priceCommitment":{"$ref":"#/components/schemas/SellerCapabilityDetail"}}},"company":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"}}},"key":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"name":{"type":"string"},"environment":{"type":"string","enum":["production","sandbox"]},"scopes":{"type":"array","items":{"type":"string"}},"rateLimited":{"type":"boolean","description":"False for production keys (IP-allowlisted, never rate limited). True for sandbox keys, which share a flat abuse cap."},"allowedIps":{"type":"array","items":{"type":"string"}}}},"integrationContextStrictProfile":{"type":["object","boolean","null"],"description":"Per-key strict integration-context profile. `null` (the default) means the standard profile; an object (or `true`) means production orders must carry full integrationOrderContext commercial evidence.","properties":{"additionalRequiredFieldPaths":{"type":"array","items":{"type":"string"}}},"additionalProperties":false},"requiredDeclarations":{"type":"array","description":"Dot-paths that every API catalog order must send: salesCountryCode, salesPriceGrossMinor, salesTaxRatePercent and salesChannel under integrationOrderContext. Missing salesCountryCode is refused with 422 SALES_COUNTRY_REQUIRED; missing salesPriceGrossMinor or salesTaxRatePercent with 422 TAX_DECLARATION_REQUIRED; missing salesChannel with 422 SALES_CHANNEL_REQUIRED. Sandbox and production alike.","items":{"type":"string"}},"requiredDeclarationsNote":{"type":"string"},"refundPolicy":{"$ref":"#/components/schemas/RefundPolicy"},"settlement":{"type":"object","description":"Settlement posture. `invoiceWithinDays` is currently always null: the platform does not automate invoice issuance (report approval accrues the share and the vendor raises the invoice as a separate deliberate act), so no invoicing deadline is committed. The field is kept for wire compatibility and reserved for a future committed SLA; treat null as no committed invoicing latency.","properties":{"mode":{"type":"string","enum":["prepaid_wallet","automated_invoice","report_only"]},"invoiceWithinDays":{"type":["integer","null"],"example":null}},"required":["mode","invoiceWithinDays"]},"footprint":{"type":"object","description":"Countries and currencies you have declared you sell into. An order into a country that is not listed is refused with 422 FOOTPRINT_COUNTRY_NOT_DECLARED. Your footprint narrows what your agreements grant and never widens it. Editable through PUT /api/seller/v1/me/footprint with the seller:account:manage scope.","properties":{"countries":{"type":"array","items":{"type":"string"},"description":"ISO 3166-1 alpha-2 codes."},"currencies":{"type":"array","items":{"type":"string"},"description":"ISO 4217 codes."},"note":{"type":"string"},"countriesWithoutReferenceRate":{"type":"array","items":{"type":"string"},"description":"Footprint countries for which the platform holds no consumer tax reference rate in force. An order into one is accepted and the key delivered, but the sale is held out of settlement until the rate is entered. Empty when every footprint country is covered."},"referenceRateNote":{"type":"string","description":"Plain-language explanation of countriesWithoutReferenceRate."}}},"permittedCurrenciesByPublisher":{"type":"array","description":"What each Content Owner's Commercial Schedule permits, one entry per in-force API agreement. Read this before choosing a checkout currency: a currency the agreement does not permit is refused with 422 CURRENCY_NOT_PERMITTED_BY_TERM whatever the catalog prices.","items":{"type":"object","properties":{"publisherCompanyId":{"type":"string"},"contractTermId":{"type":"string"},"currencyMode":{"type":["string","null"],"enum":["primary_only","all_catalog_currencies","custom",null],"description":"primary_only: each country's own currency only. all_catalog_currencies: any currency the SKU is priced or authored in. custom: only the currencies in currencyDetail, and only in the countries each names. null means the agreement states none, which refuses every order until it is amended."},"permittedChannels":{"type":["string","null"],"description":"The sales channels the agreement permits. own_storefront covers web, mobile_app and partner_embed. own_storefront_plus_named_marketplaces covers those and marketplace:<slug> for each slug in marketplaceSlugs; every other marketplace is outside it."},"note":{"type":"string","description":"What the mode means, in plain language."},"currencyDetail":{"type":["object","null"],"description":"Under currencyMode custom, which countries each named currency may be sold in. Each value is either an array of ISO 3166-1 alpha-2 country codes or the string \"territory\", meaning anywhere in the granted territory. Null under every other mode, and null when the agreement states a list the Platform cannot read, in which case every order is refused until it is amended.","additionalProperties":{"oneOf":[{"type":"array","items":{"type":"string","pattern":"^[A-Z]{2}$"}},{"type":"string","enum":["territory"]}]},"examples":[{"EUR":["PL","CZ"],"USD":"territory"}]},"marketplaceSlugs":{"type":"array","items":{"type":"string","pattern":"^[a-z0-9][a-z0-9._-]{0,48}$"},"description":"The marketplaces this agreement names. Declare one as the sales channel marketplace:<slug>. Empty under every mode that admits no marketplace.","examples":[["steam"]]}}}},"geoPolicyByPublisher":{"type":"array","description":"Each Content Owner's geo-mismatch policy and any per-SKU tightenings. The per-SKU overrides have no other route to you: a Content Owner sets them alone, because they can only ever refuse, so this block is the only place you can see one before an order hits it.","items":{"type":"object","properties":{"publisherCompanyId":{"type":"string"},"contractTermId":{"type":"string"},"policy":{"type":["string","null"],"enum":["warn","refuse","settle_at_evidence",null],"description":"warn: the sale proceeds and the disagreement is recorded, lowering the evidence rank it settles at. refuse: 422 CONSUMER_GEO_MISMATCH_POLICY_REFUSED. settle_at_evidence: the sale is re-priced at the higher of the two territories' SRPs."},"skuOverrides":{"type":"array","description":"SKUs this Content Owner has tightened. Restrictive only: an override may refuse, never widen.","items":{"type":"object","properties":{"skuId":{"type":"string"},"skuCode":{"type":["string","null"]},"policy":{"type":"string","enum":["refuse"]},"reason":{"type":["string","null"]}}}}}}}}},"SellerWhoamiResponse":{"type":"object","required":["data","meta"],"properties":{"data":{"$ref":"#/components/schemas/SellerWhoamiData"},"meta":{"type":"object","properties":{"requestId":{"type":"string"},"diagnostics":{"type":"boolean","description":"True when `?diagnostics=1` was requested."}}}}},"SellerPartnerContractsSummary":{"type":"object","description":"Read-only contract posture for integrator diagnostics (not legal PDFs or external BYO artifact ids).","required":["activeBmaTypes","mcaStatus","pendingBmaTypes","pausedBmaTypes","catalogShareMode","sharesSuspended","activeTerms","pendingAmendmentCount"],"properties":{"activeBmaTypes":{"type":"array","items":{"type":"string","enum":["wholesale","revenue_share","api","pre_order"]}},"pendingBmaTypes":{"type":"array","description":"BMA contract types in flight (draft, negotiating, pending countersign) without an active term yet.","items":{"type":"string","enum":["wholesale","revenue_share","api","pre_order"]}},"pausedBmaTypes":{"type":"array","description":"BMA contract types whose governing term is paused: signed and occupying its slot, but operationally suspended (pulls and orders are refused) until the pause is lifted. Neither active nor pending. Additive field per the versioning policy; older clients may ignore it.","items":{"type":"string","enum":["wholesale","revenue_share","api","pre_order"]}},"mcaStatus":{"type":"string","enum":["active","missing","paused","pending_ack","pending_countersign"],"description":"MCA posture: active term, no MCA, executed-but-paused (trading suspended until the pause is lifted), seller acknowledgement pending, or publisher countersign in progress. `paused` is an additive enum value per the versioning policy: clients must ignore enum values they do not understand."},"catalogShareMode":{"type":"string","enum":["all","selected"]},"sharesSuspended":{"type":"boolean","description":"True when any contract-sourced SKU share is suspended for this publisher–seller pair."},"activeTerms":{"type":"array","description":"Active governing terms with ids and versions (diagnostics only; no PDF or snapshot payload).","items":{"$ref":"#/components/schemas/SellerPartnerActiveContractTerm"}},"pendingAmendmentCount":{"type":"integer","minimum":0,"description":"Count of in-flight amendments (`status = proposed`) on this connection's contract terms."},"lastContractChangeAt":{"type":["string","null"],"format":"date-time","description":"Latest `updated_at` across contract terms on this connection; use as a cache invalidation hint."}}},"SellerPartnerActiveContractTerm":{"type":"object","required":["contractType","termId","version"],"properties":{"contractType":{"type":"string","enum":["mca","wholesale","revenue_share","api","pre_order"]},"termId":{"type":"string","format":"uuid"},"version":{"type":"integer","minimum":1},"effectiveAt":{"type":["string","null"],"format":"date-time","description":"Term effective date (`valid_from`) when set."}}},"PartnerProductSku":{"type":"object","description":"Shared SKU row on catalog list/snapshot. Includes sellability from the same readiness stack as GET /allocations (allocations remain checkout authority). Per-SKU platform/edition/SRP fields are populated when the seller company is known.","properties":{"id":{"type":"string"},"skuCode":{"type":"string"},"platformName":{"type":["string","null"]},"platformCode":{"type":["string","null"]},"editionName":{"type":["string","null"]},"keyTypeName":{"type":["string","null"]},"srpPriceCents":{"type":["integer","null"],"description":"Suggested retail price in the seller company's preferred pricing country"},"srpCurrencyCode":{"type":["string","null"]},"sellable":{"type":"boolean","description":"True when this SKU is checkout-ready (grant + share + lifecycle + pricing). Authoritative for browse; still re-check preview/allocations at commit."},"readinessBlockers":{"type":"array","items":{"type":"string"},"description":"Machine codes explaining why sellable is false (e.g. NO_ALLOCATION, NO_SKU_SHARE)."},"recommendedAction":{"type":["string","null"],"description":"Suggested partner action when not sellable."},"pricePerKeyCents":{"type":["integer","null"],"description":"Wholesale unit price from active allocation grant when present (advisory)."},"currencyCode":{"type":["string","null"],"description":"ISO 4217 currency for pricePerKeyCents."},"currencyExponent":{"type":["integer","null"],"description":"ISO 4217 minor-unit exponent for currencyCode (0 for JPY, 2 for USD, 3 for KWD)."}},"required":["id","skuCode","sellable","readinessBlockers"]},"PartnerProduct":{"type":"object","description":"Product row for external catalog browse. List price fields reflect **publisher list / SRP** (typically US tier), not the wholesale `pricePerKeyCents` on allocations.","properties":{"id":{"type":"string"},"readableId":{"type":"string","description":"Prefixed ID for debugging (e.g. prd_abc12345)"},"createdAt":{"type":["string","null"],"format":"date-time","description":"Derived from product id when UUIDv8"},"name":{"type":"string"},"slug":{"type":"string"},"productType":{"type":["string","null"],"enum":["game","dlc","expansion","bundle","edition","soundtrack","currency","other",null],"description":"Closed taxonomy — build merchandising rules on these values; unknown legacy values are normalized to \"other\"."},"status":{"type":["string","null"],"deprecated":true,"enum":["draft","active","discontinued","archived",null],"description":"Deprecated legacy lifecycle rollup, derived from the lifecycle dimensions. Use launchPhase, tradingState, and isArchived instead."},"launchPhase":{"type":["string","null"],"enum":["draft","announced","pre_order","available",null],"description":"Rolled-up launch phase across the product's live SKUs."},"tradingState":{"type":["string","null"],"enum":["open","paused","discontinued",null],"description":"Rolled-up trading state: whether new commerce is permitted."},"isArchived":{"type":"boolean","description":"True when the product is archived and hidden from catalog surfaces."},"publisherCompanyId":{"type":"string"},"publisherCompanyName":{"type":"string"},"sharedSkus":{"type":"array","items":{"$ref":"#/components/schemas/PartnerProductSku"}},"coverUrl":{"type":["string","null"],"description":"Key art URL when available"},"shortDescription":{"type":["string","null"],"description":"Localized store short copy (see locale / Accept-Language on list and detail)"},"editionCount":{"type":"integer","description":"Non-deleted catalog editions count"},"platformNames":{"type":"array","items":{"type":"string"},"description":"Platforms for shared SKUs"},"platforms":{"type":"array","description":"Stable platform code/name pairs for shared SKUs. Prefer this over name-only matching.","items":{"type":"object","properties":{"code":{"type":"string"},"name":{"type":"string"}},"required":["code","name"]}},"regionNames":{"type":"array","items":{"type":"string"}},"regions":{"type":"array","description":"Stable region code/name pairs for shared SKUs. `code` can be null for publisher-defined regions without a global AUM code.","items":{"type":"object","properties":{"code":{"type":["string","null"]},"name":{"type":"string"}},"required":["code","name"]}},"editionNamesShared":{"type":"array","items":{"type":"string"}},"sharedRegionReleaseCount":{"type":"integer"},"listPriceFromCents":{"type":["integer","null"],"description":"Lowest resolved **US** list price among shared SKUs’ region releases — browse/compare hint only. For regional SRP use `GET /products/{id}` (`pricing[]` per release) or `GET /products/{id}/pricing?country=`. Release-level pricing may not reflect per-SKU catalog overrides when the publisher sets SKU-specific prices."},"listPriceCurrencyCode":{"type":["string","null"]},"updatedAt":{"type":["string","null"],"format":"date-time","description":"Product last-updated timestamp"},"publisherCompanyImageUrl":{"type":["string","null"],"format":"uri","description":"Publisher display avatar (same resolution as partners list)"},"publisherWebsite":{"type":["string","null"],"format":"uri"},"publisherCountry":{"type":["string","null"]},"relatedProducts":{"type":"array","description":"Relationship edges — only targets visible to your seller account are listed. `requires` = DLC/expansion needs the base game; `includes` = bundle contents; `edition_of` = edition of a base product.","items":{"type":"object","required":["type","productId"],"properties":{"type":{"type":"string","enum":["requires","includes","upgrades","edition_of"]},"productId":{"type":"string","format":"uuid"}}}}}},"PartnerProductListAvailabilityExpansion":{"type":"object","description":"Per-row availability summary returned when `expand=availability` is set on `GET /products`. Aggregates pullable stock across all shared SKUs for the product. **Advisory only** — call `/availability` for commit-time accuracy.","properties":{"available":{"type":"integer","description":"Sum of pullable keys across all shared SKUs (min(allocationRemaining, inventoryAvailable))"},"allocationRemaining":{"type":"integer","description":"Sum of (quantity_limit - quantity_pulled) across all seller allocations for this product"},"inventoryAvailable":{"type":"integer","description":"Sum of the publisher's shared available keys across all batches feeding those allocations, plus any stock the publisher has dedicated to your allocations"},"skuCount":{"type":"integer","description":"Number of distinct shared SKUs that contributed to the totals above"}},"required":["available","allocationRemaining","inventoryAvailable","skuCount"]},"PartnerProductListPricingExpansion":{"type":"object","description":"Per-row pricing summary returned when `expand=pricing` is set on `GET /products`. Bundles the seller-specific wholesale band (from `seller_allocations.price_per_key_cents`) with the publisher list price band already on `PartnerProduct`.","properties":{"wholesaleFromCents":{"type":["integer","null"],"description":"Lowest wholesale `price_per_key_cents` across the seller's active allocations for this product"},"wholesaleCurrencyCode":{"type":["string","null"],"description":"Currency for `wholesaleFromCents`"},"listPriceFromCents":{"type":["integer","null"],"description":"Echo of the list-price band on `PartnerProduct.listPriceFromCents` (publisher US list / SRP)"},"listPriceCurrencyCode":{"type":["string","null"]}},"required":["wholesaleFromCents","wholesaleCurrencyCode","listPriceFromCents","listPriceCurrencyCode"]},"CatalogSnapshot":{"type":"object","description":"Denormalised snapshot of the seller's full visible catalog. Every product carries the same fields as `PartnerProduct` plus the `availability` and `pricing` expansions.","properties":{"meta":{"type":"object","properties":{"totalProducts":{"type":"integer","description":"Number of products in the snapshot"},"maxUpdatedAt":{"type":["string","null"],"format":"date-time","description":"Watermark to use as `?updatedSince=` on the next `GET /products` delta sync"},"generatedAt":{"type":"string","format":"date-time","description":"Server-side timestamp when this snapshot was built"},"version":{"type":"integer","description":"Snapshot schema version"},"emptyReason":{"$ref":"#/components/schemas/SellerCatalogEmptyReason","description":"Present when `data` is empty — same semantics as GET /products meta.emptyReason."}},"required":["totalProducts","maxUpdatedAt","generatedAt","version"]},"data":{"type":"array","items":{"$ref":"#/components/schemas/PartnerProductWithExpansions"}}},"required":["meta","data"]},"CatalogIntegrityDigest":{"type":"object","description":"Cheap catalog integrity signal for mirroring without downloading `/catalog/snapshot`.","properties":{"totalProducts":{"type":"integer"},"maxUpdatedAt":{"type":["string","null"],"format":"date-time"},"digest":{"type":"string","description":"Lowercase hex SHA-256 of sorted lines `<product_uuid>|<updated_at_iso_or_empty>`"},"digestAlgorithm":{"type":"string","enum":["sha256-sorted-product-rows-v1"]},"generatedAt":{"type":"string","format":"date-time","description":"When this digest response was built (not part of the hashed material)"}},"required":["totalProducts","maxUpdatedAt","digest","digestAlgorithm","generatedAt"]},"PartnerProductWithExpansions":{"allOf":[{"$ref":"#/components/schemas/PartnerProduct"},{"type":"object","properties":{"availability":{"$ref":"#/components/schemas/PartnerProductListAvailabilityExpansion"},"pricing":{"$ref":"#/components/schemas/PartnerProductListPricingExpansion"}}}]},"SellerBundleItem":{"type":"object","properties":{"productId":{"type":"string"},"name":{"type":"string"},"slug":{"type":"string"}},"required":["productId","name","slug"]},"SellerExternalReference":{"type":"object","properties":{"owner":{"type":"string"},"source":{"type":"string"},"name":{"type":"string"},"value":{"type":"string"}},"required":["source","name","value"]},"SellerLocalizedDescription":{"type":"object","properties":{"locale":{"type":"string"},"short":{"type":["string","null"]},"long":{"type":["string","null"]},"promotional":{"type":["string","null"]},"legal":{"type":["string","null"]}},"required":["locale"]},"SellerAgeRating":{"type":"object","properties":{"authority":{"type":"string"},"authorityCode":{"type":"string"},"code":{"type":"string"},"label":{"type":"string"},"minAge":{"type":["integer","null"]}},"required":["code","label"]},"SellerTaxonomyTerm":{"type":"object","properties":{"code":{"type":"string"},"name":{"type":"string"}},"required":["code","name"]},"SellerProductAssets":{"type":"object","properties":{"screenshots":{"type":"array","items":{"type":"string","format":"uri"}},"trailers":{"type":"array","items":{"type":"string","format":"uri"}},"capsules":{"type":"array","items":{"type":"string","format":"uri"}}},"required":["screenshots","trailers","capsules"]},"SellerSystemRequirements":{"type":"object","properties":{"minimum":{"type":["string","null"]},"recommended":{"type":["string","null"]}}},"SellerEulaEntry":{"type":"object","properties":{"locale":{"type":"string"},"text":{"type":"string"}},"required":["locale","text"]},"SellerProductDetail":{"type":"object","properties":{"id":{"type":"string"},"readableId":{"type":"string","description":"Prefixed ID for debugging (e.g. prd_abc12345)"},"createdAt":{"type":["string","null"],"format":"date-time"},"updatedAt":{"type":["string","null"],"format":"date-time","description":"Product last-updated timestamp"},"name":{"type":"string"},"slug":{"type":"string"},"productType":{"type":["string","null"],"enum":["game","dlc","expansion","bundle","edition","soundtrack","currency","other",null],"description":"Closed taxonomy — build merchandising rules on these values; unknown legacy values are normalized to \"other\"."},"status":{"type":["string","null"],"deprecated":true,"enum":["draft","active","discontinued","archived",null],"description":"Deprecated legacy lifecycle rollup, derived from the lifecycle dimensions. Use launchPhase, tradingState, and isArchived instead."},"launchPhase":{"type":["string","null"],"enum":["draft","announced","pre_order","available",null],"description":"Rolled-up launch phase across the product's live SKUs."},"tradingState":{"type":["string","null"],"enum":["open","paused","discontinued",null],"description":"Rolled-up trading state: whether new commerce is permitted."},"isArchived":{"type":"boolean","description":"True when the product is archived and hidden from catalog surfaces."},"publisherCompanyId":{"type":"string"},"publisherCompanyName":{"type":"string"},"publisherCompanyDescription":{"type":["string","null"],"description":"Company public bio from company profile (not store short copy)"},"publisherWebsite":{"type":["string","null"],"format":"uri"},"publisherCountry":{"type":["string","null"]},"publisherCompanyImageUrl":{"type":["string","null"],"format":"uri"},"shortDescription":{"type":["string","null"]},"coverUrl":{"type":["string","null"]},"bundleItems":{"type":"array","description":"Present when this product is a bundle","items":{"$ref":"#/components/schemas/SellerBundleItem"}},"localizedDescriptions":{"type":"array","items":{"$ref":"#/components/schemas/SellerLocalizedDescription"}},"supportedLanguages":{"type":"array","items":{"type":"string"}},"ageRatings":{"type":"array","items":{"$ref":"#/components/schemas/SellerAgeRating"}},"genres":{"type":"array","items":{"$ref":"#/components/schemas/SellerTaxonomyTerm"}},"tags":{"type":"array","items":{"$ref":"#/components/schemas/SellerTaxonomyTerm"}},"features":{"type":"array","items":{"$ref":"#/components/schemas/SellerTaxonomyTerm"}},"eula":{"type":"array","items":{"$ref":"#/components/schemas/SellerEulaEntry"}},"assets":{"$ref":"#/components/schemas/SellerProductAssets"},"systemRequirements":{"$ref":"#/components/schemas/SellerSystemRequirements"},"editions":{"type":"array","items":{"$ref":"#/components/schemas/SellerProductDetailEdition"}},"refundPolicy":{"$ref":"#/components/schemas/RefundPolicy"}}},"SellerProductDetailEdition":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"slug":{"type":"string"},"editionType":{"type":["string","null"]},"sortOrder":{"type":"integer","description":"Catalog edition order (matches console)"},"shortDescription":{"type":["string","null"],"description":"Preferred-language store copy; may inherit from product when flagged or empty"},"longDescription":{"type":["string","null"]},"keyFeatures":{"type":"array","items":{"type":"string"}},"editionDifferentiator":{"type":["string","null"]},"inheritsProductDescription":{"type":"boolean"},"releases":{"type":"array","items":{"$ref":"#/components/schemas/SellerProductDetailRelease"}}}},"SellerProductDetailRelease":{"type":"object","properties":{"id":{"type":"string"},"platformCode":{"type":"string"},"platformName":{"type":"string"},"regionCode":{"type":["string","null"]},"regionName":{"type":["string","null"]},"status":{"type":["string","null"],"deprecated":true,"description":"Deprecated legacy release status. Use launchPhase and tradingState instead."},"launchPhase":{"type":["string","null"],"enum":["draft","announced","pre_order","available",null],"description":"Effective launch phase for this regional release (override inheritance + date auto-advance)."},"tradingState":{"type":["string","null"],"enum":["open","paused","discontinued",null],"description":"Effective trading state for this regional release (override inheritance)."},"releaseDate":{"type":["string","null"],"format":"date-time","description":"Release go-live instant (ISO 8601 date-time, UTC). Releases created before time-aware scheduling hold midnight UTC of their original calendar date."},"preorderStart":{"type":["string","null"],"description":"Pre-order window start (ISO 8601 datetime)"},"preorderEnd":{"type":["string","null"],"description":"Pre-order window end (ISO 8601 datetime)"},"preorderUnlocked":{"type":"boolean","description":"Whether pre-ordered keys have been unlocked for delivery"},"skus":{"type":"array","items":{"$ref":"#/components/schemas/SellerProductDetailSku"}},"pricing":{"type":"array","items":{"$ref":"#/components/schemas/SellerProductDetailPricing"}},"allowedCountries":{"type":"array","items":{"type":"string","minLength":2,"maxLength":2},"description":"ISO 3166-1 alpha-2 country codes where this SKU/release may be sold (publisher region pack minus release exclusions)."}}},"SellerProductDetailSku":{"type":"object","properties":{"id":{"type":"string"},"skuCode":{"type":"string"},"keyTypeCode":{"type":"string"},"keyTypeName":{"type":"string"},"skuType":{"type":"string","enum":["regular","bundle"]},"bundleItems":{"type":"array","items":{"$ref":"#/components/schemas/SellerBundleItem"}},"externalReferences":{"type":"array","items":{"$ref":"#/components/schemas/SellerExternalReference"}},"activation":{"$ref":"#/components/schemas/SkuActivation"}},"required":["id","skuCode","keyTypeCode","keyTypeName","skuType","externalReferences"]},"SellerProductDetailPricing":{"type":"object","properties":{"countryCode":{"type":["string","null"]},"currencyCode":{"type":"string"},"basePriceCents":{"type":"integer"}}},"PricingRelease":{"type":"object","description":"Per region-release list pricing row; aligns with product detail releases (edition, platform, region, schedule).","properties":{"releaseId":{"type":"string"},"editionId":{"type":"string"},"editionName":{"type":"string"},"editionSlug":{"type":"string"},"platformCode":{"type":"string"},"platformName":{"type":"string"},"regionCode":{"type":["string","null"]},"regionName":{"type":["string","null"]},"status":{"type":["string","null"],"deprecated":true,"description":"Deprecated legacy region-release or platform-release status. Use the release launchPhase / tradingState from GET /products/{productId}."},"releaseDate":{"type":["string","null"],"format":"date-time","description":"Release go-live instant (ISO 8601 date-time, UTC). Releases created before time-aware scheduling hold midnight UTC of their original calendar date."},"preorderStart":{"type":["string","null"]},"preorderEnd":{"type":["string","null"]},"preorderUnlocked":{"type":"boolean"},"prices":{"type":"array","items":{"type":"object","properties":{"countryCode":{"type":["string","null"]},"currencyCode":{"type":"string"},"basePriceCents":{"type":"integer"}}}}}},"SellerOrderFulfilledLine":{"type":"object","description":"One fulfilled SKU line in a GET /orders aggregate (from key pulls). Does not include plaintext keys.","required":["skuCode","allocationId","fulfilledQuantity","firstKeyPullId","orderReadableId"],"properties":{"skuCode":{"type":"string"},"allocationId":{"type":"string","format":"uuid"},"fulfilledQuantity":{"type":"integer","minimum":0},"firstKeyPullId":{"type":["string","null"],"format":"uuid"},"orderReadableId":{"type":["string","null"],"description":"Prefixed id from first pull (e.g. `ord_abc12345`)"}}},"SellerOrderPreOrderLine":{"type":"object","description":"One active pre-order reservation line in a GET /orders aggregate.","required":["skuCode","allocationId","reservedQuantity","reservedUntil"],"properties":{"skuCode":{"type":"string"},"allocationId":{"type":"string","format":"uuid"},"reservedQuantity":{"type":"integer","minimum":0},"reservedUntil":{"type":"string","format":"date-time"}}},"SellerOrderAggregate":{"type":"object","description":"Aggregate fulfilment state for a store `orderReference`: completed key pulls plus active pre-order reservations. Matches `fetchSellerOrderByReference` / `fetchSellerOrderByReadableId`. Never includes plaintext keys.","required":["orderReference","fulfilled","preOrderActive","status","refunds"],"properties":{"orderReference":{"type":"string","description":"Your store order id (same value passed on create/pull)."},"fulfilled":{"type":"array","items":{"$ref":"#/components/schemas/SellerOrderFulfilledLine"}},"preOrderActive":{"type":"array","items":{"$ref":"#/components/schemas/SellerOrderPreOrderLine"}},"status":{"type":"string","enum":["preordered","awaiting_release","awaiting_stock","ready","partially_fulfilled","fulfilled","cancelled","returned","refunded","failed"],"description":"Reconstruction default is preordered|fulfilled|returned|refunded. When durable-order reads are on, status comes from sales.orders (awaiting_release, awaiting_stock, ready, …)."},"refunds":{"type":"array","description":"Refund/chargeback/return records against this reference.","items":{"type":"object","required":["refundId","status","keyIds"],"properties":{"refundId":{"type":"string"},"status":{"type":"string","enum":["pending","completed","chargeback_open","chargeback_lost","chargeback_won"]},"keyIds":{"type":"array","items":{"type":"string","format":"uuid"}}}}},"orderId":{"type":["string","null"],"description":"Readable order id (ord_…). Durable-derived when first-class order reads are on; otherwise from the first key pull."},"qtyRequested":{"type":"integer"},"qtyPending":{"type":"integer"},"qtyAssigned":{"type":"integer"},"qtyRevealed":{"type":"integer"}}},"SellerTransaction":{"type":"object","properties":{"id":{"type":"string"},"readableId":{"type":"string","description":"Prefixed order ID (e.g. ord_abc12345)"},"allocationId":{"type":"string"},"skuCode":{"type":"string"},"quantity":{"type":"integer"},"orderReference":{"type":["string","null"]},"pulledAt":{"type":"string"},"salesCountryCode":{"type":["string","null"],"description":"Declared `integrationOrderContext.salesCountryCode` at pull time; null for pulls recorded before typed geo columns."},"detectedCountryCode":{"type":["string","null"],"description":"ISO 3166-1 alpha-2 country resolved from the buyer IP by the consumer geo gate at pull time. Null when geo ran in `off` mode, no `consumerIp` was supplied, or the row predates typed geo columns. The raw IP is never returned."},"countryMismatch":{"type":["boolean","null"],"description":"True when the declared country and `detectedCountryCode` disagree; null when either side is unknown."},"warnings":{"type":"array","items":{"type":"string","enum":["COUNTRY_MISMATCH"]},"description":"Machine-readable reconciliation flags. `COUNTRY_MISMATCH`: the buyer IP resolved to a different country than the declared `salesCountryCode`. Empty when nothing was flagged or geo did not run."}}},"SellerApiKeyMasked":{"type":"object","description":"API key metadata without the secret","properties":{"id":{"type":"string","format":"uuid"},"name":{"type":"string"},"prefix":{"type":["string","null"]},"lastChars":{"type":["string","null"]},"createdAt":{"type":["string","null"],"format":"date-time"},"expiresAt":{"type":["string","null"],"format":"date-time"},"lastUsedAt":{"type":["string","null"],"format":"date-time"}}},"SellerApiKeyCreateRequest":{"type":"object","required":["name"],"properties":{"name":{"type":"string","minLength":1,"maxLength":120,"description":"Display name for the key"},"allowed_ips":{"type":"array","maxItems":50,"items":{"type":"string","description":"IPv4/IPv6 literal or CIDR (e.g. `203.0.113.5`, `203.0.113.0/24`, `2001:db8::1`, `2001:db8::/48`). Reserved/private ranges (RFC1918, loopback, link-local, CGNAT, IPv6 ULA) are rejected. `/0` networks are rejected.","example":"203.0.113.5"},"description":"Optional egress IP allowlist (0–50 entries). When the calling key is unrestricted: omitted or empty means requests from any source IP are accepted. When the calling key is IP-restricted: omitting inherits the calling key's allowlist, and provided entries must be a non-empty subset of it (widening is rejected with `403`). When configured, requests from other IPs are rejected with `403 IP_NOT_ALLOWED`. Strongly recommended — see `https://docs.avrix.io/seller-api/ip-allowlist`."},"includeFinanceScope":{"type":"boolean","description":"When `true`, adds `seller:finance:read` (finance summary, per-key API sales, invoices) to the new key. Requires the calling key to hold `seller:finance:read`; otherwise the request is rejected with `403 INSUFFICIENT_SCOPE`."}}},"SellerApiKeyAllowedIpsUpdateRequest":{"type":"object","required":["allowed_ips"],"properties":{"allowed_ips":{"type":"array","maxItems":50,"items":{"type":"string","example":"203.0.113.5"},"description":"Replacement IP allowlist (0–50 entries). Pass an empty array to remove IP restriction. Replaces the entire list; PATCH is treated as a full replacement, not a merge."}}},"SellerApiKeyCreated":{"type":"object","description":"Returned once when a key is created","properties":{"id":{"type":"string","format":"uuid"},"name":{"type":"string"},"key":{"type":"string","description":"Full secret; never returned again"},"livemode":{"type":"boolean","description":"True when NODE_ENV is production"}}},"SellerApiSaleTransaction":{"type":"object","description":"Per-key commercial ledger row exposed to sellers for ERP reconciliation. Includes settlement, fee, share, contract stamp, and declared retail context captured at pull time.","properties":{"id":{"type":"string","format":"uuid"},"publisherCompanyId":{"type":"string"},"keyPullId":{"type":["string","null"],"format":"uuid"},"keyId":{"type":["string","null"],"format":"uuid"},"skuId":{"type":"string","format":"uuid"},"productId":{"type":"string","format":"uuid"},"salePriceCents":{"type":"integer","description":"Billed unit price for this key (settlement promo already applied — see `promo`)."},"initialSalePriceCents":{"type":["integer","null"],"description":"Catalog list unit price before any settlement promo. Null on rows recorded before promo provenance existed; otherwise equal to `salePriceCents` when no promo applied."},"promo":{"type":["object","null"],"description":"Settlement promo that discounted `salePriceCents`, or null. Filter statements by `sourceId` to attribute discounts to a campaign.","required":["sourceType","sourceId"],"properties":{"sourceType":{"type":"string","enum":["event","custom"]},"sourceId":{"type":"string","description":"shareId (`event`) or responseId (`custom`) under /promotions."}}},"currencyCode":{"type":"string","description":"Allocation / settlement currency for this API sale row."},"publisherShareCents":{"type":"integer"},"sellerShareCents":{"type":"integer"},"platformFeeCents":{"type":"integer"},"revenueSharePercent":{"type":["number","null"]},"saleTimestamp":{"type":"string","format":"date-time"},"aggregationStatus":{"type":"string"},"reportId":{"type":["string","null"],"format":"uuid"},"orderReference":{"type":["string","null"]},"customerRegionCode":{"type":["string","null"],"description":"Declared `integrationOrderContext.salesCountryCode` at pull time (ISO 3166-1 alpha-2)."},"detectedCountryCode":{"type":["string","null"],"description":"ISO 3166-1 alpha-2 country resolved from the buyer IP by the consumer geo gate at pull time. Null when geo ran in `off` mode, no `consumerIp` was supplied, or the row predates typed geo columns. The raw IP is never returned."},"countryMismatch":{"type":["boolean","null"],"description":"True when the declared country and `detectedCountryCode` disagree; null when either side is unknown."},"warnings":{"type":"array","items":{"type":"string","enum":["COUNTRY_MISMATCH"]},"description":"Machine-readable reconciliation flags. `COUNTRY_MISMATCH`: the buyer IP resolved to a different country than the declared `salesCountryCode`. Empty when nothing was flagged or geo did not run."},"contractTermId":{"type":["string","null"],"format":"uuid"},"contractTermVersion":{"type":"integer"},"adjustmentStatus":{"type":"string","enum":["none","refund_pending","refunded","chargeback_open","chargeback_lost","chargeback_won"],"description":"Current adjustment/reversal state for this transaction. `none` means no linked API finance adjustment is recorded yet."},"declaredRetail":{"type":["object","null"],"description":"Normalized declared retail checkout evidence from integrationOrderContext for ERP reconciliation.","properties":{"retailCurrencyCode":{"type":["string","null"]},"grossMinor":{"type":["integer","null"]},"netMinor":{"type":["integer","null"]},"taxAmountMinor":{"type":["integer","null"]},"taxRatePercent":{"type":["number","null"]},"priceIncludesTax":{"type":["boolean","null"]},"paymentMethodFamily":{"type":["string","null"]},"paymentProcessorReference":{"type":["string","null"]},"checkoutSessionId":{"type":["string","null"]},"purchaseOrderNumber":{"type":["string","null"]}}},"integrationOrderContext":{"anyOf":[{"$ref":"#/components/schemas/IntegrationOrderContext"},{"type":"null"}]},"taxMetadata":{"type":["object","null"],"description":"Seller-declared tax evidence extracted from integrationOrderContext. Avrix is not the tax authority — `authoritative` is always false; amounts are what YOUR checkout declared, surfaced back for reconciliation and audit. This is the DECLARATION your store sent. What the Platform settled on is in `settlement`.","properties":{"declaredTaxAmountMinor":{"type":["integer","null"]},"declaredTaxRatePercent":{"type":["number","null"]},"priceIncludesTax":{"type":["boolean","null"]},"authoritative":{"type":"boolean","enum":[false]}},"required":["declaredTaxAmountMinor","declaredTaxRatePercent","priceIncludesTax","authoritative"]},"settlement":{"anyOf":[{"$ref":"#/components/schemas/SellerApiSaleSettlement"},{"type":"null"}],"description":"Null on a sale that predates the settlement basis, or one quarantined before it could be settled."},"entryType":{"type":"string","enum":["sale","sale_reversal","sale_reinstatement"],"description":"`sale`, or the entry that took one back. A reversal carries negated amounts."},"reversesTransactionId":{"type":["string","null"],"format":"uuid","description":"Set on a reversal: the sale it undoes."}}},"PaginationMeta":{"type":"object","properties":{"total":{"type":"integer"},"limit":{"type":"integer"},"hasMore":{"type":"boolean"},"nextCursor":{"type":["string","null"]},"nextUrl":{"type":["string","null"],"description":"Absolute URL continuing this request with `cursor` set to `nextCursor`. Null when there is no next page."},"localePreference":{"type":["string","null"],"description":"Present on GET /products: pipe-separated language codes used to resolve `shortDescription` (e.g. de|en)."},"emptyReason":{"$ref":"#/components/schemas/SellerCatalogEmptyReason","description":"Present when `data` is empty on GET /products or GET /catalog/snapshot — explains why the catalog feed returned zero rows."}}},"SellerCatalogEmptyReason":{"type":"string","enum":["noActiveBma","noActiveShares","noMatchingFilter","ok"],"description":"Why a catalog list/snapshot returned zero products. See https://docs.avrix.io/seller-api/sellable-sku-readiness."},"IntegrationOrderContextWebhookRedacted":{"type":"object","description":"PII-minimized subset of integrationOrderContext included on some order webhooks (no consumer IP, VAT, or PSP references). See https://docs.avrix.io/seller-api/webhooks.","additionalProperties":false,"properties":{"schemaVersion":{"type":"integer","enum":[1]},"salesCountryCode":{"type":"string"},"currencyCode":{"type":"string"},"salesPriceGrossMinor":{"type":"integer","minimum":0},"salesPriceNetMinor":{"type":"integer","minimum":0},"appliedDiscountPercentage":{"type":"number"},"appliedDiscountAmountMinor":{"type":"integer","minimum":0},"buyerLocale":{"type":"string"},"priceIncludesTax":{"type":"boolean"},"salesTaxAmountMinor":{"type":"integer","minimum":0},"salesTaxRatePercent":{"type":"number"},"purchaseOrderNumber":{"type":"string"},"customerType":{"type":"string","enum":["b2c","b2b"]},"paymentMethodFamily":{"type":"string","enum":["card","wallet","paypal","ideal","bancontact","sepa_debit","invoice","store_credit","gift_card","crypto","other"]},"salesChannel":{"type":"string","description":"Which surface the sale was declared to have come through. Echoed from the order.","example":"web"},"checkoutSessionId":{"type":"string"},"lineIndex":{"type":"integer"},"parentOrderReference":{"type":"string"},"externalMarketplaceOrderId":{"type":"string"}}},"WebhookOrderFulfilled":{"type":"object","description":"Payload for order.fulfilled webhook event. Never contains key plaintext — deliveries are redacted before dispatch. Plaintext keys are returned only in the synchronous POST /orders (or POST /keys/pull) response.","properties":{"eventId":{"type":"string"},"orderReference":{"type":["string","null"]},"deliveryMode":{"type":"string","enum":["key","keyless"]},"keyIds":{"type":"array","items":{"type":"string","format":"uuid"},"description":"Key UUIDs (never plaintext) for the delivered keys. Persist these to call POST /refunds or POST /keys/return later. Omitted when deliveryMode is keyless."},"delivery":{"$ref":"#/components/schemas/SellerOrderKeylessDelivery"},"pulled":{"type":"integer"},"allocationId":{"type":"string"},"orderReadableId":{"type":"string"},"deferredReveal":{"type":"boolean"},"exportFormat":{"type":"string","description":"Present when fulfilled via /keys/export (value: zip)"},"integrationOrderContextRedacted":{"allOf":[{"$ref":"#/components/schemas/IntegrationOrderContextWebhookRedacted"}],"description":"Declared retail correlation fields when integrationOrderContext was sent on the request. Omitted when absent."},"contractTermId":{"type":"string","format":"uuid"},"contractTermVersion":{"type":"integer","minimum":1},"materialHash":{"type":"string"}}},"WebhookOrderActivated":{"type":"object","description":"Payload for order.activated webhook event (keyless buyer activation)","properties":{"eventId":{"type":"string"},"orderReference":{"type":["string","null"]},"fulfillmentId":{"type":"string","format":"uuid"},"provider":{"type":"string","enum":["hosted_redemption","steam_gift","epic_entitlement","gog_connect"]},"method":{"type":"string","enum":["buyer_reveal","platform_activation"]},"platformCode":{"type":"string"},"integrationOrderContextRedacted":{"allOf":[{"$ref":"#/components/schemas/IntegrationOrderContextWebhookRedacted"}]}}},"WebhookOrderReserved":{"type":"object","description":"Payload for order.reserved webhook event (pre-order)","properties":{"eventId":{"type":"string"},"orderReference":{"type":["string","null"]},"reserved":{"type":"integer"},"allocationId":{"type":"string"},"skuId":{"type":"string"},"releaseDate":{"type":["string","null"],"format":"date-time","description":"Release go-live instant (ISO 8601 date-time, UTC)."},"integrationOrderContextRedacted":{"allOf":[{"$ref":"#/components/schemas/IntegrationOrderContextWebhookRedacted"}],"description":"Declared retail correlation fields when integrationOrderContext was sent on the request. Omitted when absent."}}},"WebhookOrderReturned":{"type":"object","description":"Payload for order.returned webhook event (pre-order cancellation)","properties":{"eventId":{"type":"string"},"orderReference":{"type":"string"},"cancelled":{"type":"integer"},"reason":{"type":["string","null"]}}},"WebhookOrderKeysReturned":{"type":"object","description":"Payload for order.keys_returned webhook event (post-fulfillment key return via POST /keys/return)","properties":{"eventId":{"type":"string"},"keyIds":{"type":"array","items":{"type":"string","format":"uuid"}},"returned":{"type":"integer"},"reason":{"type":["string","null"]}}},"WebhookProductUpdated":{"type":"object","description":"Payload for product.updated webhook event","properties":{"eventId":{"type":"string"},"productId":{"type":"string"},"publisherCompanyId":{"type":"string"},"productName":{"type":["string","null"]},"productSlug":{"type":["string","null"]},"productStatus":{"type":["string","null"],"deprecated":true,"enum":["draft","active","discontinued","archived",null],"description":"Deprecated legacy lifecycle rollup, derived from the lifecycle dimensions. Use launchPhase, tradingState, and isArchived instead."},"launchPhase":{"type":["string","null"],"enum":["draft","announced","pre_order","available",null],"description":"Rolled-up launch phase across the product's live SKUs."},"tradingState":{"type":["string","null"],"enum":["open","paused","discontinued",null],"description":"Rolled-up trading state: whether new commerce is permitted."},"isArchived":{"type":"boolean","description":"True when the product is archived and hidden from catalog surfaces."},"updatedAt":{"type":"string","format":"date-time"}}},"WebhookAllocationUpdated":{"type":"object","description":"Payload for allocation.updated webhook event","properties":{"eventId":{"type":"string"},"allocationId":{"type":"string"},"skuId":{"type":"string"},"quantityLimit":{"type":"integer"},"quantityPulled":{"type":"integer"},"status":{"type":"string"}}},"SellerContractTermStamp":{"type":"object","description":"Governing active BMA term recorded at fulfillment time. On mutating routes (`POST /orders`, `/keys/pull`, `/orders/commit`, `/orders/bulk` line items, and idempotent replay bodies for `/keys/export`) these fields appear when term metadata is available — use for finance reconciliation and idempotent replay parity.","properties":{"contractTermId":{"type":"string","format":"uuid","description":"Active `connection_contract_terms.id` for the pull"},"contractTermVersion":{"type":"integer","minimum":1,"description":"Term version at pull time (defaults to 1 when omitted)"},"materialHash":{"type":"string","description":"SHA-256 hex of frozen document_snapshot when populated on the governing term"}}},"SellerOrderFulfilledData":{"type":"object","description":"Keys delivered, deferred reveal, or keyless delivery. **Wholesale settlement** uses allocation/pricing — not overridden by `integrationOrderContext`. **fulfilledAt** is included when the first key pull timestamp exists. **orderReadableId** (`ord_…`) is included when an internal pull id exists. **contractTermId** / **contractTermVersion** may appear at the **response root** (sibling of `data`), not inside `data` — see `SellerContractTermStamp`. When `deliveryMode` is `keyless`, plaintext `keys` are omitted and `delivery` carries the hosted redemption reference.","required":["type","skuId","pulled","allocationId"],"properties":{"type":{"type":"string","enum":["fulfilled"]},"deliveryMode":{"type":"string","enum":["key","keyless"],"default":"key","description":"keyless when POST /orders used deliveryMode:keyless"},"skuId":{"type":"string","format":"uuid"},"skuCode":{"type":["string","null"]},"orderReference":{"type":["string","null"]},"keys":{"type":"array","items":{"type":"string"},"description":"Plaintext key codes. Omitted or empty when deliveryMode is keyless or deferredReveal is true."},"keyIds":{"type":"array","items":{"type":"string","format":"uuid"},"description":"Key UUIDs (never plaintext) for the delivered keys, in the same order as `keys`. Persist these to call POST /refunds or POST /keys/return later. Omitted when deliveryMode is keyless."},"delivery":{"$ref":"#/components/schemas/SellerOrderKeylessDelivery"},"pulled":{"type":"integer","minimum":0},"allocationId":{"type":"string","format":"uuid"},"fulfilledAt":{"type":"string","format":"date-time","description":"Omitted if no timestamp recorded"},"orderReadableId":{"type":"string","description":"Omitted if not yet assigned"},"deferredReveal":{"type":"boolean","description":"When true, keys were assigned but plaintext is omitted from this HTTP response. Webhooks do not carry plaintext keys — persist from POST when present or use the recovery path in https://docs.avrix.io/seller-api/webhooks."},"activation":{"$ref":"#/components/schemas/SkuActivation","description":"Where the delivered key can be activated — the guaranteed intersection across the SKU's inventory batches, not the specific batch this key came from. Same object as GET /allocations and POST /orders/preview lines. Show it as \"activates in\" at delivery time without a second lookup."}}},"SellerOrderKeylessDelivery":{"type":"object","description":"Keyless delivery reference for hosted_redemption and future platform-native providers.","required":["provider","fulfillmentId"],"properties":{"provider":{"type":"string","enum":["hosted_redemption","steam_gift","epic_entitlement","gog_connect"]},"redemptionUrl":{"type":["string","null"],"format":"uri","description":"Hosted one-time buyer URL (hosted_redemption only)"},"providerRef":{"type":["string","null"],"description":"External entitlement/order id for platform-native providers"},"fulfillmentId":{"type":"string","format":"uuid"},"expiresAt":{"type":["string","null"],"format":"date-time"}}},"SellerKeylessFulfillmentRevokeResult":{"type":"object","required":["fulfillmentId","revoked","status"],"properties":{"fulfillmentId":{"type":"string","format":"uuid"},"revoked":{"type":"boolean"},"status":{"type":"string","enum":["issued","viewed","activated","redeemed","expired","revoked","failed"]}}},"SellerOrderPreorderData":{"type":"object","description":"Pre-order: keys reserved until release. No `keys` in this variant.","required":["type","skuId","reserved","allocationId"],"properties":{"type":{"type":"string","enum":["pre-order"]},"skuId":{"type":"string","format":"uuid"},"skuCode":{"type":["string","null"]},"orderReference":{"type":["string","null"]},"reserved":{"type":"integer","minimum":0},"allocationId":{"type":"string","format":"uuid"},"releaseDate":{"type":["string","null"],"format":"date-time","description":"Release go-live instant (ISO 8601 date-time, UTC)."},"preorderStart":{"type":["string","null"]},"preorderEnd":{"type":["string","null"]},"activation":{"$ref":"#/components/schemas/SkuActivation","description":"Where the delivered key can be activated — the guaranteed intersection across the SKU's inventory batches, not the specific batch this key came from. Same object as GET /allocations and POST /orders/preview lines. Show it as \"activates in\" at delivery time without a second lookup."}},"x-avrix-capability":"preorder"},"IntegrationOrderContext":{"type":"object","description":"Declared retail / checkout context. Money fields are minor units in **currencyCode** (retail) and do **not** replace wholesale settlement. API catalog orders require `salesTaxRatePercent`, `salesPriceGrossMinor`, and `salesCountryCode` (422 `TAX_DECLARATION_REQUIRED` / `SALES_COUNTRY_REQUIRED` if omitted, including JSON `null`). **Production API keys** on API allocations also require commercial evidence fields (tax, PSP ref, checkout session id). `consumerIp` receives shape validation unless `whoami.capabilities.consumerGeoEnforcementEnabled` is true. See `https://docs.avrix.io/seller-api/order-context` and `https://docs.avrix.io/seller-api/territory`. Max serialized size **8192 bytes**.","required":["schemaVersion"],"additionalProperties":false,"properties":{"schemaVersion":{"type":"integer","enum":[1]},"consumerIp":{"type":"string","description":"End-customer IPv4 or IPv6 (public routable). When `whoami.capabilities.consumerGeoEnforcementEnabled` is true, buyer IP must match `salesCountryCode` and VPN/hosting/Tor are rejected (422). `CONSUMER_GEO_UNAVAILABLE` is 503 + Retry-After. During monitor (`consumerGeoMonitorEnabled`) the same checks emit additive `geoWarning` on 200 instead of blocking. Otherwise only IP shape is validated."},"salesCountryCode":{"type":"string","minLength":2,"maxLength":2,"description":"ISO 3166-1 alpha-2 declared sales territory. Required for API allocations and SKU allowedCountries checks. When `whoami.capabilities.consumerGeoEnforcementEnabled` is true, buyer IP must match `salesCountryCode` and VPN/hosting/Tor are rejected (422). `CONSUMER_GEO_UNAVAILABLE` is 503 + Retry-After. During monitor (`consumerGeoMonitorEnabled`) the same checks emit additive `geoWarning` on 200 instead of blocking. Otherwise only IP shape is validated."},"currencyCode":{"type":"string","minLength":3,"maxLength":3,"description":"ISO 4217 retail currency for gross/net minors"},"salesPriceGrossMinor":{"type":"integer","minimum":0,"description":"Retail gross in minor units of currencyCode"},"salesPriceNetMinor":{"type":"integer","minimum":0},"appliedDiscountPercentage":{"type":"number","minimum":0,"maximum":100},"appliedDiscountAmountMinor":{"type":"integer","minimum":0},"immediateFulfilment":{"type":"boolean"},"mustFulfil":{"type":"boolean"},"buyerLocale":{"type":"string","maxLength":35,"description":"BCP 47-style locale (e.g. en-NL)"},"priceIncludesTax":{"type":"boolean","description":"Whether salesPriceGrossMinor includes tax"},"salesTaxAmountMinor":{"type":"integer","minimum":0},"salesTaxRatePercent":{"type":"number","minimum":0,"maximum":100,"description":"Rate applied at checkout, as a percentage (21 for 21%). Required on API catalog orders; omitted or JSON null is 422 TAX_DECLARATION_REQUIRED."},"customerVatNumber":{"type":"string","maxLength":32,"description":"EU VAT or tax id; audit only"},"purchaseOrderNumber":{"type":"string","maxLength":64},"customerType":{"type":"string","enum":["b2c","b2b"]},"paymentMethodFamily":{"type":"string","enum":["card","wallet","paypal","ideal","bancontact","sepa_debit","invoice","store_credit","gift_card","crypto","other"],"description":"Non-PCI payment category"},"paymentProcessorReference":{"type":"string","maxLength":128,"description":"PSP or wallet transaction id"},"checkoutSessionId":{"type":"string","maxLength":128},"salesChannel":{"type":"string","maxLength":64,"description":"Which of your own surfaces the sale came through: web, mobile_app, partner_embed, or marketplace:<slug>. Required on API catalog orders: omitting it is refused with 422 SALES_CHANNEL_REQUIRED, and a channel your agreement's Commercial Schedule does not permit with 422 SALES_CHANNEL_NOT_PERMITTED. Not added to this schema's required list because the same object is also sent on non-catalog flows where it does not apply.","example":"web"},"lineIndex":{"type":"integer","minimum":0,"maximum":999},"parentOrderReference":{"type":"string","maxLength":255},"externalNetworkOrderId":{"type":"string","maxLength":255,"description":"External marketplace / network order id (alias: externalMarketplaceOrderId)"},"consumerIpHash":{"type":"string","readOnly":true,"description":"Response-only. Peppered, truncated sha256 of the `consumerIp` you sent. The raw address is resolved at request time (territory cross-check, VPN/hosting block) and never stored; finance and transaction reads return this hash instead so support can correlate orders from the same network."},"consumerIpRedacted":{"type":"boolean","readOnly":true,"description":"Response-only. True on rows recorded before hashing existed whose raw `consumerIp` was removed by the retention backfill."}}},"ApiError":{"type":"object","description":"Structured error response for 4xx/5xx responses. All error responses include X-Api-Version and X-Request-Id headers.","properties":{"code":{"type":"string","description":"Canonical error code (e.g. BAD_REQUEST, NOT_FOUND, NO_AVAILABLE_KEYS, ALLOCATION_EXCEEDED, PRODUCT_NOT_SELLABLE, WHOLESALE_PRICE_MISMATCH, IDEMPOTENCY_KEY_MISMATCH, CONFLICT, CONTRACT_NOT_ACTIVE, MINIMUM_ORDER_VIOLATION, PAYMENT_NOT_CLEARED, INSUFFICIENT_WALLET_BALANCE, KYB_NOT_VERIFIED, TREASURY_CAPABILITY_MISSING, PREORDER_STATE_UNAVAILABLE, PAYLOAD_TOO_LARGE, UNAUTHORIZED, FORBIDDEN, RATE_LIMIT_EXCEEDED); commercial enforcement: CATALOG_PRICE_NOT_SET, CATALOG_PRICE_MISMATCH, INVALID_CATALOG_PRICE, TERRITORY_NOT_ALLOWED_FOR_SKU, TERRITORY_EXCLUDED_FOR_RELEASE, SKU_REGION_UNRESOLVED, CONSUMER_IP_REQUIRED, CONSUMER_IP_INVALID, CONSUMER_GEO_MISMATCH, CONSUMER_IP_HIGH_RISK, CONSUMER_GEO_UNAVAILABLE, SALES_COUNTRY_REQUIRED, TAX_DECLARATION_REQUIRED","enum":["ACTIVATION_REGION_MISMATCH","ACTIVATION_REGION_UNKNOWN","ALLOCATION_EXCEEDED","ALLOCATION_NOT_AVAILABLE","ALLOWLIST_REQUIRED","ALREADY_ACTIVATED","API_MODEL_AGREEMENT_REQUIRED","BACKORDER_NOT_ALLOWED","BAD_REQUEST","BILLING_RECORD_FAILED","BUSINESS_MODEL_NOT_ALLOWED","CATALOG_PRICE_MISMATCH","CATALOG_PRICE_NOT_SET","CHECKOUT_HOLD_DISABLED","CONFLICT","CONSUMER_GEO_ATTEST_REQUIRED","CONSUMER_GEO_MISMATCH","CONSUMER_GEO_MISMATCH_POLICY_REFUSED","CONSUMER_GEO_UNAVAILABLE","CONSUMER_IP_HIGH_RISK","CONSUMER_IP_INVALID","CONSUMER_IP_REQUIRED","CONTRACT_NOT_ACTIVE","COUNTRY_RESTRICTED","CURRENCY_MISMATCH","CURRENCY_NOT_PERMITTED_BY_TERM","CURRENCY_NOT_PRICED_FOR_COUNTRY","EXPECTED_PRICE_CONFLICT","EXPECTED_UNIT_PRICE_REQUIRED","EXPORT_EXPIRED","FEATURE_DISABLED","FOOTPRINT_COUNTRY_NOT_DECLARED","FOOTPRINT_CURRENCY_NOT_DECLARED","FORBIDDEN","HOLD_MISMATCH","HOLD_NOT_FOUND","HOT_DROP_NOT_ENABLED","HOT_PATH_TIMEOUT","IDEMPOTENCY_KEY_MISMATCH","IDEMPOTENCY_REQUEST_IN_FLIGHT","IDEMPOTENCY_STORE_UNAVAILABLE","INSUFFICIENT_SCOPE","INSUFFICIENT_WALLET_BALANCE","INTERNAL_ERROR","INVALID_CATALOG_PRICE","INVALID_CLIENT","IP_NOT_ALLOWED","IP_NOT_RESOLVABLE","KEYLESS_ISSUANCE_FAILED","KEY_DECRYPT_FAILED","KEY_ENVIRONMENT_MISMATCH","KYB_NOT_VERIFIED","LOCATION_BLOCKED","MINIMUM_ORDER_VIOLATION","NOT_FOUND","NOT_IMPLEMENTED","NO_ACTIVE_BMA","NO_AVAILABLE_KEYS","ORDER_NOT_READY","ORDER_REFERENCE_CONFLICT","PAYLOAD_TOO_LARGE","PAYMENT_NOT_CLEARED","PREORDER_STATE_UNAVAILABLE","PRICE_COMMITMENT_EXPIRED","PRICE_COMMITMENT_INVALID","PRODUCTION_ACCESS_NOT_APPROVED","PRODUCT_NOT_SELLABLE","QUANTITY_INVALID","RATE_LIMIT_EXCEEDED","REGENERATE_NOT_SUPPORTED","RESERVATION_COMMIT_IN_PROGRESS","RESERVATION_EXTEND_EXHAUSTED","RESERVATION_GONE","SALES_CHANNEL_NOT_PERMITTED","SALES_CHANNEL_REQUIRED","SALES_COUNTRY_REQUIRED","SANDBOX_MAGIC_VALUE_REJECTED","SERVICE_UNAVAILABLE","SKU_REGION_UNRESOLVED","SRP_MISMATCH_FOR_CURRENCY","TAX_DECLARATION_REQUIRED","TERRITORY_EXCLUDED_FOR_RELEASE","REGION_LOCKED_FOR_CONTRACT","REGION_LOCKED_FOR_SKU","TERRITORY_NOT_ALLOWED_FOR_SKU","TREASURY_CAPABILITY_MISSING","UNAUTHORIZED","UNSUPPORTED_API_VERSION","VALIDATION_FAILED","WHOLESALE_PRICE_MISMATCH"]},"message":{"type":"string","description":"Human-readable error message"},"error":{"type":"string","description":"Deprecated. Use message instead. Kept for backward compatibility.","deprecated":true},"timestamp":{"type":"string","format":"date-time"},"recoverable":{"type":"boolean","description":"Whether the client can retry and recover"},"hint":{"type":"string","description":"Human-readable hint for recovery"},"doc_url":{"type":"string","format":"uri","description":"URL to relevant documentation"},"requestId":{"type":"string","description":"Request ID for traceability (echoes X-Request-Id when provided)"},"details":{"type":"object","description":"Additional error details (e.g. validation `issues`, `requestBodyHash` for `IDEMPOTENCY_KEY_MISMATCH`, or `missingScope` / `requiredScopes` for FORBIDDEN when a route scope is missing). Commercial refusals on the order path carry the refusing guard's own detail: `fixItUrl` for a footprint refusal, `floorMinor` for a secondary-currency floor, `declaredCountry` and `detectedCountry` for a geo refusal.","properties":{"missingScope":{"type":"string","description":"Present on some 403 FORBIDDEN responses when the API key lacks a required scope"},"requiredScopes":{"type":"array","items":{"type":"string"},"description":"Scopes required for this operation (e.g. single entry matching missingScope)"},"requestBodyHash":{"type":"string","description":"SHA-256 hex digest of canonical JSON body (idempotency mismatch responses only)"},"issues":{"type":"array","description":"Field-level errors for VALIDATION_FAILED (query or JSON body)","items":{"type":"object","properties":{"field":{"type":"string"},"message":{"type":"string"}}}},"validationTarget":{"type":"string","enum":["query","json_body","path"],"description":"Where validation ran — use with details.issues for client routing and logging"},"decisionCode":{"type":"string","description":"Contract authority code on pull/order failures (e.g. SKU_SHARE_MISSING, BMA_NOT_SIGNED)"},"remediation":{"type":"string","description":"Partner-facing next step when decisionCode is present"},"pullError":{"type":"string","description":"Canonical pull/fulfil error branch (mirrors top-level code on order failures; legacy parsers)"},"recommendedAction":{"type":"string","description":"Machine-readable next step for store integrations (e.g. refund_customer, retry_same_idempotency_key, fix_request_body_or_new_key). See https://docs.avrix.io/seller-api/errors.","enum":["refund_customer","retry_same_idempotency_key","fix_request_body_or_new_key","reduce_quantity_or_wait_for_stock","request_allocation_increase","retry_after_backoff","check_scopes_and_allowlist","sign_bma_with_publisher","fallback_to_profile_b_checkout","fallback_to_post_orders_without_hold","complete_account_verification","wait_for_preorder_window","wait_for_release","request_preorder_capability","delist_sku"]},"postPaymentRecovery":{"type":"string","description":"Legacy hint when NO_AVAILABLE_KEYS after external checkout (e.g. refund_customer)"},"remainingInAllocation":{"type":"integer","description":"Keys still available under the allocation cap (present on ALLOCATION_EXCEEDED, and on legacy NO_AVAILABLE_KEYS allocation shortfalls)"},"previewError":{"type":"string","description":"Preview denial branch (e.g. CATALOG_PRICE_NOT_SET, TERRITORY_NOT_ALLOWED_FOR_SKU, CONSUMER_GEO_MISMATCH, CONTRACT_NOT_ACTIVE when the granting agreement is paused)"},"expectedUnitPriceCents":{"type":"integer","description":"Catalog list price expected on CATALOG_PRICE_MISMATCH"},"salesCountryCode":{"type":"string","description":"Declared country on territory/geo failures"},"consumerIpCountry":{"type":"string","description":"Country derived from consumerIp only when geo/VPN cross-check enforcement is enabled."},"readiness":{"type":"array","items":{"type":"string","enum":["NO_SKU_SHARE","NO_ALLOCATION","NO_TERRITORY_PRICING"]},"description":"Sellable-SKU gate blockers on availability/preview denials. See https://docs.avrix.io/seller-api/sellable-sku-readiness."},"fixItUrl":{"type":"string","description":"Present on FOOTPRINT_COUNTRY_NOT_DECLARED and FOOTPRINT_CURRENCY_NOT_DECLARED: the console path where the seller fixes its own footprint. A relative path under the console origin."},"floorMinor":{"type":"integer","description":"Present on SRP_MISMATCH_FOR_CURRENCY when a floor could be computed: the minimum price in the declared currency, in minor units, the catalog SRP converted at the day's reference rate."},"countryCode":{"type":"string","description":"Present on footprint and territory refusals: the ISO 3166-1 alpha-2 country the order declared."},"currencyCode":{"type":"string","description":"Present on FOOTPRINT_CURRENCY_NOT_DECLARED: the ISO 4217 sale currency the order declared."},"declaredCountry":{"type":["string","null"],"description":"Present on consumer geo refusals: the country the order declared."},"detectedCountry":{"type":"string","description":"Present on consumer geo refusals when the buyer IP resolved to a country: the country the evidence pointed to."},"consoleUrl":{"type":"string","format":"uri","description":"Absolute link to the console page where the key-owner company can fix the cause (for example the partner contracts hub for a contract denial, or API key settings for a scope or allowlist refusal). Present only for codes whose fix lives in the console."},"consoleAction":{"type":"string","enum":["review_partner_contracts","review_allocations","manage_api_keys","complete_kyb","top_up_wallet","review_partner_catalog"],"description":"Machine-readable label for `consoleUrl`; stable across releases."},"reason":{"type":"string","enum":["PREORDER_NOT_OPEN","PREORDER_CLOSED","PREORDER_DISABLED","LIFECYCLE_NOT_LIVE"],"description":"Why `PRODUCT_NOT_SELLABLE` was returned. A pre-order becomes its release in place (same `skuId`), so poll `sku.sellability_changed` / `release.available` for this SKU rather than looking for a successor product."},"productId":{"type":["string","null"],"format":"uuid"},"launchPhase":{"type":["string","null"],"enum":["draft","announced","pre_order","available",null],"description":"Effective launch phase of the SKU's release when `PRODUCT_NOT_SELLABLE` was returned."},"preorderStart":{"type":["string","null"],"format":"date-time","description":"Pre-order window opens (PRODUCT_NOT_SELLABLE with reason PREORDER_NOT_OPEN / PREORDER_CLOSED)."},"preorderEnd":{"type":["string","null"],"format":"date-time","description":"Pre-order window closes."},"releaseDate":{"type":["string","null"],"format":"date-time","description":"Release go-live instant; the same SKU becomes sellable then."}}}},"example":{"code":"UNAUTHORIZED","message":"Missing or invalid Authorization header","error":"Missing or invalid Authorization header","timestamp":"2026-03-15T15:00:00.000Z","recoverable":true,"hint":"Check your API key in Settings → API Keys","doc_url":"https://docs.avrix.io/seller-api/errors#unauthorized","requestId":"a1b2c3d4-e5f6-7890-abcd-ef1234567890"},"required":["code","message","requestId"]},"SellerRegionSummary":{"type":"object","properties":{"code":{"type":"string"},"name":{"type":["string","null"]},"allowedCountries":{"type":"array","items":{"type":"string","minLength":2,"maxLength":2},"description":"ISO 3166-1 alpha-2 country codes where this SKU/release may be sold (publisher region pack minus release exclusions)."}}},"SellerRegionDetail":{"allOf":[{"$ref":"#/components/schemas/SellerRegionSummary"}]},"SellerRefund":{"type":"object","required":["id","status","type","skuId","productId","reversalTransactionId","salePriceCents","currencyCode","currencyExponent","saleTimestamp"],"properties":{"id":{"type":"string","format":"uuid","description":"Sale transaction id (same id returned as refundId)."},"status":{"type":"string","enum":["pending","completed","chargeback_open","chargeback_lost","chargeback_won"],"description":"Finance adjustment status after quarantine. Avrix never refunds your PSP."},"type":{"type":"string","enum":["refund","chargeback","return"]},"keyId":{"type":["string","null"],"format":"uuid"},"skuId":{"type":"string","format":"uuid"},"productId":{"type":"string","format":"uuid"},"orderReference":{"type":["string","null"]},"adjustmentReference":{"type":["string","null"],"description":"Partner refund/chargeback reference."},"reversalTransactionId":{"type":["string","null"],"format":"uuid","description":"Ledger transaction that reverses this sale, when the financial reversal has been written."},"salePriceCents":{"type":"integer"},"currencyCode":{"type":"string"},"currencyExponent":{"type":"integer"},"saleTimestamp":{"type":"string","format":"date-time"},"adjustedAt":{"type":["string","null"],"format":"date-time"},"occurredAt":{"type":["string","null"],"format":"date-time"}}},"WebhookTestPing":{"type":"object","description":"Payload for `test.ping` webhook deliveries.","required":["type","createdAt"],"properties":{"type":{"type":"string","const":"test.ping"},"createdAt":{"type":"string","format":"date-time"},"data":{"type":"object","additionalProperties":true,"description":"Event-specific payload. Never includes plaintext key codes."}}},"WebhookOrderFailed":{"type":"object","description":"Payload for `order.failed` webhook deliveries.","required":["type","createdAt"],"properties":{"type":{"type":"string","const":"order.failed"},"createdAt":{"type":"string","format":"date-time"},"data":{"type":"object","additionalProperties":true,"description":"Event-specific payload. Never includes plaintext key codes."}}},"WebhookOrderPreorderFulfilled":{"type":"object","description":"Payload for `order.preorder_fulfilled` webhook deliveries.","required":["type","createdAt"],"properties":{"type":{"type":"string","const":"order.preorder_fulfilled"},"createdAt":{"type":"string","format":"date-time"},"data":{"type":"object","additionalProperties":true,"description":"Event-specific payload. Never includes plaintext key codes."}}},"WebhookRefundCompleted":{"type":"object","description":"Payload for `refund.completed` webhook deliveries.","required":["type","createdAt"],"properties":{"type":{"type":"string","const":"refund.completed"},"createdAt":{"type":"string","format":"date-time"},"data":{"type":"object","additionalProperties":true,"description":"Event-specific payload. Never includes plaintext key codes."}}},"WebhookChargebackResolved":{"type":"object","description":"Payload for `chargeback.resolved` webhook deliveries.","required":["type","createdAt"],"properties":{"type":{"type":"string","const":"chargeback.resolved"},"createdAt":{"type":"string","format":"date-time"},"data":{"type":"object","additionalProperties":true,"description":"Event-specific payload. Never includes plaintext key codes."}}},"WebhookKeysPulled":{"type":"object","description":"Payload for `keys.pulled` webhook deliveries.","required":["type","createdAt"],"properties":{"type":{"type":"string","const":"keys.pulled"},"createdAt":{"type":"string","format":"date-time"},"data":{"type":"object","additionalProperties":true,"description":"Event-specific payload. Never includes plaintext key codes."}}},"WebhookAllocationDepleted":{"type":"object","description":"Payload for `allocation.depleted` webhook deliveries.","required":["type","createdAt"],"properties":{"type":{"type":"string","const":"allocation.depleted"},"createdAt":{"type":"string","format":"date-time"},"data":{"type":"object","additionalProperties":true,"description":"Event-specific payload. Never includes plaintext key codes."}}},"WebhookAllocationLowStock":{"type":"object","description":"Payload for `allocation.low_stock` webhook deliveries.","required":["type","createdAt"],"properties":{"type":{"type":"string","const":"allocation.low_stock"},"createdAt":{"type":"string","format":"date-time"},"data":{"type":"object","additionalProperties":true,"description":"Event-specific payload. Never includes plaintext key codes."}}},"WebhookProductAnnounced":{"type":"object","description":"Payload for `product.announced` webhook deliveries.","required":["type","createdAt"],"properties":{"type":{"type":"string","const":"product.announced"},"createdAt":{"type":"string","format":"date-time"},"data":{"type":"object","additionalProperties":true,"description":"Event-specific payload. Never includes plaintext key codes."}}},"WebhookProductDelisted":{"type":"object","description":"Payload for `product.delisted` webhook deliveries.","required":["type","createdAt"],"properties":{"type":{"type":"string","const":"product.delisted"},"createdAt":{"type":"string","format":"date-time"},"data":{"type":"object","additionalProperties":true,"description":"Event-specific payload. Never includes plaintext key codes."}}},"WebhookReleaseAvailable":{"type":"object","description":"Payload for `release.available` webhook deliveries.","required":["type","createdAt"],"properties":{"type":{"type":"string","const":"release.available"},"createdAt":{"type":"string","format":"date-time"},"data":{"type":"object","additionalProperties":true,"description":"Event-specific payload. Never includes plaintext key codes."}}},"WebhookSkuPricingUpdated":{"type":"object","description":"Payload for `sku.pricing_updated` webhook deliveries.","required":["type","createdAt"],"properties":{"type":{"type":"string","const":"sku.pricing_updated"},"createdAt":{"type":"string","format":"date-time"},"data":{"type":"object","additionalProperties":true,"description":"Event-specific payload. Never includes plaintext key codes."}}},"WebhookContractActivated":{"type":"object","description":"Payload for `contract.activated` webhook deliveries.","required":["type","createdAt"],"properties":{"type":{"type":"string","const":"contract.activated"},"createdAt":{"type":"string","format":"date-time"},"data":{"type":"object","additionalProperties":true,"description":"Event-specific payload. Never includes plaintext key codes."}}},"WebhookContractSuperseded":{"type":"object","description":"Payload for `contract.superseded` webhook deliveries.","required":["type","createdAt"],"properties":{"type":{"type":"string","const":"contract.superseded"},"createdAt":{"type":"string","format":"date-time"},"data":{"type":"object","additionalProperties":true,"description":"Event-specific payload. Never includes plaintext key codes."}}},"WebhookContractAmendmentAccepted":{"type":"object","description":"Payload for `contract.amendment_accepted` webhook deliveries.","required":["type","createdAt"],"properties":{"type":{"type":"string","const":"contract.amendment_accepted"},"createdAt":{"type":"string","format":"date-time"},"data":{"type":"object","additionalProperties":true,"description":"Event-specific payload. Never includes plaintext key codes."}}},"WebhookInvoiceCreated":{"type":"object","description":"Payload for `invoice.created` webhook deliveries.","required":["type","createdAt"],"properties":{"type":{"type":"string","const":"invoice.created"},"createdAt":{"type":"string","format":"date-time"},"data":{"type":"object","additionalProperties":true,"description":"Event-specific payload. Never includes plaintext key codes."}}},"WebhookReportReady":{"type":"object","description":"Payload for `report.ready` webhook deliveries.","required":["type","createdAt"],"properties":{"type":{"type":"string","const":"report.ready"},"createdAt":{"type":"string","format":"date-time"},"data":{"type":"object","additionalProperties":true,"description":"Event-specific payload. Never includes plaintext key codes."}}},"SellerActivityItem":{"type":"object","description":"Legacy merged row (pre settlement feed). Returned only when `kinds` is limited to `transaction` / `webhook_delivery`; use the settlement entries instead. Scheduled for removal after one release.","required":["kind","createdAt","payload"],"properties":{"kind":{"type":"string","enum":["transaction","webhook_delivery"]},"createdAt":{"type":"string","format":"date-time"},"payload":{"type":"object","additionalProperties":true,"description":"Kind-specific fields (transaction: id, readableId, allocationId, skuCode, quantity, orderReference; webhook_delivery: id, endpointId, eventId, eventType, status, attempts, responseStatus)."}},"deprecated":true},"SellerWebhookDeliveryCursorItem":{"type":"object","description":"Webhook delivery row from the cross-endpoint cursor feed (GET /events).","required":["id","endpointId","eventId","eventType","status","attempts","responseStatus","createdAt","lastAttemptAt","nextRetryAt"],"properties":{"id":{"type":"string","format":"uuid"},"endpointId":{"type":"string","format":"uuid"},"eventId":{"type":"string"},"eventType":{"type":"string"},"status":{"type":"string"},"attempts":{"type":"integer"},"responseStatus":{"type":["integer","null"]},"payload":{"type":["object","null"],"additionalProperties":true,"description":"Delivery payload snapshot. Never includes plaintext key codes."},"createdAt":{"type":"string","format":"date-time"},"lastAttemptAt":{"type":["string","null"],"format":"date-time"},"nextRetryAt":{"type":["string","null"],"format":"date-time"}}},"SellerHotDropExtendData":{"type":"object","description":"Extended hot-drop reservation (POST /orders/{orderId}/extend).","required":["reservationId","expiresAt","ttlSeconds","extendedOnce"],"properties":{"reservationId":{"type":"string","format":"uuid"},"expiresAt":{"type":"string","format":"date-time"},"ttlSeconds":{"type":"integer","minimum":1},"extendedOnce":{"type":"boolean","const":true}}},"WebhookReleaseDateChanged":{"type":"object","description":"Payload for `release.date_changed` webhook deliveries.","required":["type","createdAt"],"properties":{"type":{"type":"string","const":"release.date_changed"},"createdAt":{"type":"string","format":"date-time"},"data":{"type":"object","additionalProperties":true,"description":"Event-specific payload: `productId`, `releaseId`, `skuIds[]`, `publisherCompanyId`, `oldDate`, `newDate`. Never includes plaintext key codes."}}},"WebhookSkuSellabilityChanged":{"type":"object","description":"Payload for `sku.sellability_changed` webhook deliveries.","required":["type","createdAt"],"properties":{"type":{"type":"string","const":"sku.sellability_changed"},"createdAt":{"type":"string","format":"date-time"},"data":{"type":"object","additionalProperties":true,"description":"Event-specific payload: `skuId`, `skuCode`, `productId`, `sellable`, `reasons[]` (readiness blockers when not sellable). Never includes plaintext key codes."}}},"WebhookSystemEndpointDisabled":{"type":"object","description":"Payload for `system.webhook_endpoint_disabled` webhook deliveries.","required":["type","createdAt"],"properties":{"type":{"type":"string","const":"system.webhook_endpoint_disabled"},"createdAt":{"type":"string","format":"date-time"},"data":{"type":"object","additionalProperties":true,"description":"Event-specific payload: `endpointId`, `endpointHost`, `reason`, `consecutiveFailures`, `disabledAt`. Delivered to the company's other endpoints; the disabled endpoint's copy is buffered and flushes on re-enable."}}},"SellerOrderListItem":{"type":"object","description":"Listing row — one virtual order tuple (allocation grant, orderReference). `keyIds` are inventory key UUIDs, never plaintext.","required":["orderReference","status","skuId","allocationId","quantity","fulfilledAt","keyIds"],"properties":{"orderReference":{"type":"string"},"orderId":{"type":["string","null"],"description":"Readable order id (ord_…). Durable-derived when first-class order reads are on; otherwise from the first key pull."},"status":{"type":"string","enum":["preordered","awaiting_release","awaiting_stock","ready","partially_fulfilled","fulfilled","cancelled","returned","refunded","failed"],"description":"Derived per ORDER_LIFECYCLE labels from key statuses + refund records (derived until first-class orders land)."},"skuId":{"type":"string","format":"uuid"},"allocationId":{"type":"string","format":"uuid"},"quantity":{"type":"integer"},"fulfilledAt":{"type":"string","format":"date-time"},"keyIds":{"type":"array","items":{"type":"string","format":"uuid"},"description":"Inventory key ids for refunds / returns correlation — never plaintext codes."},"totalCents":{"type":["integer","null"],"description":"Sum of recorded sale transactions for this tuple, when present."},"currencyCode":{"type":["string","null"]},"qtyRequested":{"type":"integer"},"qtyPending":{"type":"integer"},"qtyAssigned":{"type":"integer"},"qtyRevealed":{"type":"integer"}}},"SellerOrderListPage":{"type":"object","required":["data","meta"],"properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/SellerOrderListItem"}},"meta":{"type":"object","properties":{"limit":{"type":"integer"},"count":{"type":"integer"},"nextCursor":{"type":["string","null"]},"nextUrl":{"type":["string","null"]},"hasMore":{"type":"boolean"}}}}},"WebhookRedemptionExpiring":{"type":"object","description":"Payload for `redemption.expiring` webhook deliveries.","required":["type","createdAt"],"properties":{"type":{"type":"string","const":"redemption.expiring"},"createdAt":{"type":"string","format":"date-time"},"data":{"type":"object","additionalProperties":true,"description":"Event-specific payload: `fulfillmentId`, `orderReference`, `skuId`, `platformCode`, `provider`, `expiresAt`. Never includes the redemption URL or token."}}},"SellerFinanceStatementBucket":{"type":"object","description":"Per-currency totals for the statement period. Never sum across currencies.","properties":{"currencyCode":{"type":"string","example":"EUR"},"transactionCount":{"type":"integer"},"grossSalesCents":{"type":"integer"},"refundedCents":{"type":"integer","description":"Positive magnitude of sale_reversal ledger entries in the period."},"reinstatedCents":{"type":"integer","description":"Positive amount restored by sale_reinstatement ledger entries after won chargebacks."},"netSalesCents":{"type":"integer"},"publisherShareCents":{"type":"integer"},"sellerShareCents":{"type":"integer"},"platformFeeCents":{"type":"integer"}},"required":["currencyCode","transactionCount","grossSalesCents","refundedCents","reinstatedCents","netSalesCents","publisherShareCents","sellerShareCents","platformFeeCents"]},"SellerFinanceStatement":{"type":"object","properties":{"period":{"type":"string","example":"2026-07","description":"Calendar month (UTC)."},"periodStart":{"type":"string","format":"date-time"},"periodEnd":{"type":"string","format":"date-time","description":"Exclusive upper bound."},"generatedAt":{"type":"string","format":"date-time"},"totals":{"type":"array","items":{"$ref":"#/components/schemas/SellerFinanceStatementBucket"},"description":"Legacy transaction totals for returned lines only, in sale currency. Not a payable balance."},"lines":{"type":"array","description":"Per-transaction lines (same shape as GET /finance/api-sales rows).","items":{"$ref":"#/components/schemas/SellerApiSaleTransaction"}},"lineCount":{"type":"integer"},"truncated":{"type":"boolean","description":"More lines remain in this frozen statement. Continue with nextCursor."},"totalsScope":{"type":"string","enum":["returned_lines"]},"totalLineCount":{"type":"integer","description":"Total lines across the full frozen period."},"nextCursor":{"type":["string","null"],"description":"Opaque continuation cursor; null on the final page."},"snapshotExpiresAt":{"type":"string","format":"date-time"},"activityTotals":{"type":"array","description":"Full-period activity by sale currency, including unresolved entries; not payable amounts.","items":{"$ref":"#/components/schemas/SellerFinanceStatementBucket"}},"pendingTotals":{"type":"array","description":"Full-period activity awaiting report aggregation.","items":{"$ref":"#/components/schemas/SellerFinanceStatementBucket"}},"quarantinedTotals":{"type":"array","description":"Full-period activity requiring review; unresolved monetary components are not final.","items":{"$ref":"#/components/schemas/SellerFinanceStatementBucket"}},"approvedSettlements":{"type":"array","description":"Approved reports for the requested reporting month, in payment currency. Report publisher shares are statement amounts, not outstanding balances. Related invoices are identified for reconciliation.","items":{"$ref":"#/components/schemas/SellerFinanceApprovedSettlement"}},"outstandingBalances":{"type":"array","description":"Outstanding balances across all periods, as of generatedAt, by partner, agreement and payment currency. Not limited to the requested month.","items":{"$ref":"#/components/schemas/SellerFinanceOutstandingBalance"}}},"required":["period","periodStart","periodEnd","generatedAt","totals","lines","lineCount","truncated","totalsScope","totalLineCount","nextCursor","snapshotExpiresAt","activityTotals","pendingTotals","quarantinedTotals","approvedSettlements","outstandingBalances"]},"SellerIntegrationGate":{"type":"object","properties":{"gate":{"type":"string","enum":["bmaActive","shareGranted","allocationGranted","territoryPricingSet","webhookConfigured","testPingSucceeded","firstOrderCompleted"]},"satisfied":{"type":"boolean"},"hint":{"type":"string","description":"Actionable next step when unsatisfied; confirmation when satisfied."}},"required":["gate","satisfied","hint"]},"SellerIntegrationStatus":{"type":"object","properties":{"readyToSell":{"type":"boolean","description":"True when every commerce-critical gate (BMA, share, allocation, territory pricing) is satisfied."},"gates":{"type":"array","items":{"$ref":"#/components/schemas/SellerIntegrationGate"}},"counts":{"type":"object","properties":{"sellableSkuCount":{"type":"integer"},"sharedSkuCount":{"type":"integer"},"allocatedSkuCount":{"type":"integer"}},"required":["sellableSkuCount","sharedSkuCount","allocatedSkuCount"]},"activationPolicy":{"type":"string","enum":["warn","enforce_known","enforce_strict"],"description":"EFFECTIVE activation-territory posture for this company (platform posture, upgraded to enforce_known when activationEnforceOptIn is true). warn (default) adds an advisory preview warning. enforce_known returns 422 ACTIVATION_REGION_MISMATCH for a known locked-set miss. enforce_strict also returns 422 ACTIVATION_REGION_UNKNOWN when batch activation coverage is absent. Enforcement 422s carry details: skuId, countryCode, activationType, allowedCountries."},"activationEnforceOptIn":{"type":"boolean","description":"True when this company opted in to activation-territory enforcement (enforce_known) ahead of the platform default flip. Contact support to opt in."},"priceCommitmentConfigured":{"type":"boolean","description":"True when this deployment can mint signed preview price-commitment tokens. Production deployments fail closed at boot without the signing key, so this is always true in production; when false (sandbox/local), expectedUnitPriceCents remains mandatory on commit."},"backorderEnabled":{"type":"boolean","description":"True when durable customer-order backorders are enabled. Default false: backorderOnUnavailable is rejected with 403 FEATURE_DISABLED (details.reason BACKORDER_NOT_ENABLED). When true, POST /orders may accept awaiting_stock against headroom if the vendor policy allows request_mode_backorder; otherwise BACKORDER_NOT_ALLOWED."}},"required":["readyToSell","gates","counts","activationPolicy","priceCommitmentConfigured","backorderEnabled"]},"SkuActivation":{"type":"object","description":"Where the delivered key can be ACTIVATED — distinct from sale territory. worldwide: at least one unarchived batch and none region-locked. region_locked: guaranteed country intersection. unknown: no unarchived batches / no activation metadata.","properties":{"type":{"type":"string","enum":["worldwide","region_locked","unknown"]},"countries":{"type":["array","null"],"items":{"type":"string"},"description":"Guaranteed activation countries (ISO 3166-1 alpha-2); null when worldwide or unknown."}},"required":["type","countries"]},"GeoWarning":{"type":"object","required":["code"],"properties":{"code":{"type":"string","description":"Would-be CONSUMER_* denial while consumer geo is in monitor mode."},"enforcementDate":{"type":"string","description":"Optional announced enforcement date (ISO date) when set."}}},"WebhookOrderReady":{"type":"object","description":"Payload for `order.ready` webhook deliveries.","required":["type","createdAt"],"properties":{"type":{"type":"string","const":"order.ready"},"createdAt":{"type":"string","format":"date-time"},"data":{"type":"object","additionalProperties":true,"description":"Event-specific payload. Never includes plaintext key codes."}}},"SellerOrderFulfillData":{"type":"object","required":["type","status","orderId","orderReference","pulled","keys","keyIds"],"properties":{"type":{"type":"string","const":"fulfilled"},"status":{"type":"string","const":"fulfilled"},"orderId":{"type":"string"},"orderReference":{"type":"string"},"allocationId":{"type":["string","null"],"format":"uuid"},"pulled":{"type":"integer"},"keys":{"type":"array","items":{"type":"string"},"description":"Plaintext key codes. Only returned on this mutation for deferred orders."},"keyIds":{"type":"array","items":{"type":"string","format":"uuid"}},"activation":{"$ref":"#/components/schemas/SkuActivation","description":"Where the delivered key can be activated — the guaranteed intersection across the SKU's inventory batches, not the specific batch this key came from. Same object as GET /allocations and POST /orders/preview lines. Show it as \"activates in\" at delivery time without a second lookup."}}},"SellerPromotionCalendarEntry":{"type":"object","required":["sourceType","sourceId","skuId","discountPercent","priceEffect","startDate","endDate","window"],"properties":{"sourceType":{"type":"string","enum":["event","custom"]},"sourceId":{"type":"string"},"skuId":{"type":"string","format":"uuid"},"discountPercent":{"type":"number"},"priceEffect":{"type":"string","enum":["list_price","settlement_price","both"]},"startDate":{"type":"string","format":"date-time"},"endDate":{"type":"string","format":"date-time"},"window":{"type":"string","enum":["live","upcoming"]}}},"RefundPolicy":{"type":"object","description":"Platform refund default. Per-vendor overrides do not exist yet — this is the same object on whoami, allocations, and product detail. `source` is always `platform`.","required":["windowDays","keyRevealForfeitsRefund","quarantineOnRefund","avrixMovesMoney","source"],"properties":{"windowDays":{"type":["integer","null"],"description":"Platform-imposed refund window; null = none (your storefront/PSP policy governs)."},"keyRevealForfeitsRefund":{"type":"boolean","description":"A revealed key cannot be resold — refunding after reveal forfeits the key into quarantine."},"quarantineOnRefund":{"type":"boolean","description":"Refunded keys are quarantined, never recycled into sellable inventory without operator review."},"avrixMovesMoney":{"type":"boolean","const":false},"source":{"type":"string","const":"platform","description":"Always `platform` until per-offer windows exist."}}},"WebhookRedemptionExpired":{"type":"object","description":"Payload for `redemption.expired` webhook deliveries.","required":["type","createdAt"],"properties":{"type":{"type":"string","const":"redemption.expired"},"createdAt":{"type":"string","format":"date-time"},"data":{"type":"object","additionalProperties":true,"description":"Event-specific payload. Never includes plaintext key codes."}}},"WebhookCatalogExportReady":{"type":"object","description":"Payload for `catalog.export_ready` webhook deliveries.","required":["type","createdAt"],"properties":{"type":{"type":"string","const":"catalog.export_ready"},"createdAt":{"type":"string","format":"date-time"},"data":{"type":"object","additionalProperties":true,"description":"Event-specific payload. Never includes plaintext key codes."}}},"WebhookProductDelistingScheduled":{"type":"object","description":"Payload for `product.delisting_scheduled` webhook deliveries.","required":["type","createdAt"],"properties":{"type":{"type":"string","const":"product.delisting_scheduled"},"createdAt":{"type":"string","format":"date-time"},"data":{"type":"object","additionalProperties":true,"description":"Event-specific payload. Never includes plaintext key codes."}}},"SettlementPromoRef":{"type":"object","description":"Settlement-affecting promotion applied to a quoted or billed unit price. `sourceId` is the same id you read under /promotions: the shareId for `event`, the responseId for `custom`. Render was/now from `initialUnitPriceCents` vs `unitPriceCents`; do not recompute from `discountPercent`.","required":["sourceType","sourceId","discountPercent","priceEffect","startDate","endDate"],"properties":{"sourceType":{"type":"string","enum":["event","custom"]},"sourceId":{"type":"string","description":"`event` → shareId (`GET /promotions/shares/{shareId}`); `custom` → responseId (`GET /promotions/deals/{responseId}`)."},"discountPercent":{"type":"number"},"priceEffect":{"type":"string","enum":["settlement_price","both"],"description":"Only settlement-affecting promos are reported here; `list_price` promos never change the quoted cents."},"startDate":{"type":["string","null"],"format":"date-time"},"endDate":{"type":["string","null"],"format":"date-time"}}},"SellerSettlementActivityEntry":{"type":"object","description":"One settlement activity entry — the single record partners reconcile against. Every entry carries a signed stock movement, the counterparty, the promo reference, the buyer-country evidence and the economics. `sale` (+1) and its `refund` / `chargeback` (-1) share `orderReference` and `keyId`. `pull` is a custody-only delivery (wholesale / revenue-share / complimentary) priced from the allocation; `reveal` (0) is a keyless redemption event.","required":["id","kind","occurredAt","stockMovement","counterparty","warnings","economics"],"properties":{"id":{"type":"string","description":"Stable entry id, `<kind>:<source uuid>`."},"kind":{"type":"string","enum":["sale","refund","chargeback","pull","reveal"]},"occurredAt":{"type":"string","format":"date-time"},"stockMovement":{"type":"integer","description":"+1 delivered, -1 reversed, 0 informational."},"orderReference":{"type":["string","null"]},"keyId":{"type":["string","null"],"format":"uuid"},"keyPullId":{"type":["string","null"],"format":"uuid"},"skuId":{"type":["string","null"],"format":"uuid"},"productId":{"type":["string","null"],"format":"uuid"},"counterparty":{"type":"object","required":["publisherCompanyId"],"properties":{"publisherCompanyId":{"type":["string","null"]}},"description":"The other party to the settlement. Two-party today; shaped so a distribution path can grow without a contract change."},"contractTermId":{"type":["string","null"],"format":"uuid"},"promo":{"type":["object","null"],"required":["sourceType","sourceId"],"properties":{"sourceType":{"type":"string","enum":["event","custom"]},"sourceId":{"type":"string"}},"description":"Settlement promo that discounted the entry (shareId / responseId under /promotions); filter with `promoId`."},"requestedCountry":{"type":["string","null"],"description":"Declared `salesCountryCode`."},"detectedCountry":{"type":["string","null"],"description":"Country resolved from the buyer IP at pull time; null when geo did not run."},"warnings":{"type":"array","items":{"type":"string","enum":["COUNTRY_MISMATCH"]}},"economics":{"type":"object","required":["currencyCode","currencyExponent","unitPriceCents","initialUnitPriceCents","publisherShareCents","sellerShareCents","platformFeeCents"],"properties":{"currencyCode":{"type":["string","null"]},"currencyExponent":{"type":["integer","null"]},"unitPriceCents":{"type":["integer","null"],"description":"Billed unit price; negative on reversals."},"initialUnitPriceCents":{"type":["integer","null"],"description":"List price before any settlement promo; negative on reversals."},"publisherShareCents":{"type":["integer","null"]},"sellerShareCents":{"type":["integer","null"]},"platformFeeCents":{"type":["integer","null"]}}},"adjustmentReference":{"type":["string","null"],"description":"Your refund / chargeback reference on reversal entries."}}},"SellerApiSaleSettlement":{"type":"object","description":"What the Platform settled this sale at, computed once when the key was delivered and never recomputed. A later correction to the reference rate table does not restate a sale that has already been paid on. Read it alongside `taxMetadata`: that is what your store declared, this is what the Platform did with it.","properties":{"basis":{"type":["string","null"],"enum":["purchaser_country_capped","store_country",null],"description":"The basis the governing agreement states."},"vatMinor":{"type":["integer","null"],"description":"Consumer VAT deducted, in minor units of `currencyCode`."},"netMinor":{"type":["integer","null"],"description":"Gross less VAT: the base the revenue share was computed on."},"appliedRatePercent":{"type":["number","null"],"description":"The rate actually applied, after the cap."},"declaredRatePercent":{"type":["number","null"],"description":"The rate your store declared, before the cap."},"rateReason":{"type":["string","null"],"enum":["corroborated","fallback_store_country","fixed_store_country","subnational_declared","tax_exclusive_country",null],"description":"Why the applied rate is what it is. `fallback_store_country` means the declared consumer country was not corroborated, so the sale settled at your own registered country rate."},"evidenceRank":{"type":["integer","null"],"minimum":1,"maximum":3,"description":"1 a checkout attestation, 2 the consumer IP agreeing with the declaration, 3 the declaration alone."},"requestedCountry":{"type":["string","null"],"description":"The consumer country the sale was settled for (ISO 3166-1 alpha-2)."}}},"SellerFinanceSettlementInvoice":{"type":"object","properties":{"invoiceId":{"type":"string","format":"uuid"},"status":{"type":"string"},"currencyCode":{"type":"string"},"totalMinor":{"type":"integer"}},"required":["invoiceId","status","currencyCode","totalMinor"]},"SellerFinanceApprovedSettlement":{"type":"object","properties":{"reportId":{"type":"string","format":"uuid"},"publisherCompanyId":{"type":"string"},"contractTermId":{"type":["string","null"],"format":"uuid"},"currencyCode":{"type":"string"},"publisherShareMinor":{"type":"integer"},"status":{"type":"string"},"invoices":{"type":"array","items":{"$ref":"#/components/schemas/SellerFinanceSettlementInvoice"}}},"required":["reportId","publisherCompanyId","contractTermId","currencyCode","publisherShareMinor","status","invoices"]},"SellerFinanceOutstandingBalance":{"type":"object","properties":{"publisherCompanyId":{"type":"string"},"contractTermId":{"type":["string","null"],"format":"uuid"},"currencyCode":{"type":"string"},"outstandingMinor":{"type":"integer"}},"required":["publisherCompanyId","contractTermId","currencyCode","outstandingMinor"]}},"parameters":{"IdempotencyKey":{"name":"Idempotency-Key","in":"header","required":true,"schema":{"type":"string","minLength":1,"maxLength":64,"pattern":"^[a-zA-Z0-9_-]+$"},"description":"Stable key for this logical mutation (1–64 chars, `[a-zA-Z0-9_-]`). Reuse the same key and canonical JSON body on retries. Mismatch returns 409 `IDEMPOTENCY_KEY_MISMATCH`."}}},"externalDocs":{"description":"Seller API guides","url":"https://docs.avrix.io/guides/getting-started"},"tags":[{"name":"Seller auth","description":"Health, identity, and OAuth token exchange."},{"name":"Seller meta","description":"OpenAPI document, Scalar docs redirect, and client IP echo helpers."},{"name":"Catalog","description":"Products, snapshots, changes, allocations, and availability."},{"name":"Orders","description":"Preview, hold, reserve/commit, create, cancel, refunds, and fulfilment."},{"name":"Keys","description":"API key management and key pull/export/return."},{"name":"Webhooks","description":"Endpoint registration, deliveries, and replay."},{"name":"Finance","description":"Balances, reports, and settlement summaries."},{"name":"Promotions","description":"Promotion shares and deal responses."}],"webhooks":{"test_ping":{"post":{"operationId":"webhook_test_ping","summary":"test.ping","description":"Avrix delivers `test.ping` to your registered HTTPS endpoint. Verify the signature before processing. Events may be duplicated; dedupe on the event id header.","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/WebhookTestPing"}}}},"responses":{"200":{"description":"Acknowledge receipt. Return 2xx quickly; process asynchronously."}}}},"order_fulfilled":{"post":{"operationId":"webhook_order_fulfilled","summary":"order.fulfilled","description":"Avrix delivers `order.fulfilled` to your registered HTTPS endpoint. Verify the signature before processing. Events may be duplicated; dedupe on the event id header.","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/WebhookOrderFulfilled"}}}},"responses":{"200":{"description":"Acknowledge receipt. Return 2xx quickly; process asynchronously."}}}},"order_failed":{"post":{"operationId":"webhook_order_failed","summary":"order.failed","description":"Avrix delivers `order.failed` to your registered HTTPS endpoint. Verify the signature before processing. Events may be duplicated; dedupe on the event id header.","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/WebhookOrderFailed"}}}},"responses":{"200":{"description":"Acknowledge receipt. Return 2xx quickly; process asynchronously."}}}},"order_activated":{"post":{"operationId":"webhook_order_activated","summary":"order.activated","description":"Avrix delivers `order.activated` to your registered HTTPS endpoint. Verify the signature before processing. Events may be duplicated; dedupe on the event id header.","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/WebhookOrderActivated"}}}},"responses":{"200":{"description":"Acknowledge receipt. Return 2xx quickly; process asynchronously."}}}},"order_reserved":{"post":{"operationId":"webhook_order_reserved","summary":"order.reserved","description":"Avrix delivers `order.reserved` to your registered HTTPS endpoint. Verify the signature before processing. Events may be duplicated; dedupe on the event id header.","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/WebhookOrderReserved"}}}},"responses":{"200":{"description":"Acknowledge receipt. Return 2xx quickly; process asynchronously."}}}},"order_preorder_fulfilled":{"post":{"operationId":"webhook_order_preorder_fulfilled","summary":"order.preorder_fulfilled","description":"Avrix delivers `order.preorder_fulfilled` to your registered HTTPS endpoint. Verify the signature before processing. Events may be duplicated; dedupe on the event id header.","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/WebhookOrderPreorderFulfilled"}}}},"responses":{"200":{"description":"Acknowledge receipt. Return 2xx quickly; process asynchronously."}}}},"order_returned":{"post":{"operationId":"webhook_order_returned","summary":"order.returned","description":"Avrix delivers `order.returned` to your registered HTTPS endpoint. Verify the signature before processing. Events may be duplicated; dedupe on the event id header.","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/WebhookOrderReturned"}}}},"responses":{"200":{"description":"Acknowledge receipt. Return 2xx quickly; process asynchronously."}}}},"order_keys_returned":{"post":{"operationId":"webhook_order_keys_returned","summary":"order.keys_returned","description":"Avrix delivers `order.keys_returned` to your registered HTTPS endpoint. Verify the signature before processing. Events may be duplicated; dedupe on the event id header.","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/WebhookOrderKeysReturned"}}}},"responses":{"200":{"description":"Acknowledge receipt. Return 2xx quickly; process asynchronously."}}}},"refund_completed":{"post":{"operationId":"webhook_refund_completed","summary":"refund.completed","description":"Avrix delivers `refund.completed` to your registered HTTPS endpoint. Verify the signature before processing. Events may be duplicated; dedupe on the event id header.","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/WebhookRefundCompleted"}}}},"responses":{"200":{"description":"Acknowledge receipt. Return 2xx quickly; process asynchronously."}}}},"chargeback_resolved":{"post":{"operationId":"webhook_chargeback_resolved","summary":"chargeback.resolved","description":"Avrix delivers `chargeback.resolved` to your registered HTTPS endpoint. Verify the signature before processing. Events may be duplicated; dedupe on the event id header.","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/WebhookChargebackResolved"}}}},"responses":{"200":{"description":"Acknowledge receipt. Return 2xx quickly; process asynchronously."}}}},"keys_pulled":{"post":{"operationId":"webhook_keys_pulled","summary":"keys.pulled","description":"Avrix delivers `keys.pulled` to your registered HTTPS endpoint. Verify the signature before processing. Events may be duplicated; dedupe on the event id header.","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/WebhookKeysPulled"}}}},"responses":{"200":{"description":"Acknowledge receipt. Return 2xx quickly; process asynchronously."}}}},"allocation_updated":{"post":{"operationId":"webhook_allocation_updated","summary":"allocation.updated","description":"Avrix delivers `allocation.updated` to your registered HTTPS endpoint. Verify the signature before processing. Events may be duplicated; dedupe on the event id header.","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/WebhookAllocationUpdated"}}}},"responses":{"200":{"description":"Acknowledge receipt. Return 2xx quickly; process asynchronously."}}}},"allocation_depleted":{"post":{"operationId":"webhook_allocation_depleted","summary":"allocation.depleted","description":"Avrix delivers `allocation.depleted` to your registered HTTPS endpoint. Verify the signature before processing. Events may be duplicated; dedupe on the event id header.","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/WebhookAllocationDepleted"}}}},"responses":{"200":{"description":"Acknowledge receipt. Return 2xx quickly; process asynchronously."}}}},"allocation_low_stock":{"post":{"operationId":"webhook_allocation_low_stock","summary":"allocation.low_stock","description":"Avrix delivers `allocation.low_stock` to your registered HTTPS endpoint. Verify the signature before processing. Events may be duplicated; dedupe on the event id header.","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/WebhookAllocationLowStock"}}}},"responses":{"200":{"description":"Acknowledge receipt. Return 2xx quickly; process asynchronously."}}}},"product_updated":{"post":{"operationId":"webhook_product_updated","summary":"product.updated","description":"Avrix delivers `product.updated` to your registered HTTPS endpoint. Verify the signature before processing. Events may be duplicated; dedupe on the event id header.","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/WebhookProductUpdated"}}}},"responses":{"200":{"description":"Acknowledge receipt. Return 2xx quickly; process asynchronously."}}}},"product_announced":{"post":{"operationId":"webhook_product_announced","summary":"product.announced","description":"Avrix delivers `product.announced` to your registered HTTPS endpoint. Verify the signature before processing. Events may be duplicated; dedupe on the event id header.","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/WebhookProductAnnounced"}}}},"responses":{"200":{"description":"Acknowledge receipt. Return 2xx quickly; process asynchronously."}}}},"product_delisted":{"post":{"operationId":"webhook_product_delisted","summary":"product.delisted","description":"Avrix delivers `product.delisted` to your registered HTTPS endpoint. Verify the signature before processing. Events may be duplicated; dedupe on the event id header.","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/WebhookProductDelisted"}}}},"responses":{"200":{"description":"Acknowledge receipt. Return 2xx quickly; process asynchronously."}}}},"release_available":{"post":{"operationId":"webhook_release_available","summary":"release.available","description":"Avrix delivers `release.available` to your registered HTTPS endpoint. Verify the signature before processing. Events may be duplicated; dedupe on the event id header.","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/WebhookReleaseAvailable"}}}},"responses":{"200":{"description":"Acknowledge receipt. Return 2xx quickly; process asynchronously."}}}},"sku_pricing_updated":{"post":{"operationId":"webhook_sku_pricing_updated","summary":"sku.pricing_updated","description":"Avrix delivers `sku.pricing_updated` to your registered HTTPS endpoint. Verify the signature before processing. Events may be duplicated; dedupe on the event id header.","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/WebhookSkuPricingUpdated"}}}},"responses":{"200":{"description":"Acknowledge receipt. Return 2xx quickly; process asynchronously."}}}},"contract_activated":{"post":{"operationId":"webhook_contract_activated","summary":"contract.activated","description":"Avrix delivers `contract.activated` to your registered HTTPS endpoint. Verify the signature before processing. Events may be duplicated; dedupe on the event id header.","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/WebhookContractActivated"}}}},"responses":{"200":{"description":"Acknowledge receipt. Return 2xx quickly; process asynchronously."}}}},"contract_superseded":{"post":{"operationId":"webhook_contract_superseded","summary":"contract.superseded","description":"Avrix delivers `contract.superseded` to your registered HTTPS endpoint. Verify the signature before processing. Events may be duplicated; dedupe on the event id header.","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/WebhookContractSuperseded"}}}},"responses":{"200":{"description":"Acknowledge receipt. Return 2xx quickly; process asynchronously."}}}},"contract_amendment_accepted":{"post":{"operationId":"webhook_contract_amendment_accepted","summary":"contract.amendment_accepted","description":"Avrix delivers `contract.amendment_accepted` to your registered HTTPS endpoint. Verify the signature before processing. Events may be duplicated; dedupe on the event id header.","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/WebhookContractAmendmentAccepted"}}}},"responses":{"200":{"description":"Acknowledge receipt. Return 2xx quickly; process asynchronously."}}}},"invoice_created":{"post":{"operationId":"webhook_invoice_created","summary":"invoice.created","description":"Avrix delivers `invoice.created` to your registered HTTPS endpoint. Verify the signature before processing. Events may be duplicated; dedupe on the event id header.","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/WebhookInvoiceCreated"}}}},"responses":{"200":{"description":"Acknowledge receipt. Return 2xx quickly; process asynchronously."}}}},"report_ready":{"post":{"operationId":"webhook_report_ready","summary":"report.ready","description":"Avrix delivers `report.ready` to your registered HTTPS endpoint. Verify the signature before processing. Events may be duplicated; dedupe on the event id header.","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/WebhookReportReady"}}}},"responses":{"200":{"description":"Acknowledge receipt. Return 2xx quickly; process asynchronously."}}}},"release_date_changed":{"post":{"operationId":"webhook_release_date_changed","summary":"release.date_changed","description":"Avrix delivers `release.date_changed` to your registered HTTPS endpoint when a publisher moves a release date (pre-order slip signal). Verify the signature before processing. Events may be duplicated; dedupe on the event id header.","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/WebhookReleaseDateChanged"}}}},"responses":{"200":{"description":"Acknowledge receipt. Return 2xx quickly; process asynchronously."}}}},"sku_sellability_changed":{"post":{"operationId":"webhook_sku_sellability_changed","summary":"sku.sellability_changed","description":"Avrix delivers `sku.sellability_changed` when a shared SKU crosses the sellable boundary — the storefront Buy-button push primitive. Verify the signature before processing. Events may be duplicated; dedupe on the event id header.","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/WebhookSkuSellabilityChanged"}}}},"responses":{"200":{"description":"Acknowledge receipt. Return 2xx quickly; process asynchronously."}}}},"system_webhook_endpoint_disabled":{"post":{"operationId":"webhook_system_webhook_endpoint_disabled","summary":"system.webhook_endpoint_disabled","description":"Avrix delivers `system.webhook_endpoint_disabled` when the delivery circuit breaker auto-disables one of your endpoints. New events for the disabled endpoint are buffered until re-enable. Verify the signature before processing.","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/WebhookSystemEndpointDisabled"}}}},"responses":{"200":{"description":"Acknowledge receipt. Return 2xx quickly; process asynchronously."}}}},"redemption_expiring":{"post":{"operationId":"webhook_redemption_expiring","summary":"redemption.expiring","description":"Avrix delivers `redemption.expiring` ~24h before a keyless redemption URL expires so your store can nudge the buyer. Verify the signature before processing. Events may be duplicated; dedupe on the event id header.","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/WebhookRedemptionExpiring"}}}},"responses":{"200":{"description":"Acknowledge receipt. Return 2xx quickly; process asynchronously."}}}},"order_ready":{"post":{"operationId":"webhook_order_ready","summary":"order.ready","description":"Avrix delivers `order.ready` to your registered HTTPS endpoint. Verify the signature before processing. Events may be duplicated; dedupe on the event id header.","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/WebhookOrderReady"}}}},"responses":{"200":{"description":"Acknowledge receipt. Return 2xx quickly; process asynchronously."}}}},"redemption_expired":{"post":{"operationId":"webhook_redemption_expired","summary":"redemption.expired","description":"Avrix delivers `redemption.expired` when a keyless redemption URL passes expiresAt without activation. Payload carries ids only.","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/WebhookRedemptionExpired"}}}},"responses":{"200":{"description":"Acknowledge receipt. Return 2xx quickly; process asynchronously."}}}},"catalog_export_ready":{"post":{"operationId":"webhook_catalog_export_ready","summary":"catalog.export_ready","description":"Avrix delivers `catalog.export_ready` when an async catalog export artifact is ready. Poll GET /catalog/exports/{exportId} for the signed URL.","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/WebhookCatalogExportReady"}}}},"responses":{"200":{"description":"Acknowledge receipt. Return 2xx quickly; process asynchronously."}}}},"product_delisting_scheduled":{"post":{"operationId":"webhook_product_delisting_scheduled","summary":"product.delisting_scheduled","description":"Avrix delivers `product.delisting_scheduled` when a product has a future archived_at. Immediate archive still emits product.delisted only.","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/WebhookProductDelistingScheduled"}}}},"responses":{"200":{"description":"Acknowledge receipt. Return 2xx quickly; process asynchronously."}}}}}}