{"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 (`X-Avrix-Api-Version`): `2026-04-29` (launch contract), `2026-09-01` (the default for unpinned requests; bulk orders default to `strict: true`), `2026-10-01` (opt-in; typed key objects) and `2026-12-01` (opt-in; includes `2026-10-01`, a missing `Idempotency-Key` answers `IDEMPOTENCY_KEY_REQUIRED`, a key without the scope an operation needs answers `INSUFFICIENT_SCOPE` naming every accepted scope, and `GET /orders` answers `422` for a `status` filter its listing cannot serve instead of an empty page). `next` resolves to the newest date. Responses echo the effective date. See `https://docs.avrix.io/seller-api/versioning`. `info.version` is the contract date an unpinned request is served; `x-avrix-contract-dates` lists every date. **Change notices:** every contract change is in the changelog (`https://docs.avrix.io/seller-api/changelog`, RSS at `https://docs.avrix.io/changelog.xml`) and is announced to endpoints that subscribe to the `platform.notice` webhook event; a deprecated operation or parameter with a scheduled date answers with `Deprecation` and `Sunset` headers.\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** have generous per-key fair-use limits per route class (catalog 600 / orders 1,200 / finance 300 requests a minute; full catalog snapshots 6 an hour; `304` revalidations are free), reported in `X-RateLimit-*` and, while `whoami.key.rateLimitMode` is `shadow`, never refused. Every response to a request that was counted against a limit carries `X-RateLimit-Limit`, `X-RateLimit-Remaining` and `X-RateLimit-Reset` (Unix seconds): successes, validation and not-found errors, failures and `429`. A request refused before it is counted (`401`, a scope or IP allowlist `403`) carries none. **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**, back off; `Retry-After` is present (seconds). **Throughput:** see `https://docs.avrix.io/seller-api/rate-limits` 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`; a missing scope is `INSUFFICIENT_SCOPE` on contract date `2026-12-01` and later), **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`. Every operation that reads an API key can also answer **400** `UNSUPPORTED_API_VERSION` (`SellerApiUnsupportedApiVersion`), **503** (`SellerApiServiceUnavailable`) and **504** `HOT_PATH_TIMEOUT` (`SellerApiTimeout`), the last two with `Retry-After`; a GET refuses a query parameter it does not take with **422** (`SellerApiValidationFailed`); a write that takes an `Idempotency-Key` can answer **409** (`SellerApiIdempotencyConflict`); a body over 100 KB is **413** (`SellerApiPayloadTooLarge`). Every response of an operation that reads a key, errors included, carries `X-Request-Id` and `X-Avrix-Api-Version`.\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`.\n\n**Forward compatibility:** responses are open. A new release can add a response property, a header, an error code or an enum value to a response field without a new contract date, so ignore properties you do not know and treat an unknown enum value as the closest safe case (most fields say which). Response schemas therefore leave `additionalProperties` unset. Request bodies are checked as each operation states: most ignore a property they do not take, and the ones that refuse it say so with `additionalProperties: false`. Every `servers` entry is the same host; see `bearerAuth` for how a key selects production or sandbox.","version":"2026-09-01","x-avrix-contract-dates":{"default":"2026-09-01","supported":["2026-04-29","2026-09-01","2026-10-01","2026-12-01"],"optIn":["2026-10-01","2026-12-01"]},"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 and sandbox share this host. The key decides the environment: a live key (`avrix_sk_live_...`) works on your real catalog, a sandbox key (`avrix_sk_sbx_...`) on the sandbox catalog. `X-Avrix-Sandbox: true` is optional; when sent, only a sandbox key is accepted."}],"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 — metadata and lifecycle changes. **Price changes do not move `updatedAt` and never appear here:** poll `GET /catalog/changes` (`changedFields` contains `pricing`) and subscribe to `sku.pricing_updated` for those. 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, **list price in your pricing country** where resolvable) so you can build browse pages and compare **SRP / MSRP** (`listPriceFromCents`) with your **wholesale contract pricing** on `GET /api/seller/v1/allocations` (`pricePerKeyCents`, `businessModel`) — which exists for `wholesale` / `pre_order` grants; under `api` it is `null` and the cost is a share of the territory list price.\n\n**Filters and sort.** `platform`, `externalReference` (with `externalReferenceSource`), `releaseDateFrom`, `releaseDateTo`, `launchPhase`, `tradingState`, `productType` and `sort` are accepted on every contract date. Filters on releases match through the SKUs shared with you. `meta.total` counts the filtered list. Without them the list is served exactly as before.","parameters":[{"name":"limit","in":"query","description":"Page size: how many items to return (1 to 100).","schema":{"type":"integer","default":50,"minimum":1,"maximum":100}},{"name":"cursor","in":"query","description":"Opaque cursor from the previous page's `meta.nextCursor`. Omit for the first page.","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":"Deprecated alias of `partner` (still accepted). Sending both with different values fails validation; a request that uses only this spelling gets an `X-Avrix-Deprecated-Parameter` response header naming `partner`.","deprecated":true},{"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 whose row was updated on or after this instant (metadata / lifecycle). Price changes never move a product's `updatedAt`: use `GET /catalog/changes` and `sku.pricing_updated` for those."},{"name":"platform","in":"query","required":false,"schema":{"type":"string"},"description":"Comma-separated platform codes as `GET /platforms` returns them (case-insensitive, at most 20): only products with a shared release on one of these platforms. Additive."},{"name":"externalReference","in":"query","required":false,"schema":{"type":"string","maxLength":128},"description":"A value from `skus[].externalReferences` on product detail: a Steam app id, a Steam package id (`sub/123` or its digits) or a platform product id. Only products with a shared SKU that carries it. To map many ids at once, use `GET /products/lookup`. Additive."},{"name":"externalReferenceSource","in":"query","required":false,"schema":{"type":"string"},"description":"Narrows `externalReference` to one source: `steam` (app and package ids) or a platform code in lower case. Needs `externalReference`. Additive."},{"name":"releaseDateFrom","in":"query","required":false,"schema":{"type":"string","format":"date"},"description":"`YYYY-MM-DD`, inclusive: only products with a shared release whose release date is on or after this day. Additive."},{"name":"releaseDateTo","in":"query","required":false,"schema":{"type":"string","format":"date"},"description":"`YYYY-MM-DD`, inclusive: only products with a shared release whose release date is on or before this day. Additive."},{"name":"launchPhase","in":"query","required":false,"schema":{"type":"string"},"description":"Comma-separated: `announced`, `pre_order`, `available`. Matches the product's `launchPhase`. Additive."},{"name":"tradingState","in":"query","required":false,"schema":{"type":"string"},"description":"Comma-separated: `open`, `paused`, `discontinued`. Matches the product's `tradingState`. Additive."},{"name":"productType","in":"query","required":false,"schema":{"type":"string"},"description":"Comma-separated product types (for example `game`, `dlc`). Additive."},{"name":"sort","in":"query","required":false,"schema":{"type":"string","enum":["-createdAt","createdAt","-updatedAt","updatedAt","name","-name"],"default":"-createdAt"},"description":"Order of the list. `-createdAt` (the default) is the order the list always had. `name` sorts case-insensitively. A `cursor` belongs to the sort it was issued with: sending it with another sort answers `422 VALIDATION_FAILED` on `cursor`. Additive."},{"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. Cacheable by your own HTTP cache per `Authorization`+`Accept-Language`+`expand` (no shared CDN cache)."},{"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."},{"$ref":"#/components/parameters/AvrixApiVersion"},{"$ref":"#/components/parameters/RequestId"},{"$ref":"#/components/parameters/SandboxSimulateRateLimit"},{"$ref":"#/components/parameters/IfNoneMatch"}],"responses":{"200":{"description":"Products list","headers":{"X-Request-Id":{"$ref":"#/components/headers/XRequestId"},"X-Avrix-Api-Version":{"$ref":"#/components/headers/XAvrixApiVersion"},"X-Api-Version":{"$ref":"#/components/headers/XApiVersion"},"X-RateLimit-Limit":{"$ref":"#/components/headers/XRateLimitLimit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/XRateLimitRemaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/XRateLimitReset"},"X-RateLimit-Bucket":{"$ref":"#/components/headers/XRateLimitBucket"},"ETag":{"$ref":"#/components/headers/ETag"}},"content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/PartnerProductWithExpansions"}},"meta":{"$ref":"#/components/schemas/PaginationMeta"}}},"example":{"data":[{"id":"9d706a25-4131-4ef2-85b1-826fd05daa66","readableId":"prd_ykzbfs24","createdAt":"2026-11-02T09:30:00Z","name":"Example Game","slug":"example-game","productType":"game","launchPhase":"draft","tradingState":"open","isArchived":false,"publisherCompanyId":"acme-games","publisherCompanyName":"Acme Games","sharedSkus":[{"id":"6e2fe4b0-a14d-4dda-8c9e-0bf20bb48a1a","skuCode":"EXAMPLE-STEAM-WW","platformName":"Steam","platformCode":"steam","editionName":"Standard Edition","keyTypeName":"Steam key","srpPriceCents":2450,"srpCurrencyCode":"EUR","srpCurrencyExponent":2,"sellable":true,"readinessBlockers":["example_readinessblocker"],"pricePerKeyCents":2450,"currencyCode":"null","currencyExponent":2,"territoryPrices":[{"countryCode":"DE","basePriceCents":2450,"basePriceMinor":2450,"zone":{"code":"EUR","label":"Euro area and rest of Europe (EUR)"},"currencyCode":"EUR","currencyExponent":2,"sellable":true,"blockedReason":null}]}],"coverUrl":"https://api.avrix.io/api/seller/v1/example","shortDescription":"Race through open city streets with friends.","editionCount":12,"platformNames":["Steam"],"platforms":[{"code":"steam","name":"Example Game"}],"regionNames":["Europe"],"regions":[{"code":"EU","name":"Example Game"}],"editionNamesShared":["example_editionnamesshared"],"sharedRegionReleaseCount":12,"listPriceFromCents":2450,"listPriceCurrencyCode":"EUR","listPriceCurrencyExponent":3,"updatedAt":"2026-11-02T09:30:00Z","publisherCompanyImageUrl":"https://api.avrix.io/api/seller/v1/example","publisherWebsite":"https://api.avrix.io/api/seller/v1/example","publisherCountry":"DE","relatedProducts":[{"type":"requires","productId":"7fb47dcc-5511-4f03-8da8-5a0b80dc37b5"}]}],"meta":{"total":2450,"limit":50,"hasMore":true,"nextCursor":"eyJ2IjoyLCJ0IjoiMjAyNi0xMS0wMlQwOTozMDowMFoifQ","nextUrl":"https://api.avrix.io/api/seller/v1/products?cursor=eyJ2IjoyLCJ0IjoiMjAyNi0xMS0wMlQwOTozMDowMFoifQ","localePreference":"en"}}}}},"304":{"description":"Not modified: this page of the list has not changed since the `ETag` you sent in `If-None-Match`. No body, and the regular read budget is not charged.","headers":{"X-Request-Id":{"$ref":"#/components/headers/XRequestId"},"X-Avrix-Api-Version":{"$ref":"#/components/headers/XAvrixApiVersion"},"X-Api-Version":{"$ref":"#/components/headers/XApiVersion"},"X-RateLimit-Limit":{"$ref":"#/components/headers/XRateLimitLimit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/XRateLimitRemaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/XRateLimitReset"},"X-RateLimit-Bucket":{"$ref":"#/components/headers/XRateLimitBucket"},"ETag":{"$ref":"#/components/headers/ETag"}}},"400":{"$ref":"#/components/responses/SellerApiUnsupportedApiVersion"},"401":{"$ref":"#/components/responses/SellerApiUnauthorized"},"403":{"$ref":"#/components/responses/SellerApiForbidden"},"422":{"description":"Invalid query parameters (e.g. limit, locale, partner company ID, a filter or `sort` value, a `cursor` issued for another sort)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"429":{"$ref":"#/components/responses/SellerApiRateLimited"},"500":{"$ref":"#/components/responses/SellerApiInternalError"},"503":{"$ref":"#/components/responses/SellerApiServiceUnavailable"},"504":{"$ref":"#/components/responses/SellerApiTimeout"}},"security":[{"bearerAuth":[]}],"x-avrix-scopes":["seller:products:read"],"x-avrix-tier":"catalog","x-avrix-rate-limit-class":"catalog","x-avrix-scope-mode":"anyOf","x-avrix-store-profile":"catalog","tags":["Catalog"],"operationId":"listProducts"}},"/api/seller/v1/products/lookup":{"get":{"tags":["Catalog"],"summary":"Look up products by external reference","description":"Maps up to 100 external ids (Steam app ids, Steam package ids, platform product ids) to the products and SKUs shared with you, in one call. One row per value sent, in the order sent; `matches` is empty for a value no shared SKU carries. Visibility is the catalog's: the same agreement, share and lifecycle rules as `GET /products`. Not paged and not cached. Additive.","operationId":"lookupProductsByExternalReference","security":[{"bearerAuth":[]}],"x-avrix-scopes":["seller:products:read"],"x-avrix-tier":"catalog","x-avrix-rate-limit-class":"catalog","x-avrix-scope-mode":"anyOf","parameters":[{"name":"externalReference","in":"query","required":true,"schema":{"type":"string"},"description":"Comma-separated values, 1 to 100, each 1 to 128 characters (letters, digits, `_ . : / -`). Duplicates are answered once.","example":"620,sub/12345"},{"name":"source","in":"query","required":false,"schema":{"type":"string"},"description":"Only references from this source: `steam` (app and package ids) or a platform code in lower case."},{"$ref":"#/components/parameters/AvrixApiVersion"},{"$ref":"#/components/parameters/RequestId"},{"$ref":"#/components/parameters/SandboxSimulateRateLimit"}],"responses":{"200":{"description":"One row per value sent","headers":{"X-Request-Id":{"$ref":"#/components/headers/XRequestId"},"X-Avrix-Api-Version":{"$ref":"#/components/headers/XAvrixApiVersion"},"X-Api-Version":{"$ref":"#/components/headers/XApiVersion"},"X-RateLimit-Limit":{"$ref":"#/components/headers/XRateLimitLimit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/XRateLimitRemaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/XRateLimitReset"},"X-RateLimit-Bucket":{"$ref":"#/components/headers/XRateLimitBucket"}},"content":{"application/json":{"schema":{"type":"object","required":["data","meta"],"properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/SellerProductLookupRow"}},"meta":{"type":"object","required":["requested","matched","unmatched"],"properties":{"requested":{"type":"integer","description":"Distinct values sent."},"matched":{"type":"integer","description":"Values with at least one match."},"unmatched":{"type":"integer"}}}}},"example":{"data":[{"externalReference":"620","matches":[{"productId":"8b0f7c55-2f4e-4a8b-9f0e-6b1d2c3a4e5f","readableId":"prd_k7m2p9qx","productName":"Example Game","productSlug":"example-game","publisherCompanyId":"acme-games","skuId":"3c9a1e2b-7d4f-4c6a-8e2b-1f0d9c8b7a6e","skuCode":"EXAMPLE-STEAM-WW","platformCode":"steam","reference":{"source":"steam","name":"appId","value":"620"}}]},{"externalReference":"sub/12345","matches":[]}],"meta":{"requested":2,"matched":1,"unmatched":1}}}}},"400":{"$ref":"#/components/responses/SellerApiUnsupportedApiVersion"},"401":{"$ref":"#/components/responses/SellerApiUnauthorized"},"403":{"$ref":"#/components/responses/SellerApiForbidden"},"422":{"$ref":"#/components/responses/SellerApiValidationFailed"},"429":{"$ref":"#/components/responses/SellerApiRateLimited"},"500":{"$ref":"#/components/responses/SellerApiInternalError"},"503":{"$ref":"#/components/responses/SellerApiServiceUnavailable"},"504":{"$ref":"#/components/responses/SellerApiTimeout"}}}},"/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,"description":"The product UUID, or the readable `prd_` id the product payloads return as `readableId`.","schema":{"type":"string","anyOf":[{"format":"uuid"},{"pattern":"^prd_[23456789abcdefghjkmnpqrstuvwxyz]{8}$"}]}},{"name":"expand","in":"query","description":"Comma-separated: `default` (editions and pricing, the default), `base` (product base only), `editions`, `pricing`. Any other value is 422.","schema":{"type":"string","description":"Comma-separated: `default` (editions and pricing, the default), `base` (product base only), `editions`, `pricing`. Any other value is 422."}},{"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"},{"name":"locales","in":"query","required":false,"schema":{"type":"string","example":"de,fr"},"description":"Comma-separated language tags (at most 30). Keeps only those languages in `localizedDescriptions` and `eula`; a language keeps its regional variants (`de` keeps `de-AT`). Omitted: every language, as before."},{"name":"descriptionFormat","in":"query","required":false,"schema":{"type":"string","enum":["html","text"],"default":"html"},"description":"`text` returns long descriptions as plain text: the store HTML (including embedded players and scripts) reduced to paragraphs, line breaks and bullet points."},{"name":"omit","in":"query","required":false,"schema":{"type":"string","example":"assets,eula,releasePricing"},"description":"Comma-separated blocks to leave out of the body: `assets`, `eula`, `localizedDescriptions`, `systemRequirements`, `relatedProducts`, and `releasePricing` (the deprecated `editions[].releases[].pricing`; the SKU `prices` stay). A named top-level block is absent from the response. An unknown value answers `422 VALIDATION_FAILED`. Omitted: the full body, as before. Additive."},{"$ref":"#/components/parameters/AvrixApiVersion"},{"$ref":"#/components/parameters/RequestId"},{"$ref":"#/components/parameters/SandboxSimulateRateLimit"},{"$ref":"#/components/parameters/IfNoneMatch"}],"responses":{"200":{"description":"Product detail","headers":{"X-Request-Id":{"$ref":"#/components/headers/XRequestId"},"X-Avrix-Api-Version":{"$ref":"#/components/headers/XAvrixApiVersion"},"X-Api-Version":{"$ref":"#/components/headers/XApiVersion"},"X-RateLimit-Limit":{"$ref":"#/components/headers/XRateLimitLimit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/XRateLimitRemaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/XRateLimitReset"},"X-RateLimit-Bucket":{"$ref":"#/components/headers/XRateLimitBucket"},"ETag":{"$ref":"#/components/headers/ETag"}},"content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/SellerProductDetail"},"relatedProducts":{"type":"array","description":"Never returned at this level. The edges are in `data.relatedProducts`; earlier versions of this document placed them here by mistake.","items":{"type":"object","required":["type","productId"],"properties":{"type":{"type":"string","enum":["requires","includes","upgrades","edition_of"]},"productId":{"type":"string","format":"uuid"}}},"deprecated":true}}},"example":{"data":{"id":"3c682ed5-f1d5-4bac-8043-6b6fbbd3dfa1","readableId":"prd_yq8u6t7a","createdAt":"2026-11-02T09:30:00Z","updatedAt":"2026-11-02T09:30:00Z","name":"Example Game","slug":"example-game","productType":"game","launchPhase":"draft","tradingState":"open","isArchived":false,"publisherCompanyId":"acme-games","publisherCompanyName":"Acme Games","publisherCompanyDescription":"Example text.","publisherWebsite":"https://api.avrix.io/api/seller/v1/example","publisherCountry":"DE","publisherCompanyImageUrl":"https://api.avrix.io/api/seller/v1/example","shortDescription":"Race through open city streets with friends.","coverUrl":"https://api.avrix.io/api/seller/v1/example","relatedProducts":[{"type":"requires","productId":"854f2bff-b362-4918-8033-3360a9e1df6b"}],"localizedDescriptions":[{"locale":"en","short":"example_short","long":"example_long","promotional":"example_promotional","legal":"example_legal"}],"supportedLanguages":["example_supportedlanguage"],"ageRatings":[{"authority":"PEGI","authorityCode":"PEGI","code":"PEGI_12","label":"Main storefront","minAge":1}],"genres":[{"code":"ACTION","name":"Example Game"}],"tags":[{"code":"AAA","name":"Example Game"}],"features":[{"code":"ACHIEVEMENTS","name":"Example Game"}],"eula":[{"locale":"en","text":"example_text"}],"assets":{"screenshots":["https://api.avrix.io/api/seller/v1/example"],"trailers":["https://api.avrix.io/api/seller/v1/example"],"capsules":["https://api.avrix.io/api/seller/v1/example"]},"systemRequirements":{"minimum":"example_minimum","recommended":"example_recommended"},"editions":[{"id":"b8b0ff01-f47a-49dc-8f57-40e88438af85","name":"Example Game","slug":"example-game","editionType":"standard","sortOrder":1,"shortDescription":"Race through open city streets with friends.","longDescription":"Race through open city streets with friends, tune your car and climb the weekly leaderboards.","keyFeatures":["example_keyfeature"],"editionDifferentiator":"example_editiondifferentiator","inheritsProductDescription":true,"releases":[{"id":"83bc7c93-65ba-4b37-82db-6b63ee2fa470","platformCode":"steam","platformName":"Steam","regionCode":"EU","regionName":"Europe","launchPhase":"draft","tradingState":"open","releaseDate":"2026-11-02T09:30:00Z","preorderStart":"2026-11-02T09:30:00Z","preorderEnd":"2026-11-02T09:30:00Z","preorderUnlocked":true,"skus":[{"id":"6dcc563e-8fb8-406f-8ca1-9491f60b582b","skuCode":"EXAMPLE-STEAM-WW","keyTypeCode":"RETAIL","keyTypeName":"Steam key","skuType":"regular","bundleItems":[{"productId":"c7bff07d-4a05-43b5-8a57-9a5f25716ecb","name":"Example Game","slug":"example-game"}],"externalReferences":[{"owner":"VALVE","source":"steam","name":"appId","value":"1172470"}],"activation":{"type":"worldwide","countries":["DE"]},"prices":[{"sellable":true,"countryCode":"DE","currencyCode":"EUR","basePriceCents":2450,"currencyExponent":2,"advertisedPriceCents":2450,"promoResolution":"applied"}],"promotions":[{"sourceType":"event","sourceId":"014ec920-5907-4d12-8b2d-2938240ba9fe","name":"Example Game","discountPercent":20,"priceEffect":"list_price","startDate":"2026-11-02T09:30:00Z","endDate":"2026-11-02T09:30:00Z","window":"live"}]}],"allowedCountries":["DE"]}]}],"refundPolicy":{"windowDays":1,"keyRevealForfeitsRefund":true,"quarantineOnRefund":true,"avrixMovesMoney":false,"source":"platform"},"developer":"Acme Studio","creditedPublisher":"Acme Games"}}}}},"304":{"description":"Not modified: the product has not changed since the `ETag` you sent in `If-None-Match`. No body, and the regular read budget is not charged.","headers":{"X-Request-Id":{"$ref":"#/components/headers/XRequestId"},"X-Avrix-Api-Version":{"$ref":"#/components/headers/XAvrixApiVersion"},"X-Api-Version":{"$ref":"#/components/headers/XApiVersion"},"X-RateLimit-Limit":{"$ref":"#/components/headers/XRateLimitLimit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/XRateLimitRemaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/XRateLimitReset"},"X-RateLimit-Bucket":{"$ref":"#/components/headers/XRateLimitBucket"},"ETag":{"$ref":"#/components/headers/ETag"}}},"400":{"$ref":"#/components/responses/SellerApiUnsupportedApiVersion"},"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"}}}},"422":{"$ref":"#/components/responses/SellerApiValidationFailed"},"429":{"$ref":"#/components/responses/SellerApiRateLimited"},"500":{"$ref":"#/components/responses/SellerApiInternalError"},"503":{"$ref":"#/components/responses/SellerApiServiceUnavailable"},"504":{"$ref":"#/components/responses/SellerApiTimeout"}},"security":[{"bearerAuth":[]}],"x-avrix-scopes":["seller:products:read"],"x-avrix-tier":"catalog","x-avrix-rate-limit-class":"catalog","x-avrix-scope-mode":"anyOf","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,"description":"The product UUID, or the readable `prd_` id the product payloads return as `readableId`.","schema":{"type":"string","anyOf":[{"format":"uuid"},{"pattern":"^prd_[23456789abcdefghjkmnpqrstuvwxyz]{8}$"}]}},{"name":"countryCode","in":"query","description":"Comma-separated ISO 3166-1 alpha-2 codes (e.g. `US,DE,GB`) — the canonical spelling, the same as the availability routes.","schema":{"type":"string","description":"Comma-separated country codes (e.g. US,DE,GB)"}},{"name":"country","in":"query","deprecated":true,"description":"Alias of `countryCode` (the original pricing spelling, still accepted). Sending both with different values fails validation; a request that uses only this spelling gets an `X-Avrix-Deprecated-Parameter` response header naming the replacement.","schema":{"type":"string","description":"Comma-separated country codes (e.g. US,DE,GB)"}},{"name":"expand","in":"query","description":"product = include product base in response","schema":{"type":"string","description":"product = include product base in response"}},{"$ref":"#/components/parameters/AvrixApiVersion"},{"$ref":"#/components/parameters/RequestId"},{"$ref":"#/components/parameters/SandboxSimulateRateLimit"},{"$ref":"#/components/parameters/IfNoneMatch"}],"responses":{"200":{"description":"Pricing data","headers":{"X-Request-Id":{"$ref":"#/components/headers/XRequestId"},"X-Avrix-Api-Version":{"$ref":"#/components/headers/XAvrixApiVersion"},"X-Api-Version":{"$ref":"#/components/headers/XApiVersion"},"X-RateLimit-Limit":{"$ref":"#/components/headers/XRateLimitLimit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/XRateLimitRemaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/XRateLimitReset"},"X-RateLimit-Bucket":{"$ref":"#/components/headers/XRateLimitBucket"},"ETag":{"$ref":"#/components/headers/ETag"}},"content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/PricingRelease"}}}},"example":{"data":[{"releaseId":"e6dbe63e-5175-4d04-86e5-a08296ceca3e","editionId":"e299f770-36fa-48a6-8228-adeb5adf2ee8","editionName":"Standard Edition","editionSlug":"example-game","platformCode":"steam","platformName":"Steam","regionCode":"EU","regionName":"Europe","releaseDate":"2026-11-02T09:30:00Z","preorderStart":"2026-11-02T09:30:00Z","preorderEnd":"2026-11-02T09:30:00Z","preorderUnlocked":true,"skus":[{"id":"05c0bff8-bf0c-4798-8acf-4680df088607","skuCode":"EXAMPLE-STEAM-WW","prices":[{"countryCode":"DE","currencyCode":"EUR","basePriceCents":2450,"currencyExponent":2,"sellable":true,"zone":{"code":"EUR","label":"Euro area and rest of Europe (EUR)"},"listPromo":{"sourceType":"event","sourceId":"77528dac-20c5-4ae4-8547-872c35c198c4","discountPercent":20,"priceEffect":"list_price","startDate":"2026-11-02T09:30:00Z","endDate":"2026-11-02T09:30:00Z"},"advertisedPriceCents":2450,"promo":{"sourceType":"event","sourceId":"e52f8a20-c7d0-4693-81b1-859997e181a6","discountPercent":20,"priceEffect":"settlement_price","startDate":"2026-11-02T09:30:00Z","endDate":"2026-11-02T09:30:00Z"},"promoResolution":"applied"}],"promotions":[{"sourceType":"event","sourceId":"58cabacc-d870-4343-8368-190361c6ead4","name":"Example Game","discountPercent":20,"priceEffect":"list_price","startDate":"2026-11-02T09:30:00Z","endDate":"2026-11-02T09:30:00Z","window":"live"}]}],"launchPhase":"available","tradingState":"open"}]}}}},"304":{"description":"Not modified: the pricing body has not changed since the `ETag` you sent in `If-None-Match`. No body, and the regular read budget is not charged.","headers":{"X-Request-Id":{"$ref":"#/components/headers/XRequestId"},"X-Avrix-Api-Version":{"$ref":"#/components/headers/XAvrixApiVersion"},"X-Api-Version":{"$ref":"#/components/headers/XApiVersion"},"X-RateLimit-Limit":{"$ref":"#/components/headers/XRateLimitLimit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/XRateLimitRemaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/XRateLimitReset"},"X-RateLimit-Bucket":{"$ref":"#/components/headers/XRateLimitBucket"},"ETag":{"$ref":"#/components/headers/ETag"}}},"400":{"$ref":"#/components/responses/SellerApiUnsupportedApiVersion"},"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"}}}},"422":{"$ref":"#/components/responses/SellerApiValidationFailed"},"429":{"$ref":"#/components/responses/SellerApiRateLimited"},"500":{"$ref":"#/components/responses/SellerApiInternalError"},"503":{"$ref":"#/components/responses/SellerApiServiceUnavailable"},"504":{"$ref":"#/components/responses/SellerApiTimeout"}},"security":[{"bearerAuth":[]}],"x-avrix-scopes":["seller:products:read"],"x-avrix-tier":"catalog","x-avrix-rate-limit-class":"catalog","x-avrix-scope-mode":"anyOf","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.\n\n`changesCursor` is the seller's current change-feed position: it advances on every recorded change, **including price changes, which the digest never sees** (they do not move a product's `updatedAt`). When it differs from the cursor you last applied, poll `GET /catalog/changes?cursor=`; when `digest` differs from your mirror, cold-start with the snapshot. The cursor is seller-wide even when `partner` scopes the digest.","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":"Deprecated alias of `partner` (still accepted). Sending both with different values fails validation; a request that uses only this spelling gets an `X-Avrix-Deprecated-Parameter` response header naming `partner`.","deprecated":true},{"$ref":"#/components/parameters/AvrixApiVersion"},{"$ref":"#/components/parameters/RequestId"},{"$ref":"#/components/parameters/SandboxSimulateRateLimit"}],"responses":{"200":{"description":"Integrity digest","headers":{"X-Request-Id":{"$ref":"#/components/headers/XRequestId"},"X-Avrix-Api-Version":{"$ref":"#/components/headers/XAvrixApiVersion"},"X-Api-Version":{"$ref":"#/components/headers/XApiVersion"},"X-RateLimit-Limit":{"$ref":"#/components/headers/XRateLimitLimit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/XRateLimitRemaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/XRateLimitReset"},"X-RateLimit-Bucket":{"$ref":"#/components/headers/XRateLimitBucket"}},"content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/CatalogIntegrityDigest"}},"required":["data"]},"example":{"data":{"totalProducts":2450,"maxUpdatedAt":"2026-11-02T09:30:00Z","digest":"sha256:9f86d081884c7d659a2feaa0c55ad015a3bf4f1b2b0b822cd15d6c15b0f00a08","digestAlgorithm":"sha256-sorted-product-rows-v1","changesCursor":"eyJ2IjoyLCJ0IjoiMjAyNi0xMS0wMlQwOTozMDowMFoifQ","generatedAt":"2026-11-02T09:30:00Z"}}}}},"400":{"$ref":"#/components/responses/SellerApiUnsupportedApiVersion"},"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"},"503":{"$ref":"#/components/responses/SellerApiServiceUnavailable"},"504":{"$ref":"#/components/responses/SellerApiTimeout"}},"x-avrix-scopes":["seller:products:read"],"x-avrix-tier":"catalog","x-avrix-rate-limit-class":"catalog","x-avrix-scope-mode":"anyOf","operationId":"listCatalogChecksum"}},"/api/seller/v1/catalog/changes":{"get":{"summary":"Catalog visibility delta","description":"Per-seller feed of catalog visibility transitions (`added`, `updated`, `removed` tombstones) and facet changes (`changedFields`). This is the delta source for **price changes**: they are recorded here with `changedFields: [\"pricing\"]` and never move a product's `updatedAt`. Use with `/catalog/snapshot` or `/products` for mirror correctness when products leave the catalog.\n\n**Cursor loop:** start from the snapshot's `meta.changesCursor` (or the checksum's `changesCursor`), pass it as `cursor`, apply the page, persist `meta.nextCursor` when present (it is the position of the last row returned; `null` means the page was empty — keep the cursor you sent) and poll again immediately while `meta.hasMore` is true.\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`. On contract date `2026-12-01` and later a position beyond retention is answered `409 CATALOG_RESYNC_REQUIRED` instead of a page with a silent gap.\n\nPaging keys and the cursor rules are on `https://docs.avrix.io/seller-api/pagination`.","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). On contract date `2026-12-01` and later a value that is not a whole number from 1 to 5000 is refused with 422; earlier dates fall back to the default or clamp."},{"name":"cursor","in":"query","required":false,"schema":{"type":"string"},"description":"Opaque feed position from `meta.nextCursor`, a snapshot's `meta.changesCursor` or a checksum's `changesCursor` — the preferred paging mode (tie- and clock-skew-safe). Returns events strictly after that position. When both `cursor` and `since` are sent, the cursor wins."},{"$ref":"#/components/parameters/AvrixApiVersion"},{"$ref":"#/components/parameters/RequestId"},{"$ref":"#/components/parameters/SandboxSimulateRateLimit"}],"responses":{"200":{"description":"Visibility changes","headers":{"X-Request-Id":{"$ref":"#/components/headers/XRequestId"},"X-Avrix-Api-Version":{"$ref":"#/components/headers/XAvrixApiVersion"},"X-Api-Version":{"$ref":"#/components/headers/XApiVersion"},"X-RateLimit-Limit":{"$ref":"#/components/headers/XRateLimitLimit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/XRateLimitRemaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/XRateLimitReset"},"X-RateLimit-Bucket":{"$ref":"#/components/headers/XRateLimitBucket"}},"content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"changes":{"type":"array","items":{"type":"object","properties":{"productId":{"type":"string","format":"uuid"},"skuId":{"type":["string","null"],"format":"uuid","description":"The SKU a SKU-level change is about (a territory price, SKU lifecycle or SKU share change); refetch that SKU's facet only. A `404` on that refetch, or a product that no longer lists the SKU, means it is no longer shared with you: remove it from your listing. `null` = product-level change."},"skuCode":{"type":["string","null"],"description":"`skuCode` of `skuId`; `null` for a product-level change."},"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"]},"meta":{"type":"object","properties":{"requestId":{"type":"string"},"nextCursor":{"type":["string","null"],"description":"Position of the last change in this page — persist it and send it back as `cursor`. At the head (empty page) it returns the cursor you sent unchanged, so persisting it blindly never loses your place; `null` only for an empty page when no cursor was sent. Loop on `hasMore`, not on `nextCursor`."},"hasMore":{"type":"boolean","description":"True when the page was cut at `limit`; poll again right away."},"limit":{"type":"integer","description":"The page size this response was cut at."},"nextUrl":{"type":["string","null"],"description":"Absolute URL of the next page: this request with `cursor` set to `nextCursor`. Null when there is no next page."}},"required":["nextCursor","hasMore"]}},"required":["data","meta"]},"example":{"data":{"changes":[{"productId":"61f2378b-1450-4939-83e8-a761b166e3b5","skuId":"73496151-1dab-4bc5-88fc-cdebaa27b76f","skuCode":"null","type":"added","occurredAt":"2026-11-02T09:30:00Z","changedFields":["pricing"]}]},"meta":{"requestId":"ffa5ec15-b04b-47f0-8172-1d777c400b26","nextCursor":"eyJ2IjoyLCJ0IjoiMjAyNi0xMS0wMlQwOTozMDowMFoifQ","hasMore":true,"limit":50,"nextUrl":"https://api.avrix.io/api/seller/v1/catalog/changes?cursor=eyJ2IjoyLCJ0IjoiMjAyNi0xMS0wMlQwOTozMDowMFoifQ"}}}}},"400":{"$ref":"#/components/responses/SellerApiUnsupportedApiVersion"},"401":{"$ref":"#/components/responses/SellerApiUnauthorized"},"403":{"$ref":"#/components/responses/SellerApiForbidden"},"409":{"description":"`CATALOG_RESYNC_REQUIRED`: the feed cannot continue from this position. With a sandbox key, the store moved to its isolated sandbox environment and the `cursor` (or a `since` before the move) belongs to the shared sandbox feed. Product, SKU and allocation ids changed; take a fresh `GET /catalog/snapshot` and continue from its cursors. Public sandbox fixture codes are unchanged. From contract date `2026-12-01` on, with any key: the `cursor` (or `since`) is older than the feed's retention and changes after it were deleted (`details.reason` is `retention_expired`). Take a fresh `GET /catalog/snapshot` and continue from its `meta.changesCursor` and `meta.availabilityCursor`. Earlier dates keep serving the retained rows after such a position.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"examples":{"CATALOG_RESYNC_REQUIRED":{"value":{"code":"CATALOG_RESYNC_REQUIRED","message":"Your sandbox moved to its own isolated environment: product, SKU and allocation ids changed. Take a fresh GET /catalog/snapshot and continue from its cursors. Public sandbox fixture codes are unchanged.","error":"Your sandbox moved to its own isolated environment: product, SKU and allocation ids changed. Take a fresh GET /catalog/snapshot and continue from its cursors. Public sandbox fixture codes are unchanged.","timestamp":"2026-10-12T09:30:00.000Z","recoverable":false,"doc_url":"https://docs.avrix.io/seller-api/errors#catalog-resync-required","requestId":"req_av1203_example","details":{"field":"cursor"}}},"CATALOG_RESYNC_REQUIRED_RETENTION":{"value":{"code":"CATALOG_RESYNC_REQUIRED","message":"This feed position is older than the feed's retention: changes after it were deleted and cannot be replayed. Take a fresh GET /catalog/snapshot and continue from its meta.changesCursor and meta.availabilityCursor.","error":"This feed position is older than the feed's retention: changes after it were deleted and cannot be replayed. Take a fresh GET /catalog/snapshot and continue from its meta.changesCursor and meta.availabilityCursor.","timestamp":"2026-12-02T09:30:00.000Z","recoverable":false,"doc_url":"https://docs.avrix.io/seller-api/errors#catalog-resync-required","requestId":"req_av2038_example","details":{"field":"cursor","reason":"retention_expired"}}}}}}},"422":{"description":"Invalid query parameters. On contract date `2026-12-01` and later the body uses the shared `details.issues[]` form (`validationTarget: \"query\"`), and an unreadable `cursor` or a `limit` that is not a whole number from 1 to 5000 is refused here.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"429":{"$ref":"#/components/responses/SellerApiRateLimited"},"500":{"$ref":"#/components/responses/SellerApiInternalError"},"503":{"$ref":"#/components/responses/SellerApiServiceUnavailable"},"504":{"$ref":"#/components/responses/SellerApiTimeout"}},"x-avrix-scopes":["seller:products:read"],"x-avrix-tier":"catalog","x-avrix-rate-limit-class":"catalog","x-avrix-scope-mode":"anyOf","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`.\n\n**After the snapshot:** persist `meta.changesCursor` and continue with `GET /catalog/changes?cursor=` — it lists every later change with the facets that moved (`changedFields`), **price changes included**. A price change never moves a product's `updatedAt`, so `meta.maxUpdatedAt` + `GET /products?updatedSince=` is a metadata / lifecycle delta only. Subscribe to `sku.pricing_updated`, `product.updated` and `allocation.updated` for push.\n\n**Caching:** Short-lived origin cache per `(sellerCompanyId, locale)`. No shared CDN cache: the response is `private` and key-scoped; your own cache may keep it for 5 minutes. Stable weak ETag derived from `(maxUpdatedAt, totalProducts, changesCursor)` — the feed position makes it move on every recorded change, prices included; a revalidation with `If-None-Match` returns 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"}},{"name":"pricing","in":"query","required":false,"description":"`territory` adds `territoryPrices` (every country list price) to each shared SKU, so a cold sync needs no `GET /products/{productId}/pricing` call per product. Cached and ETagged separately from the default snapshot.","schema":{"type":"string","enum":["territory"]}},{"$ref":"#/components/parameters/AvrixApiVersion"},{"$ref":"#/components/parameters/RequestId"},{"$ref":"#/components/parameters/SandboxSimulateRateLimit"}],"responses":{"200":{"description":"Full seller catalog snapshot","headers":{"ETag":{"schema":{"type":"string"},"description":"Weak ETag, e.g. `W/\"abc123...\"` — derived from `(maxUpdatedAt, totalProducts, changesCursor)`, so it moves on every recorded catalog change, price changes included"},"Cache-Control":{"schema":{"type":"string"},"description":"`private, max-age=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"},"X-Request-Id":{"$ref":"#/components/headers/XRequestId"},"X-Avrix-Api-Version":{"$ref":"#/components/headers/XAvrixApiVersion"},"X-Api-Version":{"$ref":"#/components/headers/XApiVersion"},"X-RateLimit-Limit":{"$ref":"#/components/headers/XRateLimitLimit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/XRateLimitRemaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/XRateLimitReset"},"X-RateLimit-Bucket":{"$ref":"#/components/headers/XRateLimitBucket"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CatalogSnapshot"},"example":{"meta":{"totalProducts":2450,"maxUpdatedAt":"2026-11-02T09:30:00Z","changesCursor":"eyJ2IjoyLCJ0IjoiMjAyNi0xMS0wMlQwOTozMDowMFoifQ","availabilityCursor":"eyJ2IjoyLCJ0IjoiMjAyNi0xMS0wMlQwOTozMDowMFoifQ","generatedAt":"2026-11-02T09:30:00Z","version":1},"data":[{"id":"48ebef6a-5355-4743-8574-04e74f438113","readableId":"prd_dzzkj22z","createdAt":"2026-11-02T09:30:00Z","name":"Example Game","slug":"example-game","productType":"game","launchPhase":"draft","tradingState":"open","isArchived":false,"publisherCompanyId":"acme-games","publisherCompanyName":"Acme Games","sharedSkus":[{"id":"e9f21c90-c8aa-417a-85cb-41780a612e26","skuCode":"EXAMPLE-STEAM-WW","platformName":"Steam","platformCode":"steam","editionName":"Standard Edition","keyTypeName":"Steam key","srpPriceCents":2450,"srpCurrencyCode":"EUR","srpCurrencyExponent":2,"sellable":true,"readinessBlockers":["example_readinessblocker"],"pricePerKeyCents":2450,"currencyCode":"null","currencyExponent":2,"territoryPrices":[{"countryCode":"DE","basePriceCents":2450,"basePriceMinor":2450,"zone":{"code":"EUR","label":"Euro area and rest of Europe (EUR)"},"currencyCode":"EUR","currencyExponent":2,"sellable":true,"blockedReason":null}]}],"coverUrl":"https://api.avrix.io/api/seller/v1/example","shortDescription":"Race through open city streets with friends.","editionCount":12,"platformNames":["Steam"],"platforms":[{"code":"steam","name":"Example Game"}],"regionNames":["Europe"],"regions":[{"code":"EU","name":"Example Game"}],"editionNamesShared":["example_editionnamesshared"],"sharedRegionReleaseCount":12,"listPriceFromCents":2450,"listPriceCurrencyCode":"EUR","listPriceCurrencyExponent":3,"updatedAt":"2026-11-02T09:30:00Z","publisherCompanyImageUrl":"https://api.avrix.io/api/seller/v1/example","publisherWebsite":"https://api.avrix.io/api/seller/v1/example","publisherCountry":"DE","relatedProducts":[{"type":"requires","productId":"640b3f65-149d-4062-8c6d-089eed11e11d"}]}]}},"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`","headers":{"X-Request-Id":{"$ref":"#/components/headers/XRequestId"},"X-Avrix-Api-Version":{"$ref":"#/components/headers/XAvrixApiVersion"},"X-Api-Version":{"$ref":"#/components/headers/XApiVersion"},"X-RateLimit-Limit":{"$ref":"#/components/headers/XRateLimitLimit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/XRateLimitRemaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/XRateLimitReset"},"X-RateLimit-Bucket":{"$ref":"#/components/headers/XRateLimitBucket"}}},"400":{"$ref":"#/components/responses/SellerApiUnsupportedApiVersion"},"401":{"$ref":"#/components/responses/SellerApiUnauthorized"},"403":{"$ref":"#/components/responses/SellerApiForbidden"},"413":{"description":"`BAD_REQUEST`: your visible catalog is larger than one snapshot response can carry. Request a file with `POST /catalog/exports`, or page through `GET /products`. Not the request-body limit: this operation takes no body.","headers":{"X-Request-Id":{"$ref":"#/components/headers/XRequestId"},"X-Avrix-Api-Version":{"$ref":"#/components/headers/XAvrixApiVersion"},"X-Api-Version":{"$ref":"#/components/headers/XApiVersion"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"422":{"$ref":"#/components/responses/SellerApiValidationFailed"},"429":{"$ref":"#/components/responses/SellerApiRateLimited"},"500":{"$ref":"#/components/responses/SellerApiInternalError"},"503":{"$ref":"#/components/responses/SellerApiServiceUnavailable"},"504":{"$ref":"#/components/responses/SellerApiTimeout"}},"x-avrix-scopes":["seller:products:read"],"x-avrix-tier":"catalog","x-avrix-rate-limit-class":"catalog","x-avrix-scope-mode":"anyOf","operationId":"getCatalogSnapshot"}},"/api/seller/v1/partners":{"get":{"summary":"List partners and connection requests","description":"The vendors you are connected to, and your connection requests. Each connection row has the **connection** id and timestamps, invoicing flags, public **vendor** profile fields (`publisherWebsite`, `publisherCountry`, `publisherDescription`, `publisherLogoUrl`) and a read-only **`contracts`** summary (`activeBmaTypes`, `mcaStatus`, `catalogShareMode`, `sharesSuspended`) for pre-pull diagnostics. The full agreed terms of one connection are on `GET /partners/{connectionId}/agreements`.\n\n**Statuses.** A connection is `active`, `suspended`, `terminating` (notice period running; still live) or `terminated`. A connection request is `pending` (waiting for an answer: `connectionRequest.waitingOn` says whose) or `rejected`. A request row has no connection yet: its `connectionId` is the request id (the same value as `connectionRequest.requestId`), its `contracts` summary is empty, and once the vendor approves it the row is replaced by the connection row, with the connection's own id. A vendor can appear twice: a `terminated` connection and a new request. Requests are sent, answered and cancelled in the console; `connectionRequest.consoleUrl` opens the page.\n\n**`status` filter.** `status` (comma-separated) lists exactly the statuses named, on every contract date. Without it, contract dates before `2026-12-01` list `active`, `suspended` and `terminated` rows, as before; `2026-12-01` and later also list `terminating` and `pending` rows. `rejected` rows are listed only when `status` names them.\n\n**Vendor id.** `publisherCompanyId` is the value to pass as `partner` on `GET /products` and `GET /catalog/checksum`. It is a slug-safe company id (at most 32 characters), not a UUID; `connectionId` is not accepted there.\n\n**Paging:** the shared list contract, see `https://docs.avrix.io/seller-api/pagination`. On contract date `2026-12-01` and later a `cursor` this API did not return is refused with `422 VALIDATION_FAILED` (`details.issues[].field` is `cursor`); earlier dates serve the first page.","responses":{"200":{"description":"Partners and connection requests, most recently updated first","headers":{"X-Request-Id":{"$ref":"#/components/headers/XRequestId"},"X-Avrix-Api-Version":{"$ref":"#/components/headers/XAvrixApiVersion"},"X-Api-Version":{"$ref":"#/components/headers/XApiVersion"},"X-RateLimit-Limit":{"$ref":"#/components/headers/XRateLimitLimit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/XRateLimitRemaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/XRateLimitReset"},"X-RateLimit-Bucket":{"$ref":"#/components/headers/XRateLimitBucket"}},"content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/SellerPartner"}},"meta":{"type":"object","properties":{"limit":{"type":"integer","description":"The page size this response was cut at."},"count":{"type":"integer","description":"Number of items in `data`."},"hasMore":{"type":"boolean","description":"True when another page follows. Loop on `hasMore`; send `nextCursor` back as `cursor`."},"nextCursor":{"type":["string","null"],"description":"Opaque position after the last item of this page; send it back as `cursor`. Null on the last page."},"nextUrl":{"type":["string","null"],"description":"Absolute URL of the next page: this request with `cursor` set to `nextCursor`. Null when there is no next page."}}}}},"example":{"data":[{"connectionId":"80a031bc-cd1e-451a-8df6-7725083aa787","sellerCompanyId":"e21b6d10-7ff3-4d88-87b9-533ee13f","publisherCompanyId":"acme-games","publisherCompanyName":"Acme Games","status":"active","connectionCreatedAt":"2026-11-02T09:30:00Z","connectionUpdatedAt":"2026-11-02T09:30:00Z","automatedSalesReportInvoicing":true,"offboardingStatus":"none","terminationEffectiveAt":"2026-11-02T09:30:00Z","terminationInitiatedAt":"2026-11-02T09:30:00Z","terminatedBy":null,"publisherWebsite":"https://api.avrix.io/api/seller/v1/example","publisherCountry":"DE","publisherDescription":"Example text.","publisherIndustry":"Video games","publisherCompanySize":"11-50","publisherRankingTier":"gold","publisherCompanyTypeCode":"vendor","publisherCompanyImageUrl":"https://api.avrix.io/api/seller/v1/example","publisherLogoUrl":"https://api.avrix.io/api/seller/v1/example","contracts":{"activeBmaTypes":["wholesale"],"pendingBmaTypes":["wholesale"],"pausedBmaTypes":["wholesale"],"mcaStatus":"active","catalogShareMode":"all","sharesSuspended":true,"activeTerms":[{"contractType":"mca","termId":"bbd50b36-7938-4345-8a05-28e4f048aea4","version":1,"effectiveAt":"2026-11-02T09:30:00Z"}],"pendingAmendmentCount":12,"lastContractChangeAt":"2026-11-02T09:30:00Z"}}],"meta":{"limit":50,"count":12,"hasMore":true,"nextCursor":"eyJ2IjoyLCJ0IjoiMjAyNi0xMS0wMlQwOTozMDowMFoifQ","nextUrl":"https://api.avrix.io/api/seller/v1/partners?cursor=eyJ2IjoyLCJ0IjoiMjAyNi0xMS0wMlQwOTozMDowMFoifQ"}}}}},"400":{"$ref":"#/components/responses/SellerApiUnsupportedApiVersion"},"401":{"$ref":"#/components/responses/SellerApiUnauthorized"},"403":{"$ref":"#/components/responses/SellerApiForbidden"},"422":{"$ref":"#/components/responses/SellerApiValidationFailed"},"429":{"$ref":"#/components/responses/SellerApiRateLimited"},"500":{"$ref":"#/components/responses/SellerApiInternalError"},"503":{"$ref":"#/components/responses/SellerApiServiceUnavailable"},"504":{"$ref":"#/components/responses/SellerApiTimeout"}},"security":[{"bearerAuth":[]}],"x-avrix-scopes":["seller:products:read"],"x-avrix-tier":"catalog","x-avrix-rate-limit-class":"catalog","x-avrix-scope-mode":"anyOf","tags":["Partners"],"operationId":"listPartners","parameters":[{"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 cursor from `meta.nextCursor` of the previous page."},{"name":"status","in":"query","required":false,"schema":{"type":"string","example":"active,pending"},"description":"Comma-separated statuses to list: `active`, `suspended`, `terminating`, `terminated` (connections), `pending`, `rejected` (connection requests). Accepted on every contract date; an unknown value answers `422 VALIDATION_FAILED` (`details.issues[].field` is `status`). Without it the contract date decides: before `2026-12-01` `active,suspended,terminated`; from `2026-12-01` `active,suspended,terminating,terminated,pending`."},{"$ref":"#/components/parameters/AvrixApiVersion"},{"$ref":"#/components/parameters/RequestId"},{"$ref":"#/components/parameters/SandboxSimulateRateLimit"}]}},"/api/seller/v1/partners/{connectionId}/offers":{"get":{"summary":"List pending title offers on a partner connection","description":"Titles the vendor offered under your agreement that you have not accepted or declined yet. Read only: accept or decline in the console. Only offers on an active agreement are listed. Returns an empty list when nothing is pending. A connection that is not yours, or the id of a connection request, returns 404.","security":[{"bearerAuth":[]}],"x-avrix-scopes":["seller:products:read"],"x-avrix-tier":"catalog","x-avrix-rate-limit-class":"catalog","x-avrix-scope-mode":"anyOf","parameters":[{"name":"connectionId","in":"path","required":true,"description":"Connection id (`connectionId` from GET /partners).","schema":{"type":"string","format":"uuid"}},{"$ref":"#/components/parameters/AvrixApiVersion"},{"$ref":"#/components/parameters/RequestId"},{"$ref":"#/components/parameters/SandboxSimulateRateLimit"}],"responses":{"200":{"description":"Pending title offers, oldest first","headers":{"X-Request-Id":{"$ref":"#/components/headers/XRequestId"},"X-Avrix-Api-Version":{"$ref":"#/components/headers/XAvrixApiVersion"},"X-Api-Version":{"$ref":"#/components/headers/XApiVersion"},"X-RateLimit-Limit":{"$ref":"#/components/headers/XRateLimitLimit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/XRateLimitRemaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/XRateLimitReset"},"X-RateLimit-Bucket":{"$ref":"#/components/headers/XRateLimitBucket"}},"content":{"application/json":{"schema":{"type":"object","required":["data"],"properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/SellerPartnerOffer"}}}},"example":{"data":[{"amendmentId":"f641b878-6d57-46de-8e58-aeaadce91738","releaseId":"39f29ecc-4a66-475c-8562-63d56c6cf5fa","productId":"78a207ce-41e4-4f1a-893b-1c732f2f81fc","productName":"Example Game","editionName":"Standard Edition","platformName":"Steam","message":"Example text.","proposedAt":"2026-11-02T09:30:00Z"}]}}}},"400":{"$ref":"#/components/responses/SellerApiUnsupportedApiVersion"},"401":{"$ref":"#/components/responses/SellerApiUnauthorized"},"403":{"$ref":"#/components/responses/SellerApiForbidden"},"404":{"description":"Partner connection not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"422":{"description":"Path validation failed (`connectionId` is not a UUID)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"429":{"$ref":"#/components/responses/SellerApiRateLimited"},"500":{"$ref":"#/components/responses/SellerApiInternalError"},"503":{"$ref":"#/components/responses/SellerApiServiceUnavailable"},"504":{"$ref":"#/components/responses/SellerApiTimeout"}},"operationId":"listPartnerOffers","tags":["Partners"]}},"/api/seller/v1/partners/{connectionId}/agreements":{"get":{"summary":"List the agreed terms on a partner connection","description":"The agreements in force with this vendor (`active`, `terminating`) or suspended (`paused`): the master agreement (`mca`) and each business-model agreement (`api`, `revenue_share`, `wholesale`, `pre_order`), with dates, renewal, territory, your revenue share and the settlement terms. Read only: agreements are proposed, signed and changed in the console (`consoleUrl`). Agreements still being negotiated or waiting for a signature are not listed; `GET /partners` counts them in `contracts.pendingBmaTypes`.\n\n`territory` is the grant orders are checked against: the signed countries plus later extensions. `permittedSaleCurrencies` names the currency rule; the per-currency detail is on `GET /whoami` (`permittedCurrenciesByPublisher`). `contract.activated`, `contract.expiring`, `contract.expired`, `contract.terminated` and `contract.amendment_accepted` tell you when to read this again.\n\nA connection that is not yours, or the id of a connection request, returns 404.","security":[{"bearerAuth":[]}],"x-avrix-scopes":["seller:products:read"],"x-avrix-tier":"catalog","x-avrix-rate-limit-class":"catalog","x-avrix-scope-mode":"anyOf","parameters":[{"name":"connectionId","in":"path","required":true,"description":"Connection id (`connectionId` from GET /partners).","schema":{"type":"string","format":"uuid"}},{"$ref":"#/components/parameters/AvrixApiVersion"},{"$ref":"#/components/parameters/RequestId"},{"$ref":"#/components/parameters/SandboxSimulateRateLimit"}],"responses":{"200":{"description":"Agreed terms: the master agreement first, then each business model","headers":{"X-Request-Id":{"$ref":"#/components/headers/XRequestId"},"X-Avrix-Api-Version":{"$ref":"#/components/headers/XAvrixApiVersion"},"X-Api-Version":{"$ref":"#/components/headers/XApiVersion"},"X-RateLimit-Limit":{"$ref":"#/components/headers/XRateLimitLimit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/XRateLimitRemaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/XRateLimitReset"},"X-RateLimit-Bucket":{"$ref":"#/components/headers/XRateLimitBucket"}},"content":{"application/json":{"schema":{"type":"object","required":["data"],"properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/SellerPartnerAgreement"}}}},"example":{"data":[{"termId":"1c2d3e4f-5a6b-4c7d-8e9f-0a1b2c3d4e5f","contractType":"mca","status":"active","version":1,"effectiveFrom":"2026-06-01T00:00:00.000Z","expiresAt":null,"activatedAt":"2026-06-01T08:12:00.000Z","renewalPolicy":"none","terminationNoticeAt":null,"terminationEffectiveAt":null,"territory":null,"sellerRevenueSharePercent":null,"paymentCurrency":null,"paymentTermsDays":30,"reportingFrequency":"monthly","reportingDeadlineDays":10,"permittedSaleCurrencies":null,"consoleUrl":"https://app.avrix.io/network/partners/9a8b7c6d-5e4f-4a3b-8c2d-1e0f9a8b7c6d/contracts?company=acme-store"},{"termId":"2d3e4f5a-6b7c-4d8e-9f0a-1b2c3d4e5f6a","contractType":"api","status":"active","version":2,"effectiveFrom":"2026-06-01T00:00:00.000Z","expiresAt":"2027-05-31T23:59:59.000Z","activatedAt":"2026-06-01T08:15:00.000Z","renewalPolicy":"auto_renew","terminationNoticeAt":null,"terminationEffectiveAt":null,"territory":{"worldwide":false,"countries":["BE","DE","FR","NL"]},"sellerRevenueSharePercent":25,"paymentCurrency":"EUR","paymentTermsDays":30,"reportingFrequency":"monthly","reportingDeadlineDays":10,"permittedSaleCurrencies":"primary_only","consoleUrl":"https://app.avrix.io/network/partners/9a8b7c6d-5e4f-4a3b-8c2d-1e0f9a8b7c6d/contracts?company=acme-store"}]}}}},"400":{"$ref":"#/components/responses/SellerApiUnsupportedApiVersion"},"401":{"$ref":"#/components/responses/SellerApiUnauthorized"},"403":{"$ref":"#/components/responses/SellerApiForbidden"},"404":{"description":"Partner connection not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"422":{"description":"Path validation failed (`connectionId` is not a UUID)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"429":{"$ref":"#/components/responses/SellerApiRateLimited"},"500":{"$ref":"#/components/responses/SellerApiInternalError"},"503":{"$ref":"#/components/responses/SellerApiServiceUnavailable"},"504":{"$ref":"#/components/responses/SellerApiTimeout"}},"operationId":"listPartnerAgreements","tags":["Catalog"]}},"/api/seller/v1/access/proposals":{"get":{"summary":"List partner access proposals","description":"Proposals from your Content Owners to widen what you may sell (more countries, another currency), waiting for your answer. Nothing changes until you accept. The same proposals appear per publisher under `whoami.accessByPublisher[].proposals`.","tags":["Partners"],"security":[{"bearerAuth":[]}],"parameters":[{"$ref":"#/components/parameters/AvrixApiVersion"},{"$ref":"#/components/parameters/RequestId"},{"$ref":"#/components/parameters/SandboxSimulateRateLimit"}],"responses":{"200":{"description":"Open proposals, oldest first","headers":{"X-Request-Id":{"$ref":"#/components/headers/XRequestId"},"X-Avrix-Api-Version":{"$ref":"#/components/headers/XAvrixApiVersion"},"X-Api-Version":{"$ref":"#/components/headers/XApiVersion"},"X-RateLimit-Limit":{"$ref":"#/components/headers/XRateLimitLimit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/XRateLimitRemaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/XRateLimitReset"},"X-RateLimit-Bucket":{"$ref":"#/components/headers/XRateLimitBucket"}},"content":{"application/json":{"schema":{"type":"object","required":["data"],"properties":{"data":{"type":"array","items":{"allOf":[{"$ref":"#/components/schemas/SellerPartnerAccessProposal"},{"type":"object","required":["publisherCompanyId","connectionId","contractTermId"],"properties":{"publisherCompanyId":{"type":"string"},"connectionId":{"type":"string"},"contractTermId":{"type":"string"}}}]}}}},"example":{"data":[{"id":"fe19cbc6-d16b-4b9a-8730-c3b86ec2ebf8","type":"territory_added","worldwide":true,"countryCodes":["DE"],"currencyCode":"EUR","reason":null,"effectiveFrom":"2026-11-02T09:30:00Z","proposedAt":"2026-11-02T09:30:00Z","publisherCompanyId":"acme-games","connectionId":"162f1e8d-4214-47b2-8599-3cf246db7de0","contractTermId":"dec7f681-420b-435e-80a8-a798bdcfc55e"}]}}}},"400":{"$ref":"#/components/responses/SellerApiUnsupportedApiVersion"},"401":{"$ref":"#/components/responses/SellerApiUnauthorized"},"403":{"$ref":"#/components/responses/SellerApiForbidden"},"422":{"$ref":"#/components/responses/SellerApiValidationFailed"},"429":{"$ref":"#/components/responses/SellerApiRateLimited"},"500":{"$ref":"#/components/responses/SellerApiInternalError"},"503":{"$ref":"#/components/responses/SellerApiServiceUnavailable"},"504":{"$ref":"#/components/responses/SellerApiTimeout"}},"x-avrix-scopes":[],"x-avrix-tier":"meta","x-avrix-rate-limit-class":"general","x-avrix-scope-mode":"any","operationId":"listAccessProposals"}},"/api/seller/v1/access/proposals/{id}/accept":{"post":{"summary":"Accept a partner access proposal","description":"Accept a Content Owner's proposal: the countries or the currency apply from now, or from the proposal's effectiveFrom if later. Checked again at acceptance: a currency must still be in the Content Owner's allowed currencies and convert to the agreement's payment currency at a reference rate from the last 14 days; a refusal names `details.accessCode` (ACCESS_FX_NOT_COVERED with `details.currencyPair`, ACCESS_CURRENCY_NOT_ALLOWED). Send an `Idempotency-Key` header (required). Requires `seller:account:manage`.","tags":["Partners"],"security":[{"bearerAuth":[]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","format":"uuid"},"description":"`id` from GET /access/proposals"},{"$ref":"#/components/parameters/IdempotencyKey"},{"$ref":"#/components/parameters/AvrixApiVersion"},{"$ref":"#/components/parameters/RequestId"},{"$ref":"#/components/parameters/SandboxSimulateWrite"}],"responses":{"200":{"description":"Accepted","headers":{"X-Request-Id":{"$ref":"#/components/headers/XRequestId"},"X-Avrix-Api-Version":{"$ref":"#/components/headers/XAvrixApiVersion"},"X-Api-Version":{"$ref":"#/components/headers/XApiVersion"},"Idempotency-Replayed":{"$ref":"#/components/headers/IdempotencyReplayed"},"X-RateLimit-Limit":{"$ref":"#/components/headers/XRateLimitLimit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/XRateLimitRemaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/XRateLimitReset"},"X-RateLimit-Bucket":{"$ref":"#/components/headers/XRateLimitBucket"}},"content":{"application/json":{"schema":{"type":"object","required":["data"],"properties":{"data":{"type":"object","required":["id","status","effectiveFrom"],"properties":{"id":{"type":"string","format":"uuid"},"status":{"type":"string","const":"accepted"},"effectiveFrom":{"type":["string","null"],"format":"date-time","description":"When the accepted change applies; null for a decline."}}}}},"example":{"data":{"id":"a525c1e0-81cb-42d8-8922-81a4028474a4","status":"accepted","effectiveFrom":"2026-11-02T09:30:00Z"}}}}},"400":{"$ref":"#/components/responses/SellerApiIdempotencyKeyRequired"},"401":{"$ref":"#/components/responses/SellerApiUnauthorized"},"403":{"$ref":"#/components/responses/SellerApiForbidden"},"404":{"description":"Proposal not found (or not addressed to you)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"409":{"description":"`CONFLICT`: already answered or withdrawn, the agreement is no longer active, or you have not accepted the updated platform terms yet (`details.accessCode`: `ACCESS_TERMS_NOT_ACCEPTED`). Also returned for the `Idempotency-Key` itself: `IDEMPOTENCY_KEY_MISMATCH` (the key was already used with a different body) and `IDEMPOTENCY_REQUEST_IN_FLIGHT` (an earlier request with this key is still running; retry after `Retry-After` seconds).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"422":{"description":"Invalid id, or the currency can no longer be granted (`details.accessCode`)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"429":{"$ref":"#/components/responses/SellerApiRateLimited"},"500":{"$ref":"#/components/responses/SellerApiInternalError"},"503":{"$ref":"#/components/responses/SellerApiServiceUnavailable"},"504":{"$ref":"#/components/responses/SellerApiTimeout"}},"x-avrix-scopes":["seller:account:manage"],"x-avrix-tier":"meta","x-avrix-rate-limit-class":"general","x-avrix-scope-mode":"anyOf","operationId":"acceptAccessProposal"}},"/api/seller/v1/access/proposals/{id}/decline":{"post":{"summary":"Decline a partner access proposal","description":"Decline a Content Owner's proposal. Nothing changes; the Content Owner is told. Send an `Idempotency-Key` header (required). Requires `seller:account:manage`.","tags":["Partners"],"security":[{"bearerAuth":[]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","format":"uuid"},"description":"`id` from GET /access/proposals"},{"$ref":"#/components/parameters/IdempotencyKey"},{"$ref":"#/components/parameters/AvrixApiVersion"},{"$ref":"#/components/parameters/RequestId"},{"$ref":"#/components/parameters/SandboxSimulateWrite"}],"responses":{"200":{"description":"Declined","headers":{"X-Request-Id":{"$ref":"#/components/headers/XRequestId"},"X-Avrix-Api-Version":{"$ref":"#/components/headers/XAvrixApiVersion"},"X-Api-Version":{"$ref":"#/components/headers/XApiVersion"},"Idempotency-Replayed":{"$ref":"#/components/headers/IdempotencyReplayed"},"X-RateLimit-Limit":{"$ref":"#/components/headers/XRateLimitLimit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/XRateLimitRemaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/XRateLimitReset"},"X-RateLimit-Bucket":{"$ref":"#/components/headers/XRateLimitBucket"}},"content":{"application/json":{"schema":{"type":"object","required":["data"],"properties":{"data":{"type":"object","required":["id","status","effectiveFrom"],"properties":{"id":{"type":"string","format":"uuid"},"status":{"type":"string","const":"declined"},"effectiveFrom":{"type":["string","null"],"format":"date-time","description":"When the accepted change applies; null for a decline."}}}}},"example":{"data":{"id":"1618d5f8-69ec-4c02-898b-a2c368216199","status":"declined","effectiveFrom":"2026-11-02T09:30:00Z"}}}}},"400":{"$ref":"#/components/responses/SellerApiIdempotencyKeyRequired"},"401":{"$ref":"#/components/responses/SellerApiUnauthorized"},"403":{"$ref":"#/components/responses/SellerApiForbidden"},"404":{"description":"Proposal not found (or not addressed to you)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"409":{"description":"`CONFLICT`: already answered or withdrawn, or the agreement is no longer active (`details.accessCode`). Also returned for the `Idempotency-Key` itself: `IDEMPOTENCY_KEY_MISMATCH` (the key was already used with a different body) and `IDEMPOTENCY_REQUEST_IN_FLIGHT` (an earlier request with this key is still running; retry after `Retry-After` seconds).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"422":{"description":"Invalid id, or the currency can no longer be granted (`details.accessCode`)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"429":{"$ref":"#/components/responses/SellerApiRateLimited"},"500":{"$ref":"#/components/responses/SellerApiInternalError"},"503":{"$ref":"#/components/responses/SellerApiServiceUnavailable"},"504":{"$ref":"#/components/responses/SellerApiTimeout"}},"x-avrix-scopes":["seller:account:manage"],"x-avrix-tier":"meta","x-avrix-rate-limit-class":"general","x-avrix-scope-mode":"anyOf","operationId":"declineAccessProposal"}},"/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, for the models that have one. Under `businessModel: api` there is no wholesale price: `pricePerKeyCents`, `currencyCode` and `currencyExponent` are `null` (never `0`) and the sale settles as a share of the territory list price, which every fulfilled pull records per key 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.\n\n**Paging:** the shared list contract, see `https://docs.avrix.io/seller-api/pagination`. On contract date `2026-12-01` and later a `cursor` this API did not return is refused with `422 VALIDATION_FAILED` (`details.issues[].field` is `cursor`); earlier dates serve the first page.","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"}},{"$ref":"#/components/parameters/AvrixApiVersion"},{"$ref":"#/components/parameters/RequestId"},{"$ref":"#/components/parameters/SandboxSimulateRateLimit"}],"responses":{"200":{"description":"Allocations list","headers":{"X-Request-Id":{"$ref":"#/components/headers/XRequestId"},"X-Avrix-Api-Version":{"$ref":"#/components/headers/XAvrixApiVersion"},"X-Api-Version":{"$ref":"#/components/headers/XApiVersion"},"X-RateLimit-Limit":{"$ref":"#/components/headers/XRateLimitLimit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/XRateLimitRemaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/XRateLimitReset"},"X-RateLimit-Bucket":{"$ref":"#/components/headers/XRateLimitBucket"}},"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":"Commercial model of the grant: `api` settles as a share of the territory list price (no wholesale price); `wholesale` / `pre_order` settle at `pricePerKeyCents`."},"paymentStatus":{"type":"string"},"pricePerKeyCents":{"type":["integer","null"],"description":"Deprecated name of `pricePerKeyMinor` (same value). Kept on the wire; see Naming conventions in the Versioning and compatibility guide. Wholesale contract price per key in `currencyCode` (`wholesale` / `pre_order` grants). **`null` = no wholesale price, and it is never `0`:** always `null` under `businessModel: api`, which settles as a share of the territory list price — read that from `GET /products/{productId}/pricing` and bind it with the preview `unitPriceCents` you echo on commit.","deprecated":true},"pricePerKeyMinor":{"type":["integer","null"],"description":"Wholesale contract price per key in `currencyCode` (`wholesale` / `pre_order` grants). **`null` = no wholesale price, and it is never `0`:** always `null` under `businessModel: api`, which settles as a share of the territory list price — read that from `GET /products/{productId}/pricing` and bind it with the preview `unitPriceCents` you echo on commit. Same amount as `pricePerKeyCents`, under the `...Minor` name every Seller API amount uses: integer minor units of the currency beside it (see `currencyExponent`)."},"currencyCode":{"type":["string","null"],"description":"ISO 4217 currency of `pricePerKeyCents`; `null` whenever the price is `null`."},"currencyExponent":{"type":["integer","null"],"description":"ISO 4217 minor-unit exponent for `currencyCode` (0 for JPY, 2 for USD, 3 for KWD); `null` whenever the price is `null`."},"shareActive":{"type":"boolean","description":"True when the SKU has an active share under your agreement."},"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, pricing and payment gates are satisfied for checkout. Payment follows commit's rule: wholesale and pre-order grants need confirmed payment; api and revenue-share grants do not."},"readinessBlockers":{"type":"array","items":{"type":"string"},"description":"Blocking codes such as NO_SKU_SHARE, NO_TERRITORY_PRICING, PAYMENT_NOT_CLEARED (commits under this grant are refused with 402 until its payment clears)."},"recommendedAction":{"type":["string","null"],"description":"`request_allocation_increase` once the grant has no headroom left (then call `POST /allocations/requests`); a readiness remediation such as `request_publisher_sku_share` (or `complete_allocation_payment` for PAYMENT_NOT_CLEARED) when the SKU is not sellable; null otherwise."},"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"},"hotDropMode":{"type":"boolean","description":"True while the Content Owner has this allocation in launch mode: place orders with POST /orders/reserve then POST /orders/commit (POST /orders/reserve answers 412 HOT_DROP_NOT_ENABLED otherwise). Switching it on or off sends allocation.updated with reason hot_drop_mode_changed."},"launchWindow":{"type":["object","null"],"description":"Keys the Content Owner reserved for you during a launch window, or null when there is none. When the window opens, `setAside` keys are held for your store: no other store can take them, and your orders use them first. When it closes, what you did not use goes back to the shared pool. A closed window stays visible for a day after it ends.","required":["startsAt","endsAt","reservedQuantity","state","setAside"],"properties":{"startsAt":{"type":"string","format":"date-time"},"endsAt":{"type":"string","format":"date-time"},"reservedQuantity":{"type":"integer","description":"Keys the Content Owner reserved for you."},"state":{"type":"string","enum":["scheduled","open","closed"]},"setAside":{"type":["integer","null"],"description":"Keys actually held for you when the window opened; less than `reservedQuantity` when stock was short. Null while scheduled."}}},"consumerGeoAttestRequired":{"type":"boolean","description":"True when this Content Owner requires confirming the buyer’s network from the checkout page before commercial orders. Derived from buyerVerification.level (false only for declared_ip)."},"requestable":{"type":"boolean","description":"`POST /allocations/requests` accepts a request for more on this grant (any grant of yours that is not revoked; one without an automatic rule goes to the publisher for review)."},"replenishment":{"type":"object","description":"Your automatic top-up trigger on this allocation (`PATCH /allocations/{id}`): top up when `remaining` falls to `threshold`, asking for `quantity` (null = the Content Owner's maximum). Both null = off.","required":["threshold","quantity"],"properties":{"threshold":{"type":["integer","null"]},"quantity":{"type":["integer","null"]}}},"keyless":{"type":"object","description":"The Content Owner's keyless settings: `allowed` (keyless delivery permitted; default true) and `default` (POST /orders with `deliveryMode: \"auto\"` goes keyless).","required":["allowed","default"],"properties":{"allowed":{"type":"boolean"},"default":{"type":"boolean"}}},"buyerVerification":{"$ref":"#/components/schemas/ConnectionBuyerVerification"}}}},"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"}}}}}}}},"example":{"data":[{"id":"5f806eee-a091-4312-83c5-a9cd7f1bfd15","readableId":"alc_x7pxwyu8","createdAt":"2026-11-02T09:30:00Z","publisherCompanyId":"acme-games","publisherCompanyName":"Acme Games","productId":"7483d800-44ec-4ba3-8dca-a656b522eb0b","skuId":"cfeed4af-d1c8-420b-8b05-acd821519257","skuCode":"EXAMPLE-STEAM-WW","productName":"Example Game","quantityLimit":50,"quantityPulled":12,"remaining":12,"status":"active","businessModel":"api","paymentStatus":"not_required","pricePerKeyCents":2450,"currencyCode":"null","currencyExponent":2,"shareActive":true,"catalogVisible":true,"territoryPricingSet":true,"sellable":true,"readinessBlockers":["example_readinessblocker"],"updatedAt":"2026-11-02T09:30:00Z","activation":{"type":"worldwide","countries":["DE"]},"refundPolicy":{"windowDays":1,"keyRevealForfeitsRefund":true,"quarantineOnRefund":true,"avrixMovesMoney":false,"source":"platform"},"hotDropMode":true,"launchWindow":{"startsAt":"2026-11-02T09:30:00Z","endsAt":"2026-11-02T09:30:00Z","reservedQuantity":12,"state":"scheduled","setAside":1},"consumerGeoAttestRequired":true,"requestable":true,"replenishment":{"threshold":1,"quantity":12},"keyless":{"allowed":true,"default":true},"buyerVerification":{"level":"declared_ip","riskAction":"refuse"}}],"meta":{"limit":50,"count":12,"nextCursor":"eyJ2IjoyLCJ0IjoiMjAyNi0xMS0wMlQwOTozMDowMFoifQ","nextUrl":"https://api.avrix.io/api/seller/v1/allocations?cursor=eyJ2IjoyLCJ0IjoiMjAyNi0xMS0wMlQwOTozMDowMFoifQ","hasMore":true,"warnings":[{"code":"API_SKU_MISSING_CATALOG_PRICE","message":"Example text."}]}}}}},"400":{"$ref":"#/components/responses/SellerApiUnsupportedApiVersion"},"401":{"$ref":"#/components/responses/SellerApiUnauthorized"},"403":{"$ref":"#/components/responses/SellerApiForbidden"},"422":{"$ref":"#/components/responses/SellerApiValidationFailed"},"429":{"$ref":"#/components/responses/SellerApiRateLimited"},"500":{"$ref":"#/components/responses/SellerApiInternalError"},"503":{"$ref":"#/components/responses/SellerApiServiceUnavailable"},"504":{"$ref":"#/components/responses/SellerApiTimeout"}},"security":[{"bearerAuth":[]}],"x-avrix-scopes":["seller:products:read"],"x-avrix-tier":"catalog","x-avrix-rate-limit-class":"catalog","x-avrix-scope-mode":"anyOf","tags":["Allocations"],"operationId":"listAllocations"}},"/api/seller/v1/allocations/{id}":{"patch":{"summary":"Set the automatic top-up trigger","description":"Set or clear the low-stock threshold of one of your allocations (`replenishThreshold`; null = off) and the top-up you want (`replenishQuantity`; null = the Content Owner's maximum). When a pull leaves `remaining` at or below the threshold, Avrix tops the allocation up within the Content Owner's rules (`allocation.replenished`) or files an allocation request for them to review (the manual path). A threshold that is already crossed is checked at once. `Idempotency-Key` is optional. The answer also returns the Content Owner's top-up `rules` and `effective`: what a crossing will do under them (top up at once, file a request, or nothing), so a threshold the rules will not honour is visible when you set it. On contract date `2026-12-01` and later a revoked allocation is refused with 409 `CONFLICT` (`details.reason: allocation_revoked`); earlier dates save it, and it never fires.\n\n**Shared sandbox (contract date `2026-12-01` and later):** a sandbox key on the shared sandbox gets **422** `SANDBOX_ISOLATED_ENVIRONMENT_REQUIRED` and nothing changes, because every store there shares the same allocations. Earlier contract dates still run the write. Production keys and isolated sandbox environments are not affected.","tags":["Allocations"],"security":[{"bearerAuth":[]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","format":"uuid"},"description":"Allocation id (`id` on GET /allocations)"},{"$ref":"#/components/parameters/IdempotencyKeyOptional"},{"$ref":"#/components/parameters/AvrixApiVersion"},{"$ref":"#/components/parameters/RequestId"},{"$ref":"#/components/parameters/SandboxSimulateWrite"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"properties":{"replenishThreshold":{"type":["integer","null"],"minimum":0,"maximum":1000000},"replenishQuantity":{"type":["integer","null"],"minimum":1,"maximum":1000000}}}}}},"responses":{"200":{"description":"Saved","headers":{"X-Request-Id":{"$ref":"#/components/headers/XRequestId"},"X-Avrix-Api-Version":{"$ref":"#/components/headers/XAvrixApiVersion"},"X-Api-Version":{"$ref":"#/components/headers/XApiVersion"},"Idempotency-Replayed":{"$ref":"#/components/headers/IdempotencyReplayed"},"X-RateLimit-Limit":{"$ref":"#/components/headers/XRateLimitLimit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/XRateLimitRemaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/XRateLimitReset"},"X-RateLimit-Bucket":{"$ref":"#/components/headers/XRateLimitBucket"}},"content":{"application/json":{"schema":{"type":"object","required":["data"],"properties":{"data":{"type":"object","required":["allocationId","replenishment"],"properties":{"allocationId":{"type":"string","format":"uuid"},"replenishment":{"type":"object","required":["threshold","quantity"],"properties":{"threshold":{"type":["integer","null"],"minimum":0},"quantity":{"type":["integer","null"],"minimum":1}}},"rules":{"type":"object","properties":{"automatic":{"type":"boolean"},"maxQuantity":{"type":["integer","null"]},"minIntervalHours":{"type":"integer"},"ceilingCap":{"type":["integer","null"]}},"description":"The Content Owner's top-up rules for this allocation."},"effective":{"$ref":"#/components/schemas/AllocationReplenishEffect"}}}}},"example":{"data":{"allocationId":"de3bf764-8ac2-4795-8b5f-00028594099e","replenishment":{"threshold":1,"quantity":12}}}}}},"400":{"$ref":"#/components/responses/SellerApiUnsupportedApiVersion"},"401":{"$ref":"#/components/responses/SellerApiUnauthorized"},"403":{"$ref":"#/components/responses/SellerApiForbidden"},"404":{"description":"Allocation not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"409":{"description":"`CONFLICT` with `details.reason: allocation_revoked` (contract date `2026-12-01` and later): the allocation is revoked, so a top-up trigger on it would never fire. The `Idempotency-Key` cannot be used for this request. `IDEMPOTENCY_KEY_MISMATCH`: the key was already used with a different body; use a new key for a new request. `IDEMPOTENCY_REQUEST_IN_FLIGHT`: an earlier request with this key is still running; wait `Retry-After` seconds and send the same request again.","headers":{"X-Request-Id":{"$ref":"#/components/headers/XRequestId"},"X-Avrix-Api-Version":{"$ref":"#/components/headers/XAvrixApiVersion"},"X-Api-Version":{"$ref":"#/components/headers/XApiVersion"},"Retry-After":{"$ref":"#/components/headers/RetryAfter"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"413":{"$ref":"#/components/responses/SellerApiPayloadTooLarge"},"422":{"description":"Invalid body or id (`VALIDATION_FAILED`), or `SANDBOX_ISOLATED_ENVIRONMENT_REQUIRED` for a shared-sandbox key on contract date `2026-12-01` or later","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"429":{"$ref":"#/components/responses/SellerApiRateLimited"},"500":{"$ref":"#/components/responses/SellerApiInternalError"},"503":{"$ref":"#/components/responses/SellerApiServiceUnavailable"},"504":{"$ref":"#/components/responses/SellerApiTimeout"}},"x-avrix-scopes":["seller:allocations:write","seller:orders:write","seller:keys:pull"],"x-avrix-tier":"orders","x-avrix-rate-limit-class":"orders","x-avrix-scope-mode":"anyOf","operationId":"updateAllocation"},"get":{"summary":"Get one allocation","description":"One of your allocations: the same row `GET /allocations` returns, whatever its status, so an allocation a webhook names can be read even when it is paused or revoked (the list shows active allocations only). 404 when the id is not one of your allocations.","tags":["Allocations"],"security":[{"bearerAuth":[]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","format":"uuid"},"description":"Allocation id (`id` on GET /allocations, `allocationId` on webhooks)"},{"$ref":"#/components/parameters/AvrixApiVersion"},{"$ref":"#/components/parameters/RequestId"},{"$ref":"#/components/parameters/SandboxSimulateRateLimit"}],"responses":{"200":{"description":"The allocation","headers":{"X-Request-Id":{"$ref":"#/components/headers/XRequestId"},"X-Avrix-Api-Version":{"$ref":"#/components/headers/XAvrixApiVersion"},"X-Api-Version":{"$ref":"#/components/headers/XApiVersion"},"X-RateLimit-Limit":{"$ref":"#/components/headers/XRateLimitLimit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/XRateLimitRemaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/XRateLimitReset"},"X-RateLimit-Bucket":{"$ref":"#/components/headers/XRateLimitBucket"}},"content":{"application/json":{"schema":{"type":"object","required":["data"],"properties":{"data":{"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":"Commercial model of the grant: `api` settles as a share of the territory list price (no wholesale price); `wholesale` / `pre_order` settle at `pricePerKeyCents`."},"paymentStatus":{"type":"string"},"pricePerKeyCents":{"type":["integer","null"],"description":"Deprecated name of `pricePerKeyMinor` (same value). Kept on the wire; see Naming conventions in the Versioning and compatibility guide. Wholesale contract price per key in `currencyCode` (`wholesale` / `pre_order` grants). **`null` = no wholesale price, and it is never `0`:** always `null` under `businessModel: api`, which settles as a share of the territory list price — read that from `GET /products/{productId}/pricing` and bind it with the preview `unitPriceCents` you echo on commit.","deprecated":true},"pricePerKeyMinor":{"type":["integer","null"],"description":"Wholesale contract price per key in `currencyCode` (`wholesale` / `pre_order` grants). **`null` = no wholesale price, and it is never `0`:** always `null` under `businessModel: api`, which settles as a share of the territory list price — read that from `GET /products/{productId}/pricing` and bind it with the preview `unitPriceCents` you echo on commit. Same amount as `pricePerKeyCents`, under the `...Minor` name every Seller API amount uses: integer minor units of the currency beside it (see `currencyExponent`)."},"currencyCode":{"type":["string","null"],"description":"ISO 4217 currency of `pricePerKeyCents`; `null` whenever the price is `null`."},"currencyExponent":{"type":["integer","null"],"description":"ISO 4217 minor-unit exponent for `currencyCode` (0 for JPY, 2 for USD, 3 for KWD); `null` whenever the price is `null`."},"shareActive":{"type":"boolean","description":"True when the SKU has an active share under your agreement."},"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, pricing and payment gates are satisfied for checkout. Payment follows commit's rule: wholesale and pre-order grants need confirmed payment; api and revenue-share grants do not."},"readinessBlockers":{"type":"array","items":{"type":"string"},"description":"Blocking codes such as NO_SKU_SHARE, NO_TERRITORY_PRICING, PAYMENT_NOT_CLEARED (commits under this grant are refused with 402 until its payment clears)."},"recommendedAction":{"type":["string","null"],"description":"`request_allocation_increase` once the grant has no headroom left (then call `POST /allocations/requests`); a readiness remediation such as `request_publisher_sku_share` (or `complete_allocation_payment` for PAYMENT_NOT_CLEARED) when the SKU is not sellable; null otherwise."},"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"},"hotDropMode":{"type":"boolean","description":"True while the Content Owner has this allocation in launch mode: place orders with POST /orders/reserve then POST /orders/commit (POST /orders/reserve answers 412 HOT_DROP_NOT_ENABLED otherwise). Switching it on or off sends allocation.updated with reason hot_drop_mode_changed."},"launchWindow":{"type":["object","null"],"description":"Keys the Content Owner reserved for you during a launch window, or null when there is none. When the window opens, `setAside` keys are held for your store: no other store can take them, and your orders use them first. When it closes, what you did not use goes back to the shared pool. A closed window stays visible for a day after it ends.","required":["startsAt","endsAt","reservedQuantity","state","setAside"],"properties":{"startsAt":{"type":"string","format":"date-time"},"endsAt":{"type":"string","format":"date-time"},"reservedQuantity":{"type":"integer","description":"Keys the Content Owner reserved for you."},"state":{"type":"string","enum":["scheduled","open","closed"],"description":"`scheduled`: the window has not started. `open`: the window is running and the `setAside` keys are held for your store. `closed`: the window ended and the keys you did not use went back to the shared pool."},"setAside":{"type":["integer","null"],"description":"Keys actually held for you when the window opened; less than `reservedQuantity` when stock was short. Null while scheduled."}}},"consumerGeoAttestRequired":{"type":"boolean","description":"True when this Content Owner requires confirming the buyer’s network from the checkout page before commercial orders. Derived from buyerVerification.level (false only for declared_ip)."},"requestable":{"type":"boolean","description":"`POST /allocations/requests` accepts a request for more on this grant (any grant of yours that is not revoked; one without an automatic rule goes to the publisher for review)."},"replenishment":{"type":"object","description":"Your automatic top-up trigger on this allocation (`PATCH /allocations/{id}`): top up when `remaining` falls to `threshold`, asking for `quantity` (null = the Content Owner's maximum). Both null = off.","required":["threshold","quantity"],"properties":{"threshold":{"type":["integer","null"]},"quantity":{"type":["integer","null"]}}},"keyless":{"type":"object","description":"The Content Owner's keyless settings: `allowed` (keyless delivery permitted; default true) and `default` (POST /orders with `deliveryMode: \"auto\"` goes keyless).","required":["allowed","default"],"properties":{"allowed":{"type":"boolean"},"default":{"type":"boolean"}}},"buyerVerification":{"$ref":"#/components/schemas/ConnectionBuyerVerification"}}}}},"example":{"data":{"id":"c36d1ab4-0849-49f4-8266-a904e35c099c","readableId":"alc_cdgev35u","createdAt":"2026-11-02T09:30:00Z","publisherCompanyId":"acme-games","publisherCompanyName":"Acme Games","productId":"347112d3-11a9-4a89-842c-ffa76c7d75e8","skuId":"e60cdfdf-a0ae-438a-8540-1a790e55e87b","skuCode":"EXAMPLE-STEAM-WW","productName":"Example Game","quantityLimit":50,"quantityPulled":12,"remaining":12,"status":"active","businessModel":"api","paymentStatus":"not_required","pricePerKeyMinor":2450,"currencyCode":"null","currencyExponent":2,"shareActive":true,"catalogVisible":true,"territoryPricingSet":true,"sellable":true,"readinessBlockers":["example_readinessblocker"],"updatedAt":"2026-11-02T09:30:00Z","activation":{"type":"worldwide","countries":["DE"]},"refundPolicy":{"windowDays":1,"keyRevealForfeitsRefund":true,"quarantineOnRefund":true,"avrixMovesMoney":false,"source":"platform","revealedKeysRefundable":true},"hotDropMode":true,"launchWindow":{"startsAt":"2026-11-02T09:30:00Z","endsAt":"2026-11-02T09:30:00Z","reservedQuantity":12,"state":"scheduled","setAside":1},"consumerGeoAttestRequired":true,"requestable":true,"replenishment":{"threshold":1,"quantity":12},"keyless":{"allowed":true,"default":true},"buyerVerification":{"level":"declared_ip","riskAction":"refuse"}}}}}},"400":{"$ref":"#/components/responses/SellerApiUnsupportedApiVersion"},"401":{"$ref":"#/components/responses/SellerApiUnauthorized"},"403":{"$ref":"#/components/responses/SellerApiForbidden"},"404":{"description":"NOT_FOUND: the id is not one of your allocations","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"422":{"description":"VALIDATION_FAILED: the id is not a UUID","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"429":{"$ref":"#/components/responses/SellerApiRateLimited"},"500":{"$ref":"#/components/responses/SellerApiInternalError"},"503":{"$ref":"#/components/responses/SellerApiServiceUnavailable"},"504":{"$ref":"#/components/responses/SellerApiTimeout"}},"x-avrix-scopes":["seller:products:read"],"x-avrix-tier":"catalog","x-avrix-rate-limit-class":"catalog","x-avrix-scope-mode":"anyOf","operationId":"getAllocation"}},"/api/seller/v1/allocations/{id}/replenishments":{"get":{"summary":"Automatic top-up history","description":"Your top-up trigger on the allocation, the Content Owner's rules for it, and every automatic top-up (`auto_replenished`) or request filed outside the rules (`auto_replenish_requested`), newest first. The Content Owner sees the same history. `effective` says what a crossing does under the rules. A read that fails answers 500, 503 or 504 (with `Retry-After` on 503/504), never 404 or an empty history.","tags":["Allocations"],"security":[{"bearerAuth":[]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","format":"uuid"},"description":"Allocation id (`id` on GET /allocations)"},{"$ref":"#/components/parameters/AvrixApiVersion"},{"$ref":"#/components/parameters/RequestId"},{"$ref":"#/components/parameters/SandboxSimulateRateLimit"}],"responses":{"200":{"description":"History","headers":{"X-Request-Id":{"$ref":"#/components/headers/XRequestId"},"X-Avrix-Api-Version":{"$ref":"#/components/headers/XAvrixApiVersion"},"X-Api-Version":{"$ref":"#/components/headers/XApiVersion"},"X-RateLimit-Limit":{"$ref":"#/components/headers/XRateLimitLimit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/XRateLimitRemaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/XRateLimitReset"},"X-RateLimit-Bucket":{"$ref":"#/components/headers/XRateLimitBucket"}},"content":{"application/json":{"schema":{"type":"object","required":["data"],"properties":{"data":{"type":"object","required":["allocationId","replenishment","rules","history"],"properties":{"allocationId":{"type":"string","format":"uuid"},"replenishment":{"type":"object","required":["threshold","quantity"],"properties":{"threshold":{"type":["integer","null"],"minimum":0},"quantity":{"type":["integer","null"],"minimum":1}}},"rules":{"type":"object","properties":{"automatic":{"type":"boolean"},"maxQuantity":{"type":["integer","null"]},"minIntervalHours":{"type":"integer"},"ceilingCap":{"type":["integer","null"]}}},"history":{"type":"array","items":{"type":"object","properties":{"type":{"type":"string","enum":["auto_replenished","auto_replenish_requested"]},"quantity":{"type":"integer"},"occurredAt":{"type":"string","format":"date-time"},"details":{"type":"object","additionalProperties":true}}}},"effective":{"$ref":"#/components/schemas/AllocationReplenishEffect"}}},"meta":{"type":"object","properties":{"requestId":{"type":"string"}}}}},"example":{"data":{"allocationId":"63443ec2-dfe3-4b6f-825d-eab329152d71","replenishment":{"threshold":1,"quantity":12},"rules":{"automatic":true,"maxQuantity":12,"minIntervalHours":1,"ceilingCap":12},"history":[{"type":"auto_replenished","quantity":12,"occurredAt":"2026-11-02T09:30:00Z","details":{}}]},"meta":{"requestId":"421d84b8-784e-4676-87b8-9c30653c65e2"}}}}},"400":{"$ref":"#/components/responses/SellerApiUnsupportedApiVersion"},"401":{"$ref":"#/components/responses/SellerApiUnauthorized"},"403":{"$ref":"#/components/responses/SellerApiForbidden"},"404":{"description":"Allocation not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"422":{"description":"Invalid id","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"429":{"$ref":"#/components/responses/SellerApiRateLimited"},"500":{"$ref":"#/components/responses/SellerApiInternalError"},"503":{"$ref":"#/components/responses/SellerApiServiceUnavailable"},"504":{"$ref":"#/components/responses/SellerApiTimeout"}},"x-avrix-scopes":["seller:products:read"],"x-avrix-tier":"catalog","x-avrix-rate-limit-class":"catalog","x-avrix-scope-mode":"anyOf","operationId":"listAllocationReplenishments"}},"/api/seller/v1/allocations/requests":{"get":{"summary":"List allocation requests","description":"Allocation requests you filed, newest first. Page with `limit` and `cursor` until `meta.nextCursor` is null (the list contract on `https://docs.avrix.io/seller-api/pagination`). Without `limit` a page holds up to 100 rows. Filter with `state` (one or more, comma-separated) and `allocationId`. Read one request with `GET /allocations/requests/{id}`.","parameters":[{"name":"limit","in":"query","required":false,"schema":{"type":"integer","minimum":1,"maximum":100,"default":100},"description":"Page size (1-100, default 100)."},{"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":"state","in":"query","required":false,"schema":{"type":"string"},"description":"Only requests in these states, comma-separated: `pending`, `auto_granted`, `approved`, `denied`, `backordered`, `cancelled`.","example":"pending,backordered"},{"name":"allocationId","in":"query","required":false,"schema":{"type":"string","format":"uuid"},"description":"Only requests for this allocation."},{"$ref":"#/components/parameters/AvrixApiVersion"},{"$ref":"#/components/parameters/RequestId"},{"$ref":"#/components/parameters/SandboxSimulateRateLimit"}],"responses":{"200":{"description":"Request list","headers":{"X-Request-Id":{"$ref":"#/components/headers/XRequestId"},"X-Avrix-Api-Version":{"$ref":"#/components/headers/XAvrixApiVersion"},"X-Api-Version":{"$ref":"#/components/headers/XApiVersion"},"X-RateLimit-Limit":{"$ref":"#/components/headers/XRateLimitLimit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/XRateLimitRemaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/XRateLimitReset"},"X-RateLimit-Bucket":{"$ref":"#/components/headers/XRateLimitBucket"}},"content":{"application/json":{"schema":{"type":"object","required":["data","meta"],"properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/SellerAllocationRequest"}},"meta":{"type":"object","required":["limit","hasMore","nextCursor","count"],"properties":{"limit":{"type":"integer"},"count":{"type":"integer","description":"Rows in this page."},"hasMore":{"type":"boolean"},"nextCursor":{"type":["string","null"],"description":"Cursor for the next page; null on the last page."},"nextUrl":{"type":["string","null"],"description":"Absolute URL of the next page; null on the last page."}}}}},"example":{"data":[{"id":"042e2592-3d48-4912-8aa7-524b5bfbe2c7","publisherCompanyId":"acme-games","sellerCompanyId":"8f0e747d-36c4-4b3a-842c-3d72959430a3","skuId":"67ce1fb9-ff07-4dcc-8793-eba855dc8a58","businessModel":"wholesale","allocationGrantId":"06d3443d-c78a-47c2-828f-a126e4d9b5f4","requestedQuantity":12,"declaredForecast":1,"status":"pending","resolution":"auto_granted","resolvedGrantDelta":1,"resolvedBy":null,"resolvedAt":"2026-11-02T09:30:00Z","decisionNote":"Example text.","createdAt":"2026-11-02T09:30:00Z","allocationId":"e7dc9a4f-91b5-4e7b-8c7a-31ba8084a32d","state":"pending","updatedAt":"2026-11-02T09:30:00Z"}],"meta":{"limit":50,"count":12,"hasMore":true,"nextCursor":"eyJ2IjoyLCJ0IjoiMjAyNi0xMS0wMlQwOTozMDowMFoifQ","nextUrl":"https://api.avrix.io/api/seller/v1/example?cursor=eyJ2IjoyfQ"}}}}},"400":{"$ref":"#/components/responses/SellerApiUnsupportedApiVersion"},"401":{"$ref":"#/components/responses/SellerApiUnauthorized"},"403":{"$ref":"#/components/responses/SellerApiForbidden"},"422":{"$ref":"#/components/responses/SellerApiValidationFailed"},"429":{"$ref":"#/components/responses/SellerApiRateLimited"},"500":{"$ref":"#/components/responses/SellerApiInternalError"},"503":{"$ref":"#/components/responses/SellerApiServiceUnavailable"},"504":{"$ref":"#/components/responses/SellerApiTimeout"}},"security":[{"bearerAuth":[]}],"x-avrix-scopes":["seller:products:read"],"x-avrix-tier":"orders","x-avrix-rate-limit-class":"orders","x-avrix-scope-mode":"anyOf","tags":["Allocations"],"operationId":"listAllocationsRequests"},"post":{"summary":"Create allocation request","description":"Ask the Content Owner for more keys on one of your allocations. Name the allocation with `allocationId` (`grantId` is the older name of the same field and stays accepted; send one, or both with the same value). The Content Owner's rules may grant it at once (`resolution: auto_granted`); otherwise it waits for them (`pending_review`) and `allocation.request_decided` tells you the outcome. Their free stock is read on the server; `publisherAvailableKeys` is accepted for compatibility and ignored. One pending request per allocation: a second answers 409 with `details.pendingRequestId`. Withdraw a pending request with `POST /allocations/requests/{id}/cancel`; to change the quantity, cancel and file a new one. **Status:** 200 before contract date `2026-12-01`; 201 on `2026-12-01` and later, with the same body. **Retries:** send an `Idempotency-Key` to make a retry safe: the same key and body replay the first answer with `Idempotency-Replayed: true` instead of acting twice. An automatic grant is checked against the vendor's auto-grant cap when it is applied; a request that would take the grant past the cap stays pending for the vendor.","parameters":[{"$ref":"#/components/parameters/IdempotencyKeyOptional"},{"$ref":"#/components/parameters/AvrixApiVersion"},{"$ref":"#/components/parameters/RequestId"},{"$ref":"#/components/parameters/SandboxSimulateWrite"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["requestedQuantity"],"properties":{"allocationId":{"type":"string","format":"uuid","description":"The allocation to grow (`id` on GET /allocations)."},"grantId":{"type":"string","format":"uuid","description":"Older name of `allocationId`; still accepted. When both are sent they must be equal."},"requestedQuantity":{"type":"integer","minimum":1,"description":"Keys you want added."},"declaredForecast":{"type":"integer","minimum":0,"description":"Optional: the units you expect to sell, for the Content Owner's review."},"publisherAvailableKeys":{"type":"integer","minimum":0,"description":"Ignored. Accepted so existing callers keep working; the Content Owner's free stock is always read on the server."}},"additionalProperties":false,"anyOf":[{"required":["allocationId"]},{"required":["grantId"]}]},"example":{"allocationId":"3f1c2a9e-8b7d-4c6e-9a10-5d2e7b4f8c21","requestedQuantity":100,"declaredForecast":250}}}},"responses":{"200":{"description":"Request filed or granted at once (contract dates before `2026-12-01`).","headers":{"X-Request-Id":{"$ref":"#/components/headers/XRequestId"},"X-Avrix-Api-Version":{"$ref":"#/components/headers/XAvrixApiVersion"},"X-Api-Version":{"$ref":"#/components/headers/XApiVersion"},"Idempotency-Replayed":{"$ref":"#/components/headers/IdempotencyReplayed"},"X-RateLimit-Limit":{"$ref":"#/components/headers/XRateLimitLimit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/XRateLimitRemaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/XRateLimitReset"},"X-RateLimit-Bucket":{"$ref":"#/components/headers/XRateLimitBucket"}},"content":{"application/json":{"schema":{"type":"object","required":["data"],"properties":{"data":{"$ref":"#/components/schemas/SellerAllocationRequestCreated"}}},"example":{"data":{"requestId":"40193189-7864-4b21-8d70-08120597f7cc","resolution":"auto_granted","grantDelta":1,"allocationId":"1164918c-d613-4ea6-8aca-ba348968b285","state":"pending"}}}}},"201":{"description":"Request filed or granted at once (contract date `2026-12-01` and later).","headers":{"X-Request-Id":{"$ref":"#/components/headers/XRequestId"},"X-Avrix-Api-Version":{"$ref":"#/components/headers/XAvrixApiVersion"},"X-Api-Version":{"$ref":"#/components/headers/XApiVersion"},"Idempotency-Replayed":{"$ref":"#/components/headers/IdempotencyReplayed"},"X-RateLimit-Limit":{"$ref":"#/components/headers/XRateLimitLimit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/XRateLimitRemaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/XRateLimitReset"},"X-RateLimit-Bucket":{"$ref":"#/components/headers/XRateLimitBucket"}},"content":{"application/json":{"schema":{"type":"object","required":["data"],"properties":{"data":{"$ref":"#/components/schemas/SellerAllocationRequestCreated"}}},"example":{"data":{"requestId":"7f8548d2-789a-48a6-81b2-ca7fe6f72c0b","resolution":"pending_review","grantDelta":1,"allocationId":"19fb6af6-0ce1-47ef-8a61-3af04f19b2ac","state":"pending"}}}}},"400":{"$ref":"#/components/responses/SellerApiUnsupportedApiVersion"},"401":{"$ref":"#/components/responses/SellerApiUnauthorized"},"403":{"$ref":"#/components/responses/SellerApiForbidden"},"404":{"description":"NOT_FOUND: the allocation does not exist or is not yours","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"409":{"description":"CONFLICT: the request cannot be filed. `details.reason`: `ALLOCATION_REQUEST_PENDING` (a request on this allocation is already waiting; `details.pendingRequestId` names it), `grant_not_requestable` (the allocation is revoked), `ALLOCATION_CEILING_EXCEEDS_STOCK` (the Content Owner has fewer free keys than the ceiling would need), `ALLOCATION_GRANT_GROWTH_NOT_AUTHORISED` (the agreement does not let this allocation grow), `model_not_activated`, `sku_not_found`, `sku_not_enabled_for_model`, `no_connection`, `deal_agreement`, `deal_agreement_pending_publisher`, `deal_agreement_pending_seller` (Content Owner or agreement gates). Also `IDEMPOTENCY_KEY_MISMATCH`: the `Idempotency-Key` was already used with a different body; use a new key for a new request. `IDEMPOTENCY_REQUEST_IN_FLIGHT`: an earlier request with this key is still running; wait `Retry-After` seconds and send the same request again.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"413":{"$ref":"#/components/responses/SellerApiPayloadTooLarge"},"422":{"description":"VALIDATION_FAILED: the body does not match the schema (unknown properties are refused; neither `allocationId` nor `grantId`; or both with different values)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"429":{"$ref":"#/components/responses/SellerApiRateLimited"},"500":{"$ref":"#/components/responses/SellerApiInternalError"},"503":{"$ref":"#/components/responses/SellerApiServiceUnavailable"},"504":{"$ref":"#/components/responses/SellerApiTimeout"}},"security":[{"bearerAuth":[]}],"x-avrix-scopes":["seller:allocations:write","seller:orders:write","seller:keys:pull"],"x-avrix-tier":"orders","x-avrix-rate-limit-class":"orders","x-avrix-scope-mode":"anyOf","tags":["Allocations"],"operationId":"createRequest"}},"/api/seller/v1/allocations/requests/{id}":{"get":{"summary":"Get one allocation request","description":"One allocation request you filed, in any state. 404 when the id is not one of your requests.","tags":["Allocations"],"security":[{"bearerAuth":[]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","format":"uuid"},"description":"Allocation request id (`requestId` on create and on the webhooks)"},{"$ref":"#/components/parameters/AvrixApiVersion"},{"$ref":"#/components/parameters/RequestId"},{"$ref":"#/components/parameters/SandboxSimulateRateLimit"}],"responses":{"200":{"description":"The request","headers":{"X-Request-Id":{"$ref":"#/components/headers/XRequestId"},"X-Avrix-Api-Version":{"$ref":"#/components/headers/XAvrixApiVersion"},"X-Api-Version":{"$ref":"#/components/headers/XApiVersion"},"X-RateLimit-Limit":{"$ref":"#/components/headers/XRateLimitLimit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/XRateLimitRemaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/XRateLimitReset"},"X-RateLimit-Bucket":{"$ref":"#/components/headers/XRateLimitBucket"}},"content":{"application/json":{"schema":{"type":"object","required":["data"],"properties":{"data":{"$ref":"#/components/schemas/SellerAllocationRequest"}}},"example":{"data":{"id":"4bff5aa2-75d9-47ba-8847-9d507987a944","state":"pending","allocationId":"b658872f-49eb-4f71-8416-262e4c883e51","allocationGrantId":"bba01716-cce8-49a4-8aff-8197e267e7f5","skuId":"02d4f1b0-4cf3-4c63-8ed5-dc730831296f","skuCode":"EXAMPLE-STEAM-WW","publisherCompanyId":"acme-games","sellerCompanyId":"d0685bec-cd5f-44dc-8a15-2b1dda048afb","businessModel":"wholesale","requestedQuantity":12,"declaredForecast":1,"status":"pending","resolution":"auto_granted","resolvedGrantDelta":1,"resolvedBy":"example_resolvedby","resolvedAt":"2026-11-02T09:30:00Z","decisionNote":"Example text.","createdAt":"2026-11-02T09:30:00Z","updatedAt":"2026-11-02T09:30:00Z"}}}}},"400":{"$ref":"#/components/responses/SellerApiUnsupportedApiVersion"},"401":{"$ref":"#/components/responses/SellerApiUnauthorized"},"403":{"$ref":"#/components/responses/SellerApiForbidden"},"404":{"description":"NOT_FOUND: the id is not one of your requests","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"422":{"description":"VALIDATION_FAILED: the id is not a UUID","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"429":{"$ref":"#/components/responses/SellerApiRateLimited"},"500":{"$ref":"#/components/responses/SellerApiInternalError"},"503":{"$ref":"#/components/responses/SellerApiServiceUnavailable"},"504":{"$ref":"#/components/responses/SellerApiTimeout"}},"x-avrix-scopes":["seller:products:read"],"x-avrix-tier":"orders","x-avrix-rate-limit-class":"orders","x-avrix-scope-mode":"anyOf","operationId":"getAllocationRequest"}},"/api/seller/v1/allocations/requests/{id}/cancel":{"post":{"summary":"Cancel an allocation request","description":"Withdraw a pending allocation request before the Content Owner decides it. The answer is the request with `state: cancelled`; cancelling a request that is already cancelled answers the same 200, so a retry is safe. A request the Content Owner already decided answers 409 (`details.reason: ALLOCATION_REQUEST_ALREADY_RESOLVED`, `details.state`). Sends `allocation.request_cancelled`. There is no amend: cancel, then file a new request. No body. `Idempotency-Key` is optional.","tags":["Allocations"],"security":[{"bearerAuth":[]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","format":"uuid"},"description":"Allocation request id (`requestId` on create and on the webhooks)"},{"$ref":"#/components/parameters/IdempotencyKeyOptional"},{"$ref":"#/components/parameters/AvrixApiVersion"},{"$ref":"#/components/parameters/RequestId"},{"$ref":"#/components/parameters/SandboxSimulateWrite"}],"responses":{"200":{"description":"Cancelled (or already cancelled)","headers":{"X-Request-Id":{"$ref":"#/components/headers/XRequestId"},"X-Avrix-Api-Version":{"$ref":"#/components/headers/XAvrixApiVersion"},"X-Api-Version":{"$ref":"#/components/headers/XApiVersion"},"Idempotency-Replayed":{"$ref":"#/components/headers/IdempotencyReplayed"},"X-RateLimit-Limit":{"$ref":"#/components/headers/XRateLimitLimit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/XRateLimitRemaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/XRateLimitReset"},"X-RateLimit-Bucket":{"$ref":"#/components/headers/XRateLimitBucket"}},"content":{"application/json":{"schema":{"type":"object","required":["data"],"properties":{"data":{"$ref":"#/components/schemas/SellerAllocationRequest"}}},"example":{"data":{"id":"3585a03a-c870-4965-810a-a854782c0f89","state":"pending","allocationId":"5b6333bc-96f2-4462-8c9f-70eefd8c244f","allocationGrantId":"7f2b61ef-4f72-474f-8b29-10ee1bb3e1ad","skuId":"7bb644c9-aded-427f-8da2-48d0150cd7d3","skuCode":"EXAMPLE-STEAM-WW","publisherCompanyId":"acme-games","sellerCompanyId":"faf08228-1733-4641-8dfc-6649bba40798","businessModel":"wholesale","requestedQuantity":12,"declaredForecast":1,"status":"pending","resolution":"auto_granted","resolvedGrantDelta":1,"resolvedBy":"example_resolvedby","resolvedAt":"2026-11-02T09:30:00Z","decisionNote":"Example text.","createdAt":"2026-11-02T09:30:00Z","updatedAt":"2026-11-02T09:30:00Z"}}}}},"400":{"$ref":"#/components/responses/SellerApiUnsupportedApiVersion"},"401":{"$ref":"#/components/responses/SellerApiUnauthorized"},"403":{"$ref":"#/components/responses/SellerApiForbidden"},"404":{"description":"NOT_FOUND: the id is not one of your requests","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"409":{"description":"CONFLICT: the Content Owner already decided this request (`details.reason: ALLOCATION_REQUEST_ALREADY_RESOLVED`, `details.state`). Also `IDEMPOTENCY_KEY_MISMATCH` and `IDEMPOTENCY_REQUEST_IN_FLIGHT` for a reused `Idempotency-Key`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"413":{"$ref":"#/components/responses/SellerApiPayloadTooLarge"},"422":{"description":"VALIDATION_FAILED: the id is not a UUID","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"429":{"$ref":"#/components/responses/SellerApiRateLimited"},"500":{"$ref":"#/components/responses/SellerApiInternalError"},"503":{"$ref":"#/components/responses/SellerApiServiceUnavailable"},"504":{"$ref":"#/components/responses/SellerApiTimeout"}},"x-avrix-scopes":["seller:allocations:write","seller:orders:write","seller:keys:pull"],"x-avrix-tier":"orders","x-avrix-rate-limit-class":"orders","x-avrix-scope-mode":"anyOf","operationId":"cancelAllocationRequest"}},"/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,"deprecated":true,"description":"Alias of `countryCode` (the original availability spelling, still accepted). Sending both with different values fails validation; a request that uses only this spelling gets an `X-Avrix-Deprecated-Parameter` response header naming the replacement.","schema":{"type":"string","pattern":"^[A-Za-z]{2}$"}},{"$ref":"#/components/parameters/AvrixApiVersion"},{"$ref":"#/components/parameters/RequestId"},{"$ref":"#/components/parameters/SandboxSimulateRateLimit"}],"responses":{"200":{"description":"Availability data (single object or array for bulk)","headers":{"Server-Timing":{"description":"Phase breakdown of this response in milliseconds: `db` (grant, readiness and inventory reads), `redis` (checkout-hold ledger), `sellability` (per-country answer, when `country=` was sent) and `total`. Use it to attribute a slow response; the same phases are logged server-side above the platform threshold.","schema":{"type":"string"}},"X-Request-Id":{"$ref":"#/components/headers/XRequestId"},"X-Avrix-Api-Version":{"$ref":"#/components/headers/XAvrixApiVersion"},"X-Api-Version":{"$ref":"#/components/headers/XApiVersion"},"X-RateLimit-Limit":{"$ref":"#/components/headers/XRateLimitLimit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/XRateLimitRemaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/XRateLimitReset"},"X-RateLimit-Bucket":{"$ref":"#/components/headers/XRateLimitBucket"}},"content":{"application/json":{"schema":{"type":"object","properties":{"data":{"oneOf":[{"$ref":"#/components/schemas/SellerAvailability"},{"type":"array","items":{"$ref":"#/components/schemas/SellerAvailability"}}]},"meta":{"type":"object","description":"Present on the bulk form (skuCodes=).","properties":{"requestId":{"type":"string"},"notFound":{"type":"array","items":{"type":"string"},"description":"Requested skuCodes that returned nothing: unknown, not shared with you, or without an allocation. Empty when every code answered."}}}}},"example":{"data":{"available":12,"allocationRemaining":12,"inventoryAvailable":12,"allocationId":"95a3f5dc-9d83-4ee5-85fd-b61c1dfc8f4e","allocationReadableId":"alc_adg79ecg","skuId":"dc5ece9b-d119-4c22-87e3-b91c6f2c8768","skuCode":"EXAMPLE-STEAM-WW","heldQuantity":12,"sellableNow":12,"maxFulfillableQuantity":12,"cannotFullyFulfill":true,"allOrNothingWillFail":true,"requestable":true,"backordered":true,"country":"DE","dedicatedAvailable":12,"sharedPoolAvailable":12,"backorderEligible":true},"meta":{"requestId":"b988a31b-ad87-41a3-896e-dc0bddc07fd5","notFound":["example_notfound"]}}}}},"400":{"description":"`BAD_REQUEST`: the availability lookup for the `skuCodes` you sent could not be run; `message` says why. Also returned for an `X-Avrix-Api-Version` this API does not serve (`UNSUPPORTED_API_VERSION`).","headers":{"X-Request-Id":{"$ref":"#/components/headers/XRequestId"},"X-Avrix-Api-Version":{"$ref":"#/components/headers/XAvrixApiVersion"},"X-Api-Version":{"$ref":"#/components/headers/XApiVersion"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"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"},"503":{"$ref":"#/components/responses/SellerApiServiceUnavailable"},"504":{"$ref":"#/components/responses/SellerApiTimeout"}},"security":[{"bearerAuth":[]}],"x-avrix-scopes":["seller:products:read"],"x-avrix-tier":"catalog","x-avrix-rate-limit-class":"catalog","x-avrix-scope-mode":"anyOf","x-avrix-store-profile":"checkout-read","tags":["Allocations"],"operationId":"listAvailability"}},"/api/seller/v1/transactions":{"get":{"summary":"List transactions","description":"**Deprecated name.** Use `GET /keys/pulls`, which runs the same handler. This path keeps working; nothing is scheduled for removal.\n\nKey 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).\n\n**Paging:** the shared list contract, see `https://docs.avrix.io/seller-api/pagination`. On contract date `2026-12-01` and later a `cursor` this API did not return is refused with `422 VALIDATION_FAILED` (`details.issues[].field` is `cursor`); earlier dates serve the first page.","parameters":[{"name":"limit","in":"query","description":"Page size: how many items to return (1 to 100).","schema":{"type":"integer","default":50,"minimum":1,"maximum":100}},{"name":"cursor","in":"query","description":"Opaque cursor from the previous page's `meta.nextCursor`. Omit for the first page.","schema":{"type":"string"}},{"name":"orderReference","in":"query","description":"Return only transactions with this order reference (exact match). Same as `filter[orderReference]=eq:<value>`; both together must name the same value.","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."},{"name":"parentOrderReference","in":"query","required":false,"schema":{"type":"string","minLength":1,"maxLength":255},"description":"Only the pulls of one bulk cart (its `parentOrderReference`)."},{"$ref":"#/components/parameters/AvrixApiVersion"},{"$ref":"#/components/parameters/RequestId"},{"$ref":"#/components/parameters/SandboxSimulateRateLimit"}],"responses":{"200":{"description":"Transactions list","headers":{"X-Request-Id":{"$ref":"#/components/headers/XRequestId"},"X-Avrix-Api-Version":{"$ref":"#/components/headers/XAvrixApiVersion"},"X-Api-Version":{"$ref":"#/components/headers/XApiVersion"},"X-RateLimit-Limit":{"$ref":"#/components/headers/XRateLimitLimit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/XRateLimitRemaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/XRateLimitReset"},"X-RateLimit-Bucket":{"$ref":"#/components/headers/XRateLimitBucket"}},"content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/SellerTransaction"}},"meta":{"$ref":"#/components/schemas/PaginationMeta"}}},"example":{"data":[{"id":"b5c89009-cbb4-4656-8d72-ba97b8ba9da7","readableId":"ord_cpwewsg2","allocationId":"4a59e316-54a6-4eff-87e5-8147cc58420f","skuCode":"EXAMPLE-STEAM-WW","quantity":12,"orderReference":"store-order-10432","pulledAt":"2026-11-02T09:30:00Z","salesCountryCode":"DE","detectedCountryCode":"off","countryMismatch":true,"warnings":["COUNTRY_MISMATCH"],"parentOrderReference":"store-order-10432","lineIndex":1}],"meta":{"total":2450,"limit":50,"hasMore":true,"nextCursor":"eyJ2IjoyLCJ0IjoiMjAyNi0xMS0wMlQwOTozMDowMFoifQ","nextUrl":"https://api.avrix.io/api/seller/v1/transactions?cursor=eyJ2IjoyLCJ0IjoiMjAyNi0xMS0wMlQwOTozMDowMFoifQ","localePreference":"en"}}}}},"400":{"$ref":"#/components/responses/SellerApiUnsupportedApiVersion"},"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"},"503":{"$ref":"#/components/responses/SellerApiServiceUnavailable"},"504":{"$ref":"#/components/responses/SellerApiTimeout"}},"security":[{"bearerAuth":[]}],"x-avrix-scopes":["seller:orders:read","seller:orders:write","seller:products:read","seller:keys:pull"],"x-avrix-tier":"orders","x-avrix-rate-limit-class":"orders","x-avrix-scope-mode":"anyOf","tags":["Orders"],"operationId":"listTransactions","deprecated":true}},"/api/seller/v1/keys":{"get":{"summary":"List seller API keys","description":"**Deprecated name.** Use `GET /api-keys`, which runs the same handler. This path keeps working; nothing is scheduled for removal.\n\nList API keys for the authenticated company (masked identifiers only; full secrets are never returned). Revoked keys stay listed until archived in the console; each row carries `status` (`active` or `revoked`) and `revokedAt`. Each row also carries the key's `scopes`, `environment` and `allowedIps`, so a key inventory can be audited over the API. Requires `seller:keys:read` or `seller:keys:write`.\n\n**Paging:** the shared list contract, see `https://docs.avrix.io/seller-api/pagination`. On contract date `2026-12-01` and later a `cursor` this API did not return is refused with `422 VALIDATION_FAILED` (`details.issues[].field` is `cursor`); earlier dates serve the first page.","responses":{"200":{"description":"Masked keys","headers":{"X-Request-Id":{"$ref":"#/components/headers/XRequestId"},"X-Avrix-Api-Version":{"$ref":"#/components/headers/XAvrixApiVersion"},"X-Api-Version":{"$ref":"#/components/headers/XApiVersion"},"X-RateLimit-Limit":{"$ref":"#/components/headers/XRateLimitLimit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/XRateLimitRemaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/XRateLimitReset"},"X-RateLimit-Bucket":{"$ref":"#/components/headers/XRateLimitBucket"}},"content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/SellerApiKeyMasked"}},"meta":{"type":"object","properties":{"limit":{"type":"integer"},"count":{"type":"integer","description":"Rows in this page."},"nextCursor":{"type":["string","null"],"description":"Send as `cursor` for the next page; null on the last page."},"nextUrl":{"type":["string","null"],"description":"The full URL of the next page; null on the last page."},"hasMore":{"type":"boolean","description":"True when another page follows. Loop on `hasMore`; send `nextCursor` back as `cursor`."}}}}},"example":{"data":[{"id":"46962dbf-0be0-49ce-8955-e47d1acf7d9f","name":"Example Game","prefix":"avrix_sk_sbx_","lastChars":"9f2c","createdAt":"2026-11-02T09:30:00Z","expiresAt":"2026-11-02T09:30:00Z","lastUsedAt":"2026-11-02T09:30:00Z","status":"active","revokedAt":"2026-11-02T09:30:00Z"}],"meta":{"limit":50,"count":12,"nextCursor":"eyJ2IjoyLCJ0IjoiMjAyNi0xMS0wMlQwOTozMDowMFoifQ","nextUrl":"https://api.avrix.io/api/seller/v1/keys?cursor=eyJ2IjoyLCJ0IjoiMjAyNi0xMS0wMlQwOTozMDowMFoifQ","hasMore":true}}}}},"400":{"$ref":"#/components/responses/SellerApiUnsupportedApiVersion"},"401":{"$ref":"#/components/responses/SellerApiUnauthorized"},"403":{"$ref":"#/components/responses/SellerApiForbidden"},"422":{"$ref":"#/components/responses/SellerApiValidationFailed"},"429":{"$ref":"#/components/responses/SellerApiRateLimited"},"500":{"$ref":"#/components/responses/SellerApiInternalError"},"503":{"$ref":"#/components/responses/SellerApiServiceUnavailable"},"504":{"$ref":"#/components/responses/SellerApiTimeout"}},"security":[{"bearerAuth":[]}],"x-avrix-scopes":["seller:keys:read","seller:keys:write"],"x-avrix-tier":"keys","x-avrix-rate-limit-class":"orders","x-avrix-rate-limit-class-2026-12-01":"general","x-avrix-scope-mode":"anyOf","tags":["Seller auth"],"operationId":"listKeys","parameters":[{"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 cursor from `meta.nextCursor` of the previous page."},{"name":"filters","in":"query","required":false,"schema":{"type":"string"},"description":"Optional JSON filter DSL `[{ \"field\", \"op\", \"value\" }]`; fields: `name`. See the filter guide."},{"$ref":"#/components/parameters/AvrixApiVersion"},{"$ref":"#/components/parameters/RequestId"},{"$ref":"#/components/parameters/SandboxSimulateRateLimit"}],"deprecated":true},"post":{"summary":"Create seller API key","description":"**Deprecated name.** Use `POST /api-keys`, which runs the same handler. This path keeps working; nothing is scheduled for removal.\n\nCreate 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 exactly the `scopes` you send, each of which the calling key must hold (`403 INSUFFICIENT_SCOPE` naming them in `details.missingScopes` otherwise), or, when you send none, the server's default set intersected with the calling key's scopes; it inherits the calling key's environment (sandbox keys mint sandbox keys); it expires at `expiresAt` when you send one, which must be at least a minute ahead (`422` otherwise) and no later than the calling key's expiry (`403` otherwise), and otherwise when the calling key does; 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. **Retries:** send an `Idempotency-Key` to make a retry safe: the same key and body replay the first answer with `Idempotency-Replayed: true` instead of acting twice. The secret is never stored for a replay: a replayed answer omits `key` and sets `secretRedacted: true`.","parameters":[{"$ref":"#/components/parameters/IdempotencyKeyOptional"},{"$ref":"#/components/parameters/AvrixApiVersion"},{"$ref":"#/components/parameters/RequestId"},{"$ref":"#/components/parameters/SandboxSimulateWrite"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/SellerApiKeyCreateRequest"},"examples":{"minimal":{"summary":"A key that inherits the calling key's IP allowlist","value":{"name":"checkout-service"}},"withAllowlist":{"summary":"A key restricted to your own egress address","description":"`203.0.113.10` is a documentation address (RFC 5737) and stands for your own public egress address: sent as is, it is refused with 422 `VALIDATION_FAILED`. `GET /whoami-ip` returns the address your requests arrive from.","value":{"name":"checkout-service","allowed_ips":["203.0.113.10"]}}}}}},"responses":{"201":{"description":"Key created","headers":{"X-Request-Id":{"$ref":"#/components/headers/XRequestId"},"X-Avrix-Api-Version":{"$ref":"#/components/headers/XAvrixApiVersion"},"X-Api-Version":{"$ref":"#/components/headers/XApiVersion"},"Idempotency-Replayed":{"$ref":"#/components/headers/IdempotencyReplayed"},"X-RateLimit-Limit":{"$ref":"#/components/headers/XRateLimitLimit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/XRateLimitRemaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/XRateLimitReset"},"X-RateLimit-Bucket":{"$ref":"#/components/headers/XRateLimitBucket"}},"content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/SellerApiKeyCreated"}}},"example":{"data":{"id":"d17a4cab-8e23-495b-8719-e08df3d792e0","name":"Example Game","key":"XXXXX-XXXXX-XXXXX-XXXXX","livemode":true,"secretRedacted":true}}}}},"400":{"$ref":"#/components/responses/SellerApiUnsupportedApiVersion"},"401":{"$ref":"#/components/responses/SellerApiUnauthorized"},"403":{"$ref":"#/components/responses/SellerApiForbidden"},"409":{"$ref":"#/components/responses/SellerApiIdempotencyConflict"},"413":{"$ref":"#/components/responses/SellerApiPayloadTooLarge"},"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"},"503":{"$ref":"#/components/responses/SellerApiServiceUnavailable"},"504":{"$ref":"#/components/responses/SellerApiTimeout"}},"security":[{"bearerAuth":[]}],"x-avrix-scopes":["seller:keys:write"],"x-avrix-tier":"keys","x-avrix-rate-limit-class":"orders","x-avrix-rate-limit-class-2026-12-01":"general","x-avrix-scope-mode":"anyOf","tags":["Seller auth"],"operationId":"createKey","deprecated":true}},"/api/seller/v1/api-keys":{"get":{"summary":"List API keys","description":"API credentials live under `/api-keys`; `/keys` names game keys (`/keys/pull`, `/keys/return`, `/keys/export`, `/keys/pulls`). The same handler as `GET /keys`, which is the deprecated name of this operation.\n\nList API keys for the authenticated company (masked identifiers only; full secrets are never returned). Revoked keys stay listed until archived in the console; each row carries `status` (`active` or `revoked`) and `revokedAt`. Requires `seller:keys:write` scope.\n\n**Paging:** the shared list contract, see `https://docs.avrix.io/seller-api/pagination`. On contract date `2026-12-01` and later a `cursor` this API did not return is refused with `422 VALIDATION_FAILED` (`details.issues[].field` is `cursor`); earlier dates serve the first page.","responses":{"200":{"description":"Masked keys","headers":{"X-Request-Id":{"$ref":"#/components/headers/XRequestId"},"X-Avrix-Api-Version":{"$ref":"#/components/headers/XAvrixApiVersion"},"X-Api-Version":{"$ref":"#/components/headers/XApiVersion"},"X-RateLimit-Limit":{"$ref":"#/components/headers/XRateLimitLimit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/XRateLimitRemaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/XRateLimitReset"},"X-RateLimit-Bucket":{"$ref":"#/components/headers/XRateLimitBucket"}},"content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/SellerApiKeyMasked"}},"meta":{"type":"object","properties":{"limit":{"type":"integer"},"count":{"type":"integer","description":"Rows in this page."},"nextCursor":{"type":["string","null"],"description":"Send as `cursor` for the next page; null on the last page."},"nextUrl":{"type":["string","null"],"description":"The full URL of the next page; null on the last page."},"hasMore":{"type":"boolean","description":"True when another page follows. Loop on `hasMore`; send `nextCursor` back as `cursor`."}}}}},"example":{"data":[{"id":"99c6660a-c74f-4897-8b7f-273274235912","name":"Example Game","prefix":"avrix_sk_sbx_","lastChars":"9f2c","createdAt":"2026-11-02T09:30:00Z","expiresAt":"2026-11-02T09:30:00Z","lastUsedAt":"2026-11-02T09:30:00Z","status":"active","revokedAt":"2026-11-02T09:30:00Z","scopes":[],"environment":"production","allowedIps":["example_allowedip"]}],"meta":{"limit":50,"count":12,"nextCursor":"eyJ2IjoyLCJ0IjoiMjAyNi0xMS0wMlQwOTozMDowMFoifQ","nextUrl":"https://api.avrix.io/api/seller/v1/api-keys?cursor=eyJ2IjoyLCJ0IjoiMjAyNi0xMS0wMlQwOTozMDowMFoifQ","hasMore":true}}}}},"400":{"$ref":"#/components/responses/SellerApiUnsupportedApiVersion"},"401":{"$ref":"#/components/responses/SellerApiUnauthorized"},"403":{"$ref":"#/components/responses/SellerApiForbidden"},"422":{"$ref":"#/components/responses/SellerApiValidationFailed"},"429":{"$ref":"#/components/responses/SellerApiRateLimited"},"500":{"$ref":"#/components/responses/SellerApiInternalError"},"503":{"$ref":"#/components/responses/SellerApiServiceUnavailable"},"504":{"$ref":"#/components/responses/SellerApiTimeout"}},"security":[{"bearerAuth":[]}],"x-avrix-scopes":["seller:keys:read","seller:keys:write"],"x-avrix-tier":"keys","x-avrix-rate-limit-class":"orders","x-avrix-rate-limit-class-2026-12-01":"general","x-avrix-scope-mode":"anyOf","tags":["Seller auth"],"operationId":"listApiKeys","parameters":[{"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 cursor from `meta.nextCursor` of the previous page."},{"name":"filters","in":"query","required":false,"schema":{"type":"string"},"description":"Optional JSON filter DSL `[{ \"field\", \"op\", \"value\" }]`; fields: `name`. See the filter guide."},{"$ref":"#/components/parameters/AvrixApiVersion"},{"$ref":"#/components/parameters/RequestId"},{"$ref":"#/components/parameters/SandboxSimulateRateLimit"}]},"post":{"summary":"Create an API key","description":"API credentials live under `/api-keys`; `/keys` names game keys (`/keys/pull`, `/keys/return`, `/keys/export`, `/keys/pulls`). The same handler as `POST /keys`, which is the deprecated name of this operation.\n\nCreate 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. **Retries:** send an `Idempotency-Key` to make a retry safe: the same key and body replay the first answer with `Idempotency-Replayed: true` instead of acting twice. The secret is never stored for a replay: a replayed answer omits `key` and sets `secretRedacted: true`.","parameters":[{"$ref":"#/components/parameters/IdempotencyKeyOptional"},{"$ref":"#/components/parameters/AvrixApiVersion"},{"$ref":"#/components/parameters/RequestId"},{"$ref":"#/components/parameters/SandboxSimulateWrite"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/SellerApiKeyCreateRequest"},"examples":{"minimal":{"summary":"A key that inherits the calling key's IP allowlist","value":{"name":"checkout-service"}},"withAllowlist":{"summary":"A key restricted to your own egress address","description":"`203.0.113.10` is a documentation address (RFC 5737) and stands for your own public egress address: sent as is, it is refused with 422 `VALIDATION_FAILED`. `GET /whoami-ip` returns the address your requests arrive from.","value":{"name":"checkout-service","allowed_ips":["203.0.113.10"]}}}}}},"responses":{"201":{"description":"Key created","headers":{"X-Request-Id":{"$ref":"#/components/headers/XRequestId"},"X-Avrix-Api-Version":{"$ref":"#/components/headers/XAvrixApiVersion"},"X-Api-Version":{"$ref":"#/components/headers/XApiVersion"},"Idempotency-Replayed":{"$ref":"#/components/headers/IdempotencyReplayed"},"X-RateLimit-Limit":{"$ref":"#/components/headers/XRateLimitLimit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/XRateLimitRemaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/XRateLimitReset"},"X-RateLimit-Bucket":{"$ref":"#/components/headers/XRateLimitBucket"}},"content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/SellerApiKeyCreated"}}},"example":{"data":{"id":"322466e1-0e24-424a-81fb-e71883103e5e","name":"Example Game","key":"XXXXX-XXXXX-XXXXX-XXXXX","livemode":true,"secretRedacted":true,"scopes":[],"expiresAt":"2026-11-02T09:30:00Z"}}}}},"400":{"$ref":"#/components/responses/SellerApiUnsupportedApiVersion"},"401":{"$ref":"#/components/responses/SellerApiUnauthorized"},"403":{"$ref":"#/components/responses/SellerApiForbidden"},"409":{"$ref":"#/components/responses/SellerApiIdempotencyConflict"},"413":{"$ref":"#/components/responses/SellerApiPayloadTooLarge"},"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"},"503":{"$ref":"#/components/responses/SellerApiServiceUnavailable"},"504":{"$ref":"#/components/responses/SellerApiTimeout"}},"security":[{"bearerAuth":[]}],"x-avrix-scopes":["seller:keys:write"],"x-avrix-tier":"keys","x-avrix-rate-limit-class":"orders","x-avrix-rate-limit-class-2026-12-01":"general","x-avrix-scope-mode":"anyOf","tags":["Seller auth"],"operationId":"createApiKey"}},"/api/seller/v1/keys/{id}":{"delete":{"summary":"Revoke seller API key","description":"**Deprecated name.** Use `DELETE /api-keys/{id}`, which runs the same handler. This path keeps working; nothing is scheduled for removal.\n\nSoft-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,"description":"API key id (`id` from `GET /keys`).","schema":{"type":"string","format":"uuid"}},{"$ref":"#/components/parameters/AvrixApiVersion"},{"$ref":"#/components/parameters/RequestId"},{"$ref":"#/components/parameters/SandboxSimulateWrite"}],"responses":{"204":{"description":"Key revoked","headers":{"X-Request-Id":{"$ref":"#/components/headers/XRequestId"},"X-Avrix-Api-Version":{"$ref":"#/components/headers/XAvrixApiVersion"},"X-Api-Version":{"$ref":"#/components/headers/XApiVersion"},"X-RateLimit-Limit":{"$ref":"#/components/headers/XRateLimitLimit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/XRateLimitRemaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/XRateLimitReset"},"X-RateLimit-Bucket":{"$ref":"#/components/headers/XRateLimitBucket"}}},"400":{"$ref":"#/components/responses/SellerApiUnsupportedApiVersion"},"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"}}}},"422":{"$ref":"#/components/responses/SellerApiValidationFailed"},"429":{"$ref":"#/components/responses/SellerApiRateLimited"},"500":{"$ref":"#/components/responses/SellerApiInternalError"},"503":{"$ref":"#/components/responses/SellerApiServiceUnavailable"},"504":{"$ref":"#/components/responses/SellerApiTimeout"}},"security":[{"bearerAuth":[]}],"x-avrix-scopes":["seller:keys:write"],"x-avrix-tier":"keys","x-avrix-rate-limit-class":"orders","x-avrix-rate-limit-class-2026-12-01":"general","x-avrix-scope-mode":"anyOf","tags":["Seller auth"],"operationId":"deleteKey","deprecated":true}},"/api/seller/v1/api-keys/{id}":{"delete":{"summary":"Revoke an API key","description":"API credentials live under `/api-keys`; `/keys` names game keys (`/keys/pull`, `/keys/return`, `/keys/export`, `/keys/pulls`). The same handler as `DELETE /keys/{id}`, which is the deprecated name of this operation.\n\nSoft-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"},"description":"API key id (`id` from `GET /api-keys`)."},{"$ref":"#/components/parameters/AvrixApiVersion"},{"$ref":"#/components/parameters/RequestId"},{"$ref":"#/components/parameters/SandboxSimulateWrite"}],"responses":{"204":{"description":"Key revoked","headers":{"X-Request-Id":{"$ref":"#/components/headers/XRequestId"},"X-Avrix-Api-Version":{"$ref":"#/components/headers/XAvrixApiVersion"},"X-Api-Version":{"$ref":"#/components/headers/XApiVersion"},"X-RateLimit-Limit":{"$ref":"#/components/headers/XRateLimitLimit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/XRateLimitRemaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/XRateLimitReset"},"X-RateLimit-Bucket":{"$ref":"#/components/headers/XRateLimitBucket"}}},"400":{"$ref":"#/components/responses/SellerApiUnsupportedApiVersion"},"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"}}}},"422":{"$ref":"#/components/responses/SellerApiValidationFailed"},"429":{"$ref":"#/components/responses/SellerApiRateLimited"},"500":{"$ref":"#/components/responses/SellerApiInternalError"},"503":{"$ref":"#/components/responses/SellerApiServiceUnavailable"},"504":{"$ref":"#/components/responses/SellerApiTimeout"}},"security":[{"bearerAuth":[]}],"x-avrix-scopes":["seller:keys:write"],"x-avrix-tier":"keys","x-avrix-rate-limit-class":"orders","x-avrix-rate-limit-class-2026-12-01":"general","x-avrix-scope-mode":"anyOf","tags":["Seller auth"],"operationId":"deleteApiKey"}},"/api/seller/v1/keys/{id}/allowed-ips":{"patch":{"summary":"Update seller API key IP allowlist","description":"**Deprecated name.** Use `PATCH /api-keys/{id}/allowed-ips`, which runs the same handler. This path keeps working; nothing is scheduled for removal.\n\nReplace 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,"description":"API key id (`id` from `GET /keys`).","schema":{"type":"string","format":"uuid"}},{"$ref":"#/components/parameters/AvrixApiVersion"},{"$ref":"#/components/parameters/RequestId"},{"$ref":"#/components/parameters/SandboxSimulateWrite"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/SellerApiKeyAllowedIpsUpdateRequest"},"examples":{"replaceAllowlist":{"summary":"Replace the allowlist with your own egress address","description":"`203.0.113.10` is a documentation address (RFC 5737) and stands for your own public egress address: sent as is, it is refused with 422 `VALIDATION_FAILED`. `GET /whoami-ip` returns the address your requests arrive from.","value":{"allowed_ips":["203.0.113.10"]}}}}}},"responses":{"204":{"description":"Allowlist updated. Changes propagate within ~60s as cached entries refresh.","headers":{"X-Request-Id":{"$ref":"#/components/headers/XRequestId"},"X-Avrix-Api-Version":{"$ref":"#/components/headers/XAvrixApiVersion"},"X-Api-Version":{"$ref":"#/components/headers/XApiVersion"},"X-RateLimit-Limit":{"$ref":"#/components/headers/XRateLimitLimit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/XRateLimitRemaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/XRateLimitReset"},"X-RateLimit-Bucket":{"$ref":"#/components/headers/XRateLimitBucket"}}},"400":{"$ref":"#/components/responses/SellerApiUnsupportedApiVersion"},"401":{"$ref":"#/components/responses/SellerApiUnauthorized"},"403":{"$ref":"#/components/responses/SellerApiForbidden"},"404":{"description":"Key not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"413":{"$ref":"#/components/responses/SellerApiPayloadTooLarge"},"422":{"description":"Validation failed — `allowed_ips` exceeds 50 entries, contains an invalid literal/CIDR, or contains a reserved/private range. Also the console's rules, on every contract date (`details.issues[0].field` is `allowed_ips`): `details.issues[0].code` `PRODUCTION_ALLOWLIST_REQUIRED` for an empty list on a production key that is not bound to a trusted workload, `SANDBOX_ALLOWLIST_NOT_ALLOWED` for a non-empty list on a sandbox key. The key keeps the list it had.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"429":{"$ref":"#/components/responses/SellerApiRateLimited"},"500":{"$ref":"#/components/responses/SellerApiInternalError"},"503":{"$ref":"#/components/responses/SellerApiServiceUnavailable"},"504":{"$ref":"#/components/responses/SellerApiTimeout"}},"security":[{"bearerAuth":[]}],"x-avrix-scopes":["seller:keys:write"],"x-avrix-tier":"keys","x-avrix-rate-limit-class":"orders","x-avrix-rate-limit-class-2026-12-01":"general","x-avrix-scope-mode":"anyOf","tags":["Seller auth"],"operationId":"updateAllowedIp","deprecated":true}},"/api/seller/v1/api-keys/{id}/allowed-ips":{"patch":{"summary":"Replace an API key's IP allowlist","description":"API credentials live under `/api-keys`; `/keys` names game keys (`/keys/pull`, `/keys/return`, `/keys/export`, `/keys/pulls`). The same handler as `PATCH /keys/{id}/allowed-ips`, which is the deprecated name of this operation.\n\nReplace 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"},"description":"API key id (`id` from `GET /api-keys`)."},{"$ref":"#/components/parameters/AvrixApiVersion"},{"$ref":"#/components/parameters/RequestId"},{"$ref":"#/components/parameters/SandboxSimulateWrite"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/SellerApiKeyAllowedIpsUpdateRequest"},"examples":{"replaceAllowlist":{"summary":"Replace the allowlist with your own egress address","description":"`203.0.113.10` is a documentation address (RFC 5737) and stands for your own public egress address: sent as is, it is refused with 422 `VALIDATION_FAILED`. `GET /whoami-ip` returns the address your requests arrive from.","value":{"allowed_ips":["203.0.113.10"]}}}}}},"responses":{"204":{"description":"Allowlist updated. Changes propagate within ~60s as cached entries refresh.","headers":{"X-Request-Id":{"$ref":"#/components/headers/XRequestId"},"X-Avrix-Api-Version":{"$ref":"#/components/headers/XAvrixApiVersion"},"X-Api-Version":{"$ref":"#/components/headers/XApiVersion"},"X-RateLimit-Limit":{"$ref":"#/components/headers/XRateLimitLimit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/XRateLimitRemaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/XRateLimitReset"},"X-RateLimit-Bucket":{"$ref":"#/components/headers/XRateLimitBucket"}}},"400":{"$ref":"#/components/responses/SellerApiUnsupportedApiVersion"},"401":{"$ref":"#/components/responses/SellerApiUnauthorized"},"403":{"$ref":"#/components/responses/SellerApiForbidden"},"404":{"description":"Key not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"413":{"$ref":"#/components/responses/SellerApiPayloadTooLarge"},"422":{"description":"Validation failed — `allowed_ips` exceeds 50 entries, contains an invalid literal/CIDR, or contains a reserved/private range. Also the console's rules, on every contract date (`details.issues[0].field` is `allowed_ips`): `details.issues[0].code` `PRODUCTION_ALLOWLIST_REQUIRED` for an empty list on a production key that is not bound to a trusted workload, `SANDBOX_ALLOWLIST_NOT_ALLOWED` for a non-empty list on a sandbox key. The key keeps the list it had.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"429":{"$ref":"#/components/responses/SellerApiRateLimited"},"500":{"$ref":"#/components/responses/SellerApiInternalError"},"503":{"$ref":"#/components/responses/SellerApiServiceUnavailable"},"504":{"$ref":"#/components/responses/SellerApiTimeout"}},"security":[{"bearerAuth":[]}],"x-avrix-scopes":["seller:keys:write"],"x-avrix-tier":"keys","x-avrix-rate-limit-class":"orders","x-avrix-rate-limit-class-2026-12-01":"general","x-avrix-scope-mode":"anyOf","tags":["Seller auth"],"operationId":"updateApiKeyAllowedIps"}},"/api/seller/v1/keys/{id}/rotate":{"post":{"summary":"Rotate seller API key secret","description":"**Deprecated name.** Use `POST /api-keys/{id}/rotate`, which runs the same handler. This path keeps working; nothing is scheduled for removal.\n\nIn-place rotation of an API key secret. Returns the new raw secret once, as `data.secret`. Requires `seller:keys:write`. Without a body the replaced secret stops working at once. With `overlapSeconds` it keeps working until `previousSecretExpiresAt`; rotating again before then issues another new secret and keeps that same replaced secret and expiry, and a rotation without `overlapSeconds` ends the window. Revoking the key stops every secret it has. **Retries:** send an `Idempotency-Key` to make a retry safe: the same key and body replay the first answer with `Idempotency-Replayed: true` instead of acting twice. The secret is never stored for a replay: a replayed answer omits `secret` and sets `secretRedacted: true`.","parameters":[{"name":"id","in":"path","required":true,"description":"API key id (`id` from `GET /keys`).","schema":{"type":"string","format":"uuid"}},{"$ref":"#/components/parameters/IdempotencyKeyOptional"},{"$ref":"#/components/parameters/AvrixApiVersion"},{"$ref":"#/components/parameters/RequestId"},{"$ref":"#/components/parameters/SandboxSimulateWrite"}],"responses":{"200":{"description":"Key rotated","headers":{"X-Request-Id":{"$ref":"#/components/headers/XRequestId"},"X-Avrix-Api-Version":{"$ref":"#/components/headers/XAvrixApiVersion"},"X-Api-Version":{"$ref":"#/components/headers/XApiVersion"},"Idempotency-Replayed":{"$ref":"#/components/headers/IdempotencyReplayed"},"X-RateLimit-Limit":{"$ref":"#/components/headers/XRateLimitLimit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/XRateLimitRemaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/XRateLimitReset"},"X-RateLimit-Bucket":{"$ref":"#/components/headers/XRateLimitBucket"}},"content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/SellerApiKeyRotated"},"meta":{"type":"object","properties":{"requestId":{"type":"string"}}}}},"example":{"data":{"id":"d2fd2421-bcf4-4527-8fa3-b1b6f8da59eb","secret":"whsec_8f2c1d0e9b7a6c5d4e3f2a1b0c9d8e7f","previousSecretExpiresAt":"2026-11-02T09:30:00Z","secretRedacted":true},"meta":{"requestId":"b94c84e1-2f92-4a7d-8c21-80f5aebc122a"}}}}},"400":{"$ref":"#/components/responses/SellerApiUnsupportedApiVersion"},"401":{"$ref":"#/components/responses/SellerApiUnauthorized"},"403":{"$ref":"#/components/responses/SellerApiForbidden"},"404":{"description":"Key not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"409":{"$ref":"#/components/responses/SellerApiIdempotencyConflict"},"413":{"$ref":"#/components/responses/SellerApiPayloadTooLarge"},"422":{"description":"Invalid path id, or `overlapSeconds` is not a whole number from 60 to 86400.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"429":{"$ref":"#/components/responses/SellerApiRateLimited"},"500":{"$ref":"#/components/responses/SellerApiInternalError"},"503":{"$ref":"#/components/responses/SellerApiServiceUnavailable"},"504":{"$ref":"#/components/responses/SellerApiTimeout"}},"security":[{"bearerAuth":[]}],"x-avrix-scopes":["seller:keys:write"],"x-avrix-tier":"keys","x-avrix-rate-limit-class":"orders","x-avrix-rate-limit-class-2026-12-01":"general","x-avrix-scope-mode":"anyOf","tags":["Seller auth"],"operationId":"createRotate","requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{"overlapSeconds":{"type":"integer","minimum":60,"maximum":86400,"description":"Keep the replaced secret working for this many seconds, so a rotation whose answer is lost does not lock you out. Omit it and the replaced secret stops at once."}}},"example":{"overlapSeconds":3600}}}},"deprecated":true}},"/api/seller/v1/api-keys/{id}/rotate":{"post":{"summary":"Rotate an API key","description":"API credentials live under `/api-keys`; `/keys` names game keys (`/keys/pull`, `/keys/return`, `/keys/export`, `/keys/pulls`). The same handler as `POST /keys/{id}/rotate`, which is the deprecated name of this operation.\n\nIn-place rotation of an API key secret. Returns the new raw secret once, as `data.secret`. Requires `seller:keys:write`. Without a body the replaced secret stops working at once. With `overlapSeconds` it keeps working until `previousSecretExpiresAt`; rotating again before then issues another new secret and keeps that same replaced secret and expiry, and a rotation without `overlapSeconds` ends the window. Revoking the key stops every secret it has. **Retries:** send an `Idempotency-Key` to make a retry safe: the same key and body replay the first answer with `Idempotency-Replayed: true` instead of acting twice. The secret is never stored for a replay: a replayed answer omits `secret` and sets `secretRedacted: true`.","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","format":"uuid"},"description":"API key id (`id` from `GET /api-keys`)."},{"$ref":"#/components/parameters/IdempotencyKeyOptional"},{"$ref":"#/components/parameters/AvrixApiVersion"},{"$ref":"#/components/parameters/RequestId"},{"$ref":"#/components/parameters/SandboxSimulateWrite"}],"responses":{"200":{"description":"Key rotated","headers":{"X-Request-Id":{"$ref":"#/components/headers/XRequestId"},"X-Avrix-Api-Version":{"$ref":"#/components/headers/XAvrixApiVersion"},"X-Api-Version":{"$ref":"#/components/headers/XApiVersion"},"Idempotency-Replayed":{"$ref":"#/components/headers/IdempotencyReplayed"},"X-RateLimit-Limit":{"$ref":"#/components/headers/XRateLimitLimit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/XRateLimitRemaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/XRateLimitReset"},"X-RateLimit-Bucket":{"$ref":"#/components/headers/XRateLimitBucket"}},"content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/SellerApiKeyRotated"},"meta":{"type":"object","properties":{"requestId":{"type":"string"}}}}},"example":{"data":{"id":"1e56bfac-9e93-45dc-8404-5d5021aedfc4","secret":"whsec_8f2c1d0e9b7a6c5d4e3f2a1b0c9d8e7f","previousSecretExpiresAt":"2026-11-02T09:30:00Z","secretRedacted":true},"meta":{"requestId":"00b01245-0334-4937-8412-67d0593c24c2"}}}}},"400":{"$ref":"#/components/responses/SellerApiUnsupportedApiVersion"},"401":{"$ref":"#/components/responses/SellerApiUnauthorized"},"403":{"$ref":"#/components/responses/SellerApiForbidden"},"404":{"description":"Key not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"409":{"$ref":"#/components/responses/SellerApiIdempotencyConflict"},"413":{"$ref":"#/components/responses/SellerApiPayloadTooLarge"},"422":{"description":"Invalid path id, or `overlapSeconds` is not a whole number from 60 to 86400.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"429":{"$ref":"#/components/responses/SellerApiRateLimited"},"500":{"$ref":"#/components/responses/SellerApiInternalError"},"503":{"$ref":"#/components/responses/SellerApiServiceUnavailable"},"504":{"$ref":"#/components/responses/SellerApiTimeout"}},"security":[{"bearerAuth":[]}],"x-avrix-scopes":["seller:keys:write"],"x-avrix-tier":"keys","x-avrix-rate-limit-class":"orders","x-avrix-rate-limit-class-2026-12-01":"general","x-avrix-scope-mode":"anyOf","tags":["Seller auth"],"operationId":"rotateApiKey","requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{"overlapSeconds":{"type":"integer","minimum":60,"maximum":86400,"description":"Keep the replaced secret working for this many seconds, so a rotation whose answer is lost does not lock you out. Omit it and the replaced secret stops at once."}}},"example":{"overlapSeconds":3600}}}}}},"/api/seller/v1/whoami-ip":{"get":{"summary":"Echo the request's normalized client IP","description":"**Public, unauthenticated; limited to 60 requests a minute per client IP (429 with Retry-After beyond that).** 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. Responses carry `X-RateLimit-Limit`, `X-RateLimit-Remaining` and `X-RateLimit-Reset` for that per-IP budget. The route reads no API key, so it never answers 401 or 403.","security":[],"parameters":[{"$ref":"#/components/parameters/RequestId"}],"responses":{"200":{"description":"Client IP resolved (or `null` when no header parsed)","headers":{"X-Request-Id":{"$ref":"#/components/headers/XRequestId"},"X-Avrix-Api-Version":{"$ref":"#/components/headers/XAvrixApiVersion"},"X-Api-Version":{"$ref":"#/components/headers/XApiVersion"},"X-RateLimit-Limit":{"$ref":"#/components/headers/XRateLimitLimit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/XRateLimitRemaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/XRateLimitReset"}},"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..."}}}}},"example":{"data":{"clientIp":"203.0.113.5"},"meta":{"requestId":"req_01J9..."}}}}},"401":{"description":"Not returned by this operation: it reads no API key. The entry is kept so that clients generated from earlier versions of this document keep their error types.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"403":{"description":"Not returned by this operation: it reads no API key. The entry is kept so that clients generated from earlier versions of this document keep their error types.","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","x-avrix-rate-limit-class":"none","x-avrix-scope-mode":"public","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. Requires the opt-in `seller:keys:export` scope (`seller:keys:pull` and `seller:orders:write` do not grant it). **Pre-order** SKUs return JSON (`application/json`) with reserved counts instead of a ZIP (pre-order purchasing is capability-gated — `whoami.capabilities.preorderEnabled`, default true; a Content Owner can opt its products out). 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, CONSUMER_GEO_ATTEST_REQUIRED, CONSUMER_RISK_HIGH, CONSUMER_RISK_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":[{"$ref":"#/components/parameters/IdempotencyKey"},{"$ref":"#/components/parameters/AvrixApiVersion"},{"$ref":"#/components/parameters/RequestId"},{"$ref":"#/components/parameters/SandboxSimulateWrite"}],"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":"Read on contract date `2026-12-01` and later, as on `POST /keys/pull`: required for API allocations on production keys and must equal `unitPriceCents` from `POST /orders/preview`. Earlier dates ignore it, and an export from an API allocation is refused with `422 EXPECTED_UNIT_PRICE_REQUIRED`."},"expectedWholesaleUnitPriceCents":{"type":"integer","minimum":1,"description":"Deprecated alias of `expectedUnitPriceCents`; when both are sent they must be equal. Read on contract date `2026-12-01` and later only.","deprecated":true},"priceCommitmentToken":{"type":"string","minLength":16,"maxLength":2048,"description":"Price commitment from `POST /orders/preview`, read on contract date `2026-12-01` and later with the same rules as `POST /keys/pull`. Earlier dates ignore it. Treat it as opaque: store and forward it as-is and never parse it."},"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"]}}}}},"example":{"data":{"type":"pre-order","skuId":"281d38df-5779-4f1f-8d97-f5dffc76f83b","skuCode":"EXAMPLE-STEAM-WW","orderReference":"store-order-10432","reserved":1,"allocationId":"071711e7-f983-420c-8bb3-c6fc224b3792","releaseDate":"2026-11-02T09:30:00Z","preorderStart":"2026-11-02T09:30:00Z","preorderEnd":"2026-11-02T09:30:00Z"}}}},"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)"},"X-Request-Id":{"$ref":"#/components/headers/XRequestId"},"X-Avrix-Api-Version":{"$ref":"#/components/headers/XAvrixApiVersion"},"X-Api-Version":{"$ref":"#/components/headers/XApiVersion"},"Idempotency-Replayed":{"$ref":"#/components/headers/IdempotencyReplayed"},"X-RateLimit-Limit":{"$ref":"#/components/headers/XRateLimitLimit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/XRateLimitRemaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/XRateLimitReset"},"X-RateLimit-Bucket":{"$ref":"#/components/headers/XRateLimitBucket"}}},"400":{"description":"Client error. Also returned when the `Idempotency-Key` header is missing or malformed: `IDEMPOTENCY_KEY_REQUIRED` on contract date `2026-12-01` and later, `BAD_REQUEST` on earlier dates. Also returned for an `X-Avrix-Api-Version` this API does not serve (`UNSUPPORTED_API_VERSION`).","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. Also returned for the `Idempotency-Key` itself: `IDEMPOTENCY_KEY_MISMATCH` (the key was already used with a different body) and `IDEMPOTENCY_REQUEST_IN_FLIGHT` (an earlier request with this key is still running; retry after `Retry-After` seconds).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"413":{"$ref":"#/components/responses/SellerApiPayloadTooLarge"},"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. Also returned when a platform dependency is temporarily unavailable (`SERVICE_UNAVAILABLE`) and, on a write that sends an `Idempotency-Key`, when the claim cannot be recorded (`IDEMPOTENCY_STORE_UNAVAILABLE`). Retry after `Retry-After` seconds.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"504":{"$ref":"#/components/responses/SellerApiTimeout"}},"security":[{"bearerAuth":[]}],"x-avrix-scopes":["seller:keys:export"],"x-avrix-tier":"keys","x-avrix-rate-limit-class":"orders","x-avrix-scope-mode":"anyOf","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:orders:write` or the legacy `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, CONSUMER_GEO_ATTEST_REQUIRED, CONSUMER_RISK_HIGH, CONSUMER_RISK_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":[{"$ref":"#/components/parameters/IdempotencyKey"},{"$ref":"#/components/parameters/AvrixApiVersion"},{"$ref":"#/components/parameters/RequestId"},{"$ref":"#/components/parameters/SandboxSimulate"}],"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":"Price commitment from `POST /orders/preview`. Read on contract date `2026-12-01` and later: the token must belong to you and this SKU (`422 PRICE_COMMITMENT_INVALID` / `PRICE_COMMITMENT_EXPIRED`), an `expectedUnitPriceCents` you also send must equal its price, and its price and country bind the sale, as on `POST /orders`. Earlier dates accept the field and ignore it. Treat it as opaque: store and forward it as-is and never parse it."},"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."},"immediateFulfilment":{"type":"boolean","default":true,"description":"When `false`, keys are assigned but plaintext is omitted (`deferredReveal: true`, `keys: []`), as on `POST /orders`."}}},"example":{"skuCode":"SANDBOX-ALWAYS-001","quantity":1,"orderReference":"store-order-10432"}}}},"responses":{"200":{"description":"Keys pulled or pre-order reserved","headers":{"X-Request-Id":{"$ref":"#/components/headers/XRequestId"},"X-Avrix-Api-Version":{"$ref":"#/components/headers/XAvrixApiVersion"},"X-Api-Version":{"$ref":"#/components/headers/XApiVersion"},"Idempotency-Replayed":{"$ref":"#/components/headers/IdempotencyReplayed"},"X-RateLimit-Limit":{"$ref":"#/components/headers/XRateLimitLimit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/XRateLimitRemaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/XRateLimitReset"},"X-RateLimit-Bucket":{"$ref":"#/components/headers/XRateLimitBucket"}},"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","description":"Plaintext codes (`string`) up to contract date 2026-09-01; typed key objects from 2026-10-01 (`X-Avrix-Api-Version`). Same order as `keyIds`.","items":{"$ref":"#/components/schemas/SellerDeliveredKey"}},"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)"},"warnings":{"type":"array","items":{"type":"string"},"description":"Settlement warnings for this delivery, same vocabulary and meaning as `POST /orders` `warnings` (e.g. `vat_declared_rate_below_expected`). Absent when nothing was flagged."},"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."},"keyIds":{"type":"array","items":{"type":"string","format":"uuid"},"description":"Key UUIDs of the delivered keys (for refunds / returns); an idempotent replay re-reads `keys` from them."}}},{"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"}}},"example":{"data":{"type":"fulfilled","skuId":"48dcff94-ce20-4ec2-8c2d-4c800f4800b1","skuCode":"EXAMPLE-STEAM-WW","orderReference":"store-order-10432","keys":["XXXXX-XXXXX-XXXXX-XXXXX"],"pulled":12,"allocationId":"99c8d06d-98f6-4c4a-82cc-72c877877672","fulfilledAt":"2026-11-02T09:30:00Z","orderReadableId":"ord_rje477e4","warnings":["example_warning"],"activation":{"type":"worldwide","countries":["DE"]},"keyIds":["a6dcec74-7f48-4f31-8b5a-dbf959a48af5"]},"contractTermId":"3428afdf-7aa7-46fe-891f-0430470a0579","contractTermVersion":1}}}},"400":{"description":"Client error. Also returned when the `Idempotency-Key` header is missing or malformed: `IDEMPOTENCY_KEY_REQUIRED` on contract date `2026-12-01` and later, `BAD_REQUEST` on earlier dates. Also returned for an `X-Avrix-Api-Version` this API does not serve (`UNSUPPORTED_API_VERSION`).","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. Also returned for the `Idempotency-Key` itself: `IDEMPOTENCY_KEY_MISMATCH` (the key was already used with a different body) and `IDEMPOTENCY_REQUEST_IN_FLIGHT` (an earlier request with this key is still running; retry after `Retry-After` seconds).","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"}}}}}}},"413":{"$ref":"#/components/responses/SellerApiPayloadTooLarge"},"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":{"$ref":"#/components/responses/SellerApiRateLimited"},"500":{"$ref":"#/components/responses/SellerApiInternalError"},"503":{"description":"Pre-order state unavailable. Also returned when a platform dependency is temporarily unavailable (`SERVICE_UNAVAILABLE`) and, on a write that sends an `Idempotency-Key`, when the claim cannot be recorded (`IDEMPOTENCY_STORE_UNAVAILABLE`). Retry after `Retry-After` seconds.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"504":{"$ref":"#/components/responses/SellerApiTimeout"}},"security":[{"bearerAuth":[]}],"x-avrix-scopes":["seller:orders:write","seller:keys:pull"],"x-avrix-tier":"keys","x-avrix-rate-limit-class":"orders","x-avrix-scope-mode":"anyOf","tags":["Keys"],"operationId":"pullKey"}},"/api/seller/v1/keys/pulls":{"get":{"summary":"List key pulls","description":"Key pull history, newest first: one row per game key your API keys pulled (`POST /orders`, `POST /keys/pull`, `POST /keys/export`). Rows name the pull (`keyPullId`) and the sale row it produced (`transactionId`, the id `GET /finance/api-sales/{transactionId}` reads). This is not a payment list: amounts are on `GET /finance/api-sales` and `GET /finance/ledger`.\n\nThe same handler, parameters and rows as `GET /transactions`, which is the deprecated name of this operation.\n\nPaging keys and the cursor rules are on `https://docs.avrix.io/seller-api/pagination`.","parameters":[{"name":"limit","in":"query","schema":{"type":"integer","default":50,"minimum":1,"maximum":100},"description":"Page size: how many items to return (1 to 100)."},{"name":"cursor","in":"query","schema":{"type":"string"},"description":"Opaque cursor from the previous page's `meta.nextCursor`. Omit for the first page."},{"name":"orderReference","in":"query","schema":{"type":"string"},"description":"Return only pulls with this order reference (exact match). Same as `filter[orderReference]=eq:<value>`; both together must name the same value."},{"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."},{"name":"parentOrderReference","in":"query","required":false,"schema":{"type":"string","minLength":1,"maxLength":255},"description":"Only the pulls of one bulk cart (its `parentOrderReference`)."},{"$ref":"#/components/parameters/AvrixApiVersion"},{"$ref":"#/components/parameters/RequestId"},{"$ref":"#/components/parameters/SandboxSimulateRateLimit"}],"responses":{"200":{"description":"Transactions list","headers":{"X-Request-Id":{"$ref":"#/components/headers/XRequestId"},"X-Avrix-Api-Version":{"$ref":"#/components/headers/XAvrixApiVersion"},"X-Api-Version":{"$ref":"#/components/headers/XApiVersion"},"X-RateLimit-Limit":{"$ref":"#/components/headers/XRateLimitLimit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/XRateLimitRemaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/XRateLimitReset"},"X-RateLimit-Bucket":{"$ref":"#/components/headers/XRateLimitBucket"}},"content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/SellerTransaction"}},"meta":{"$ref":"#/components/schemas/PaginationMeta"}}},"example":{"data":[{"keyPullId":"b5dca714-eed8-414e-849d-dc00457b4b91","transactionId":"099d5735-82de-4bd1-897d-40dc714f403f","allocationId":"638d711a-63e4-434e-8206-1ce00cce16ff","skuId":"89b18c2e-f2d3-4a38-889b-846eb020ec4e","skuCode":"EXAMPLE-STEAM-WW","quantity":12,"orderReference":"store-order-10432","pulledAt":"2026-11-02T09:30:00Z","salesCountryCode":"DE","detectedCountryCode":"off","countryMismatch":true,"warnings":["COUNTRY_MISMATCH"],"parentOrderReference":"store-order-10432","lineIndex":1}],"meta":{"total":2450,"limit":50,"hasMore":true,"nextCursor":"eyJ2IjoyLCJ0IjoiMjAyNi0xMS0wMlQwOTozMDowMFoifQ","nextUrl":"https://api.avrix.io/api/seller/v1/keys/pulls?cursor=eyJ2IjoyLCJ0IjoiMjAyNi0xMS0wMlQwOTozMDowMFoifQ","localePreference":"en"}}}}},"400":{"$ref":"#/components/responses/SellerApiUnsupportedApiVersion"},"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"},"503":{"$ref":"#/components/responses/SellerApiServiceUnavailable"},"504":{"$ref":"#/components/responses/SellerApiTimeout"}},"security":[{"bearerAuth":[]}],"x-avrix-scopes":["seller:orders:read","seller:orders:write","seller:products:read","seller:keys:pull"],"x-avrix-tier":"orders","x-avrix-rate-limit-class":"orders","x-avrix-scope-mode":"anyOf","tags":["Keys"],"operationId":"listKeyPulls"}},"/api/seller/v1/keys/return":{"post":{"summary":"Return keys after a refund","deprecated":true,"description":"Take delivered keys out of circulation after you refunded the buyer. Deprecated: use `POST /refunds`, which does the same and also records your refund or chargeback reference. This operation keeps working for existing integrations; no removal date is set.\n\nKeys sold under a revenue-share agreement stay with you (`held`); every other key is quarantined and never sold again, and the allocation headroom is restored. Before contract date `2026-12-01` the response always says `quarantined`; from `2026-12-01` it gives the real outcome and the call also ends any dispute freeze on the keys (`key.unfrozen`, resolution `refunded`). The Content Owner's refund window applies (`422 REFUND_WINDOW_EXPIRED`). Requires `seller:refunds:write` or `seller:orders:write`; the legacy `seller:keys:pull` is also accepted. Requires an **Idempotency-Key**. Emits `order.keys_returned` and `refund.completed`. See https://docs.avrix.io/seller-api/refunds-returns.\n\nSee `https://docs.avrix.io/seller-api/errors`.","parameters":[{"$ref":"#/components/parameters/IdempotencyKey"},{"$ref":"#/components/parameters/AvrixApiVersion"},{"$ref":"#/components/parameters/RequestId"},{"$ref":"#/components/parameters/SandboxSimulateWrite"}],"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":["7c9e6679-7425-40de-944b-e07fc1f90ae7"],"reason":"customer_refund"}}}},"responses":{"200":{"description":"Keys quarantined and allocation headroom restored","headers":{"X-Request-Id":{"$ref":"#/components/headers/XRequestId"},"X-Avrix-Api-Version":{"$ref":"#/components/headers/XAvrixApiVersion"},"X-Api-Version":{"$ref":"#/components/headers/XApiVersion"},"Idempotency-Replayed":{"$ref":"#/components/headers/IdempotencyReplayed"},"X-RateLimit-Limit":{"$ref":"#/components/headers/XRateLimitLimit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/XRateLimitRemaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/XRateLimitReset"},"X-RateLimit-Bucket":{"$ref":"#/components/headers/XRateLimitBucket"}},"content":{"application/json":{"schema":{"type":"object","required":["data"],"properties":{"data":{"type":"object","properties":{"returned":{"type":"integer","description":"Number of keys quarantined"},"keyDisposition":{"type":"string","enum":["quarantined","held","mixed"],"description":"What happened to the refunded keys. Before contract date `2026-12-01` always `quarantined`. From `2026-12-01`: `quarantined` (never sold again, headroom restored), `held` (revenue-share keys stay with you, no headroom change) or `mixed` (both; see `refunds[].keyDisposition`)."},"refunds":{"type":"array","description":"One refund record per refunded key sold under the API model. Keys sold under other business models have no sale record in Avrix, so they have no refund record and are not listed here. Empty when the call refunded nothing.","items":{"type":"object","required":["id","keyId","keyDisposition"],"properties":{"id":{"type":"string","format":"uuid","description":"The refund record id; read it with `GET /refunds/{refundId}`."},"keyId":{"type":"string","format":"uuid"},"keyDisposition":{"type":"string","enum":["quarantined","held"],"description":"`held`: the key stays with you (revenue share). `quarantined`: never sold again."}}}}},"required":["returned","keyDisposition"]}}},"example":{"data":{"returned":1,"keyDisposition":"quarantined"}}}}},"400":{"description":"Keys not returnable or not owned by this seller. Also returned when the `Idempotency-Key` header is missing or malformed: `IDEMPOTENCY_KEY_REQUIRED` on contract date `2026-12-01` and later, `BAD_REQUEST` on earlier dates. Also returned for an `X-Avrix-Api-Version` this API does not serve (`UNSUPPORTED_API_VERSION`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"401":{"$ref":"#/components/responses/SellerApiUnauthorized"},"403":{"$ref":"#/components/responses/SellerApiForbidden"},"404":{"description":"NOT_FOUND: a keyId was not pulled by your account","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"409":{"description":"KEY_NOT_RETURNABLE: a key is already returned or refunded (details.keyId, keyStatus, businessModel); nothing was changed. Also returned for the `Idempotency-Key` itself: `IDEMPOTENCY_KEY_MISMATCH` (the key was already used with a different body) and `IDEMPOTENCY_REQUEST_IN_FLIGHT` (an earlier request with this key is still running; retry after `Retry-After` seconds).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"413":{"$ref":"#/components/responses/SellerApiPayloadTooLarge"},"422":{"description":"Validation failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"429":{"$ref":"#/components/responses/SellerApiRateLimited"},"500":{"$ref":"#/components/responses/SellerApiInternalError"},"503":{"description":"SERVICE_UNAVAILABLE: retry with the same Idempotency-Key after Retry-After","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"504":{"$ref":"#/components/responses/SellerApiTimeout"}},"security":[{"bearerAuth":[]}],"x-avrix-scopes":["seller:refunds:write","seller:orders:write","seller:keys:pull"],"x-avrix-tier":"keys","x-avrix-rate-limit-class":"orders","x-avrix-scope-mode":"anyOf","tags":["Refunds"],"operationId":"returnKey"}},"/api/seller/v1/refunds":{"post":{"summary":"Declare a refund or chargeback","description":"Tell Avrix that you refunded a buyer, or that a buyer's payment was charged back, so the keys of that sale leave circulation. Avrix never moves the money: refund the buyer in your own payment provider first. This is the call to use for every refund and chargeback you give a buyer (`POST /keys/return` does the same without references and is kept for existing integrations). To ask the Content Owner for a refund or a replacement instead, file a return request with `POST /returns`.\n\nBefore calling, `POST /refunds/preview` answers per key whether it can be refunded, until when, and what will happen to it.\n\nWhat happens to the keys (`keyDisposition`): keys sold under a revenue-share agreement stay with you (`held`); every other key is quarantined and never sold again, and the allocation headroom is restored. Before contract date `2026-12-01` the response always says `quarantined`; from `2026-12-01` it says `held`, `quarantined` or `mixed` (both, in one call). Each refunded key sold under the API model gets a refund record: `refunds[].id` is the id `GET /refunds/{refundId}` reads. Keys sold under other business models have no sale record in Avrix and get none.\n\nA refund (`type: refund`) is accepted within the Content Owner's refund window (`422 REFUND_WINDOW_EXPIRED` after it); chargebacks are never windowed. Any dispute freeze on the keys ends (`key.unfrozen`, resolution `refunded` or `chargeback`). From `2026-12-01` the order's status follows its keys: a partial refund leaves the order `fulfilled`, and it reads `refunded` once every key is refunded. Before that date the `orderReference` you send is marked `refunded` whatever the keys.\n\nEmits `order.keys_returned` (inventory side), `refund.completed` (the refund record) and, for `type: chargeback`, `chargeback.opened`. Requires `seller:refunds:write` or `seller:orders:write` (or the legacy `seller:keys:pull`) and an `Idempotency-Key`.\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\nSee `https://docs.avrix.io/seller-api/errors`.","parameters":[{"$ref":"#/components/parameters/IdempotencyKey"},{"$ref":"#/components/parameters/AvrixApiVersion"},{"$ref":"#/components/parameters/RequestId"},{"$ref":"#/components/parameters/SandboxSimulateWrite"}],"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"},"strict":{"type":"boolean","description":"With `quantity`: refuse the whole request (409 `REFUND_QUANTITY_EXCEEDS_LIVE_KEYS`) instead of refunding fewer keys than asked when fewer are still live under `orderReference`."}}},"example":{"type":"refund","keyIds":["7c9e6679-7425-40de-944b-e07fc1f90ae7"],"refundReference":"psp_refund_10432"}}}},"responses":{"200":{"description":"Refund or chargeback accepted and keys quarantined","headers":{"X-Request-Id":{"$ref":"#/components/headers/XRequestId"},"X-Avrix-Api-Version":{"$ref":"#/components/headers/XAvrixApiVersion"},"X-Api-Version":{"$ref":"#/components/headers/XApiVersion"},"Idempotency-Replayed":{"$ref":"#/components/headers/IdempotencyReplayed"},"X-RateLimit-Limit":{"$ref":"#/components/headers/XRateLimitLimit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/XRateLimitRemaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/XRateLimitReset"},"X-RateLimit-Bucket":{"$ref":"#/components/headers/XRateLimitBucket"}},"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"},"requested":{"type":"integer","description":"Keys asked for: the length of `keyIds`, or `quantity`."},"skipped":{"type":"array","description":"Requested units not refunded because no live key was left under `orderReference` (`quantity` without `strict`). Empty when everything asked for was refunded.","items":{"type":"object","properties":{"keyId":{"type":["string","null"],"format":"uuid"},"reason":{"type":"string","enum":["no_live_key"]}},"required":["keyId","reason"]}},"keyDisposition":{"type":"string","enum":["quarantined","held","mixed"],"description":"What happened to the refunded keys. Before contract date `2026-12-01` always `quarantined`. From `2026-12-01`: `quarantined` (never sold again, headroom restored), `held` (revenue-share keys stay with you, no headroom change) or `mixed` (both; see `refunds[].keyDisposition`)."},"refunds":{"type":"array","description":"One refund record per refunded key sold under the API model. Keys sold under other business models have no sale record in Avrix, so they have no refund record and are not listed here. Empty when the call refunded nothing.","items":{"type":"object","required":["id","keyId","keyDisposition"],"properties":{"id":{"type":"string","format":"uuid","description":"The refund record id; read it with `GET /refunds/{refundId}`."},"keyId":{"type":"string","format":"uuid"},"keyDisposition":{"type":"string","enum":["quarantined","held"],"description":"`held`: the key stays with you (revenue share). `quarantined`: never sold again."}}}}},"required":["type","requested","returned","skipped","keyDisposition"]}}},"example":{"data":{"returned":1,"refundReference":"rfnd_10432","chargebackReference":"chbk_10432","orderReference":"store-order-10432","occurredAt":"2026-11-02T09:30:00Z","requested":1,"skipped":[{"keyId":"8c5c2045-0c13-4fd2-8e59-ebb79267ec67","reason":"no_live_key"}],"keyDisposition":"quarantined","type":"refund"}}}}},"400":{"description":"Keys not returnable or not owned by this seller. Also returned when the `Idempotency-Key` header is missing or malformed: `IDEMPOTENCY_KEY_REQUIRED` on contract date `2026-12-01` and later, `BAD_REQUEST` on earlier dates. Also returned for an `X-Avrix-Api-Version` this API does not serve (`UNSUPPORTED_API_VERSION`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"401":{"$ref":"#/components/responses/SellerApiUnauthorized"},"403":{"$ref":"#/components/responses/SellerApiForbidden"},"404":{"description":"NOT_FOUND: a keyId was not pulled by your account, or no live keys under orderReference","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"409":{"description":"KEY_NOT_RETURNABLE (a key is already returned or refunded; details.keyId, keyStatus, businessModel) or REFUND_QUANTITY_EXCEEDS_LIVE_KEYS (strict: true). Also returned for the `Idempotency-Key` itself: `IDEMPOTENCY_KEY_MISMATCH` (the key was already used with a different body) and `IDEMPOTENCY_REQUEST_IN_FLIGHT` (an earlier request with this key is still running; retry after `Retry-After` seconds).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"413":{"$ref":"#/components/responses/SellerApiPayloadTooLarge"},"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"},"503":{"description":"SERVICE_UNAVAILABLE: retry with the same Idempotency-Key after Retry-After","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"504":{"$ref":"#/components/responses/SellerApiTimeout"}},"security":[{"bearerAuth":[]}],"x-avrix-scopes":["seller:refunds:write","seller:orders:write","seller:keys:pull"],"x-avrix-tier":"orders","x-avrix-rate-limit-class":"orders","x-avrix-scope-mode":"anyOf","tags":["Refunds"],"operationId":"createRefund"},"get":{"summary":"List refunds and chargebacks","description":"Paginated refund and chargeback records, one per refunded key sold under the API model (keys sold under other business models have no sale record in Avrix). **Avrix never refunds your PSP**: refund the buyer first, then declare it with `POST /refunds`. Find a refund by the reference you sent (`refundReference`, `chargebackReference`), by `orderReference`, `keyId`, `status` or `type`; filters combine. A value outside the documented set is refused with `422 VALIDATION_FAILED` naming the field. Read one record with `GET /refunds/{refundId}`. Scopes: `seller:refunds:read` (also `seller:refunds:write`, `seller:finance:read`, `seller:orders:write`, or the legacy `seller:keys:pull`).\n\n**Paging:** the shared list contract, see `https://docs.avrix.io/seller-api/pagination`. On contract date `2026-12-01` and later a `cursor` this API did not return is refused with `422 VALIDATION_FAILED` (`details.issues[].field` is `cursor`); earlier dates serve the first page.","security":[{"bearerAuth":[]}],"x-avrix-scopes":["seller:refunds:read","seller:refunds:write","seller:finance:read","seller:orders:write","seller:keys:pull"],"x-avrix-tier":"standard","x-avrix-rate-limit-class":"orders","x-avrix-scope-mode":"anyOf","parameters":[{"name":"limit","in":"query","description":"Page size: how many items to return (1 to 100).","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"},{"name":"refundReference","in":"query","schema":{"type":"string","maxLength":128},"description":"The `refundReference` you sent on `POST /refunds`. Lists refunds and returns only."},{"name":"chargebackReference","in":"query","schema":{"type":"string","maxLength":128},"description":"The `chargebackReference` you sent on `POST /refunds`. Lists chargebacks only."},{"name":"status","in":"query","schema":{"type":"string","enum":["pending","completed","chargeback_open","chargeback_lost","chargeback_won"]},"description":"Only records in this status."},{"name":"type","in":"query","schema":{"type":"string","enum":["refund","chargeback","return"]},"description":"Only records of this type."},{"name":"keyId","in":"query","schema":{"type":"string","format":"uuid"},"description":"Only the record for this key."},{"$ref":"#/components/parameters/AvrixApiVersion"},{"$ref":"#/components/parameters/RequestId"},{"$ref":"#/components/parameters/SandboxSimulateRateLimit"}],"responses":{"200":{"description":"Refund list","headers":{"X-Request-Id":{"$ref":"#/components/headers/XRequestId"},"X-Avrix-Api-Version":{"$ref":"#/components/headers/XAvrixApiVersion"},"X-Api-Version":{"$ref":"#/components/headers/XApiVersion"},"X-RateLimit-Limit":{"$ref":"#/components/headers/XRateLimitLimit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/XRateLimitRemaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/XRateLimitReset"},"X-RateLimit-Bucket":{"$ref":"#/components/headers/XRateLimitBucket"}},"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"]},"hasMore":{"type":"boolean","description":"True when another page follows. Loop on `hasMore`; send `nextCursor` back as `cursor`."}}}}},"example":{"data":[{"id":"20c8c24e-6204-4c6c-813d-a0783f82d2f6","status":"pending","type":"refund","keyId":"e16ba746-99a3-42b3-826b-e762cafea964","skuId":"38c0b9a7-e2d8-4032-855b-3499d0c2382b","productId":"6ff5886c-e14d-4065-8b34-2539cc775d63","orderReference":"store-order-10432","adjustmentReference":"adj_10432","reversalTransactionId":"3e990f0b-be2c-4237-881f-fc65e424ee49","salePriceCents":2450,"salePriceMinor":2450,"currencyCode":"EUR","currencyExponent":2,"saleTimestamp":"2026-11-02T09:30:00Z","adjustedAt":"2026-11-02T09:30:00Z","occurredAt":"2026-11-02T09:30:00Z"}],"meta":{"limit":50,"nextCursor":"eyJ2IjoyLCJ0IjoiMjAyNi0xMS0wMlQwOTozMDowMFoifQ","nextUrl":"https://api.avrix.io/api/seller/v1/refunds?cursor=eyJ2IjoyLCJ0IjoiMjAyNi0xMS0wMlQwOTozMDowMFoifQ","hasMore":true}}}}},"400":{"$ref":"#/components/responses/SellerApiUnsupportedApiVersion"},"401":{"$ref":"#/components/responses/SellerApiUnauthorized"},"403":{"$ref":"#/components/responses/SellerApiForbidden"},"422":{"$ref":"#/components/responses/SellerApiValidationFailed"},"429":{"$ref":"#/components/responses/SellerApiRateLimited"},"500":{"$ref":"#/components/responses/SellerApiInternalError"},"503":{"$ref":"#/components/responses/SellerApiServiceUnavailable"},"504":{"$ref":"#/components/responses/SellerApiTimeout"}},"operationId":"listRefunds","tags":["Refunds"]}},"/api/seller/v1/promotions/summary":{"get":{"summary":"Get promotions summary","description":"Counts of platform event shares and custom deals by state. Shares the vendor has not sent yet are not counted. Requires seller:promotions:read scope.\n\nOn contract date `2026-12-01` and later a failed read of the deals answers `503` or `504` (or a sanitized `500`) instead of `200` with zero deal counts.","parameters":[{"$ref":"#/components/parameters/AvrixApiVersion"},{"$ref":"#/components/parameters/RequestId"},{"$ref":"#/components/parameters/SandboxSimulateRateLimit"}],"responses":{"200":{"description":"Summary counts","headers":{"X-Request-Id":{"$ref":"#/components/headers/XRequestId"},"X-Avrix-Api-Version":{"$ref":"#/components/headers/XAvrixApiVersion"},"X-Api-Version":{"$ref":"#/components/headers/XApiVersion"},"X-RateLimit-Limit":{"$ref":"#/components/headers/XRateLimitLimit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/XRateLimitRemaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/XRateLimitReset"},"X-RateLimit-Bucket":{"$ref":"#/components/headers/XRateLimitBucket"}},"content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/SellerPromotionsSummary"}}},"example":{"data":{"shares":{"pending":1,"accepted":1,"declined":1,"expired":1,"vendor_withdrawn":1,"total":2450},"deals":{"pending":1,"approved":1,"rejected":1,"expired":1,"total":2450}}}}}},"400":{"$ref":"#/components/responses/SellerApiUnsupportedApiVersion"},"401":{"$ref":"#/components/responses/SellerApiUnauthorized"},"403":{"$ref":"#/components/responses/SellerApiForbidden"},"422":{"$ref":"#/components/responses/SellerApiValidationFailed"},"429":{"$ref":"#/components/responses/SellerApiRateLimited"},"500":{"$ref":"#/components/responses/SellerApiInternalError"},"503":{"$ref":"#/components/responses/SellerApiServiceUnavailable"},"504":{"$ref":"#/components/responses/SellerApiTimeout"}},"security":[{"bearerAuth":[]}],"x-avrix-scopes":["seller:promotions:read"],"x-avrix-tier":"promotions","x-avrix-rate-limit-class":"finance","x-avrix-scope-mode":"anyOf","tags":["Promotions"],"operationId":"getPromotionsSummary"}},"/api/seller/v1/promotions/shares":{"get":{"summary":"List platform event shares","description":"Platform event promotions vendors offered your company. Filter by status (pending, accepted, declined, expired, vendor_withdrawn), by vendor (`vendor`), by promotion window (`from`, `to`) and by last change (`updatedSince`); order with `sort`. Shares the vendor has not sent yet are never listed. Requires seller:promotions:read scope.\n\n**Paging:** the shared list contract, see `https://docs.avrix.io/seller-api/pagination`. On contract date `2026-12-01` and later a `cursor` this API did not return is refused with `422 VALIDATION_FAILED` (`details.issues[].field` is `cursor`); earlier dates serve the first page.","parameters":[{"name":"status","in":"query","schema":{"type":"string"},"description":"Comma-separated: pending, accepted, declined, expired, vendor_withdrawn"},{"name":"vendor","in":"query","required":false,"schema":{"type":"string","maxLength":32,"pattern":"^[a-zA-Z0-9_-]+$"},"description":"Only shares from this vendor (company id). Additive."},{"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 cursor from `meta.nextCursor` of the previous page."},{"name":"from","in":"query","required":false,"schema":{"type":"string","format":"date-time"},"description":"Only offers whose promotion window ends at or after this instant (ISO 8601, UTC). With `to`, the window overlaps [`from`, `to`]. Additive."},{"name":"to","in":"query","required":false,"schema":{"type":"string","format":"date-time"},"description":"Only offers whose promotion window starts at or before this instant (ISO 8601, UTC). Additive."},{"name":"updatedSince","in":"query","required":false,"schema":{"type":"string","format":"date-time"},"description":"Only offers that changed at or after this instant (`updated_at`), for incremental sync. Additive."},{"name":"sort","in":"query","required":false,"schema":{"type":"string","enum":["-offeredAt","offeredAt","-updatedAt","updatedAt"],"default":"-offeredAt"},"description":"List order: `offeredAt` is when the vendor sent the offer, `updatedAt` its last change. A leading `-` is newest first. Keep the same `sort` while you follow `nextCursor`. Additive."},{"$ref":"#/components/parameters/AvrixApiVersion"},{"$ref":"#/components/parameters/RequestId"},{"$ref":"#/components/parameters/SandboxSimulateRateLimit"}],"responses":{"200":{"description":"Shares list","headers":{"X-Request-Id":{"$ref":"#/components/headers/XRequestId"},"X-Avrix-Api-Version":{"$ref":"#/components/headers/XAvrixApiVersion"},"X-Api-Version":{"$ref":"#/components/headers/XApiVersion"},"X-RateLimit-Limit":{"$ref":"#/components/headers/XRateLimitLimit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/XRateLimitRemaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/XRateLimitReset"},"X-RateLimit-Bucket":{"$ref":"#/components/headers/XRateLimitBucket"}},"content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/SellerPromotionShare"}},"meta":{"type":"object","properties":{"limit":{"type":"integer","description":"The page size this response was cut at."},"count":{"type":"integer","description":"Number of items in `data`."},"hasMore":{"type":"boolean","description":"True when another page follows. Loop on `hasMore`; send `nextCursor` back as `cursor`."},"nextCursor":{"type":["string","null"],"description":"Opaque position after the last item of this page; send it back as `cursor`. Null on the last page."},"nextUrl":{"type":["string","null"],"description":"Absolute URL of the next page: this request with `cursor` set to `nextCursor`. Null when there is no next page."}}}}},"example":{"data":[{"share_id":"93c6a1b2-85ae-40b6-85a9-e79c0bdfdf30","participation_id":"162e2a03-6a8d-4152-8b24-8f497b4df8c4","status":"pending","participation_status":"participating","seller_notes":"Happy to take part.","shared_at":"2026-11-02T09:30:00Z","responded_at":"2026-11-02T09:30:00Z","product_snapshot":[{"sku_id":"c38a3f89-130c-4dc7-82ed-c5cf5f823584","discount_percent":20,"base_price_cents":2450,"currency_code":"EUR","status":"included","product_name":"Example Game","edition_name":"Standard Edition","sku_name":"Example Game - Standard Edition"}],"vendor_company_id":"acme-games","vendor_company_name":"Acme Games","event_id":"b06a338f-2935-4b0a-8ff0-da0c9da05eac","event_name":"Autumn sale","event_starts_at":"2026-11-02T09:30:00Z","event_ends_at":"2026-11-02T09:30:00Z","event_submission_deadline":"2026-11-02T09:30:00Z","platform_id":"7d44ba84-14af-4d5b-80c0-5a146522e486","platform_name":"Steam","platform_code":"steam","product_count":12,"genre_names":["Example name"],"updated_at":"2026-11-02T09:30:00Z","respond_by":"2026-11-02T09:30:00Z"}],"meta":{"limit":50,"count":12,"hasMore":true,"nextCursor":"eyJ2IjoyLCJ0IjoiMjAyNi0xMS0wMlQwOTozMDowMFoifQ","nextUrl":"https://api.avrix.io/api/seller/v1/promotions/shares?cursor=eyJ2IjoyLCJ0IjoiMjAyNi0xMS0wMlQwOTozMDowMFoifQ"}}}}},"400":{"$ref":"#/components/responses/SellerApiUnsupportedApiVersion"},"401":{"$ref":"#/components/responses/SellerApiUnauthorized"},"403":{"$ref":"#/components/responses/SellerApiForbidden"},"422":{"$ref":"#/components/responses/SellerApiValidationFailed"},"429":{"$ref":"#/components/responses/SellerApiRateLimited"},"500":{"$ref":"#/components/responses/SellerApiInternalError"},"503":{"$ref":"#/components/responses/SellerApiServiceUnavailable"},"504":{"$ref":"#/components/responses/SellerApiTimeout"}},"security":[{"bearerAuth":[]}],"x-avrix-scopes":["seller:promotions:read"],"x-avrix-tier":"promotions","x-avrix-rate-limit-class":"finance","x-avrix-scope-mode":"anyOf","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,"description":"Promotion share id.","schema":{"type":"string","format":"uuid"}},{"$ref":"#/components/parameters/AvrixApiVersion"},{"$ref":"#/components/parameters/RequestId"},{"$ref":"#/components/parameters/SandboxSimulateRateLimit"}],"responses":{"200":{"description":"Share detail with products","headers":{"X-Request-Id":{"$ref":"#/components/headers/XRequestId"},"X-Avrix-Api-Version":{"$ref":"#/components/headers/XAvrixApiVersion"},"X-Api-Version":{"$ref":"#/components/headers/XApiVersion"},"X-RateLimit-Limit":{"$ref":"#/components/headers/XRateLimitLimit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/XRateLimitRemaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/XRateLimitReset"},"X-RateLimit-Bucket":{"$ref":"#/components/headers/XRateLimitBucket"}},"content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/SellerPromotionShareDetail"}}},"example":{"data":{"share_id":"05a2a1cc-8292-406d-82d1-d1483d7fb8cb","participation_id":"3db44e1e-9a74-4ff8-8d1a-cdf46d4aaf5a","status":"pending","participation_status":"participating","seller_notes":"Happy to take part.","shared_at":"2026-11-02T09:30:00Z","responded_at":"2026-11-02T09:30:00Z","product_snapshot":[{"sku_id":"283a2f08-133a-4413-8a2c-f6dc6ba66775","discount_percent":20,"base_price_cents":2450,"currency_code":"EUR","status":"included","product_name":"Example Game","edition_name":"Standard Edition","sku_name":"Example Game - Standard Edition"}],"vendor_company_id":"acme-games","vendor_company_name":"Acme Games","event_id":"b3e077cf-68c0-45b5-8e67-8ec85dd58eca","event_name":"Autumn sale","event_starts_at":"2026-11-02T09:30:00Z","event_ends_at":"2026-11-02T09:30:00Z","event_submission_deadline":"2026-11-02T09:30:00Z","platform_id":"199d3a71-f331-44db-894a-55c698e690c5","platform_name":"Steam","platform_code":"steam","product_count":12,"genre_names":["Example name"],"updated_at":"2026-11-02T09:30:00Z","respond_by":"2026-11-02T09:30:00Z","products":[{"sku_id":"1e03e431-499a-43ab-88cd-176201dd2769","sku_code":"EXAMPLE-STEAM-WW","product_id":"b5efa304-96cf-4955-8f73-7d06691a13f4","product_name":"Example Game","edition_name":"Standard Edition","key_type_name":"Steam key","region_name":"Europe","discount_percent":20,"base_price_cents":2450,"currency_code":"base_price_cents","price_effect":"list_price"}]}}}}},"400":{"$ref":"#/components/responses/SellerApiUnsupportedApiVersion"},"401":{"$ref":"#/components/responses/SellerApiUnauthorized"},"403":{"$ref":"#/components/responses/SellerApiForbidden"},"404":{"description":"Share not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"422":{"$ref":"#/components/responses/SellerApiValidationFailed"},"429":{"$ref":"#/components/responses/SellerApiRateLimited"},"500":{"$ref":"#/components/responses/SellerApiInternalError"},"503":{"$ref":"#/components/responses/SellerApiServiceUnavailable"},"504":{"$ref":"#/components/responses/SellerApiTimeout"}},"security":[{"bearerAuth":[]}],"x-avrix-scopes":["seller:promotions:read"],"x-avrix-tier":"promotions","x-avrix-rate-limit-class":"finance","x-avrix-scope-mode":"anyOf","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. **Retries:** send an `Idempotency-Key` to make a retry safe: the same key and body replay the first answer with `Idempotency-Replayed: true` instead of acting twice. On contract date `2026-12-01` and later a repeat without the key is also safe: the same answer returns 200, a different one 409.","parameters":[{"name":"shareId","in":"path","required":true,"description":"Promotion share id.","schema":{"type":"string","format":"uuid"}},{"$ref":"#/components/parameters/IdempotencyKeyOptional"},{"$ref":"#/components/parameters/AvrixApiVersion"},{"$ref":"#/components/parameters/RequestId"},{"$ref":"#/components/parameters/SandboxSimulateWrite"}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"sellerNotes":{"type":"string","description":"Optional notes"}}},"example":{}}}},"responses":{"200":{"description":"Share accepted","headers":{"X-Request-Id":{"$ref":"#/components/headers/XRequestId"},"X-Avrix-Api-Version":{"$ref":"#/components/headers/XAvrixApiVersion"},"X-Api-Version":{"$ref":"#/components/headers/XApiVersion"},"Idempotency-Replayed":{"$ref":"#/components/headers/IdempotencyReplayed"},"X-RateLimit-Limit":{"$ref":"#/components/headers/XRateLimitLimit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/XRateLimitRemaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/XRateLimitReset"},"X-RateLimit-Bucket":{"$ref":"#/components/headers/XRateLimitBucket"}},"content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"shareId":{"type":"string"},"status":{"type":"string","enum":["accepted"],"description":"The share's state after this call: `accepted`."}}}}},"example":{"data":{"shareId":"4d55896a-c600-45dc-855d-ae4a478683be","status":"accepted"}}}}},"400":{"description":"Already responded or expired. On contract date `2026-12-01` and later, answering again with the answer the share already has returns 200 with the share's state, a different answer returns 409, and an expired share returns 409 (`details.reason: SHARE_EXPIRED`). Also returned for an `X-Avrix-Api-Version` this API does not serve (`UNSUPPORTED_API_VERSION`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"401":{"$ref":"#/components/responses/SellerApiUnauthorized"},"403":{"$ref":"#/components/responses/SellerApiForbidden"},"404":{"description":"`NOT_FOUND`: no promotion share with this id was offered to your company.","headers":{"X-Request-Id":{"$ref":"#/components/headers/XRequestId"},"X-Avrix-Api-Version":{"$ref":"#/components/headers/XAvrixApiVersion"},"X-Api-Version":{"$ref":"#/components/headers/XApiVersion"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"409":{"description":"`IDEMPOTENCY_KEY_MISMATCH`: the `Idempotency-Key` was already used with a different body; use a new key for a new request. `IDEMPOTENCY_REQUEST_IN_FLIGHT`: an earlier request with this key is still running; wait `Retry-After` seconds and send the same request again. On contract date `2026-12-01` and later also `CONFLICT`: the share already has a different answer, which cannot be replaced (`details.reason` is `SHARE_ALREADY_RESPONDED`, `details.currentStatus` names it), or it can no longer be answered (`details.reason` is `SHARE_EXPIRED`). Earlier contract dates answer 400 instead.","headers":{"X-Request-Id":{"$ref":"#/components/headers/XRequestId"},"X-Avrix-Api-Version":{"$ref":"#/components/headers/XAvrixApiVersion"},"X-Api-Version":{"$ref":"#/components/headers/XApiVersion"},"Retry-After":{"$ref":"#/components/headers/RetryAfter"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"413":{"$ref":"#/components/responses/SellerApiPayloadTooLarge"},"422":{"$ref":"#/components/responses/SellerApiValidationFailed"},"429":{"$ref":"#/components/responses/SellerApiRateLimited"},"500":{"$ref":"#/components/responses/SellerApiInternalError"},"503":{"$ref":"#/components/responses/SellerApiServiceUnavailable"},"504":{"$ref":"#/components/responses/SellerApiTimeout"}},"security":[{"bearerAuth":[]}],"x-avrix-scopes":["seller:promotions:respond"],"x-avrix-tier":"promotions","x-avrix-rate-limit-class":"finance","x-avrix-scope-mode":"anyOf","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. **Retries:** send an `Idempotency-Key` to make a retry safe: the same key and body replay the first answer with `Idempotency-Replayed: true` instead of acting twice. On contract date `2026-12-01` and later a repeat without the key is also safe: the same answer returns 200, a different one 409.","parameters":[{"name":"shareId","in":"path","required":true,"description":"Promotion share id.","schema":{"type":"string","format":"uuid"}},{"$ref":"#/components/parameters/IdempotencyKeyOptional"},{"$ref":"#/components/parameters/AvrixApiVersion"},{"$ref":"#/components/parameters/RequestId"},{"$ref":"#/components/parameters/SandboxSimulateWrite"}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"notes":{"type":"string","description":"Optional decline reason"}}},"example":{}}}},"responses":{"200":{"description":"Share declined","headers":{"X-Request-Id":{"$ref":"#/components/headers/XRequestId"},"X-Avrix-Api-Version":{"$ref":"#/components/headers/XAvrixApiVersion"},"X-Api-Version":{"$ref":"#/components/headers/XApiVersion"},"Idempotency-Replayed":{"$ref":"#/components/headers/IdempotencyReplayed"},"X-RateLimit-Limit":{"$ref":"#/components/headers/XRateLimitLimit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/XRateLimitRemaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/XRateLimitReset"},"X-RateLimit-Bucket":{"$ref":"#/components/headers/XRateLimitBucket"}},"content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"shareId":{"type":"string"},"status":{"type":"string","enum":["declined"],"description":"The share's state after this call: `declined`."}}}}},"example":{"data":{"shareId":"4c6940fe-041d-4d8c-8ed7-10ee6247dc94","status":"declined"}}}}},"400":{"description":"Already responded or expired. On contract date `2026-12-01` and later, answering again with the answer the share already has returns 200 with the share's state, a different answer returns 409, and an expired share returns 409 (`details.reason: SHARE_EXPIRED`). Also returned for an `X-Avrix-Api-Version` this API does not serve (`UNSUPPORTED_API_VERSION`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"401":{"$ref":"#/components/responses/SellerApiUnauthorized"},"403":{"$ref":"#/components/responses/SellerApiForbidden"},"404":{"description":"`NOT_FOUND`: no promotion share with this id was offered to your company.","headers":{"X-Request-Id":{"$ref":"#/components/headers/XRequestId"},"X-Avrix-Api-Version":{"$ref":"#/components/headers/XAvrixApiVersion"},"X-Api-Version":{"$ref":"#/components/headers/XApiVersion"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"409":{"description":"`IDEMPOTENCY_KEY_MISMATCH`: the `Idempotency-Key` was already used with a different body; use a new key for a new request. `IDEMPOTENCY_REQUEST_IN_FLIGHT`: an earlier request with this key is still running; wait `Retry-After` seconds and send the same request again. On contract date `2026-12-01` and later also `CONFLICT`: the share already has a different answer, which cannot be replaced (`details.reason` is `SHARE_ALREADY_RESPONDED`, `details.currentStatus` names it), or it can no longer be answered (`details.reason` is `SHARE_EXPIRED`). Earlier contract dates answer 400 instead.","headers":{"X-Request-Id":{"$ref":"#/components/headers/XRequestId"},"X-Avrix-Api-Version":{"$ref":"#/components/headers/XAvrixApiVersion"},"X-Api-Version":{"$ref":"#/components/headers/XApiVersion"},"Retry-After":{"$ref":"#/components/headers/RetryAfter"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"413":{"$ref":"#/components/responses/SellerApiPayloadTooLarge"},"422":{"$ref":"#/components/responses/SellerApiValidationFailed"},"429":{"$ref":"#/components/responses/SellerApiRateLimited"},"500":{"$ref":"#/components/responses/SellerApiInternalError"},"503":{"$ref":"#/components/responses/SellerApiServiceUnavailable"},"504":{"$ref":"#/components/responses/SellerApiTimeout"}},"security":[{"bearerAuth":[]}],"x-avrix-scopes":["seller:promotions:respond"],"x-avrix-tier":"promotions","x-avrix-rate-limit-class":"finance","x-avrix-scope-mode":"anyOf","tags":["Promotions"],"operationId":"declineShare"}},"/api/seller/v1/promotions/deals":{"get":{"summary":"List received custom deals","description":"Custom promotions vendors offered your company. Filter by vendor (`vendor`), status (pending, approved, rejected, expired), promotion window (`from`, `to`) and last change (`updatedSince`); order with `sort`. Requires seller:promotions:read scope.\n\n**Paging:** the shared list contract, see `https://docs.avrix.io/seller-api/pagination`. On contract date `2026-12-01` and later a `cursor` this API did not return is refused with `422 VALIDATION_FAILED` (`details.issues[].field` is `cursor`); earlier dates serve the first page.","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"},{"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 cursor from `meta.nextCursor` of the previous page."},{"name":"from","in":"query","required":false,"schema":{"type":"string","format":"date-time"},"description":"Only offers whose promotion window ends at or after this instant (ISO 8601, UTC). With `to`, the window overlaps [`from`, `to`]. Additive."},{"name":"to","in":"query","required":false,"schema":{"type":"string","format":"date-time"},"description":"Only offers whose promotion window starts at or before this instant (ISO 8601, UTC). Additive."},{"name":"updatedSince","in":"query","required":false,"schema":{"type":"string","format":"date-time"},"description":"Only offers that changed at or after this instant (`updated_at`), for incremental sync. Additive."},{"name":"sort","in":"query","required":false,"schema":{"type":"string","enum":["-offeredAt","offeredAt","-updatedAt","updatedAt"],"default":"-offeredAt"},"description":"List order: `offeredAt` is when the vendor sent the offer, `updatedAt` its last change. A leading `-` is newest first. Keep the same `sort` while you follow `nextCursor`. Additive."},{"name":"vendorCompanyId","in":"query","required":false,"deprecated":true,"schema":{"type":"string"},"description":"Deprecated alias of `vendor`."},{"$ref":"#/components/parameters/AvrixApiVersion"},{"$ref":"#/components/parameters/RequestId"},{"$ref":"#/components/parameters/SandboxSimulateRateLimit"}],"responses":{"200":{"description":"Deals list","headers":{"X-Request-Id":{"$ref":"#/components/headers/XRequestId"},"X-Avrix-Api-Version":{"$ref":"#/components/headers/XAvrixApiVersion"},"X-Api-Version":{"$ref":"#/components/headers/XApiVersion"},"X-RateLimit-Limit":{"$ref":"#/components/headers/XRateLimitLimit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/XRateLimitRemaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/XRateLimitReset"},"X-RateLimit-Bucket":{"$ref":"#/components/headers/XRateLimitBucket"}},"content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/SellerPromotionDeal"}},"meta":{"type":"object","properties":{"limit":{"type":"integer","description":"The page size this response was cut at."},"count":{"type":"integer","description":"Number of items in `data`."},"hasMore":{"type":"boolean","description":"True when another page follows. Loop on `hasMore`; send `nextCursor` back as `cursor`."},"nextCursor":{"type":["string","null"],"description":"Opaque position after the last item of this page; send it back as `cursor`. Null on the last page."},"nextUrl":{"type":["string","null"],"description":"Absolute URL of the next page: this request with `cursor` set to `nextCursor`. Null when there is no next page."}}}}},"example":{"data":[{"id":"cb4baf6a-94ea-40b5-829c-bc3d8d02b590","promotion_id":"3cae451a-f8ae-48cb-8e7e-d8a3542cf9b7","promotion_name":"Autumn sale","vendor_company_id":"acme-games","vendor_company_name":"Acme Games","start_date":"2026-11-02T09:30:00Z","end_date":"2026-11-02T09:30:00Z","response_deadline":"2026-11-02T09:30:00Z","promotion_status":"submitted","response_status":"pending","response_note":"Example text.","responded_at":"2026-11-02T09:30:00Z","product_count":12,"created_at":"2026-11-02T09:30:00Z","updated_at":"2026-11-02T09:30:00Z","respond_by":"2026-11-02T09:30:00Z"}],"meta":{"limit":50,"count":12,"hasMore":true,"nextCursor":"eyJ2IjoyLCJ0IjoiMjAyNi0xMS0wMlQwOTozMDowMFoifQ","nextUrl":"https://api.avrix.io/api/seller/v1/promotions/deals?cursor=eyJ2IjoyLCJ0IjoiMjAyNi0xMS0wMlQwOTozMDowMFoifQ"}}}}},"400":{"$ref":"#/components/responses/SellerApiUnsupportedApiVersion"},"401":{"$ref":"#/components/responses/SellerApiUnauthorized"},"403":{"$ref":"#/components/responses/SellerApiForbidden"},"422":{"$ref":"#/components/responses/SellerApiValidationFailed"},"429":{"$ref":"#/components/responses/SellerApiRateLimited"},"500":{"$ref":"#/components/responses/SellerApiInternalError"},"503":{"$ref":"#/components/responses/SellerApiServiceUnavailable"},"504":{"$ref":"#/components/responses/SellerApiTimeout"}},"security":[{"bearerAuth":[]}],"x-avrix-scopes":["seller:promotions:read"],"x-avrix-tier":"promotions","x-avrix-rate-limit-class":"finance","x-avrix-scope-mode":"anyOf","tags":["Promotions"],"operationId":"listPromotionsDeals"}},"/api/seller/v1/promotions/deals/{responseId}":{"get":{"summary":"Get deal detail","description":"Custom deal detail with products, which price each discount lowers (`price_effect`) and when it must be answered (`respond_by`). Requires seller:promotions:read scope.\n\nAn unknown deal, or one offered to another company, is `404`. A storage failure is `503` or `504` with `Retry-After` on contract date `2026-12-01` and later; earlier dates answer `500` without the database text.","parameters":[{"name":"responseId","in":"path","required":true,"description":"Deal response id.","schema":{"type":"string","format":"uuid"}},{"$ref":"#/components/parameters/AvrixApiVersion"},{"$ref":"#/components/parameters/RequestId"},{"$ref":"#/components/parameters/SandboxSimulateRateLimit"}],"responses":{"200":{"description":"Deal detail with products","headers":{"X-Request-Id":{"$ref":"#/components/headers/XRequestId"},"X-Avrix-Api-Version":{"$ref":"#/components/headers/XAvrixApiVersion"},"X-Api-Version":{"$ref":"#/components/headers/XApiVersion"},"X-RateLimit-Limit":{"$ref":"#/components/headers/XRateLimitLimit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/XRateLimitRemaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/XRateLimitReset"},"X-RateLimit-Bucket":{"$ref":"#/components/headers/XRateLimitBucket"}},"content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/SellerPromotionDealDetail"}}},"example":{"data":{"id":"36cbcf4d-0554-464c-86bc-e90ab4dac017","promotion_id":"600d7b75-f74b-41ff-80bd-7488d120ad6d","promotion_name":"Autumn sale","vendor_company_id":"acme-games","vendor_company_name":"Acme Games","start_date":"2026-11-02T09:30:00Z","end_date":"2026-11-02T09:30:00Z","response_deadline":"2026-11-02T09:30:00Z","promotion_status":"submitted","response_status":"pending","response_note":"Example text.","responded_at":"2026-11-02T09:30:00Z","product_count":12,"created_at":"2026-11-02T09:30:00Z","updated_at":"2026-11-02T09:30:00Z","respond_by":"2026-11-02T09:30:00Z","description":"Example text.","message":"Example text.","products":[{"sku_id":"e65109e5-54e3-4e9f-8fbd-a1fe05123124","sku_code":"EXAMPLE-STEAM-WW","product_id":"ea00be18-eed8-4c66-88bf-cd7a7b48e275","product_name":"Example Game","edition_name":"Standard Edition","platform_code":"steam","platform_name":"Steam","key_type_name":"Steam key","region_name":"Europe","discount_percent":20,"base_price_cents":2450,"currency_code":"base_price_cents","price_effect":"list_price"}]}}}}},"400":{"$ref":"#/components/responses/SellerApiUnsupportedApiVersion"},"401":{"$ref":"#/components/responses/SellerApiUnauthorized"},"403":{"$ref":"#/components/responses/SellerApiForbidden"},"404":{"description":"Deal not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"422":{"$ref":"#/components/responses/SellerApiValidationFailed"},"429":{"$ref":"#/components/responses/SellerApiRateLimited"},"500":{"$ref":"#/components/responses/SellerApiInternalError"},"503":{"$ref":"#/components/responses/SellerApiServiceUnavailable"},"504":{"$ref":"#/components/responses/SellerApiTimeout"}},"security":[{"bearerAuth":[]}],"x-avrix-scopes":["seller:promotions:read"],"x-avrix-tier":"promotions","x-avrix-rate-limit-class":"finance","x-avrix-scope-mode":"anyOf","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. **Retries:** send an `Idempotency-Key` to make a retry safe: the same key and body replay the first answer with `Idempotency-Replayed: true` instead of acting twice. On contract date `2026-12-01` and later a repeat without the key is also safe: the same decision returns 200, a different one 409.","parameters":[{"name":"responseId","in":"path","required":true,"description":"Deal response id.","schema":{"type":"string","format":"uuid"}},{"$ref":"#/components/parameters/IdempotencyKeyOptional"},{"$ref":"#/components/parameters/AvrixApiVersion"},{"$ref":"#/components/parameters/RequestId"},{"$ref":"#/components/parameters/SandboxSimulateWrite"}],"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":"approved"}}}},"responses":{"200":{"description":"Response recorded","headers":{"X-Request-Id":{"$ref":"#/components/headers/XRequestId"},"X-Avrix-Api-Version":{"$ref":"#/components/headers/XAvrixApiVersion"},"X-Api-Version":{"$ref":"#/components/headers/XApiVersion"},"Idempotency-Replayed":{"$ref":"#/components/headers/IdempotencyReplayed"},"X-RateLimit-Limit":{"$ref":"#/components/headers/XRateLimitLimit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/XRateLimitRemaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/XRateLimitReset"},"X-RateLimit-Bucket":{"$ref":"#/components/headers/XRateLimitBucket"}},"content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"responseId":{"type":"string"},"status":{"type":"string","enum":["approved","rejected"],"description":"The deal response's state after this call: the `decision` sent."}}}}},"example":{"data":{"responseId":"7245799e-2856-4ff0-80f9-faf9b4073cc5","status":"approved"}}}}},"400":{"description":"Already responded, withdrawn, started or deadline passed. On contract date `2026-12-01` and later, answering again with the decision the deal already has returns 200 with its state, and every other case here returns 409 with `details.reason`. Also returned for an `X-Avrix-Api-Version` this API does not serve (`UNSUPPORTED_API_VERSION`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"401":{"$ref":"#/components/responses/SellerApiUnauthorized"},"403":{"$ref":"#/components/responses/SellerApiForbidden"},"404":{"description":"`NOT_FOUND`: no deal with this id. On contract date `2026-12-01` and later also for a deal offered to another company (earlier dates answer 400 `Access denied`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"409":{"description":"`IDEMPOTENCY_KEY_MISMATCH`: the `Idempotency-Key` was already used with a different body; use a new key for a new request. `IDEMPOTENCY_REQUEST_IN_FLIGHT`: an earlier request with this key is still running; wait `Retry-After` seconds and send the same request again. On contract date `2026-12-01` and later also `CONFLICT`, with `details.reason`: `RESPONSE_ALREADY_ANSWERED` (a different answer is recorded; `details.currentStatus` names it), `PROMOTION_WITHDRAWN` (the vendor withdrew the deal), `PROMOTION_STARTED` or `RESPONSE_DEADLINE_PASSED` (too late to answer; the deal is now `expired`). Earlier contract dates answer 400 instead.","headers":{"X-Request-Id":{"$ref":"#/components/headers/XRequestId"},"X-Avrix-Api-Version":{"$ref":"#/components/headers/XAvrixApiVersion"},"X-Api-Version":{"$ref":"#/components/headers/XApiVersion"},"Retry-After":{"$ref":"#/components/headers/RetryAfter"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"413":{"$ref":"#/components/responses/SellerApiPayloadTooLarge"},"422":{"$ref":"#/components/responses/SellerApiValidationFailed"},"429":{"$ref":"#/components/responses/SellerApiRateLimited"},"500":{"$ref":"#/components/responses/SellerApiInternalError"},"503":{"$ref":"#/components/responses/SellerApiServiceUnavailable"},"504":{"$ref":"#/components/responses/SellerApiTimeout"}},"security":[{"bearerAuth":[]}],"x-avrix-scopes":["seller:promotions:respond"],"x-avrix-tier":"promotions","x-avrix-rate-limit-class":"finance","x-avrix-scope-mode":"anyOf","tags":["Promotions"],"operationId":"respondDeal"}},"/api/seller/v1/health":{"get":{"summary":"Health check (with sub-component status)","description":"Uptime + per-component status. Auth optional. Returns 503 only when the **db** probe is degraded; otherwise 200. The `components` object reports `db`, `redis`, `qstash`, `webhookDelivery`, `outboxJobs`, `catalogIndex` and `consumerGeo` independently with `status` (`ok` / `degraded` / `unconfigured`), `latencyMs`, and an optional `message` field. The top-level `status` is `degraded` (still HTTP 200, with `degradedReasons`) when a queue is behind, QStash is unconfigured in production, or the deployment has no (or stale) buyer geolocation data (`consumerGeo`). `catalogIndex` never downgrades the top-level status. The legacy `redisConfigured` boolean is preserved for backwards compatibility. Note: Unlike other endpoints, health does not wrap the response in a `data` object.","security":[],"parameters":[{"$ref":"#/components/parameters/RequestId"}],"responses":{"200":{"description":"API is operational","headers":{"X-Request-Id":{"$ref":"#/components/headers/XRequestId"},"X-Avrix-Api-Version":{"$ref":"#/components/headers/XAvrixApiVersion"},"X-Api-Version":{"$ref":"#/components/headers/XApiVersion"}},"content":{"application/json":{"schema":{"type":"object","properties":{"status":{"type":"string","enum":["ok","degraded"],"description":"`degraded` when the database probe fails (HTTP 503) or when a queue is degraded: webhook deliveries or background jobs overdue past their due time or backlogged past threshold, or push delivery not configured in production (HTTP 200, with `degradedReasons`)."},"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"},"webhookDelivery":{"$ref":"#/components/schemas/SellerHealthComponent"},"outboxJobs":{"$ref":"#/components/schemas/SellerHealthComponent"},"consumerGeo":{"$ref":"#/components/schemas/SellerHealthComponent"},"orderPath":{"$ref":"#/components/schemas/SellerHealthComponent"},"sandbox":{"$ref":"#/components/schemas/SellerHealthComponent"},"checkoutHold":{"$ref":"#/components/schemas/SellerHealthComponent"}}},"degradedReasons":{"type":"array","items":{"type":"string"},"description":"Present only when a queue or the buyer geolocation data made `status` degraded: one short sentence per reason."},"backlog":{"type":"object","properties":{"webhookDeliveriesPending":{"type":["integer","null"]},"outboxJobsPending":{"type":["integer","null"]}}}}},"example":{"status":"ok","timestamp":"2026-11-02T09:30:00Z","version":"1","redisConfigured":true,"checkDurationMs":1,"components":{"db":{"status":"ok","latencyMs":1,"message":"Example text.","lastUpdated":"2026-11-02T09:30:00Z","ageSeconds":300,"publisher":true,"receiver":true,"pending":1,"buffered":1,"dueLagSeconds":300,"failedLast24h":1,"oldestPendingAgeSeconds":300},"redis":{"status":"ok","latencyMs":1,"message":"Example text.","lastUpdated":"2026-11-02T09:30:00Z","ageSeconds":300,"publisher":true,"receiver":true,"pending":1,"buffered":1,"dueLagSeconds":300,"failedLast24h":1,"oldestPendingAgeSeconds":300},"qstash":{"status":"ok","latencyMs":1,"message":"Example text.","lastUpdated":"2026-11-02T09:30:00Z","ageSeconds":300,"publisher":true,"receiver":true,"pending":1,"buffered":1,"dueLagSeconds":300,"failedLast24h":1,"oldestPendingAgeSeconds":300},"catalogIndex":{"status":"ok","latencyMs":1,"message":"Example text.","lastUpdated":"2026-11-02T09:30:00Z","ageSeconds":300,"publisher":true,"receiver":true,"pending":1,"buffered":1,"dueLagSeconds":300,"failedLast24h":1,"oldestPendingAgeSeconds":300},"webhookDelivery":{"status":"ok","latencyMs":1,"message":"Example text.","lastUpdated":"2026-11-02T09:30:00Z","ageSeconds":300,"publisher":true,"receiver":true,"pending":1,"buffered":1,"dueLagSeconds":300,"failedLast24h":1,"oldestPendingAgeSeconds":300},"outboxJobs":{"status":"ok","latencyMs":1,"message":"Example text.","lastUpdated":"2026-11-02T09:30:00Z","ageSeconds":300,"publisher":true,"receiver":true,"pending":1,"buffered":1,"dueLagSeconds":300,"failedLast24h":1,"oldestPendingAgeSeconds":300},"consumerGeo":{"status":"ok","latencyMs":1,"message":"Example text.","lastUpdated":"2026-11-02T09:30:00Z","ageSeconds":300,"publisher":true,"receiver":true,"pending":1,"buffered":1,"dueLagSeconds":300,"failedLast24h":1,"oldestPendingAgeSeconds":300},"orderPath":{"status":"ok","latencyMs":1,"message":"Example text.","lastUpdated":"2026-11-02T09:30:00Z","ageSeconds":300,"publisher":true,"receiver":true,"pending":1,"buffered":1,"dueLagSeconds":300,"failedLast24h":1,"oldestPendingAgeSeconds":300},"sandbox":{"status":"ok","latencyMs":1,"message":"Example text.","lastUpdated":"2026-11-02T09:30:00Z","ageSeconds":300,"publisher":true,"receiver":true,"pending":1,"buffered":1,"dueLagSeconds":300,"failedLast24h":1,"oldestPendingAgeSeconds":300},"checkoutHold":{"status":"ok","latencyMs":1,"message":"Example text.","lastUpdated":"2026-11-02T09:30:00Z","ageSeconds":300,"publisher":true,"receiver":true,"pending":1,"buffered":1,"dueLagSeconds":300,"failedLast24h":1,"oldestPendingAgeSeconds":300}},"backlog":{"webhookDeliveriesPending":1,"outboxJobsPending":1}}}}},"401":{"description":"Not returned by this operation: it reads no API key. The entry is kept so that clients generated from earlier versions of this document keep their error types.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"403":{"description":"Not returned by this operation: it reads no API key. The entry is kept so that clients generated from earlier versions of this document keep their error types.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"429":{"description":"Not returned by this operation: it is not rate limited. The entry is kept so that clients generated from earlier versions of this document keep their error types.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}},"headers":{"X-RateLimit-Limit":{"description":"Not sent by this operation: it is not rate limited. The entry is kept so that clients generated from earlier versions of this document keep their header types.","required":false,"schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Not sent by this operation: it is not rate limited. The entry is kept so that clients generated from earlier versions of this document keep their header types.","required":false,"schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"Not sent by this operation: it is not rate limited. The entry is kept so that clients generated from earlier versions of this document keep their header types.","required":false,"schema":{"type":"integer","format":"int64"}}}},"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","x-avrix-rate-limit-class":"none","x-avrix-scope-mode":"public","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.","parameters":[{"$ref":"#/components/parameters/AvrixApiVersion"},{"$ref":"#/components/parameters/RequestId"},{"$ref":"#/components/parameters/SandboxSimulateRateLimit"}],"responses":{"200":{"description":"Webhook event type catalog","headers":{"X-Request-Id":{"$ref":"#/components/headers/XRequestId"},"X-Avrix-Api-Version":{"$ref":"#/components/headers/XAvrixApiVersion"},"X-Api-Version":{"$ref":"#/components/headers/XApiVersion"},"X-RateLimit-Limit":{"$ref":"#/components/headers/XRateLimitLimit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/XRateLimitRemaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/XRateLimitReset"},"X-RateLimit-Bucket":{"$ref":"#/components/headers/XRateLimitBucket"}},"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.backorder_expired","order.preorder_fulfilled","order.returned","order.cancelled","order.keys_returned","refund.completed","chargeback.opened","chargeback.resolved","redemption.expiring","redemption.expired","fulfillment.revoked","catalog.export_ready","keys.pulled","key.replaced","key.replacement_rejected","keys.revoked","key.frozen","key.unfrozen","allocation.updated","allocation.depleted","allocation.low_stock","allocation.running_low","allocation.replenished","allocation.request_decided","allocation.request_cancelled","product.added","product.updated","product.announced","product.delisted","product.delisting_scheduled","release.available","release.date_changed","sku.pricing_updated","sku.sellability_changed","promotion.offered","promotion.changed","promotion.accepted","promotion.declined","promotion.withdrawn","promotion.expired","promotion.started","promotion.ended","contract.activated","contract.superseded","contract.amendment_accepted","contract.expiring","contract.expired","contract.terminated","connection.suspended","connection.reactivated","connection.ended","connection.request_decided","access.proposal_created","return.decided","return.information_requested","invoice.created","invoice.issued","invoice.paid","invoice.overdue","invoice.disputed","invoice.dispute_updated","report.ready","payout.file_ready","system.webhook_endpoint_disabled","system.webhook_endpoint_failing","system.webhook_endpoint_recovered","platform.notice","api_key.created","api_key.rotated","api_key.revoked","api_key.expiring","api_key.expired","sandbox.certification_passed"]},"description":{"type":"string"},"category":{"type":"string","description":"The event's family, the part before the dot. Subscribe to the whole family with `<category>.*`."},"schemaRef":{"type":"string","description":"JSON Pointer to the event's payload schema in this OpenAPI document (`#/webhooks/<name with dots as underscores>`)."}}}}}},"example":{"data":[{"name":"test.ping","description":"Example text."}]}}}},"400":{"$ref":"#/components/responses/SellerApiUnsupportedApiVersion"},"401":{"$ref":"#/components/responses/SellerApiUnauthorized"},"403":{"$ref":"#/components/responses/SellerApiForbidden"},"422":{"$ref":"#/components/responses/SellerApiValidationFailed"},"429":{"$ref":"#/components/responses/SellerApiRateLimited"},"500":{"$ref":"#/components/responses/SellerApiInternalError"},"503":{"$ref":"#/components/responses/SellerApiServiceUnavailable"},"504":{"$ref":"#/components/responses/SellerApiTimeout"}},"security":[{"bearerAuth":[]}],"x-avrix-scopes":["seller:webhooks:read"],"x-avrix-tier":"webhooks","x-avrix-rate-limit-class":"webhooks-mgmt","x-avrix-scope-mode":"anyOf","tags":["Webhooks"],"operationId":"listWebhooksEventTypes"}},"/api/seller/v1/webhooks":{"get":{"summary":"List webhook endpoints","description":"List registered webhook endpoints for your company.\n\n**Paging:** the shared list contract, see `https://docs.avrix.io/seller-api/pagination`. On contract date `2026-12-01` and later a `cursor` this API did not return is refused with `422 VALIDATION_FAILED` (`details.issues[].field` is `cursor`); earlier dates serve the first page.","responses":{"200":{"description":"Webhook endpoints list","headers":{"X-Request-Id":{"$ref":"#/components/headers/XRequestId"},"X-Avrix-Api-Version":{"$ref":"#/components/headers/XAvrixApiVersion"},"X-Api-Version":{"$ref":"#/components/headers/XApiVersion"},"X-RateLimit-Limit":{"$ref":"#/components/headers/XRateLimitLimit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/XRateLimitRemaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/XRateLimitReset"},"X-RateLimit-Bucket":{"$ref":"#/components/headers/XRateLimitBucket"}},"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)."},"consecutiveFailures":{"type":"integer","description":"Deliveries in a row that exhausted their retries (terminal failures). Reset by a successful delivery. The endpoint is disabled when it reaches the platform threshold."},"disabledReason":{"type":["string","null"],"description":"Why the endpoint is disabled (for example `consecutive_failures`), or null while it is active."},"updatedAt":{"type":["string","null"],"format":"date-time","description":"When the endpoint was last changed."},"failing":{"type":"boolean","description":"True while deliveries to this active endpoint keep failing: at least 3 failed attempts in a row over at least 10 minutes. The endpoint stays active and retries continue; this is the early warning, well before the circuit breaker disables it (see `consecutiveFailures`). `system.webhook_endpoint_failing` is sent when it turns true, `system.webhook_endpoint_recovered` when a delivery succeeds again. Always false for a disabled endpoint."},"failingSince":{"type":["string","null"],"format":"date-time","description":"When the endpoint turned `failing`; null while it is not."},"lastSuccessAt":{"type":["string","null"],"format":"date-time","description":"The last delivery attempt your endpoint answered with 2xx."},"lastFailureAt":{"type":["string","null"],"format":"date-time","description":"The last delivery attempt that failed (non-2xx, timeout or connection error)."},"consecutiveFailedAttempts":{"type":"integer","description":"Failed attempts in a row, counting every retry. `consecutiveFailures` counts only deliveries that used up all their retries."},"pendingDeliveries":{"type":"integer","description":"Deliveries waiting to be sent or retried (buffered deliveries of a disabled endpoint are in `bufferedDeliveries`)."}}}},"meta":{"type":"object","properties":{"limit":{"type":"integer"},"count":{"type":"integer"},"nextCursor":{"type":["string","null"]},"nextUrl":{"type":["string","null"]},"hasMore":{"type":"boolean","description":"True when another page follows. Loop on `hasMore`; send `nextCursor` back as `cursor`."}}}}},"example":{"data":[{"id":"c06fad5d-e496-48e3-8405-537a2b458aef","url":"https://store.example.com/webhooks/avrix","events":["order.fulfilled"],"status":"active","createdAt":"2026-11-02T09:30:00Z","bufferedDeliveries":1,"bufferCapacity":12}],"meta":{"limit":50,"count":12,"nextCursor":"eyJ2IjoyLCJ0IjoiMjAyNi0xMS0wMlQwOTozMDowMFoifQ","nextUrl":"https://api.avrix.io/api/seller/v1/webhooks?cursor=eyJ2IjoyLCJ0IjoiMjAyNi0xMS0wMlQwOTozMDowMFoifQ","hasMore":true}}}}},"400":{"$ref":"#/components/responses/SellerApiUnsupportedApiVersion"},"401":{"$ref":"#/components/responses/SellerApiUnauthorized"},"403":{"$ref":"#/components/responses/SellerApiForbidden"},"422":{"$ref":"#/components/responses/SellerApiValidationFailed"},"429":{"$ref":"#/components/responses/SellerApiRateLimited"},"500":{"$ref":"#/components/responses/SellerApiInternalError"},"503":{"$ref":"#/components/responses/SellerApiServiceUnavailable"},"504":{"$ref":"#/components/responses/SellerApiTimeout"}},"security":[{"bearerAuth":[]}],"x-avrix-scopes":["seller:webhooks:read"],"x-avrix-tier":"webhooks","x-avrix-rate-limit-class":"webhooks-mgmt","x-avrix-scope-mode":"anyOf","tags":["Webhooks"],"operationId":"listWebhooks","parameters":[{"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 cursor from `meta.nextCursor` of the previous page."},{"$ref":"#/components/parameters/AvrixApiVersion"},{"$ref":"#/components/parameters/RequestId"},{"$ref":"#/components/parameters/SandboxSimulateRateLimit"}]},"post":{"summary":"Create webhook endpoint","description":"Register a webhook endpoint. Returns the signing secret ONCE - store it securely.\n\n**Limit:** on contract date `2026-12-01` and later a company registers at most 16 endpoints (active and disabled; for a sandbox key, per key). The seventeenth answers **409** `WEBHOOK_ENDPOINT_LIMIT_REACHED` with `details.limit` and `details.current`. Endpoints that already exist above the limit keep working, and earlier dates have no limit. One endpoint can take many events: use wildcards (`*`, `order.*`).","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["url","events"],"properties":{"url":{"type":"string","format":"uri"},"events":{"description":"Event names to deliver to this endpoint. Besides each event name, `*` subscribes to every event (including ones added later) and `<family>.*` (for example `order.*`) to every event of one family. A wildcard never delivers an event twice; an older alias name (`order.returned`) is delivered only to endpoints that name it.","type":"array","items":{"type":"string","enum":["test.ping","order.fulfilled","order.failed","order.activated","order.reserved","order.ready","order.backorder_expired","order.preorder_fulfilled","order.returned","order.cancelled","order.keys_returned","refund.completed","chargeback.opened","chargeback.resolved","redemption.expiring","redemption.expired","fulfillment.revoked","catalog.export_ready","keys.pulled","key.replaced","key.replacement_rejected","keys.revoked","key.frozen","key.unfrozen","allocation.updated","allocation.depleted","allocation.low_stock","allocation.running_low","allocation.replenished","allocation.request_decided","allocation.request_cancelled","product.added","product.updated","product.announced","product.delisted","product.delisting_scheduled","release.available","release.date_changed","sku.pricing_updated","sku.sellability_changed","promotion.offered","promotion.changed","promotion.accepted","promotion.declined","promotion.withdrawn","promotion.expired","promotion.started","promotion.ended","contract.activated","contract.superseded","contract.amendment_accepted","contract.expiring","contract.expired","contract.terminated","connection.suspended","connection.reactivated","connection.ended","connection.request_decided","access.proposal_created","return.decided","return.information_requested","invoice.created","invoice.issued","invoice.paid","invoice.overdue","invoice.disputed","invoice.dispute_updated","report.ready","payout.file_ready","system.webhook_endpoint_disabled","system.webhook_endpoint_failing","system.webhook_endpoint_recovered","platform.notice","api_key.created","api_key.rotated","api_key.revoked","api_key.expiring","api_key.expired","sandbox.certification_passed","*","order.*","refund.*","chargeback.*","redemption.*","fulfillment.*","catalog.*","keys.*","key.*","allocation.*","product.*","release.*","sku.*","promotion.*","contract.*","connection.*","access.*","return.*","invoice.*","report.*","payout.*","system.*","platform.*","api_key.*","sandbox.*"]}}}},"example":{"url":"https://merchant.example/webhooks/avrix","events":["order.fulfilled","order.failed","test.ping"]}}}},"responses":{"201":{"description":"Webhook created","headers":{"X-Request-Id":{"$ref":"#/components/headers/XRequestId"},"X-Avrix-Api-Version":{"$ref":"#/components/headers/XAvrixApiVersion"},"X-Api-Version":{"$ref":"#/components/headers/XApiVersion"},"Idempotency-Replayed":{"$ref":"#/components/headers/IdempotencyReplayed"},"X-RateLimit-Limit":{"$ref":"#/components/headers/XRateLimitLimit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/XRateLimitRemaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/XRateLimitReset"},"X-RateLimit-Bucket":{"$ref":"#/components/headers/XRateLimitBucket"}},"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"},"deliveryProbe":{"type":"object","description":"Best-effort reachability check of the URL at registration. It never blocks creation; a failed probe says what to fix before the first delivery.","properties":{"reachable":{"type":"boolean"},"statusCode":{"type":["integer","null"],"description":"HTTP status your endpoint answered, when it answered."},"error":{"type":["string","null"]}}},"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)."},"consecutiveFailures":{"type":"integer","description":"Deliveries in a row that exhausted their retries (terminal failures). Reset by a successful delivery. The endpoint is disabled when it reaches the platform threshold."},"disabledReason":{"type":["string","null"],"description":"Why the endpoint is disabled (for example `consecutive_failures`), or null while it is active."},"updatedAt":{"type":["string","null"],"format":"date-time","description":"When the endpoint was last changed."},"failing":{"type":"boolean","description":"True while deliveries to this active endpoint keep failing: at least 3 failed attempts in a row over at least 10 minutes. The endpoint stays active and retries continue; this is the early warning, well before the circuit breaker disables it (see `consecutiveFailures`). `system.webhook_endpoint_failing` is sent when it turns true, `system.webhook_endpoint_recovered` when a delivery succeeds again. Always false for a disabled endpoint."},"failingSince":{"type":["string","null"],"format":"date-time","description":"When the endpoint turned `failing`; null while it is not."},"lastSuccessAt":{"type":["string","null"],"format":"date-time","description":"The last delivery attempt your endpoint answered with 2xx."},"lastFailureAt":{"type":["string","null"],"format":"date-time","description":"The last delivery attempt that failed (non-2xx, timeout or connection error)."},"consecutiveFailedAttempts":{"type":"integer","description":"Failed attempts in a row, counting every retry. `consecutiveFailures` counts only deliveries that used up all their retries."},"pendingDeliveries":{"type":"integer","description":"Deliveries waiting to be sent or retried (buffered deliveries of a disabled endpoint are in `bufferedDeliveries`)."}}}}},"example":{"data":{"id":"002873e6-76ce-45cc-8caf-b522a28632df","url":"https://store.example.com/webhooks/avrix","events":["order.fulfilled"],"secret":"whsec_8f2c1d0e9b7a6c5d4e3f2a1b0c9d8e7f","deliveryProbe":{"reachable":true,"statusCode":200}}}}}},"400":{"$ref":"#/components/responses/SellerApiIdempotencyKeyRequired"},"401":{"$ref":"#/components/responses/SellerApiUnauthorized"},"403":{"$ref":"#/components/responses/SellerApiForbidden"},"409":{"description":"`NO_ACTIVE_BMA`: a webhook endpoint can be registered only once your company has at least one active agreement with a vendor. Nothing was created; register the endpoint after the first agreement is active. Also returned for the `Idempotency-Key` itself: `IDEMPOTENCY_KEY_MISMATCH` (the key was already used with a different body) and `IDEMPOTENCY_REQUEST_IN_FLIGHT` (an earlier request with this key is still running; retry after `Retry-After` seconds). On contract date `2026-12-01` and later also `WEBHOOK_ENDPOINT_LIMIT_REACHED`: the company already has 16 endpoints (`details.limit`, `details.current`).","headers":{"X-Request-Id":{"$ref":"#/components/headers/XRequestId"},"X-Avrix-Api-Version":{"$ref":"#/components/headers/XAvrixApiVersion"},"X-Api-Version":{"$ref":"#/components/headers/XApiVersion"},"Retry-After":{"$ref":"#/components/headers/RetryAfter"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"413":{"$ref":"#/components/responses/SellerApiPayloadTooLarge"},"422":{"$ref":"#/components/responses/SellerApiValidationFailed"},"429":{"$ref":"#/components/responses/SellerApiRateLimited"},"500":{"$ref":"#/components/responses/SellerApiInternalError"},"503":{"$ref":"#/components/responses/SellerApiServiceUnavailable"},"504":{"$ref":"#/components/responses/SellerApiTimeout"}},"security":[{"bearerAuth":[]}],"x-avrix-scopes":["seller:webhooks:write"],"x-avrix-tier":"webhooks","x-avrix-rate-limit-class":"webhooks-mgmt","x-avrix-scope-mode":"anyOf","tags":["Webhooks"],"operationId":"createWebhook","parameters":[{"$ref":"#/components/parameters/IdempotencyKey"},{"$ref":"#/components/parameters/AvrixApiVersion"},{"$ref":"#/components/parameters/RequestId"},{"$ref":"#/components/parameters/SandboxSimulateWrite"}]}},"/api/seller/v1/webhooks/{id}":{"get":{"summary":"Get webhook endpoint","description":"One webhook endpoint, in the shape `GET /webhooks` lists it: its subscription, status, delivery health (`failing`, `lastSuccessAt`, `lastFailureAt`, `consecutiveFailedAttempts`) and queue (`pendingDeliveries`, `bufferedDeliveries`). The signing secret is never returned.","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","format":"uuid"},"description":"Webhook endpoint ID"},{"$ref":"#/components/parameters/AvrixApiVersion"},{"$ref":"#/components/parameters/RequestId"},{"$ref":"#/components/parameters/SandboxSimulateRateLimit"}],"responses":{"200":{"description":"The endpoint","headers":{"X-Request-Id":{"$ref":"#/components/headers/XRequestId"},"X-Avrix-Api-Version":{"$ref":"#/components/headers/XAvrixApiVersion"},"X-Api-Version":{"$ref":"#/components/headers/XApiVersion"},"X-RateLimit-Limit":{"$ref":"#/components/headers/XRateLimitLimit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/XRateLimitRemaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/XRateLimitReset"},"X-RateLimit-Bucket":{"$ref":"#/components/headers/XRateLimitBucket"}},"content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/WebhookEndpoint"}}},"example":{"data":{"id":"e3856f36-ce7e-4d8b-81fa-a50411164874","url":"https://store.example.com/webhooks/avrix","events":["order.fulfilled"],"status":"active","createdAt":"2026-11-02T09:30:00Z","bufferedDeliveries":1,"bufferCapacity":12,"updatedAt":"2026-11-02T09:30:00Z","failing":false,"failingSince":"2026-11-02T09:30:00Z","lastSuccessAt":"2026-11-02T09:30:00Z","consecutiveFailedAttempts":1,"pendingDeliveries":1}}}}},"400":{"description":"`UNSUPPORTED_API_VERSION`: the `X-Avrix-Api-Version` sent is not one this API serves.","headers":{"X-Request-Id":{"$ref":"#/components/headers/XRequestId"},"X-Avrix-Api-Version":{"$ref":"#/components/headers/XAvrixApiVersion"},"X-Api-Version":{"$ref":"#/components/headers/XApiVersion"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"401":{"$ref":"#/components/responses/SellerApiUnauthorized"},"403":{"$ref":"#/components/responses/SellerApiForbidden"},"404":{"description":"`NOT_FOUND`: no webhook endpoint with this id belongs to your company (for a sandbox key: to this key).","headers":{"X-Request-Id":{"$ref":"#/components/headers/XRequestId"},"X-Avrix-Api-Version":{"$ref":"#/components/headers/XAvrixApiVersion"},"X-Api-Version":{"$ref":"#/components/headers/XApiVersion"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"422":{"$ref":"#/components/responses/SellerApiValidationFailed"},"429":{"$ref":"#/components/responses/SellerApiRateLimited"},"500":{"$ref":"#/components/responses/SellerApiInternalError"},"503":{"$ref":"#/components/responses/SellerApiServiceUnavailable"},"504":{"$ref":"#/components/responses/SellerApiTimeout"}},"security":[{"bearerAuth":[]}],"x-avrix-scopes":["seller:webhooks:read"],"x-avrix-tier":"webhooks","x-avrix-rate-limit-class":"webhooks-mgmt","x-avrix-scope-mode":"anyOf","tags":["Webhooks"],"operationId":"getWebhook"},"patch":{"summary":"Update webhook endpoint","description":"Update URL and/or events, or rotate the signing secret (`rotateSecret: true`). **Retries:** send an `Idempotency-Key` to make a retry safe: the same key and body replay the first answer with `Idempotency-Replayed: true` instead of acting twice. A retried rotation with the same key does not rotate again: it answers with the secret the first call minted.","parameters":[{"name":"id","in":"path","required":true,"description":"Webhook endpoint id (`id` from `GET /webhooks`).","schema":{"type":"string","format":"uuid"}},{"$ref":"#/components/parameters/IdempotencyKeyOptional"},{"$ref":"#/components/parameters/AvrixApiVersion"},{"$ref":"#/components/parameters/RequestId"},{"$ref":"#/components/parameters/SandboxSimulateWrite"}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"url":{"type":"string","format":"uri"},"events":{"description":"Replaces the subscription. Accepts the same event names and wildcards (`*`, `<family>.*`) as `POST /webhooks`.","type":"array","items":{"type":"string"}},"rotateSecret":{"type":"boolean"}}},"example":{"events":["order.fulfilled","order.failed","order.reserved","test.ping"]}}}},"responses":{"200":{"description":"Updated","headers":{"X-Request-Id":{"$ref":"#/components/headers/XRequestId"},"X-Avrix-Api-Version":{"$ref":"#/components/headers/XAvrixApiVersion"},"X-Api-Version":{"$ref":"#/components/headers/XApiVersion"},"Idempotency-Replayed":{"$ref":"#/components/headers/IdempotencyReplayed"},"X-RateLimit-Limit":{"$ref":"#/components/headers/XRateLimitLimit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/XRateLimitRemaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/XRateLimitReset"},"X-RateLimit-Bucket":{"$ref":"#/components/headers/XRateLimitBucket"}},"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. On a replay (same `Idempotency-Key`) it is the secret the first call minted, while that is still the endpoint's secret."},"previousSecretExpiresAt":{"type":"string","format":"date-time","description":"Present only when rotateSecret was true: until when deliveries are also signed with the replaced secret."},"secretRedacted":{"type":"boolean","description":"Present (`true`) only on a replayed rotation when the endpoint has been rotated again since: the secret that call minted is no longer in use and is not shown. `secret` is absent."},"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)."},"consecutiveFailures":{"type":"integer","description":"Deliveries in a row that exhausted their retries (terminal failures). Reset by a successful delivery. The endpoint is disabled when it reaches the platform threshold."},"disabledReason":{"type":["string","null"],"description":"Why the endpoint is disabled (for example `consecutive_failures`), or null while it is active."},"updatedAt":{"type":["string","null"],"format":"date-time","description":"When the endpoint was last changed."},"failing":{"type":"boolean","description":"True while deliveries to this active endpoint keep failing: at least 3 failed attempts in a row over at least 10 minutes. The endpoint stays active and retries continue; this is the early warning, well before the circuit breaker disables it (see `consecutiveFailures`). `system.webhook_endpoint_failing` is sent when it turns true, `system.webhook_endpoint_recovered` when a delivery succeeds again. Always false for a disabled endpoint."},"failingSince":{"type":["string","null"],"format":"date-time","description":"When the endpoint turned `failing`; null while it is not."},"lastSuccessAt":{"type":["string","null"],"format":"date-time","description":"The last delivery attempt your endpoint answered with 2xx."},"lastFailureAt":{"type":["string","null"],"format":"date-time","description":"The last delivery attempt that failed (non-2xx, timeout or connection error)."},"consecutiveFailedAttempts":{"type":"integer","description":"Failed attempts in a row, counting every retry. `consecutiveFailures` counts only deliveries that used up all their retries."},"pendingDeliveries":{"type":"integer","description":"Deliveries waiting to be sent or retried (buffered deliveries of a disabled endpoint are in `bufferedDeliveries`)."}}}}},"example":{"data":{"id":"8267ba06-36b3-480e-81a2-c171876c7ed5","url":"https://store.example.com/webhooks/avrix","events":["order.fulfilled"],"secretRedacted":true}}}}},"400":{"description":"`BAD_REQUEST`: the update was refused: no change was sent, the URL is empty or refused, or the event list is empty; `message` says which. Also returned for an `X-Avrix-Api-Version` this API does not serve (`UNSUPPORTED_API_VERSION`).","headers":{"X-Request-Id":{"$ref":"#/components/headers/XRequestId"},"X-Avrix-Api-Version":{"$ref":"#/components/headers/XAvrixApiVersion"},"X-Api-Version":{"$ref":"#/components/headers/XApiVersion"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"401":{"$ref":"#/components/responses/SellerApiUnauthorized"},"403":{"$ref":"#/components/responses/SellerApiForbidden"},"404":{"description":"`NOT_FOUND`: no webhook endpoint with this id belongs to your company (for a sandbox key: to this key).","headers":{"X-Request-Id":{"$ref":"#/components/headers/XRequestId"},"X-Avrix-Api-Version":{"$ref":"#/components/headers/XAvrixApiVersion"},"X-Api-Version":{"$ref":"#/components/headers/XApiVersion"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"409":{"$ref":"#/components/responses/SellerApiIdempotencyConflict"},"413":{"$ref":"#/components/responses/SellerApiPayloadTooLarge"},"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"},"503":{"$ref":"#/components/responses/SellerApiServiceUnavailable"},"504":{"$ref":"#/components/responses/SellerApiTimeout"}},"security":[{"bearerAuth":[]}],"x-avrix-scopes":["seller:webhooks:write"],"x-avrix-tier":"webhooks","x-avrix-rate-limit-class":"webhooks-mgmt","x-avrix-scope-mode":"anyOf","tags":["Webhooks"],"operationId":"updateWebhook"},"delete":{"summary":"Delete webhook endpoint","description":"Remove a webhook endpoint. Stops sending events.","parameters":[{"name":"id","in":"path","required":true,"description":"Webhook endpoint id (`id` from `GET /webhooks`).","schema":{"type":"string","format":"uuid"}},{"$ref":"#/components/parameters/AvrixApiVersion"},{"$ref":"#/components/parameters/RequestId"},{"$ref":"#/components/parameters/SandboxSimulateWrite"}],"responses":{"204":{"description":"Webhook deleted. The endpoint stops receiving and leaves the listing; its delivery history stays readable on GET /events and GET /webhooks/{id}/deliveries (meta.endpointDeleted).","headers":{"X-Request-Id":{"$ref":"#/components/headers/XRequestId"},"X-Avrix-Api-Version":{"$ref":"#/components/headers/XAvrixApiVersion"},"X-Api-Version":{"$ref":"#/components/headers/XApiVersion"},"X-RateLimit-Limit":{"$ref":"#/components/headers/XRateLimitLimit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/XRateLimitRemaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/XRateLimitReset"},"X-RateLimit-Bucket":{"$ref":"#/components/headers/XRateLimitBucket"}}},"400":{"$ref":"#/components/responses/SellerApiUnsupportedApiVersion"},"401":{"$ref":"#/components/responses/SellerApiUnauthorized"},"403":{"$ref":"#/components/responses/SellerApiForbidden"},"404":{"description":"`NOT_FOUND`: no webhook endpoint with this id belongs to your company (for a sandbox key: to this key).","headers":{"X-Request-Id":{"$ref":"#/components/headers/XRequestId"},"X-Avrix-Api-Version":{"$ref":"#/components/headers/XAvrixApiVersion"},"X-Api-Version":{"$ref":"#/components/headers/XApiVersion"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"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"},"503":{"$ref":"#/components/responses/SellerApiServiceUnavailable"},"504":{"$ref":"#/components/responses/SellerApiTimeout"}},"security":[{"bearerAuth":[]}],"x-avrix-scopes":["seller:webhooks:write"],"x-avrix-tier":"webhooks","x-avrix-rate-limit-class":"webhooks-mgmt","x-avrix-scope-mode":"anyOf","tags":["Webhooks"],"operationId":"deleteWebhook"}},"/api/seller/v1/webhooks/{id}/test":{"post":{"summary":"Send test webhook","description":"Queues a signed test delivery to the endpoint and delivers it through the normal signing and delivery pipeline. With no body (or `{}`) it sends `test.ping`, which verifies the URL and HMAC handling.\n\n**Sandbox keys** can also send any Seller API event type (`eventType`) with a contract-valid sample payload, and turn the delivery into a receiver challenge (`challenge`): mis-signed, ten minutes stale, delivered twice with one `eventId`, or signed with the previous secret only. Every such delivery carries a top-level `testEvent` object (`testRunId`, `challenge`) so your handler can tell it from real traffic. The certification report (`GET /sandbox/certification`) reads the outcomes.\n\n**Production keys** can send `test.ping` only; a different `eventType` or any `challenge` answers **422** `SANDBOX_KEY_REQUIRED`. An unknown `eventType` answers **422** `VALIDATION_FAILED`.\n\nThe body is strict: unknown fields answer **422** `VALIDATION_FAILED`. `X-Avrix-Sandbox-Simulate: webhook_delay_30s` delays the first attempt by 30 seconds on sandbox keys.\n\n**Disabled endpoints:** on contract date `2026-12-01` and later a test send to a disabled endpoint (paused, or disabled by the circuit breaker) is sent once, so you can check a fix before re-enabling. It does not re-enable the endpoint, is not retried, and does not count toward the endpoint's health. Earlier dates answer **400** `BAD_REQUEST` (\"Webhook endpoint is not active\").","parameters":[{"name":"id","in":"path","required":true,"description":"Webhook endpoint id (`id` from `GET /webhooks`).","schema":{"type":"string","format":"uuid"}},{"$ref":"#/components/parameters/AvrixApiVersion"},{"$ref":"#/components/parameters/RequestId"},{"$ref":"#/components/parameters/SandboxSimulate"}],"requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"properties":{"eventType":{"type":"string","enum":["test.ping","order.fulfilled","order.failed","order.activated","order.reserved","order.ready","order.backorder_expired","order.preorder_fulfilled","order.returned","order.cancelled","order.keys_returned","refund.completed","chargeback.opened","chargeback.resolved","redemption.expiring","redemption.expired","fulfillment.revoked","catalog.export_ready","keys.pulled","key.replaced","key.replacement_rejected","keys.revoked","key.frozen","key.unfrozen","allocation.updated","allocation.depleted","allocation.low_stock","allocation.running_low","allocation.replenished","allocation.request_decided","allocation.request_cancelled","product.added","product.updated","product.announced","product.delisted","product.delisting_scheduled","release.available","release.date_changed","sku.pricing_updated","sku.sellability_changed","promotion.offered","promotion.changed","promotion.accepted","promotion.declined","promotion.withdrawn","promotion.expired","promotion.started","promotion.ended","contract.activated","contract.superseded","contract.amendment_accepted","contract.expiring","contract.expired","contract.terminated","connection.suspended","connection.reactivated","connection.ended","connection.request_decided","access.proposal_created","return.decided","return.information_requested","invoice.created","invoice.issued","invoice.paid","invoice.overdue","invoice.disputed","invoice.dispute_updated","report.ready","payout.file_ready","system.webhook_endpoint_disabled","system.webhook_endpoint_failing","system.webhook_endpoint_recovered","platform.notice","api_key.created","api_key.rotated","api_key.revoked","api_key.expiring","api_key.expired","sandbox.certification_passed"],"default":"test.ping","description":"Event to send. Defaults to `test.ping`. Any other value requires a sandbox key."},"challenge":{"$ref":"#/components/schemas/WebhookTestChallenge"}}},"examples":{"ping":{"summary":"test.ping (any key)","value":{}},"event":{"summary":"A sample order.fulfilled (sandbox key)","value":{"eventType":"order.fulfilled"}},"invalidSignature":{"summary":"Receiver challenge: mis-signed delivery (sandbox key)","value":{"eventType":"order.fulfilled","challenge":"invalid_signature"}}}}}},"responses":{"202":{"description":"Test delivery queued","headers":{"X-Request-Id":{"$ref":"#/components/headers/XRequestId"},"X-Avrix-Api-Version":{"$ref":"#/components/headers/XAvrixApiVersion"},"X-Api-Version":{"$ref":"#/components/headers/XApiVersion"},"X-RateLimit-Limit":{"$ref":"#/components/headers/XRateLimitLimit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/XRateLimitRemaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/XRateLimitReset"},"X-RateLimit-Bucket":{"$ref":"#/components/headers/XRateLimitBucket"}},"content":{"application/json":{"schema":{"type":"object","required":["data"],"properties":{"data":{"type":"object","required":["deliveryId","deliveryIds","eventId","eventType","challenge","testRunId","message"],"properties":{"deliveryId":{"type":"string","description":"Id of the queued delivery row (the first of `deliveryIds`)."},"deliveryIds":{"type":"array","items":{"type":"string"},"description":"Every delivery row queued by this call. Follow them on `GET /webhooks/{id}/deliveries`. A `duplicate` challenge is one delivery row that is sent twice with the same `eventId`."},"eventId":{"type":"string","description":"`eventId` the delivery carries (also the `X-Avrix-Event-Id` header)."},"eventType":{"type":"string","description":"Event type that was queued (`test.ping` when the body named none)."},"challenge":{"anyOf":[{"$ref":"#/components/schemas/WebhookTestChallenge"},{"type":"null"}],"description":"Receiver challenge of this delivery, or null."},"testRunId":{"type":"string","description":"Id of this test-fire call; repeated in the delivery's `testEvent.testRunId`."},"message":{"type":"string"}}}}},"example":{"data":{"deliveryId":"8d4e2b1a-6c3f-4a5e-9b7d-1f2e3c4d5a6b","deliveryIds":["8d4e2b1a-6c3f-4a5e-9b7d-1f2e3c4d5a6b"],"eventId":"evt_1760256600000_3c1d9a7b2e4f6a80","eventType":"order.fulfilled","challenge":"invalid_signature","testRunId":"4b8e1f2a-9c3d-4e5f-8a6b-7c9d0e1f2a3b","message":"Test delivery queued. Check GET .../webhooks/:id/deliveries for status."}}}}},"400":{"description":"The endpoint cannot receive a test delivery: on dates before `2026-12-01`, it is not active. Also returned for an `X-Avrix-Api-Version` this API does not serve (`UNSUPPORTED_API_VERSION`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"401":{"$ref":"#/components/responses/SellerApiUnauthorized"},"403":{"$ref":"#/components/responses/SellerApiForbidden"},"404":{"description":"No endpoint with this id belongs to the calling key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"422":{"description":"`VALIDATION_FAILED` for an invalid path id, malformed JSON, an unknown field or an unknown `eventType`; `SANDBOX_KEY_REQUIRED` when a production key sends an `eventType` other than `test.ping` or a `challenge`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"examples":{"VALIDATION_FAILED":{"value":{"code":"VALIDATION_FAILED","message":"Unknown webhook event type: order.unknown","error":"Unknown webhook event type: order.unknown","timestamp":"2026-10-12T09:30:00.000Z","recoverable":true,"doc_url":"https://docs.avrix.io/seller-api/errors#validation-failed","requestId":"req_av1203_example","details":{"field":"eventType"}}},"SANDBOX_KEY_REQUIRED":{"value":{"code":"SANDBOX_KEY_REQUIRED","message":"Production keys can only send test.ping. Fire other event types and receiver challenges with a sandbox key.","error":"Production keys can only send test.ping. Fire other event types and receiver challenges with a sandbox key.","timestamp":"2026-10-12T09:30:00.000Z","recoverable":false,"doc_url":"https://docs.avrix.io/seller-api/errors#sandbox-key-required","requestId":"req_av1203_example","details":{"field":"eventType"}}}}}}},"429":{"$ref":"#/components/responses/SellerApiRateLimited"},"500":{"$ref":"#/components/responses/SellerApiInternalError"},"503":{"$ref":"#/components/responses/SellerApiServiceUnavailable"},"504":{"$ref":"#/components/responses/SellerApiTimeout"}},"security":[{"bearerAuth":[]}],"x-avrix-scopes":["seller:webhooks:write"],"x-avrix-tier":"webhooks","x-avrix-rate-limit-class":"webhooks-mgmt","x-avrix-scope-mode":"anyOf","tags":["Webhooks"],"operationId":"createTest"}},"/api/seller/v1/webhooks/{id}/enable":{"post":{"summary":"Re-enable webhook endpoint","description":"Sets status to active after a circuit-breaker disable or a pause (`POST /webhooks/{id}/disable`); resets failure counters and the `failing` signal.\n\n**Buffered events:** deliveries queued while the endpoint was disabled are flushed on re-enable (`flushedBufferedDeliveries` reports the count). To resume without the backlog, send `replayFrom`: only buffered events created at or after it are sent, older ones are closed as failed with `lastError` `skipped_on_enable` (`skippedBufferedDeliveries`) and stay in the delivery log, where retry and replay can still send them. Without a body every buffered event is sent, as before.\n\n**Body:** optional. An invalid or future `replayFrom` answers **422** `VALIDATION_FAILED`. On contract date `2026-12-01` and later a body that is not a JSON object also answers **422**; earlier dates ignore it. Unknown fields are ignored.","parameters":[{"name":"id","in":"path","required":true,"description":"Webhook endpoint id (`id` from `GET /webhooks`).","schema":{"type":"string","format":"uuid"}},{"$ref":"#/components/parameters/AvrixApiVersion"},{"$ref":"#/components/parameters/RequestId"},{"$ref":"#/components/parameters/SandboxSimulateWrite"}],"requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{"replayFrom":{"type":"string","format":"date-time","description":"Send only the buffered events created at or after this instant. Must not be in the future."}}},"example":{"replayFrom":"2026-11-13T09:00:00Z"}}}},"responses":{"200":{"description":"Re-enabled. The endpoint in its `GET /webhooks/{id}` shape, plus the buffer outcome.","headers":{"X-Request-Id":{"$ref":"#/components/headers/XRequestId"},"X-Avrix-Api-Version":{"$ref":"#/components/headers/XAvrixApiVersion"},"X-Api-Version":{"$ref":"#/components/headers/XApiVersion"},"X-RateLimit-Limit":{"$ref":"#/components/headers/XRateLimitLimit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/XRateLimitRemaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/XRateLimitReset"},"X-RateLimit-Bucket":{"$ref":"#/components/headers/XRateLimitBucket"}},"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."},"url":{"type":"string"},"events":{"type":"array","items":{"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)."},"consecutiveFailures":{"type":"integer","description":"Deliveries in a row that exhausted their retries (terminal failures). Reset by a successful delivery. The endpoint is disabled when it reaches the platform threshold."},"disabledReason":{"type":["string","null"],"description":"Why the endpoint is disabled (for example `consecutive_failures`), or null while it is active."},"updatedAt":{"type":["string","null"],"format":"date-time","description":"When the endpoint was last changed."},"failing":{"type":"boolean","description":"True while deliveries to this active endpoint keep failing: at least 3 failed attempts in a row over at least 10 minutes. The endpoint stays active and retries continue; this is the early warning, well before the circuit breaker disables it (see `consecutiveFailures`). `system.webhook_endpoint_failing` is sent when it turns true, `system.webhook_endpoint_recovered` when a delivery succeeds again. Always false for a disabled endpoint."},"failingSince":{"type":["string","null"],"format":"date-time","description":"When the endpoint turned `failing`; null while it is not."},"lastSuccessAt":{"type":["string","null"],"format":"date-time","description":"The last delivery attempt your endpoint answered with 2xx."},"lastFailureAt":{"type":["string","null"],"format":"date-time","description":"The last delivery attempt that failed (non-2xx, timeout or connection error)."},"consecutiveFailedAttempts":{"type":"integer","description":"Failed attempts in a row, counting every retry. `consecutiveFailures` counts only deliveries that used up all their retries."},"pendingDeliveries":{"type":"integer","description":"Deliveries waiting to be sent or retried (buffered deliveries of a disabled endpoint are in `bufferedDeliveries`)."},"skippedBufferedDeliveries":{"type":"integer","description":"Buffered deliveries older than `replayFrom`, closed as `failed` with `lastError` `skipped_on_enable` instead of being sent. They stay in the delivery log; retry or replay sends them. 0 without `replayFrom`."}}}}},"example":{"data":{"id":"b1ec8da3-4525-4382-87c7-1675ceddfa43","status":"active","message":"Example text.","flushedBufferedDeliveries":1}}}}},"400":{"description":"`BAD_REQUEST`: the endpoint could not be re-enabled; `message` says why. Also returned for an `X-Avrix-Api-Version` this API does not serve (`UNSUPPORTED_API_VERSION`).","headers":{"X-Request-Id":{"$ref":"#/components/headers/XRequestId"},"X-Avrix-Api-Version":{"$ref":"#/components/headers/XAvrixApiVersion"},"X-Api-Version":{"$ref":"#/components/headers/XApiVersion"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"401":{"$ref":"#/components/responses/SellerApiUnauthorized"},"403":{"$ref":"#/components/responses/SellerApiForbidden"},"404":{"description":"`NOT_FOUND`: no webhook endpoint with this id belongs to your company (for a sandbox key: to this key).","headers":{"X-Request-Id":{"$ref":"#/components/headers/XRequestId"},"X-Avrix-Api-Version":{"$ref":"#/components/headers/XAvrixApiVersion"},"X-Api-Version":{"$ref":"#/components/headers/XApiVersion"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"422":{"$ref":"#/components/responses/SellerApiValidationFailed"},"429":{"$ref":"#/components/responses/SellerApiRateLimited"},"500":{"$ref":"#/components/responses/SellerApiInternalError"},"503":{"$ref":"#/components/responses/SellerApiServiceUnavailable"},"504":{"$ref":"#/components/responses/SellerApiTimeout"}},"security":[{"bearerAuth":[]}],"x-avrix-scopes":["seller:webhooks:write"],"x-avrix-tier":"webhooks","x-avrix-rate-limit-class":"webhooks-mgmt","x-avrix-scope-mode":"anyOf","tags":["Webhooks"],"operationId":"createEnable"}},"/api/seller/v1/webhooks/{id}/disable":{"post":{"summary":"Pause webhook endpoint","description":"Pauses an active endpoint: nothing is sent to it until `POST /webhooks/{id}/enable`. Events that happen meanwhile are buffered as after a circuit-breaker disable (up to `bufferCapacity`), and `GET /events` keeps every event. `disabledReason` is `manual`; a pause raises no disabled alert. Pausing a disabled endpoint changes nothing (`alreadyDisabled`). Resume with `POST /webhooks/{id}/enable`, optionally with `replayFrom` to skip the backlog; check your receiver first with `POST /webhooks/{id}/test` (contract date `2026-12-01` and later).","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","format":"uuid"},"description":"Webhook endpoint ID"},{"$ref":"#/components/parameters/AvrixApiVersion"},{"$ref":"#/components/parameters/RequestId"},{"$ref":"#/components/parameters/SandboxSimulateWrite"}],"responses":{"200":{"description":"Paused (or already disabled)","headers":{"X-Request-Id":{"$ref":"#/components/headers/XRequestId"},"X-Avrix-Api-Version":{"$ref":"#/components/headers/XAvrixApiVersion"},"X-Api-Version":{"$ref":"#/components/headers/XApiVersion"},"X-RateLimit-Limit":{"$ref":"#/components/headers/XRateLimitLimit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/XRateLimitRemaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/XRateLimitReset"},"X-RateLimit-Bucket":{"$ref":"#/components/headers/XRateLimitBucket"}},"content":{"application/json":{"schema":{"type":"object","properties":{"data":{"allOf":[{"$ref":"#/components/schemas/WebhookEndpoint"},{"type":"object","properties":{"alreadyDisabled":{"type":"boolean","description":"True when the endpoint was already disabled; nothing changed."},"message":{"type":"string"}}}]}}},"example":{"data":{"id":"2731f87a-b6f0-442f-832f-a94011003f83","url":"https://store.example.com/webhooks/avrix","events":["order.fulfilled"],"status":"active","createdAt":"2026-11-02T09:30:00Z","bufferedDeliveries":1,"bufferCapacity":12,"updatedAt":"2026-11-02T09:30:00Z","failing":false,"failingSince":"2026-11-02T09:30:00Z","lastSuccessAt":"2026-11-02T09:30:00Z","consecutiveFailedAttempts":1,"pendingDeliveries":1,"message":"Example text."}}}}},"400":{"description":"`UNSUPPORTED_API_VERSION`: the `X-Avrix-Api-Version` sent is not one this API serves.","headers":{"X-Request-Id":{"$ref":"#/components/headers/XRequestId"},"X-Avrix-Api-Version":{"$ref":"#/components/headers/XAvrixApiVersion"},"X-Api-Version":{"$ref":"#/components/headers/XApiVersion"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"401":{"$ref":"#/components/responses/SellerApiUnauthorized"},"403":{"$ref":"#/components/responses/SellerApiForbidden"},"404":{"description":"`NOT_FOUND`: no webhook endpoint with this id belongs to your company (for a sandbox key: to this key).","headers":{"X-Request-Id":{"$ref":"#/components/headers/XRequestId"},"X-Avrix-Api-Version":{"$ref":"#/components/headers/XAvrixApiVersion"},"X-Api-Version":{"$ref":"#/components/headers/XApiVersion"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"422":{"$ref":"#/components/responses/SellerApiValidationFailed"},"429":{"$ref":"#/components/responses/SellerApiRateLimited"},"500":{"$ref":"#/components/responses/SellerApiInternalError"},"503":{"$ref":"#/components/responses/SellerApiServiceUnavailable"},"504":{"$ref":"#/components/responses/SellerApiTimeout"}},"security":[{"bearerAuth":[]}],"x-avrix-scopes":["seller:webhooks:write"],"x-avrix-tier":"webhooks","x-avrix-rate-limit-class":"webhooks-mgmt","x-avrix-scope-mode":"anyOf","tags":["Webhooks"],"operationId":"createDisable"}},"/api/seller/v1/webhooks/{id}/deliveries/{deliveryId}":{"get":{"summary":"Get webhook delivery","description":"One delivery in full: the body your endpoint received, the identifying headers, your endpoint's last answer and one entry per attempt (status, a bounded and redacted excerpt of the answer, the classified error, the duration). Readable after the endpoint is deleted (`meta.endpointDeleted`). Deliveries are kept 30 days.","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","format":"uuid"},"description":"Webhook endpoint ID"},{"name":"deliveryId","in":"path","required":true,"schema":{"type":"string","format":"uuid"},"description":"`id` from GET /webhooks/{id}/deliveries"},{"$ref":"#/components/parameters/AvrixApiVersion"},{"$ref":"#/components/parameters/RequestId"},{"$ref":"#/components/parameters/SandboxSimulateRateLimit"}],"responses":{"200":{"description":"The delivery","headers":{"X-Request-Id":{"$ref":"#/components/headers/XRequestId"},"X-Avrix-Api-Version":{"$ref":"#/components/headers/XAvrixApiVersion"},"X-Api-Version":{"$ref":"#/components/headers/XApiVersion"},"X-RateLimit-Limit":{"$ref":"#/components/headers/XRateLimitLimit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/XRateLimitRemaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/XRateLimitReset"},"X-RateLimit-Bucket":{"$ref":"#/components/headers/XRateLimitBucket"}},"content":{"application/json":{"schema":{"type":"object","properties":{"data":{"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"},"eventLogId":{"type":["string","null"],"description":"The event's own id (`eventLogId` in the body, `X-Avrix-Event-Log-Id` header, `id` in `GET /events`). Null on test sends and on deliveries older than the event log."},"status":{"type":"string"},"attempts":{"type":"integer"},"responseStatus":{"type":["integer","null"]},"lastError":{"type":["string","null"],"description":"Classified reason of the last failed attempt: timeout, dns_private_address, dns_failure, connect_refused, connection_error, redirect_limit, url_not_allowed, secret_decrypt_failed, endpoint_deleted, contract_not_active, skipped_on_enable (closed unsent by `POST /webhooks/{id}/enable` with `replayFrom`), no_previous_secret (a `previous_secret_only` test challenge on an endpoint with no previous secret in its rotation overlap), or http_<status> when the endpoint answered non-2xx. Null after a success. responseStatus is only ever the endpoint's own status; a transport failure leaves it null."},"createdAt":{"type":"string","format":"date-time"},"lastAttemptAt":{"type":["string","null"],"format":"date-time"},"nextRetryAt":{"type":["string","null"],"format":"date-time"},"testEvent":{"type":"boolean","description":"True for a test send (`POST /webhooks/{id}/test`)."},"body":{"type":"object","additionalProperties":true,"description":"The JSON body your endpoint received (the same on every attempt)."},"headers":{"type":"object","additionalProperties":{"type":"string"},"description":"The identifying headers sent with every attempt. `X-Avrix-Signature` is computed per attempt and not shown."},"responseBodyExcerpt":{"type":["string","null"],"description":"Your endpoint's last answer: at most 500 characters, credentials masked."},"attemptHistory":{"type":"array","items":{"type":"object","properties":{"attemptNumber":{"type":"integer","description":"1 for the first attempt."},"attemptedAt":{"type":"string","format":"date-time"},"outcome":{"type":"string","enum":["succeeded","failed"],"description":"`succeeded`: your endpoint accepted the attempt. `failed`: it did not (see `responseStatus` and `errorCode`)."},"responseStatus":{"type":["integer","null"],"description":"Your endpoint's HTTP status; null when it did not answer."},"responseBodyExcerpt":{"type":["string","null"],"description":"At most 500 characters of your endpoint's answer, with credentials it echoed (secrets, API keys, bearer tokens, JWTs, password and token fields) masked."},"error":{"type":["string","null"],"description":"Classified reason of a failed attempt, as `lastError` on the delivery list."},"durationMs":{"type":["integer","null"],"description":"How long the attempt took."}}},"description":"One entry per attempt, oldest first. Empty for attempts made before 2026-11-13, when the history began; the delivery's own counters still apply."}}},"meta":{"type":"object","properties":{"endpointDeleted":{"type":"boolean","description":"True when the endpoint was deleted."}}}}},"example":{"data":{"id":"4e6ba46e-b94b-4c2c-8068-ad176df86e6a","endpointId":"ac262fc7-fe00-498b-821d-2050094f64d9","eventId":"f47b9cd1-e808-459d-8f50-382bfb30ec26","eventType":"order.fulfilled","eventLogId":"12229ce7-4f5c-4079-83ea-05787b30a410","status":"active","attempts":1,"responseStatus":200,"createdAt":"2026-11-02T09:30:00Z","lastAttemptAt":"2026-11-02T09:30:00Z","nextRetryAt":"2026-11-02T09:30:00Z","testEvent":true,"body":{},"headers":{"example":"example_headers"},"responseBodyExcerpt":"example_responsebodyexcerpt","attemptHistory":[{"attemptNumber":1,"attemptedAt":"2026-11-02T09:30:00Z","outcome":"succeeded","responseStatus":200,"responseBodyExcerpt":"example_responsebodyexcerpt","durationMs":1}]},"meta":{"endpointDeleted":true}}}}},"400":{"description":"`UNSUPPORTED_API_VERSION`: the `X-Avrix-Api-Version` sent is not one this API serves.","headers":{"X-Request-Id":{"$ref":"#/components/headers/XRequestId"},"X-Avrix-Api-Version":{"$ref":"#/components/headers/XAvrixApiVersion"},"X-Api-Version":{"$ref":"#/components/headers/XApiVersion"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"401":{"$ref":"#/components/responses/SellerApiUnauthorized"},"403":{"$ref":"#/components/responses/SellerApiForbidden"},"404":{"description":"`NOT_FOUND`: no webhook endpoint with this id belongs to your company (for a sandbox key: to this key), or the delivery is not one of its deliveries.","headers":{"X-Request-Id":{"$ref":"#/components/headers/XRequestId"},"X-Avrix-Api-Version":{"$ref":"#/components/headers/XAvrixApiVersion"},"X-Api-Version":{"$ref":"#/components/headers/XApiVersion"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"422":{"$ref":"#/components/responses/SellerApiValidationFailed"},"429":{"$ref":"#/components/responses/SellerApiRateLimited"},"500":{"$ref":"#/components/responses/SellerApiInternalError"},"503":{"$ref":"#/components/responses/SellerApiServiceUnavailable"},"504":{"$ref":"#/components/responses/SellerApiTimeout"}},"security":[{"bearerAuth":[]}],"x-avrix-scopes":["seller:webhooks:read"],"x-avrix-tier":"webhooks","x-avrix-rate-limit-class":"webhooks-mgmt","x-avrix-scope-mode":"anyOf","tags":["Webhooks"],"operationId":"getWebhooksDelivery"}},"/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,"description":"Webhook endpoint id (`id` from `GET /webhooks`).","schema":{"type":"string","format":"uuid"}},{"name":"deliveryId","in":"path","required":true,"description":"Delivery id (`id` from `GET /webhooks/{id}/deliveries`).","schema":{"type":"string","format":"uuid"}},{"$ref":"#/components/parameters/AvrixApiVersion"},{"$ref":"#/components/parameters/RequestId"},{"$ref":"#/components/parameters/SandboxSimulateWrite"}],"responses":{"202":{"description":"Delivery re-queued","headers":{"X-Request-Id":{"$ref":"#/components/headers/XRequestId"},"X-Avrix-Api-Version":{"$ref":"#/components/headers/XAvrixApiVersion"},"X-Api-Version":{"$ref":"#/components/headers/XApiVersion"},"X-RateLimit-Limit":{"$ref":"#/components/headers/XRateLimitLimit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/XRateLimitRemaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/XRateLimitReset"},"X-RateLimit-Bucket":{"$ref":"#/components/headers/XRateLimitBucket"}},"content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"deliveryId":{"type":"string","format":"uuid","description":"The delivery that was queued again."},"message":{"type":"string"}}}}},"example":{"data":{"deliveryId":"a1dcd313-4d44-4ff9-8ef6-87320fc2aef8","message":"Example text."}}}}},"400":{"description":"`BAD_REQUEST`: the delivery could not be queued again; `message` says why. Also returned for an `X-Avrix-Api-Version` this API does not serve (`UNSUPPORTED_API_VERSION`).","headers":{"X-Request-Id":{"$ref":"#/components/headers/XRequestId"},"X-Avrix-Api-Version":{"$ref":"#/components/headers/XAvrixApiVersion"},"X-Api-Version":{"$ref":"#/components/headers/XApiVersion"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"401":{"$ref":"#/components/responses/SellerApiUnauthorized"},"403":{"$ref":"#/components/responses/SellerApiForbidden"},"404":{"description":"`NOT_FOUND`: the webhook endpoint or the delivery does not exist for your company (for a sandbox key: for this key).","headers":{"X-Request-Id":{"$ref":"#/components/headers/XRequestId"},"X-Avrix-Api-Version":{"$ref":"#/components/headers/XAvrixApiVersion"},"X-Api-Version":{"$ref":"#/components/headers/XApiVersion"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"409":{"description":"`CONFLICT`: only a failed delivery can be retried. A delivery that is pending or already delivered is left as it is.","headers":{"X-Request-Id":{"$ref":"#/components/headers/XRequestId"},"X-Avrix-Api-Version":{"$ref":"#/components/headers/XAvrixApiVersion"},"X-Api-Version":{"$ref":"#/components/headers/XApiVersion"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"422":{"$ref":"#/components/responses/SellerApiValidationFailed"},"429":{"$ref":"#/components/responses/SellerApiRateLimited"},"500":{"$ref":"#/components/responses/SellerApiInternalError"},"503":{"$ref":"#/components/responses/SellerApiServiceUnavailable"},"504":{"$ref":"#/components/responses/SellerApiTimeout"}},"security":[{"bearerAuth":[]}],"x-avrix-scopes":["seller:webhooks:write"],"x-avrix-tier":"webhooks","x-avrix-rate-limit-class":"webhooks-mgmt","x-avrix-scope-mode":"anyOf","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. **Retries:** send an `Idempotency-Key` to make a retry safe: the same key and body replay the first answer with `Idempotency-Replayed: true` instead of acting twice. On contract date `2026-12-01` and later a replay never clones a delivery that is itself a replay (its payload carries `replay`) or a test delivery, so replaying the same window twice does not multiply deliveries; earlier contract dates clone every matching delivery.","parameters":[{"name":"id","in":"path","required":true,"description":"Webhook endpoint id (`id` from `GET /webhooks`).","schema":{"type":"string","format":"uuid"}},{"$ref":"#/components/parameters/IdempotencyKeyOptional"},{"$ref":"#/components/parameters/AvrixApiVersion"},{"$ref":"#/components/parameters/RequestId"},{"$ref":"#/components/parameters/SandboxSimulateWrite"}],"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","headers":{"X-Request-Id":{"$ref":"#/components/headers/XRequestId"},"X-Avrix-Api-Version":{"$ref":"#/components/headers/XAvrixApiVersion"},"X-Api-Version":{"$ref":"#/components/headers/XApiVersion"},"Idempotency-Replayed":{"$ref":"#/components/headers/IdempotencyReplayed"},"X-RateLimit-Limit":{"$ref":"#/components/headers/XRateLimitLimit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/XRateLimitRemaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/XRateLimitReset"},"X-RateLimit-Bucket":{"$ref":"#/components/headers/XRateLimitBucket"}},"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."},"hasMore":{"type":"boolean","description":"True when more deliveries matched the window than `limit` allowed. Call again with `since` set to `nextSince` to replay the rest."},"nextSince":{"type":["string","null"],"format":"date-time","description":"When `hasMore` is true: the `created_at` of the first matching delivery this call left out; send it as `since` on the next call. Null otherwise. Deliveries created at that same instant are matched again by the next call."}}}}},"example":{"data":{"enqueued":1,"deliveryIds":["a8275cd5-d398-4d42-8778-546b0c2a84ef"],"sourceDeliveryIds":["e6b168e8-0c03-4de7-8d81-b65988b416a6"],"hasMore":true}}}}},"400":{"description":"Invalid window or input Also returned for an `X-Avrix-Api-Version` this API does not serve (`UNSUPPORTED_API_VERSION`).","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":"`CONFLICT`: the webhook endpoint is not active; re-enable it first. `IDEMPOTENCY_KEY_MISMATCH`: the `Idempotency-Key` was already used with a different body; use a new key for a new request. `IDEMPOTENCY_REQUEST_IN_FLIGHT`: an earlier request with this key is still running; wait `Retry-After` seconds and send the same request again.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"413":{"$ref":"#/components/responses/SellerApiPayloadTooLarge"},"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"},"503":{"$ref":"#/components/responses/SellerApiServiceUnavailable"},"504":{"$ref":"#/components/responses/SellerApiTimeout"}},"security":[{"bearerAuth":[]}],"x-avrix-scopes":["seller:webhooks:write"],"x-avrix-tier":"webhooks","x-avrix-rate-limit-class":"webhooks-mgmt","x-avrix-scope-mode":"anyOf","tags":["Webhooks"],"operationId":"createReplay"}},"/api/seller/v1/usage":{"get":{"summary":"API usage summary","description":"Request counts for the key owner in the calling key's environment (UTC window, both ends inclusive; default: last 7 days), computed from the per-request call log: every response is counted once — successes, reads and denials included — never sampled. Retention of the call log is 90 days; ask for longer ranges in pieces.\n\nThe totals and the `byRoute`, `byStatus`, `byDay` and `byKey` breakdowns always cover the whole window, however many requests it holds. `byRoute` labels each endpoint as a template (`/v1/orders/{id}`: a path segment that contains a digit is an id); `byEndpoint` keeps path parameters as sent, so each id is its own entry, and lists at most `maxEndpointBuckets` entries, largest first (`truncated` is `true` when it leaves some out). `byStatus` gives the error code of every error response (`VALIDATION_FAILED`, `RATE_LIMIT_EXCEEDED`, ...); responses recorded before error codes were stored report `HTTP_<status>`. Pass `keyId` to count one of your keys only.","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)"},{"name":"keyId","in":"query","required":false,"schema":{"type":"string","format":"uuid"},"description":"Count only the requests made with this API key of yours (an `id` from `GET /keys` or `data.key.id` of `GET /whoami`). Omit it to count every key of the key owner in the calling key's environment."},{"$ref":"#/components/parameters/AvrixApiVersion"},{"$ref":"#/components/parameters/RequestId"},{"$ref":"#/components/parameters/SandboxSimulateRateLimit"}],"responses":{"200":{"description":"Usage aggregates","headers":{"X-Request-Id":{"$ref":"#/components/headers/XRequestId"},"X-Avrix-Api-Version":{"$ref":"#/components/headers/XAvrixApiVersion"},"X-Api-Version":{"$ref":"#/components/headers/XApiVersion"},"X-RateLimit-Limit":{"$ref":"#/components/headers/XRateLimitLimit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/XRateLimitRemaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/XRateLimitReset"},"X-RateLimit-Bucket":{"$ref":"#/components/headers/XRateLimitBucket"}},"content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"from":{"type":"string"},"to":{"type":"string"},"truncated":{"type":"boolean","description":"`true` when `byEndpoint` leaves out entries because the window has more than `maxEndpointBuckets` distinct method and endpoint pairs. The totals and every other breakdown are complete either way."},"maxCountedRequests":{"type":"integer","deprecated":true,"description":"Deprecated: the totals are no longer capped. Kept at its old value, 50,000. Use `truncated` and `maxEndpointBuckets`."},"maxEndpointBuckets":{"type":"integer","description":"The most entries `byEndpoint` lists. Currently 50,000."},"keyId":{"type":["string","null"],"format":"uuid","description":"The key the counts are limited to (`keyId` query parameter), or null for all keys."},"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."},"byRoute":{"type":"array","description":"One entry per method and route template (`/v1/orders/{id}`), every request of the window counted.","items":{"type":"object","properties":{"route":{"type":"string"},"method":{"type":"string"},"requests":{"type":"integer"},"errors":{"type":"integer","description":"Responses >= 400, excluding lookup misses."},"lookupMisses":{"type":"integer","description":"404s on GET requests."}}}},"byStatus":{"type":"array","description":"One entry per HTTP status and error code, every request of the window counted, ordered by status.","items":{"type":"object","properties":{"status":{"type":"integer"},"code":{"type":["string","null"],"description":"The `code` of the error body, or `HTTP_<status>` for an error recorded without one. Null below 400."},"requests":{"type":"integer"}}}},"byDay":{"type":"array","description":"One entry per UTC day of the window that has requests, oldest first.","items":{"type":"object","properties":{"day":{"type":"string","format":"date"},"requests":{"type":"integer"},"errors":{"type":"integer","description":"Responses >= 400, excluding lookup misses."},"lookupMisses":{"type":"integer","description":"404s on GET requests."}}}},"byKey":{"type":"array","description":"One entry per API key, largest first.","items":{"type":"object","properties":{"apiKeyId":{"type":["string","null"],"format":"uuid"},"requests":{"type":"integer"},"errors":{"type":"integer","description":"Responses >= 400, excluding lookup misses."},"lookupMisses":{"type":"integer","description":"404s on GET requests."}}}},"byEndpoint":{"type":"array","description":"One bucket per method + endpoint, path parameters as sent; a GET lookup and a POST commit on the same path are separate buckets. At most `maxEndpointBuckets` entries, largest first.","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."}}}}}}}},"example":{"data":{"from":"2026-11-02T09:30:00Z","to":"2026-11-02T09:30:00Z","truncated":false,"maxCountedRequests":12,"totalRequests":2450,"totalLookupMisses":2450,"byEndpoint":[{"endpoint":"/api/seller/v1/orders","method":"POST","requests":1,"errors":1,"lookupMisses":1}]}}}}},"400":{"$ref":"#/components/responses/SellerApiUnsupportedApiVersion"},"401":{"$ref":"#/components/responses/SellerApiUnauthorized"},"403":{"$ref":"#/components/responses/SellerApiForbidden"},"422":{"description":"`VALIDATION_FAILED`: invalid query parameters (`from`, `to`, the range, or a `keyId` that is not a UUID)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"429":{"$ref":"#/components/responses/SellerApiRateLimited"},"500":{"$ref":"#/components/responses/SellerApiInternalError"},"503":{"$ref":"#/components/responses/SellerApiServiceUnavailable"},"504":{"$ref":"#/components/responses/SellerApiTimeout"}},"security":[{"bearerAuth":[]}],"x-avrix-scopes":["seller:products:read"],"x-avrix-tier":"meta","x-avrix-rate-limit-class":"finance","x-avrix-scope-mode":"anyOf","tags":["Seller meta"],"operationId":"getUsage"}},"/api/seller/v1/requests/{requestId}":{"get":{"summary":"Inspect a Seller API request by X-Request-Id","description":"Returns what was recorded about one of your requests, and the webhook deliveries it produced. Raw keys, webhook secrets, PSP tokens and free-form metadata are never returned.\n\n**Two records, two depths.**\n- `callLog`: every response to a request made with one of your keys has a row, never sampled: method, endpoint, status, latency, error code and key. It is looked up for the key owner and the calling key's environment, as `GET /usage` counts. A request refused before the key was identified (`401`) has none.\n- `traces`: the request audit log adds the fields an order or refund needs (`orderReference`, `outcome`, `keyPullId`, ...). It is sampled: on the order, key pull, key export, key return, refund and webhook paths every write and every error the route records is kept; elsewhere `429` and `5xx` responses are kept in full, other `4xx` at about 1 in 10, `2xx` and `3xx` at about 1 in 100. These rates can change.\n\n`coverage` says what was found: `detailed` (a trace), `summary` (a call-log row only) or `none`.\n\n**An id nothing recorded:** on contract date `2026-12-01` and later the answer is `404 NOT_FOUND` with `details.lookupRequestId` and `details.retentionDays`. Earlier dates answer `200` with `coverage: \"none\"` and empty lists.\n\n**Retention:** both records are kept for 90 days.","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."},{"$ref":"#/components/parameters/AvrixApiVersion"},{"$ref":"#/components/parameters/RequestId"},{"$ref":"#/components/parameters/SandboxSimulateRateLimit"}],"responses":{"200":{"description":"Redacted request trace","headers":{"X-Request-Id":{"$ref":"#/components/headers/XRequestId"},"X-Avrix-Api-Version":{"$ref":"#/components/headers/XAvrixApiVersion"},"X-Api-Version":{"$ref":"#/components/headers/XApiVersion"},"X-RateLimit-Limit":{"$ref":"#/components/headers/XRateLimitLimit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/XRateLimitRemaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/XRateLimitReset"},"X-RateLimit-Bucket":{"$ref":"#/components/headers/XRateLimitBucket"}},"content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"requestId":{"type":"string"},"coverage":{"type":"string","enum":["detailed","summary","none"],"description":"`detailed`: at least one sampled trace was kept. `summary`: only the call-log row (method, endpoint, status, latency, error code). `none`: nothing was recorded for this id in the last 90 days (on contract date `2026-12-01` and later this is a `404` unless a webhook delivery names the id)."},"callLog":{"type":"array","description":"The call-log rows for this id (one per response; a retried id can have several), newest first. Never sampled.","items":{"type":"object","properties":{"requestId":{"type":"string"},"endpoint":{"type":"string","description":"The path as requested."},"method":{"type":"string"},"statusCode":{"type":"integer"},"responseTimeMs":{"type":["integer","null"]},"errorCode":{"type":["string","null"],"description":"The `code` of the error body; `HTTP_<status>` for an error recorded before codes were stored; null for a success."},"apiKeyId":{"type":["string","null"],"format":"uuid"},"createdAt":{"type":"string","format":"date-time"}}}},"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"},"orderReference":{"type":["string","null"],"description":"The order reference this request handled (orders, refunds, returns)."},"outcome":{"type":["string","null"],"enum":["fulfilled","preordered","backordered","deferred","replayed","reserved","refunded","returned",null],"description":"What a successful order-path request did. Every 2xx POST /orders row has either `keyPullId` or an outcome explaining why not."}}}},"webhookDeliveries":{"type":"array","description":"Webhook deliveries this request produced (`sameRequest: true`), plus later deliveries for the same order reference (for example a preorder fulfilled afterwards). Your endpoints only; payloads are not included.","items":{"type":"object","properties":{"deliveryId":{"type":"string","format":"uuid"},"eventId":{"type":"string"},"eventType":{"type":"string"},"endpointId":{"type":"string","format":"uuid"},"status":{"type":"string"},"attempts":{"type":"integer"},"responseStatus":{"type":["integer","null"]},"lastError":{"type":["string","null"]},"orderReference":{"type":["string","null"]},"sameRequest":{"type":"boolean"},"createdAt":{"type":"string","format":"date-time"},"lastAttemptAt":{"type":["string","null"],"format":"date-time"}}}}}}}},"example":{"data":{"requestId":"df8e4ff5-235a-417a-8ed8-3d3ce0db11cf","traces":[{"endpoint":"/api/seller/v1/orders","method":"POST","statusCode":200,"responseTimeMs":1,"apiKeyId":"77c742ad-e20e-4b52-81b3-90a819f3cdcb","integrationContextBytes":1,"pulledCount":12,"allocationId":"27985f40-057b-4135-893f-c7183fdc03c0","skuId":"43284760-95bd-4db3-83cb-a4943648a850","keyPullId":"e7e0666f-07e0-43b6-861c-f254e4d95569","createdAt":"2026-11-02T09:30:00Z","orderReference":"store-order-10432","outcome":"fulfilled"}],"webhookDeliveries":[{"deliveryId":"0c62d44a-14e5-431d-8d6b-f98a571a695a","eventId":"b40aef82-f632-4220-8465-afbd19eedcce","eventType":"order.fulfilled","endpointId":"f23c96dd-f210-4222-8f37-58887a41a37f","status":"succeeded","attempts":1,"responseStatus":200,"orderReference":"store-order-10432","sameRequest":true,"createdAt":"2026-11-02T09:30:00Z","lastAttemptAt":"2026-11-02T09:30:00Z"}]}}}}},"400":{"$ref":"#/components/responses/SellerApiUnsupportedApiVersion"},"401":{"$ref":"#/components/responses/SellerApiUnauthorized"},"403":{"$ref":"#/components/responses/SellerApiForbidden"},"404":{"description":"`NOT_FOUND` (contract date `2026-12-01` and later): nothing was recorded for this id for your company in the last 90 days, and no webhook delivery names it. Check the id you logged, or the key's environment. Earlier dates answer `200` with `coverage: \"none\"`.","headers":{"X-Request-Id":{"$ref":"#/components/headers/XRequestId"},"X-Avrix-Api-Version":{"$ref":"#/components/headers/XAvrixApiVersion"},"X-Api-Version":{"$ref":"#/components/headers/XApiVersion"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"422":{"description":"Invalid request id","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"429":{"$ref":"#/components/responses/SellerApiRateLimited"},"500":{"$ref":"#/components/responses/SellerApiInternalError"},"503":{"$ref":"#/components/responses/SellerApiServiceUnavailable"},"504":{"$ref":"#/components/responses/SellerApiTimeout"}},"security":[{"bearerAuth":[]}],"x-avrix-scopes":["seller:products:read"],"x-avrix-tier":"meta","x-avrix-rate-limit-class":"finance","x-avrix-scope-mode":"anyOf","tags":["Seller meta"],"operationId":"getRequest"}},"/api/seller/v1/orders":{"get":{"summary":"List orders, or look one up by reference or id","description":"One operation, three modes, chosen by the query. **Look up one order:** `orderReference` (your store order id) or `orderReadableId` (any order id, `orderId` from any order response); `data` is one order aggregate, 404 when no order matches. To fetch by id you can also call `GET /orders/{orderId}`. **One bulk cart:** `parentOrderReference`; `data` is an array of aggregates. **List:** none of those; `data` is an array of order rows with a cursor (see Listing mode below), an empty page when nothing matches. Tell the modes apart by the query you sent, or by `data` being an object (lookup) or an array (cart, list). 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 `seller:orders:read`; `seller:orders:write` and the legacy `seller:products:read` and `seller:keys:pull` are also accepted. Does not return key plaintext. **Read model:** every order also has a durable record, written when it is placed and moved by fulfil, return, refund, cancellation and backorder expiry. It is compared with the delivery rows daily and is the source of `status` once durable reads are switched on for the environment; key-level line detail always comes from the delivery rows, and the response shape does not change.\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, at most 255 characters there; a longer value matches no order). Mutually exclusive with orderReadableId."},{"name":"orderReadableId","in":"query","required":false,"schema":{"type":"string","minLength":1,"maxLength":128},"description":"Any order id (`ord_…`): `orderId` from any order response, or `orderReadableId` from a create response, a bulk line or `POST /keys/pull`. 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 order status. The listing pages until it has `limit` matches or reaches the end of your orders; `meta.nextCursor` is null when nothing more matches. `preordered` selects the same orders as `awaiting_release` (its earlier name). **Values the listing can serve:** until durable order reads are switched on for an environment, its listing is built from delivered keys and holds `fulfilled`, `returned` and `refunded` orders only. Every other value needs the durable read model: without it the filter returns an empty page on contract dates before `2026-12-01`, and `422 VALIDATION_FAILED` on `2026-12-01` and later, where `details.issues[0]` names `status` and its `allowedValues` lists what can be served. Once durable reads are on, every value is served."},{"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)."},{"name":"parentOrderReference","in":"query","required":false,"schema":{"type":"string","minLength":1,"maxLength":255},"description":"Every line of one bulk cart, by the `parentOrderReference` you sent in its `integrationOrderContext`. Returns `data` as an array of order aggregates in line order (at most 100) and `meta.parentOrderReference`. Cannot be combined with `orderReference` or `orderReadableId`. Refunds stay per line: refund each line by its own `orderReference`."},{"$ref":"#/components/parameters/AvrixApiVersion"},{"$ref":"#/components/parameters/RequestId"},{"$ref":"#/components/parameters/SandboxSimulateRateLimit"}],"responses":{"200":{"description":"Order aggregate for the given orderReference or orderReadableId (fulfilled pulls + active pre-orders). No plaintext keys.","headers":{"X-Request-Id":{"$ref":"#/components/headers/XRequestId"},"X-Avrix-Api-Version":{"$ref":"#/components/headers/XAvrixApiVersion"},"X-Api-Version":{"$ref":"#/components/headers/XApiVersion"},"X-RateLimit-Limit":{"$ref":"#/components/headers/XRateLimitLimit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/XRateLimitRemaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/XRateLimitReset"},"X-RateLimit-Bucket":{"$ref":"#/components/headers/XRateLimitBucket"}},"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"},{"type":"object","required":["data","meta"],"description":"Cart mode (`parentOrderReference` given).","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/SellerOrderAggregate"}},"meta":{"type":"object","properties":{"parentOrderReference":{"type":"string"},"count":{"type":"integer"}}}}}]},"example":{"data":{"orderReference":"store-order-10432","status":"fulfilled","fulfilled":[{"skuCode":"SANDBOX-ALWAYS-001","allocationId":"00000000-0000-4000-8000-000000000001","fulfilledQuantity":1,"firstKeyPullId":"00000000-0000-4000-8000-0000000000aa","orderReadableId":"ord_abc12345"}],"preOrderActive":[],"refunds":[],"parentOrderReference":null,"lineIndex":null}}}}},"400":{"$ref":"#/components/responses/SellerApiUnsupportedApiVersion"},"401":{"$ref":"#/components/responses/SellerApiUnauthorized"},"403":{"$ref":"#/components/responses/SellerApiForbidden"},"404":{"description":"Lookup mode only: no order matches this orderReference or orderReadableId. The list and cart modes answer 200 with an empty `data` array instead.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"422":{"description":"Invalid query parameters: both orderReference and orderReadableId given, a value over its maximum length, or a malformed list filter, date or cursor. On contract date `2026-12-01` and later also: a `status` filter the environment's order listing cannot serve yet (see the `status` parameter); older dates return an empty page instead.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"429":{"$ref":"#/components/responses/SellerApiRateLimited"},"500":{"$ref":"#/components/responses/SellerApiInternalError"},"503":{"$ref":"#/components/responses/SellerApiServiceUnavailable"},"504":{"$ref":"#/components/responses/SellerApiTimeout"}},"security":[{"bearerAuth":[]}],"x-avrix-scopes":["seller:orders:read","seller:orders:write","seller:products:read","seller:keys:pull"],"x-avrix-tier":"orders","x-avrix-rate-limit-class":"orders","x-avrix-scope-mode":"anyOf","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:orders:write` or the legacy `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, CONSUMER_GEO_ATTEST_REQUIRED, CONSUMER_RISK_HIGH, CONSUMER_RISK_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 **true**; a Content Owner can opt its products out). Without it, pre-order-phase SKUs fail with **`PRODUCT_NOT_SELLABLE`** (`recoverable: false`) — check the capability up front instead of retrying.","parameters":[{"$ref":"#/components/parameters/IdempotencyKey"},{"$ref":"#/components/parameters/AvrixApiVersion"},{"$ref":"#/components/parameters/RequestId"},{"$ref":"#/components/parameters/SandboxSimulate"}],"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)"},"holdId":{"type":"string","format":"uuid","description":"Alias of `checkoutHoldId`, the name POST /orders/hold returns it under. Send one of the two; both with different values is 422 VALIDATION_FAILED."},"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","auto"],"default":"key","description":"`key` (default): plaintext codes. `keyless`: hosted redemption links instead of codes, up to 20 keys per line with one link for all of them (`delivery.items` lists each key); 403 FEATURE_DISABLED with `details.reason` `KEYLESS_NOT_ALLOWED_BY_PUBLISHER` when the Content Owner does not allow keyless, or `KEYLESS_DISABLED` when the platform switch is off. `auto`: keyless when the Content Owner's default says so (`GET /allocations` `keyless.default`), otherwise key."},"keylessProvider":{"type":"string","enum":["hosted_redemption","steam_gift","epic_entitlement","gog_connect"],"description":"Optional explicit keyless provider; omit it (hosted redemption). Platform entitlement providers are not available yet: asking for one answers 422 before any key is pulled."},"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. Treat it as opaque: its length and contents may change, so store and forward it as-is and never parse it."},"backorderOnUnavailable":{"type":"boolean","description":"Recommended after the buyer has paid: when true and immediate fulfilment returns NO_AVAILABLE_KEYS, the order becomes a durable customer-order backorder (`status: awaiting_stock`, `backorderExpiresAt`) instead of a 409. On by default (`whoami.capabilities.backorderEnabled`); 403 FEATURE_DISABLED only when the platform switch is off, 403 BACKORDER_NOT_ALLOWED when the Content Owner opted out. Accepted orders wait for order.ready, then POST /orders/{orderId}/fulfill; unfulfilled at `backorderExpiresAt` (default 14 days) they are cancelled with order.backorder_expired — refund the buyer. Not used for ALLOCATION_EXCEEDED.","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`.**","headers":{"Server-Timing":{"description":"Phase breakdown of this response in milliseconds, one entry per phase that ran: auth, idempotency, sku-resolve, allocation, availability, authority, term, geo, price, settlement, rpc, decrypt, billing, idempotency-commit, then total. Use it to attribute a slow response; the same phases are logged server-side above the platform threshold. Phase names are stable.","schema":{"type":"string"}},"X-Request-Id":{"$ref":"#/components/headers/XRequestId"},"X-Avrix-Api-Version":{"$ref":"#/components/headers/XAvrixApiVersion"},"X-Api-Version":{"$ref":"#/components/headers/XApiVersion"},"Idempotency-Replayed":{"$ref":"#/components/headers/IdempotencyReplayed"},"X-RateLimit-Limit":{"$ref":"#/components/headers/XRateLimitLimit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/XRateLimitRemaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/XRateLimitReset"},"X-RateLimit-Bucket":{"$ref":"#/components/headers/XRateLimitBucket"}},"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"}]},"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"},"meta":{"type":"object","properties":{"requestId":{"type":"string","description":"Same as the X-Request-Id response header."}}}}},"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). Also returned when the `Idempotency-Key` header is missing or malformed: `IDEMPOTENCY_KEY_REQUIRED` on contract date `2026-12-01` and later, `BAD_REQUEST` on earlier dates. Also returned for an `X-Avrix-Api-Version` this API does not serve (`UNSUPPORTED_API_VERSION`).","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. Also returned for the `Idempotency-Key` itself: `IDEMPOTENCY_KEY_MISMATCH` (the key was already used with a different body) and `IDEMPOTENCY_REQUEST_IN_FLIGHT` (an earlier request with this key is still running; retry after `Retry-After` seconds).","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 available keys in inventory","details":{"pullError":"NO_AVAILABLE_KEYS","recommendedAction":"refund_customer","allocationId":"00000000-0000-4000-8000-000000000001","skuId":"00000000-0000-4000-8000-000000000002","orderReference":"store-order-10432","postPaymentRecovery":"refund_customer"},"timestamp":"2026-11-12T10:15:00.000Z","error":"No available keys in inventory","recoverable":false,"hint":"Check GET /availability first to see allocation and inventory","doc_url":"https://docs.avrix.io/seller-api/errors#no-available-keys","requestId":"0198c2f4-7b1e-8c3a-9d2f-5e6a7b8c9d01"}},"idempotencyMismatch":{"summary":"Same Idempotency-Key, different JSON body","value":{"code":"IDEMPOTENCY_KEY_MISMATCH","message":"Idempotency-Key was already used with a different request body","details":{"requestBodyHash":"a1b2c3d4e5f6789012345678901234567890abcdef1234567890abcdef123456","recommendedAction":"fix_request_body_or_new_key"},"timestamp":"2026-11-12T10:15:00.000Z","error":"Idempotency-Key was already used with a different request body","recoverable":false,"hint":"Reuse the same Idempotency-Key only when retrying the identical request body. Compare `details.requestBodyHash` with the first request if debugging.","doc_url":"https://docs.avrix.io/seller-api/errors#idempotency-key-mismatch","requestId":"0198c2f4-7b1e-8c3a-9d2f-5e6a7b8c9d01"}},"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":{"pullError":"ORDER_REFERENCE_CONFLICT","recommendedAction":"fix_request_body_or_new_key","allocationId":"00000000-0000-4000-8000-000000000001","skuId":"00000000-0000-4000-8000-000000000002"},"timestamp":"2026-11-12T10:15:00.000Z","error":"orderReference already fulfilled 1 key(s); requested 3. Use a new orderReference for a new sale.","recoverable":false,"hint":"Use a new orderReference for a new sale. An orderReference replays its original keys only for the same quantity; a larger or smaller quantity is refused.","doc_url":"https://docs.avrix.io/seller-api/errors#order-reference-conflict","requestId":"0198c2f4-7b1e-8c3a-9d2f-5e6a7b8c9d01"}},"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"}}}}}}},"413":{"$ref":"#/components/responses/SellerApiPayloadTooLarge"},"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":{"$ref":"#/components/responses/SellerApiRateLimited"},"500":{"$ref":"#/components/responses/SellerApiInternalError"},"503":{"description":"Pre-order state unavailable (`PREORDER_STATE_UNAVAILABLE`). Also returned when a platform dependency is temporarily unavailable (`SERVICE_UNAVAILABLE`) and, on a write that sends an `Idempotency-Key`, when the claim cannot be recorded (`IDEMPOTENCY_STORE_UNAVAILABLE`). Retry after `Retry-After` seconds.","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}}}}}}},"504":{"$ref":"#/components/responses/SellerApiTimeout"}},"security":[{"bearerAuth":[]}],"x-avrix-scopes":["seller:orders:write","seller:keys:pull"],"x-avrix-tier":"orders","x-avrix-rate-limit-class":"orders","x-avrix-scope-mode":"anyOf","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. The reservation runs the same order admission as `POST /orders`, `POST /orders/preview` and `POST /orders/hold` on the declaration you send (`countryCode` or `integrationOrderContext.salesCountryCode` is required, there is no default country; `expectedUnitPriceCents` or `expectedWholesaleUnitPriceCents` is compared when sent; a declared `currencyCode` and `salesChannel` are checked against your footprint and the agreement), so a slot is never reserved for a sale commit refuses for a reason you control. The slot binds the admitted price and currency, which is what `POST /orders/commit` compares against. Error codes (422 unless noted, `details.reserveError`): SALES_COUNTRY_REQUIRED, CATALOG_PRICE_NOT_SET, CATALOG_PRICE_MISMATCH (409), INVALID_CATALOG_PRICE, EXPECTED_PRICE_CONFLICT, TERRITORY_NOT_ALLOWED_FOR_SKU, TERRITORY_NOT_GRANTED, TERRITORY_EXCLUDED_FOR_RELEASE, SKU_REGION_UNRESOLVED, COUNTRY_RESTRICTED, REGION_LOCKED_FOR_SKU, REGION_LOCKED_FOR_CONTRACT, FOOTPRINT_COUNTRY_NOT_DECLARED, FOOTPRINT_CURRENCY_NOT_DECLARED, CURRENCY_NOT_PRICED_FOR_COUNTRY, CURRENCY_NOT_PERMITTED_BY_TERM, SALES_CHANNEL_NOT_PERMITTED, CONSUMER_IP_REQUIRED, CONSUMER_IP_INVALID, CONSUMER_GEO_MISMATCH, CONSUMER_IP_HIGH_RISK, CONSUMER_GEO_UNAVAILABLE (503), CONSUMER_GEO_ATTEST_REQUIRED, CONSUMER_RISK_HIGH, CONSUMER_RISK_UNAVAILABLE (503). See `https://docs.avrix.io/seller-api/territory` and `https://docs.avrix.io/seller-api/creating-orders`.","parameters":[{"$ref":"#/components/parameters/IdempotencyKey"},{"$ref":"#/components/parameters/AvrixApiVersion"},{"$ref":"#/components/parameters/RequestId"},{"$ref":"#/components/parameters/SandboxSimulateCheckout"}],"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`.","headers":{"X-Request-Id":{"$ref":"#/components/headers/XRequestId"},"X-Avrix-Api-Version":{"$ref":"#/components/headers/XAvrixApiVersion"},"X-Api-Version":{"$ref":"#/components/headers/XApiVersion"},"Idempotency-Replayed":{"$ref":"#/components/headers/IdempotencyReplayed"},"X-RateLimit-Limit":{"$ref":"#/components/headers/XRateLimitLimit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/XRateLimitRemaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/XRateLimitReset"},"X-RateLimit-Bucket":{"$ref":"#/components/headers/XRateLimitBucket"}},"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`."},"riskWarning":{"$ref":"#/components/schemas/RiskWarning"},"remainingSlots":{"type":"integer","description":"Approximate remaining hot-drop slots after this reservation."},"orderReference":{"type":["string","null"]},"geoWarning":{"$ref":"#/components/schemas/GeoWarning","description":"Present only while consumer geo runs in monitor mode (`whoami.capabilities.consumerGeoMonitorEnabled`) and the buyer IP check would have denied the reservation under enforcement. Additive: the reservation still succeeded. Omitted otherwise."}}}}},"example":{"data":{"type":"reservation","reservationId":"35e95216-ec11-476d-87ae-ff21f19db6a2","allocationId":"8115d79d-d9e6-42d4-8af3-45a2af7ae8c5","quantity":12,"expiresAt":"2026-11-02T09:30:00Z","expiresInSeconds":300,"remainingSlots":12,"orderReference":"store-order-10432"}}}}},"400":{"description":"Request missing `skuId`/`skuCode`/`allocationId`. Also returned when the `Idempotency-Key` header is missing or malformed: `IDEMPOTENCY_KEY_REQUIRED` on contract date `2026-12-01` and later, `BAD_REQUEST` on earlier dates. Also returned for an `X-Avrix-Api-Version` this API does not serve (`UNSUPPORTED_API_VERSION`).","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. `CATALOG_PRICE_MISMATCH`: the `expectedUnitPriceCents` you sent does not match the territory catalog list price, the same code and status as on `POST /orders/preview`, `POST /orders/hold` and `POST /orders`; no slot is reserved. Also returned for the `Idempotency-Key` itself: `IDEMPOTENCY_KEY_MISMATCH` (the key was already used with a different body) and `IDEMPOTENCY_REQUEST_IN_FLIGHT` (an earlier request with this key is still running; retry after `Retry-After` seconds).","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"}}}},"413":{"$ref":"#/components/responses/SellerApiPayloadTooLarge"},"422":{"description":"Validation failed (malformed body or invalid `quantity`), or a refusal of the shared order admission on an API allocation; `details.reserveError` carries the code and the operation description lists them. Every code answers the same status as on `POST /orders`.","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. `CONSUMER_GEO_UNAVAILABLE` or `CONSUMER_RISK_UNAVAILABLE`: the buyer network or risk check could not run. In every case retry after `Retry-After` seconds with the same Idempotency-Key. Also returned when a platform dependency is temporarily unavailable (`SERVICE_UNAVAILABLE`) and, on a write that sends an `Idempotency-Key`, when the claim cannot be recorded (`IDEMPOTENCY_STORE_UNAVAILABLE`). Retry after `Retry-After` seconds.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"504":{"$ref":"#/components/responses/SellerApiTimeout"}},"security":[{"bearerAuth":[]}],"x-avrix-scopes":["seller:orders:write","seller:keys:pull"],"x-avrix-tier":"orders","x-avrix-rate-limit-class":"orders","x-avrix-scope-mode":"anyOf","tags":["Orders"],"operationId":"reserveOrder"}},"/api/seller/v1/orders/commit":{"post":{"summary":"Commit a hot-drop reservation","description":"**Deprecated name.** Use `POST /orders/reservations/{reservationId}/commit`, which runs the same handler. This path keeps working; nothing is scheduled for removal.\n\nFinalise 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":[{"$ref":"#/components/parameters/IdempotencyKey"},{"$ref":"#/components/parameters/AvrixApiVersion"},{"$ref":"#/components/parameters/RequestId"},{"$ref":"#/components/parameters/SandboxSimulate"}],"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":"0b9f4c1e-6a57-4d1c-9a55-2f1f0c3d7e42"}}}},"responses":{"200":{"description":"Reservation committed. Shape depends on `type`: `fulfilled` returns real keys, `pre-order` returns reserved counts with release window.","headers":{"X-Request-Id":{"$ref":"#/components/headers/XRequestId"},"X-Avrix-Api-Version":{"$ref":"#/components/headers/XAvrixApiVersion"},"X-Api-Version":{"$ref":"#/components/headers/XApiVersion"},"Idempotency-Replayed":{"$ref":"#/components/headers/IdempotencyReplayed"},"X-RateLimit-Limit":{"$ref":"#/components/headers/XRateLimitLimit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/XRateLimitRemaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/XRateLimitReset"},"X-RateLimit-Bucket":{"$ref":"#/components/headers/XRateLimitBucket"}},"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","description":"Plaintext codes (`string`) up to contract date 2026-09-01; typed key objects from 2026-10-01 (`X-Avrix-Api-Version`). Same order as `keyIds`.","items":{"$ref":"#/components/schemas/SellerDeliveredKey"}},"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","deprecated":true,"description":"Deprecated: use `orderId`. On contract date `2026-12-01` and later this is always the same value as `orderId`. On older dates it is the id of the order's first key pull, which differs from `orderId` for an order placed before this change shipped (changelog, `2026-12-01`) and for a pre-order delivered later. Both values keep resolving on every order lookup."},"orderId":{"type":"string","description":"The order's id (`ord_` plus eight characters). One value for the life of the order: the same in the create response, `GET /orders`, `GET /orders/{orderId}`, the bulk line and the `order.fulfilled` webhook. Store this one. Every endpoint that addresses an order (`GET /orders/{orderId}`, `GET /orders?orderReadableId=`, `POST /orders/{orderId}/fulfill`, key replacement) accepts it."},"geoWarning":{"$ref":"#/components/schemas/GeoWarning","description":"Only on `api` business-model allocations, and only when the buyer IP check flagged the sale without refusing it: consumer geo in monitor mode (`whoami.capabilities.consumerGeoMonitorEnabled`) with a would-be denial, or — under enforcement — a `CONSUMER_GEO_MISMATCH` / `CONSUMER_IP_HIGH_RISK` that the Content Owner's agreement geo policy lets through (`warn` or `settle_at_evidence`). Additive: the order still succeeded. Omitted otherwise."},"warnings":{"type":"array","items":{"type":"string"},"description":"Settlement warnings for this delivery, same vocabulary and meaning as `POST /orders` `warnings` (e.g. `vat_declared_rate_below_expected`). Absent when nothing was flagged."}}},{"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"},"geoWarning":{"$ref":"#/components/schemas/GeoWarning","description":"Only on `api` business-model allocations, and only when the buyer IP check flagged the sale without refusing it: consumer geo in monitor mode (`whoami.capabilities.consumerGeoMonitorEnabled`) with a would-be denial, or — under enforcement — a `CONSUMER_GEO_MISMATCH` / `CONSUMER_IP_HIGH_RISK` that the Content Owner's agreement geo policy lets through (`warn` or `settle_at_evidence`). Additive: the reservation still succeeded. Omitted otherwise."}},"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"}}},"example":{"data":{"type":"fulfilled","allocationId":"86ee5c36-8025-4d10-808b-15e23b6687f6","orderReference":"store-order-10432","keys":["XXXXX-XXXXX-XXXXX-XXXXX"],"keyIds":["09f897e2-04b4-4ccf-851a-a44e9a6cc294"],"pulled":12,"fulfilledAt":"2026-11-02T09:30:00Z","orderId":"ord_a9s7uz9y","warnings":["example_warning"]},"contractTermId":"84292b34-365e-4177-8c5c-ef13ee9a9229","contractTermVersion":1}}}},"400":{"$ref":"#/components/responses/SellerApiIdempotencyKeyRequired"},"401":{"$ref":"#/components/responses/SellerApiUnauthorized"},"402":{"description":"`PAYMENT_NOT_CLEARED` or `INSUFFICIENT_WALLET_BALANCE`: your settlement position with Avrix does not allow this sale. The reservation is released.","headers":{"X-Request-Id":{"$ref":"#/components/headers/XRequestId"},"X-Avrix-Api-Version":{"$ref":"#/components/headers/XAvrixApiVersion"},"X-Api-Version":{"$ref":"#/components/headers/XApiVersion"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"403":{"$ref":"#/components/responses/SellerApiForbidden"},"404":{"description":"`SKU_NOT_FOUND`, `PRODUCT_NOT_SELLABLE`, `ALLOCATION_NOT_FOUND` or `ALLOCATION_INACTIVE`: what the reservation was for can no longer be sold. The reservation is released.","headers":{"X-Request-Id":{"$ref":"#/components/headers/XRequestId"},"X-Avrix-Api-Version":{"$ref":"#/components/headers/XAvrixApiVersion"},"X-Api-Version":{"$ref":"#/components/headers/XApiVersion"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"409":{"description":"`ALLOCATION_NOT_AVAILABLE` — the underlying allocation is no longer active or no longer in hot-drop mode. The reservation is released. Also returned for the `Idempotency-Key` itself: `IDEMPOTENCY_KEY_MISMATCH` (the key was already used with a different body) and `IDEMPOTENCY_REQUEST_IN_FLIGHT` (an earlier request with this key is still running; retry after `Retry-After` seconds).","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"}}}},"412":{"description":"`HOT_DROP_NOT_ENABLED`: hot-drop is not enabled for your allocations, so there is no reservation to commit. Use `POST /orders`. `POST /orders/reserve` answers the same.","headers":{"X-Request-Id":{"$ref":"#/components/headers/XRequestId"},"X-Avrix-Api-Version":{"$ref":"#/components/headers/XAvrixApiVersion"},"X-Api-Version":{"$ref":"#/components/headers/XApiVersion"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"413":{"$ref":"#/components/responses/SellerApiPayloadTooLarge"},"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"},"503":{"$ref":"#/components/responses/SellerApiServiceUnavailable"},"504":{"$ref":"#/components/responses/SellerApiTimeout"}},"security":[{"bearerAuth":[]}],"x-avrix-scopes":["seller:orders:write","seller:keys:pull"],"x-avrix-tier":"orders","x-avrix-rate-limit-class":"orders","x-avrix-scope-mode":"anyOf","tags":["Orders"],"operationId":"commitOrder","deprecated":true}},"/api/seller/v1/orders/reservations/{reservationId}/commit":{"post":{"summary":"Commit a hot-drop reservation","description":"Turn a hot-drop reservation into an order; the reservation is named in the path. The body carries the same optional fields as `POST /orders/commit` (`metadata`, `integrationOrderContext`, `consumerGeoAttestId`), and `reservationId` may be left out. A body that also sends the id must send the same one: a different value is refused with 422 `VALIDATION_FAILED` naming the field.\n\nThe same handler, idempotency and responses as `POST /orders/commit`, which takes `reservationId` in the body and is the deprecated name of this operation.","parameters":[{"name":"reservationId","in":"path","required":true,"description":"The reservation to commit: `reservationId` from `POST /orders/reserve`.","schema":{"type":"string","format":"uuid"}},{"$ref":"#/components/parameters/IdempotencyKey"},{"$ref":"#/components/parameters/AvrixApiVersion"},{"$ref":"#/components/parameters/RequestId"},{"$ref":"#/components/parameters/SandboxSimulate"}],"requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{"reservationId":{"type":"string","format":"uuid","description":"Optional here: the path names the reservation. When sent, it must equal the path value."},"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":{}}}},"responses":{"200":{"description":"Reservation committed. Shape depends on `type`: `fulfilled` returns real keys, `pre-order` returns reserved counts with release window.","headers":{"X-Request-Id":{"$ref":"#/components/headers/XRequestId"},"X-Avrix-Api-Version":{"$ref":"#/components/headers/XAvrixApiVersion"},"X-Api-Version":{"$ref":"#/components/headers/XApiVersion"},"Idempotency-Replayed":{"$ref":"#/components/headers/IdempotencyReplayed"},"X-RateLimit-Limit":{"$ref":"#/components/headers/XRateLimitLimit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/XRateLimitRemaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/XRateLimitReset"},"X-RateLimit-Bucket":{"$ref":"#/components/headers/XRateLimitBucket"}},"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","description":"Plaintext codes (`string`) up to contract date 2026-09-01; typed key objects from 2026-10-01 (`X-Avrix-Api-Version`). Same order as `keyIds`.","items":{"$ref":"#/components/schemas/SellerDeliveredKey"}},"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","deprecated":true,"description":"Deprecated: use `orderId`. On contract date `2026-12-01` and later this is always the same value as `orderId`. On older dates it is the id of the order's first key pull, which differs from `orderId` for an order placed before this change shipped (changelog, `2026-12-01`) and for a pre-order delivered later. Both values keep resolving on every order lookup."},"orderId":{"type":"string","description":"The order's id (`ord_` plus eight characters). One value for the life of the order: the same in the create response, `GET /orders`, `GET /orders/{orderId}`, the bulk line and the `order.fulfilled` webhook. Store this one. Every endpoint that addresses an order (`GET /orders/{orderId}`, `GET /orders?orderReadableId=`, `POST /orders/{orderId}/fulfill`, key replacement) accepts it."},"geoWarning":{"$ref":"#/components/schemas/GeoWarning","description":"Only on `api` business-model allocations, and only when the buyer IP check flagged the sale without refusing it: consumer geo in monitor mode (`whoami.capabilities.consumerGeoMonitorEnabled`) with a would-be denial, or — under enforcement — a `CONSUMER_GEO_MISMATCH` / `CONSUMER_IP_HIGH_RISK` that the Content Owner's agreement geo policy lets through (`warn` or `settle_at_evidence`). Additive: the order still succeeded. Omitted otherwise."},"warnings":{"type":"array","items":{"type":"string"},"description":"Settlement warnings for this delivery, same vocabulary and meaning as `POST /orders` `warnings` (e.g. `vat_declared_rate_below_expected`). Absent when nothing was flagged."}}},{"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"},"geoWarning":{"$ref":"#/components/schemas/GeoWarning","description":"Only on `api` business-model allocations, and only when the buyer IP check flagged the sale without refusing it: consumer geo in monitor mode (`whoami.capabilities.consumerGeoMonitorEnabled`) with a would-be denial, or — under enforcement — a `CONSUMER_GEO_MISMATCH` / `CONSUMER_IP_HIGH_RISK` that the Content Owner's agreement geo policy lets through (`warn` or `settle_at_evidence`). Additive: the reservation still succeeded. Omitted otherwise."}},"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"}}},"example":{"data":{"type":"fulfilled","allocationId":"69f4bd3e-20e1-414b-806c-01ec0ce8ed1a","orderReference":"store-order-10432","keys":["XXXXX-XXXXX-XXXXX-XXXXX"],"keyIds":["b6d7b421-88a8-4b50-8c06-cfed92b28978"],"pulled":12,"fulfilledAt":"2026-11-02T09:30:00Z","orderId":"ord_cysr5dde","warnings":["example_warning"]},"contractTermId":"5d36b545-f7f9-4885-8668-00b4cf2d9723","contractTermVersion":1}}}},"400":{"$ref":"#/components/responses/SellerApiIdempotencyKeyRequired"},"401":{"$ref":"#/components/responses/SellerApiUnauthorized"},"402":{"description":"`PAYMENT_NOT_CLEARED` or `INSUFFICIENT_WALLET_BALANCE`: your settlement position with Avrix does not allow this sale. The reservation is released.","headers":{"X-Request-Id":{"$ref":"#/components/headers/XRequestId"},"X-Avrix-Api-Version":{"$ref":"#/components/headers/XAvrixApiVersion"},"X-Api-Version":{"$ref":"#/components/headers/XApiVersion"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"403":{"$ref":"#/components/responses/SellerApiForbidden"},"404":{"description":"`SKU_NOT_FOUND`, `PRODUCT_NOT_SELLABLE`, `ALLOCATION_NOT_FOUND` or `ALLOCATION_INACTIVE`: what the reservation was for can no longer be sold. The reservation is released.","headers":{"X-Request-Id":{"$ref":"#/components/headers/XRequestId"},"X-Avrix-Api-Version":{"$ref":"#/components/headers/XAvrixApiVersion"},"X-Api-Version":{"$ref":"#/components/headers/XApiVersion"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"409":{"description":"`ALLOCATION_NOT_AVAILABLE` — the underlying allocation is no longer active or no longer in hot-drop mode. The reservation is released. Also returned for the `Idempotency-Key` itself: `IDEMPOTENCY_KEY_MISMATCH` (the key was already used with a different body) and `IDEMPOTENCY_REQUEST_IN_FLIGHT` (an earlier request with this key is still running; retry after `Retry-After` seconds).","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"}}}},"412":{"description":"`HOT_DROP_NOT_ENABLED`: hot-drop is not enabled for your allocations, so there is no reservation to commit. Use `POST /orders`. `POST /orders/reserve` answers the same.","headers":{"X-Request-Id":{"$ref":"#/components/headers/XRequestId"},"X-Avrix-Api-Version":{"$ref":"#/components/headers/XAvrixApiVersion"},"X-Api-Version":{"$ref":"#/components/headers/XApiVersion"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"413":{"$ref":"#/components/responses/SellerApiPayloadTooLarge"},"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"},"503":{"$ref":"#/components/responses/SellerApiServiceUnavailable"},"504":{"$ref":"#/components/responses/SellerApiTimeout"}},"security":[{"bearerAuth":[]}],"x-avrix-scopes":["seller:orders:write","seller:keys:pull"],"x-avrix-tier":"orders","x-avrix-rate-limit-class":"orders","x-avrix-scope-mode":"anyOf","tags":["Orders"],"operationId":"commitReservation"}},"/api/seller/v1/orders/preview":{"post":{"summary":"Preview order (price + fulfillment estimate)","description":"**Scopes:** `seller:orders:preview`, `seller:orders:write` or the legacy `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, CONSUMER_GEO_ATTEST_REQUIRED, CONSUMER_RISK_HIGH, CONSUMER_RISK_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 **true**; a Content Owner can opt its products out). Without it, 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).","parameters":[{"$ref":"#/components/parameters/AvrixApiVersion"},{"$ref":"#/components/parameters/RequestId"},{"$ref":"#/components/parameters/SandboxSimulateCheckout"}],"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). A malformed address, or a private, loopback, link-local or carrier-NAT one, is refused at parse time with 422 `CONSUMER_IP_INVALID` on every surface. On production keys, the calling server's own address or one matching the key's IP allowlist is also refused with 422 `CONSUMER_IP_INVALID` (the buyer, not the store). 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."},"expectedUnitPriceCents":{"type":"integer","minimum":1,"description":"Optional echo of the unit price you expect, compared exactly as `POST /orders/hold` and `POST /orders` compare it. On an API-model line that does not match the territory catalog list price, preview refuses with **409** `CATALOG_PRICE_MISMATCH` (`details.previewError`) instead of quoting. Omit it to receive the current quote."},"expectedWholesaleUnitPriceCents":{"type":"integer","minimum":1,"description":"Deprecated alias of expectedUnitPriceCents (removal planned for v2). When both are sent they must be equal.","deprecated":true}},"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","headers":{"Server-Timing":{"description":"Phase breakdown of this response in milliseconds, one entry per phase that ran: auth, idempotency, sku-resolve, allocation, availability, authority, term, geo, price, settlement, rpc, decrypt, billing, idempotency-commit, then total. Use it to attribute a slow response; the same phases are logged server-side above the platform threshold. Phase names are stable.","schema":{"type":"string"}},"X-Request-Id":{"$ref":"#/components/headers/XRequestId"},"X-Avrix-Api-Version":{"$ref":"#/components/headers/XAvrixApiVersion"},"X-Api-Version":{"$ref":"#/components/headers/XApiVersion"},"X-RateLimit-Limit":{"$ref":"#/components/headers/XRateLimitLimit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/XRateLimitRemaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/XRateLimitReset"},"X-RateLimit-Bucket":{"$ref":"#/components/headers/XRateLimitBucket"}},"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`."},"heldQuantity":{"type":["integer","null"],"description":"Keys inside live checkout holds right now; `null` when the hold ledger could not be read."},"sellableNow":{"type":"integer","description":"`available` (min of allocation headroom and inventory) minus `heldQuantity`: what `POST /orders` can take right now."},"maxFulfillableQuantity":{"type":"integer","description":"Maximum quantity fulfillable now (same as available for immediate fulfillment) Net of live checkout holds (same as `sellableNow`) since 2026-09-22."},"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":"Deprecated name of `unitPriceMinor` (same value). Kept on the wire; see Naming conventions in the Versioning and compatibility guide. Effective unit price to echo as `expectedUnitPriceCents`. Already includes any settlement promo (see `promo`).","deprecated":true},"unitPriceMinor":{"type":["integer","null"],"description":"Effective unit price to echo as `expectedUnitPriceCents`. Already includes any settlement promo (see `promo`). Same amount as `unitPriceCents`, under the `...Minor` name every Seller API amount uses: integer minor units of the currency beside it (see `currencyExponent`)."},"lineTotalCents":{"type":["integer","null"],"deprecated":true,"description":"Deprecated name of `lineTotalMinor` (same value). Kept on the wire; see Naming conventions in the Versioning and compatibility guide."},"lineTotalMinor":{"type":["integer","null"],"description":"Same amount as `lineTotalCents`, under the `...Minor` name every Seller API amount uses: integer minor units of the currency beside it (see `currencyExponent`)."},"currencyCode":{"type":["string","null"]},"currencyExponent":{"type":["integer","null"],"minimum":0,"maximum":3,"description":"Number of minor-unit digits for `currencyCode`: 2 for USD, 0 for JPY, 3 for KWD. amount = cents / 10^currencyExponent; `null` when `currencyCode` is `null`."},"initialUnitPriceCents":{"type":["integer","null"],"description":"Deprecated name of `initialUnitPriceMinor` (same value). Kept on the wire; see Naming conventions in the Versioning and compatibility guide. Catalog list unit price before any settlement promo. Equal to `unitPriceCents` when no promo applies.","deprecated":true},"initialUnitPriceMinor":{"type":["integer","null"],"description":"Catalog list unit price before any settlement promo. Equal to `unitPriceCents` when no promo applies. Same amount as `initialUnitPriceCents`, under the `...Minor` name every Seller API amount uses: integer minor units of the currency beside it (see `currencyExponent`)."},"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). Describes the settlement axis only — a live list-price promotion is reported as `listPromo`."},"listPromo":{"anyOf":[{"$ref":"#/components/schemas/ListPromoRef"},{"type":"null"}],"description":"Live list-price promotion (`priceEffect` `list_price` or `both`) the vendor asks you to advertise for this SKU, or null. `listPromo` itself never changes `unitPriceCents`; a `both` promotion (the default) also appears as `promo`, which does. Also reported on a quote in a permitted secondary currency, where no settlement promo applies. Null when `promoResolution` is `unavailable`: re-preview before rendering a sale badge."},"advertisedUnitPriceCents":{"type":["integer","null"],"description":"Deprecated name of `advertisedUnitPriceMinor` (same value). Kept on the wire; see Naming conventions in the Versioning and compatibility guide. `initialUnitPriceCents` with `listPromo` applied — the was/now \"now\" for your product page (render `initialUnitPriceCents` as \"was\"). Equal to `initialUnitPriceCents` when no list-price promo is live. API business model only: null on wholesale and revenue-share lines, whose `unitPriceCents` is your negotiated cost rather than the territory list price (apply `listPromo.discountPercent` to `GET /products/{id}/pricing` there); null when the price is null.","deprecated":true},"advertisedUnitPriceMinor":{"type":["integer","null"],"description":"`initialUnitPriceCents` with `listPromo` applied — the was/now \"now\" for your product page (render `initialUnitPriceCents` as \"was\"). Equal to `initialUnitPriceCents` when no list-price promo is live. API business model only: null on wholesale and revenue-share lines, whose `unitPriceCents` is your negotiated cost rather than the territory list price (apply `listPromo.discountPercent` to `GET /products/{id}/pricing` there); null when the price is null. Same amount as `advertisedUnitPriceCents`, under the `...Minor` name every Seller API amount uses: integer minor units of the currency beside it (see `currencyExponent`)."},"activation":{"$ref":"#/components/schemas/SkuActivation"}}}},"totalCents":{"type":["integer","null"],"deprecated":true,"description":"Deprecated name of `totalMinor` (same value). Kept on the wire; see Naming conventions in the Versioning and compatibility guide."},"totalMinor":{"type":["integer","null"],"description":"Same amount as `totalCents`, under the `...Minor` name every Seller API amount uses: integer minor units of the currency beside it (see `currencyExponent`)."},"currencyCode":{"type":["string","null"]},"currencyExponent":{"type":["integer","null"],"minimum":0,"maximum":3,"description":"Number of minor-unit digits for `currencyCode`: 2 for USD, 0 for JPY, 3 for KWD. amount = cents / 10^currencyExponent; `null` when `currencyCode` is `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."},"riskWarning":{"$ref":"#/components/schemas/RiskWarning"},"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`. Treat it as opaque: its length and contents may change, so store and forward it as-is and never parse it."},"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.*). It carries the promotion the price was quoted under, so a commit after the promotion ended still records it. Treat it as opaque: its length and contents may change, so store and forward it as-is and never parse it."},"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","COMMIT_FIELDS_MISSING"]},"description":"Advisory warnings. `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 a line's guaranteed activation set and the sale's activation policy is warn (a Content Owner opted its SKUs down). Under enforce_known, the default, or enforce_strict this condition is a 422 instead of a warning. enforce_strict also returns 422 ACTIVATION_REGION_UNKNOWN when coverage is absent. `COMMIT_FIELDS_MISSING` — POST /orders would refuse this body until the fields in `commitRequirements.missing` are added."},"commitRequirements":{"type":"object","required":["missing"],"description":"Every integrationOrderContext field POST /orders will still refuse without for this key and allocation (payment-time fields a quote cannot demand: the charged amounts, the tax split, the payment method and processor reference, the checkout session). Each entry is a path such as `integrationOrderContext.paymentProcessorReference`. Empty when the body already carries everything the commit needs. Quote-time fields (the sale country; on a production key the buyer's consumerIp or a consumerGeoAttestId) are refused by the quote itself with the commit's 422 VALIDATION_FAILED.","properties":{"missing":{"type":"array","items":{"type":"string"}}}},"geoWarning":{"$ref":"#/components/schemas/GeoWarning","description":"Present only while consumer geo runs in monitor mode (`whoami.capabilities.consumerGeoMonitorEnabled`) and the buyer IP check would deny the order under enforcement. Additive: the preview still returned 200. Omitted otherwise."},"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"},"currencyExponent":{"type":["integer","null"],"minimum":0,"maximum":3,"example":2,"description":"Number of minor-unit digits for `currency`: 2 for USD, 0 for JPY, 3 for KWD. amount = minor / 10^currencyExponent; `null` when `currency` is `null`."},"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 and your own registered country's rate lowered the declared rate; `declared_within_store_cap` means the same missing evidence with a declared rate at or under that cap, applied as declared."},"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,"unitPriceMinor":999,"lineTotalCents":999,"lineTotalMinor":999,"currencyCode":"USD","currencyExponent":2,"initialUnitPriceCents":999,"initialUnitPriceMinor":999,"promo":null,"promoResolution":"none","listPromo":null,"advertisedUnitPriceCents":999,"advertisedUnitPriceMinor":999}],"totalCents":999,"totalMinor":999,"currencyCode":"USD","currencyExponent":2,"estimateOnly":true}}}}},"400":{"description":"`UNSUPPORTED_API_VERSION`: the `X-Avrix-Api-Version` request header names a contract date this API does not serve. `details.supportedVersions` lists the dates you can pin and `details.requestedVersion` repeats what you sent. Nothing was read or changed. Send a listed date, or omit the header to be served on the stamped default.\n\n`BAD_REQUEST` on contract date `2026-12-01` and later when the allocation is paused or otherwise inactive: the message and `details` (`orderStage: allocation`, `allocationResolve: NO_ACTIVE_ALLOCATION`, `allocationStatus`, `previewError: ALLOCATION_INACTIVE`) that `POST /orders` returns for the same order. Earlier dates and unpinned requests answer `404 ALLOCATION_INACTIVE`.","headers":{"X-Request-Id":{"$ref":"#/components/headers/XRequestId"},"X-Avrix-Api-Version":{"$ref":"#/components/headers/XAvrixApiVersion"},"X-Api-Version":{"$ref":"#/components/headers/XApiVersion"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"401":{"$ref":"#/components/responses/SellerApiUnauthorized"},"402":{"description":"**`PAYMENT_NOT_CLEARED`**: the allocation's payment has not cleared for its model (wholesale and pre-order grants need confirmed payment), so `POST /orders` would refuse with the same code and status. `details.previewError` carries the code. The allocation's `readinessBlockers` on `GET /allocations` names it in advance.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"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`), and `PRODUCT_NOT_SELLABLE` when the product is not open for sale. On contract date `2026-12-01` and later, a paused or otherwise inactive allocation answers `400 BAD_REQUEST` as `POST /orders` does instead of `404 ALLOCATION_INACTIVE`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"409":{"description":"**`CATALOG_PRICE_MISMATCH`**: the `expectedUnitPriceCents` you sent does not match the territory catalog list price of an API-model line. Same code and status as `POST /orders/hold` and `POST /orders`; no quote is returned. Re-run preview without the echo to read the current price.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"413":{"$ref":"#/components/responses/SellerApiPayloadTooLarge"},"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`**.\n\nAlso every refusal of the shared order admission, which preview runs on the declaration you send exactly as `POST /orders` runs it (`details.previewError` carries the code): `SALES_COUNTRY_REQUIRED`, `CATALOG_PRICE_NOT_SET`, `INVALID_CATALOG_PRICE`, `TERRITORY_NOT_ALLOWED_FOR_SKU`, `TERRITORY_NOT_GRANTED`, `TERRITORY_EXCLUDED_FOR_RELEASE`, `SKU_REGION_UNRESOLVED`, `COUNTRY_RESTRICTED`, `REGION_LOCKED_FOR_SKU`, `REGION_LOCKED_FOR_CONTRACT`, `FOOTPRINT_COUNTRY_NOT_DECLARED`, `FOOTPRINT_CURRENCY_NOT_DECLARED`, `CURRENCY_NOT_PRICED_FOR_COUNTRY`, `CURRENCY_NOT_PERMITTED_BY_TERM`, `SALES_CHANNEL_NOT_PERMITTED`, `CURRENCY_MISMATCH`, `TAX_DECLARATION_REQUIRED`, `SALES_CHANNEL_REQUIRED`, `VAT_DECLARATION_BELOW_REFERENCE`, `MINIMUM_ORDER_VIOLATION`, plus the consumer-geo codes. Every code answers the same status as on `POST /orders`. A preview that answers 200 is not refused by `POST /orders` for any of these.","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, or `CONSUMER_GEO_UNAVAILABLE` / `CONSUMER_RISK_UNAVAILABLE` when the buyer network check could not run. Also returned when a platform dependency is temporarily unavailable (`SERVICE_UNAVAILABLE`) and, on a write that sends an `Idempotency-Key`, when the claim cannot be recorded (`IDEMPOTENCY_STORE_UNAVAILABLE`). Retry after `Retry-After` seconds.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"504":{"$ref":"#/components/responses/SellerApiTimeout"}},"security":[{"bearerAuth":[]}],"x-avrix-scopes":["seller:orders:preview","seller:orders:write","seller:keys:pull"],"x-avrix-tier":"orders","x-avrix-rate-limit-class":"orders","x-avrix-scope-mode":"anyOf","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. The hold runs the same order admission as `POST /orders` on the declaration you send (`countryCode` or `integrationOrderContext.salesCountryCode` is required; a declared `currencyCode` and `salesChannel` are checked against your footprint and the agreement), so a hold is never granted for a sale commit refuses for a reason you control. Error codes (422, `details.holdError`): SALES_COUNTRY_REQUIRED, CATALOG_PRICE_NOT_SET, CATALOG_PRICE_MISMATCH, INVALID_CATALOG_PRICE, TERRITORY_NOT_ALLOWED_FOR_SKU, TERRITORY_NOT_GRANTED, TERRITORY_EXCLUDED_FOR_RELEASE, SKU_REGION_UNRESOLVED, COUNTRY_RESTRICTED, REGION_LOCKED_FOR_SKU, REGION_LOCKED_FOR_CONTRACT, FOOTPRINT_COUNTRY_NOT_DECLARED, FOOTPRINT_CURRENCY_NOT_DECLARED, CURRENCY_NOT_PRICED_FOR_COUNTRY, CURRENCY_NOT_PERMITTED_BY_TERM, SALES_CHANNEL_NOT_PERMITTED, CONSUMER_IP_REQUIRED, CONSUMER_IP_INVALID, CONSUMER_GEO_MISMATCH, CONSUMER_IP_HIGH_RISK, CONSUMER_GEO_UNAVAILABLE, CONSUMER_GEO_ATTEST_REQUIRED, CONSUMER_RISK_HIGH, CONSUMER_RISK_UNAVAILABLE. 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","orderReference":"store-order-10432","expectedUnitPriceCents":5999}}}},"responses":{"200":{"description":"Hold created","headers":{"X-Request-Id":{"$ref":"#/components/headers/XRequestId"},"X-Avrix-Api-Version":{"$ref":"#/components/headers/XAvrixApiVersion"},"X-Api-Version":{"$ref":"#/components/headers/XApiVersion"},"Idempotency-Replayed":{"$ref":"#/components/headers/IdempotencyReplayed"},"X-RateLimit-Limit":{"$ref":"#/components/headers/XRateLimitLimit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/XRateLimitRemaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/XRateLimitReset"},"X-RateLimit-Bucket":{"$ref":"#/components/headers/XRateLimitBucket"}},"content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","required":["type","holdId","expiresAt","expiresInSeconds","allocationId","checkoutHoldId"],"properties":{"type":{"type":"string","enum":["checkout_hold"]},"holdId":{"type":"string","format":"uuid","description":"The hold. Send it to POST /orders as `checkoutHoldId` (or `holdId`), read it with `GET /orders/hold/{holdId}`, release it with DELETE /orders/hold."},"checkoutHoldId":{"type":"string","format":"uuid","description":"Same value as `holdId`, under the name POST /orders takes it (`checkoutHoldId`; `holdId` is accepted there as an alias)."},"expiresAt":{"type":"string","format":"date-time","description":"When the hold ends unless POST /orders consumes it or DELETE releases it first. The lifetime is a platform setting (30 minutes by default) and cannot be chosen per request."},"expiresInSeconds":{"type":"integer","description":"Seconds until `expiresAt`."},"allocationId":{"type":"string","format":"uuid","description":"The allocation the units are held on."},"maxFulfillableQuantity":{"type":"integer","description":"Units you could order on this allocation now, counting this hold's units."},"commitRequirements":{"type":"object","required":["missing"],"description":"Every integrationOrderContext field POST /orders will still refuse without for this key and allocation (payment-time fields a quote cannot demand: the charged amounts, the tax split, the payment method and processor reference, the checkout session). Each entry is a path such as `integrationOrderContext.paymentProcessorReference`. Empty when the body already carries everything the commit needs. Quote-time fields (the sale country; on a production key the buyer's consumerIp or a consumerGeoAttestId) are refused by the quote itself with the commit's 422 VALIDATION_FAILED.","properties":{"missing":{"type":"array","items":{"type":"string"}}}},"riskWarning":{"$ref":"#/components/schemas/RiskWarning"},"unitPriceCents":{"type":"integer","description":"Deprecated name of `unitPriceMinor` (same value). Kept on the wire; see Naming conventions in the Versioning and compatibility guide. Bound effective unit price for API allocations (settlement promo already applied; honored on POST /orders while the hold is valid). Echo it as `expectedUnitPriceCents`.","deprecated":true},"unitPriceMinor":{"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`. Same amount as `unitPriceCents`, under the `...Minor` name every Seller API amount uses: integer minor units of the currency beside it (see `currencyExponent`)."},"initialUnitPriceCents":{"type":"integer","description":"Deprecated name of `initialUnitPriceMinor` (same value). Kept on the wire; see Naming conventions in the Versioning and compatibility guide. Catalog list unit price before any settlement promo. Equal to `unitPriceCents` when no promo applies.","deprecated":true},"initialUnitPriceMinor":{"type":"integer","description":"Catalog list unit price before any settlement promo. Equal to `unitPriceCents` when no promo applies. Same amount as `initialUnitPriceCents`, under the `...Minor` name every Seller API amount uses: integer minor units of the currency beside it (see `currencyExponent`)."},"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). Describes the settlement axis only — a live list-price promotion is reported as `listPromo`."},"listPromo":{"anyOf":[{"$ref":"#/components/schemas/ListPromoRef"},{"type":"null"}],"description":"Live list-price promotion (`priceEffect` `list_price` or `both`) the vendor asks you to advertise for this SKU at hold time, or null. `listPromo` itself never changes the bound `unitPriceCents`; a `both` promotion (the default) also appears as `promo`, which does. Not frozen into the hold: re-preview if the window ends before checkout."},"advertisedUnitPriceCents":{"type":"integer","description":"Deprecated name of `advertisedUnitPriceMinor` (same value). Kept on the wire; see Naming conventions in the Versioning and compatibility guide. `initialUnitPriceCents` with `listPromo` applied — the was/now \"now\" for your product page. Equal to `initialUnitPriceCents` when no list-price promo is live. Holds bind API-model prices only, so this is always the territory list price basis.","deprecated":true},"advertisedUnitPriceMinor":{"type":"integer","description":"`initialUnitPriceCents` with `listPromo` applied — the was/now \"now\" for your product page. Equal to `initialUnitPriceCents` when no list-price promo is live. Holds bind API-model prices only, so this is always the territory list price basis. Same amount as `advertisedUnitPriceCents`, under the `...Minor` name every Seller API amount uses: integer minor units of the currency beside it (see `currencyExponent`)."},"currencyCode":{"type":["string","null"],"description":"Currency of `unitPriceCents`; null when the hold bound no price (models other than API)."},"currencyExponent":{"type":["integer","null"],"minimum":0,"maximum":3,"description":"Number of minor-unit digits for `currencyCode`: 2 for USD, 0 for JPY, 3 for KWD. amount = cents / 10^currencyExponent; `null` when `currencyCode` is `null`."},"salesCountryCode":{"type":["string","null"],"description":"The country the price was bound for (from `countryCode` or the buyer context)."},"priceBoundAt":{"type":["string","null"],"format":"date-time","description":"When the price was bound. POST /orders charges `unitPriceCents` while the hold is live, even if the list price changed since."},"geoWarning":{"$ref":"#/components/schemas/GeoWarning","description":"Present only while consumer geo runs in monitor mode (`whoami.capabilities.consumerGeoMonitorEnabled`) and the buyer IP check would have denied the hold under enforcement, or when the agreement's `warn` / `settle_at_evidence` geo-mismatch policy recorded a disagreement. Additive: the hold was still granted. Omitted otherwise."},"skuId":{"type":"string","format":"uuid","description":"The SKU the hold is on, resolved from skuId or skuCode in the request."},"skuCode":{"type":"string","description":"SKU code of the held SKU. Empty string when the request used skuId and the allocation row carries no code."},"quantity":{"type":"integer","description":"Units held. Matches the requested quantity."},"orderReference":{"type":["string","null"],"description":"The orderReference sent with the request, echoed back; null when none was sent."},"remainingSlots":{"type":"integer","description":"Units still available to hold or order after this hold, excluding the units this hold blocks."}}}}},"example":{"data":{"type":"checkout_hold","holdId":"dc478e35-1633-4ff9-87a8-718d6088ca50","checkoutHoldId":"1bdd043f-e0f8-45cb-8910-25d12932469a","expiresAt":"2026-11-02T09:30:00Z","expiresInSeconds":300,"allocationId":"4e29935c-6045-48a9-8190-efaacca47148","maxFulfillableQuantity":12,"commitRequirements":{"missing":["example_missing"]},"unitPriceCents":2450,"initialUnitPriceCents":2450,"promo":{"sourceType":"event","sourceId":"b103e708-ee3b-4e3e-86ab-a931b42bf0a7","discountPercent":20,"priceEffect":"settlement_price","startDate":"2026-11-02T09:30:00Z","endDate":"2026-11-02T09:30:00Z"},"promoResolution":"applied","listPromo":{"sourceType":"event","sourceId":"b8839dd7-8f06-47a6-82d9-1d6a44568ad8","discountPercent":20,"priceEffect":"list_price","startDate":"2026-11-02T09:30:00Z","endDate":"2026-11-02T09:30:00Z"},"advertisedUnitPriceCents":2450,"currencyCode":"EUR","currencyExponent":2,"salesCountryCode":"DE","priceBoundAt":"2026-11-02T09:30:00Z","skuId":"dbe11a56-fa39-40c4-821a-9bbdafd51362","skuCode":"EXAMPLE-STEAM-WW","quantity":12,"orderReference":"store-order-10432","remainingSlots":12}}}}},"400":{"$ref":"#/components/responses/SellerApiIdempotencyKeyRequired"},"401":{"$ref":"#/components/responses/SellerApiUnauthorized"},"403":{"$ref":"#/components/responses/SellerApiForbidden"},"404":{"description":"HOLD_NOT_FOUND on an idempotent replay: this Idempotency-Key created a hold that is no longer live. `details.holdState` is `released`, `consumed` or `expired`; send a new Idempotency-Key to create a new hold.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"409":{"description":"Insufficient headroom for hold (`SOLD_OUT`), or a live hold already covers this `orderReference` (`HOLD_EXISTS`, with `details.holdId` and `details.expiresAt` — reuse it or release it first; a second hold for one cart is never granted), or the `expectedUnitPriceCents` you sent does not match the territory catalog list price (`CATALOG_PRICE_MISMATCH`, no hold is created). Also returned for the `Idempotency-Key` itself: `IDEMPOTENCY_KEY_MISMATCH` (the key was already used with a different body) and `IDEMPOTENCY_REQUEST_IN_FLIGHT` (an earlier request with this key is still running; retry after `Retry-After` seconds).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"412":{"description":"Checkout hold disabled on deployment","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"413":{"$ref":"#/components/responses/SellerApiPayloadTooLarge"},"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`). Also returned when a platform dependency is temporarily unavailable (`SERVICE_UNAVAILABLE`) and, on a write that sends an `Idempotency-Key`, when the claim cannot be recorded (`IDEMPOTENCY_STORE_UNAVAILABLE`). Retry after `Retry-After` seconds.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"504":{"$ref":"#/components/responses/SellerApiTimeout"}},"security":[{"bearerAuth":[]}],"x-avrix-scopes":["seller:orders:write","seller:keys:pull"],"x-avrix-tier":"orders","x-avrix-rate-limit-class":"orders","x-avrix-scope-mode":"anyOf","tags":["Orders"],"operationId":"holdOrder","parameters":[{"$ref":"#/components/parameters/IdempotencyKey"},{"$ref":"#/components/parameters/AvrixApiVersion"},{"$ref":"#/components/parameters/RequestId"},{"$ref":"#/components/parameters/SandboxSimulate"}]},"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":"5f0c1b7e-2d94-4c1a-8f3e-9b6a4d2c7e10"}}}},"responses":{"200":{"description":"Release acknowledged. `data.released` is true when this call freed the hold, false when it was already released, consumed or expired — the cart is free either way and the call is safe to retry (never 404).","headers":{"X-Request-Id":{"$ref":"#/components/headers/XRequestId"},"X-Avrix-Api-Version":{"$ref":"#/components/headers/XAvrixApiVersion"},"X-Api-Version":{"$ref":"#/components/headers/XApiVersion"},"Idempotency-Replayed":{"$ref":"#/components/headers/IdempotencyReplayed"},"X-RateLimit-Limit":{"$ref":"#/components/headers/XRateLimitLimit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/XRateLimitRemaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/XRateLimitReset"},"X-RateLimit-Bucket":{"$ref":"#/components/headers/XRateLimitBucket"}}},"400":{"$ref":"#/components/responses/SellerApiIdempotencyKeyRequired"},"401":{"$ref":"#/components/responses/SellerApiUnauthorized"},"403":{"$ref":"#/components/responses/SellerApiForbidden"},"409":{"$ref":"#/components/responses/SellerApiIdempotencyConflict"},"413":{"$ref":"#/components/responses/SellerApiPayloadTooLarge"},"422":{"description":"Validation failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"429":{"$ref":"#/components/responses/SellerApiRateLimited"},"500":{"$ref":"#/components/responses/SellerApiInternalError"},"503":{"$ref":"#/components/responses/SellerApiServiceUnavailable"},"504":{"$ref":"#/components/responses/SellerApiTimeout"}},"security":[{"bearerAuth":[]}],"x-avrix-scopes":["seller:orders:write","seller:keys:pull"],"x-avrix-tier":"orders","x-avrix-rate-limit-class":"orders","x-avrix-scope-mode":"anyOf","tags":["Orders"],"operationId":"deleteHold","parameters":[{"$ref":"#/components/parameters/IdempotencyKey"},{"$ref":"#/components/parameters/AvrixApiVersion"},{"$ref":"#/components/parameters/RequestId"},{"$ref":"#/components/parameters/SandboxSimulateWrite"}],"description":"**Deprecated name.** Use `DELETE /orders/hold/{holdId}`, which runs the same handler. This path keeps working; nothing is scheduled for removal.\n\nRelease a checkout hold early. Requires `Idempotency-Key`. Scope: `seller:orders:write` or the legacy `seller:keys:pull`. Capability: `whoami.capabilities.checkoutHoldEnabled`.","deprecated":true}},"/api/seller/v1/orders/hold/{holdId}":{"delete":{"summary":"Release a checkout hold","responses":{"200":{"description":"Release acknowledged. `data.released` is true when this call freed the hold, false when it was already released, consumed or expired — the cart is free either way and the call is safe to retry (never 404).","headers":{"X-Request-Id":{"$ref":"#/components/headers/XRequestId"},"X-Avrix-Api-Version":{"$ref":"#/components/headers/XAvrixApiVersion"},"X-Api-Version":{"$ref":"#/components/headers/XApiVersion"},"Idempotency-Replayed":{"$ref":"#/components/headers/IdempotencyReplayed"},"X-RateLimit-Limit":{"$ref":"#/components/headers/XRateLimitLimit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/XRateLimitRemaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/XRateLimitReset"},"X-RateLimit-Bucket":{"$ref":"#/components/headers/XRateLimitBucket"}}},"400":{"$ref":"#/components/responses/SellerApiIdempotencyKeyRequired"},"401":{"$ref":"#/components/responses/SellerApiUnauthorized"},"403":{"$ref":"#/components/responses/SellerApiForbidden"},"409":{"$ref":"#/components/responses/SellerApiIdempotencyConflict"},"413":{"$ref":"#/components/responses/SellerApiPayloadTooLarge"},"422":{"description":"Validation failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"429":{"$ref":"#/components/responses/SellerApiRateLimited"},"500":{"$ref":"#/components/responses/SellerApiInternalError"},"503":{"$ref":"#/components/responses/SellerApiServiceUnavailable"},"504":{"$ref":"#/components/responses/SellerApiTimeout"}},"security":[{"bearerAuth":[]}],"x-avrix-scopes":["seller:orders:write","seller:keys:pull"],"x-avrix-tier":"orders","x-avrix-rate-limit-class":"orders","x-avrix-scope-mode":"anyOf","tags":["Orders"],"operationId":"releaseHold","parameters":[{"name":"holdId","in":"path","required":true,"description":"The hold to release: `holdId` from `POST /orders/hold`.","schema":{"type":"string","format":"uuid"}},{"$ref":"#/components/parameters/IdempotencyKey"},{"$ref":"#/components/parameters/AvrixApiVersion"},{"$ref":"#/components/parameters/RequestId"},{"$ref":"#/components/parameters/SandboxSimulateWrite"}],"description":"Release a checkout hold before it expires; the hold is named in the path and no body is needed. Releasing is idempotent: a hold that is already released, consumed or expired answers 200 with `released: false`.\n\nThe same handler as `DELETE /orders/hold`, which takes `{ \"holdId\" }` in a JSON body and is the deprecated name of this operation. A body that also sends the id must send the same one: a different value is refused with 422 `VALIDATION_FAILED` naming the field."},"get":{"summary":"Get a checkout hold","description":"Read a checkout hold created with the same API key: what it holds, until when, and the price it bound. 404 `HOLD_NOT_FOUND` once it is no longer live; `details.holdState` is `released` or `consumed` when the hold store still remembers (24 hours), else `not_found` (expired, never existed, or created with another key). To recover a lost `holdId`, replay `POST /orders/hold` with its original `Idempotency-Key`.","tags":["Orders"],"security":[{"bearerAuth":[]}],"parameters":[{"name":"holdId","in":"path","required":true,"schema":{"type":"string","format":"uuid"},"description":"`holdId` from POST /orders/hold"},{"$ref":"#/components/parameters/AvrixApiVersion"},{"$ref":"#/components/parameters/RequestId"},{"$ref":"#/components/parameters/SandboxSimulateRateLimit"}],"responses":{"200":{"description":"The live hold","headers":{"X-Request-Id":{"$ref":"#/components/headers/XRequestId"},"X-Avrix-Api-Version":{"$ref":"#/components/headers/XAvrixApiVersion"},"X-Api-Version":{"$ref":"#/components/headers/XApiVersion"},"X-RateLimit-Limit":{"$ref":"#/components/headers/XRateLimitLimit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/XRateLimitRemaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/XRateLimitReset"},"X-RateLimit-Bucket":{"$ref":"#/components/headers/XRateLimitBucket"}},"content":{"application/json":{"schema":{"type":"object","required":["data"],"properties":{"data":{"$ref":"#/components/schemas/SellerCheckoutHold"}}},"example":{"data":{"type":"checkout_hold","holdId":"3478c902-b0b1-47ef-8c88-1c909cf993df","checkoutHoldId":"e3e957ab-c932-473d-8a7e-ee53cccbdc8e","state":"active","createdAt":"2026-11-02T09:30:00Z","expiresAt":"2026-11-02T09:30:00Z","expiresInSeconds":300,"allocationId":"87a9d04d-e98a-4e01-8402-ca5cf8f3643f","skuId":"e0e8c379-2d05-40a7-8bc6-aae350819aa5","skuCode":"EXAMPLE-STEAM-WW","quantity":12,"orderReference":"store-order-10432","customerReference":"example_customerreference","unitPriceMinor":2450,"currencyCode":"EUR","currencyExponent":2,"salesCountryCode":"DE","priceBoundAt":"2026-11-02T09:30:00Z"}}}}},"400":{"$ref":"#/components/responses/SellerApiUnsupportedApiVersion"},"401":{"$ref":"#/components/responses/SellerApiUnauthorized"},"403":{"$ref":"#/components/responses/SellerApiForbidden"},"404":{"description":"HOLD_NOT_FOUND: the hold is not live. `details.holdState`: `released`, `consumed` or `not_found`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"412":{"description":"CHECKOUT_HOLD_DISABLED: checkout holds are not enabled on this deployment","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"422":{"description":"VALIDATION_FAILED: holdId is not a UUID","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"429":{"$ref":"#/components/responses/SellerApiRateLimited"},"500":{"$ref":"#/components/responses/SellerApiInternalError"},"503":{"description":"STORE_UNAVAILABLE: the hold store could not be read; retry after `Retry-After`. Also the other 503 causes of every route.","headers":{"Retry-After":{"schema":{"type":"integer"},"description":"Seconds to wait before retrying."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"504":{"$ref":"#/components/responses/SellerApiTimeout"}},"x-avrix-scopes":["seller:orders:read","seller:orders:write","seller:products:read","seller:keys:pull"],"x-avrix-tier":"orders","x-avrix-rate-limit-class":"orders","x-avrix-scope-mode":"anyOf","operationId":"getHold"}},"/api/seller/v1/disputes/freeze":{"post":{"summary":"Freeze keys for a dispute","description":"While a payment dispute is open, freeze the delivered keys: `POST /orders/recover-keys` withholds them (`frozen[]`) and `POST /orders/{orderId}/keys/{keyId}/replace` refuses them. The freeze ends when you release it (`POST /disputes/{freezeId}/release`), when `POST /refunds` refunds or charges back its keys (`status: converted`), or at `expiresAt` (default 30 days, at most 90). `key.frozen` and `key.unfrozen` report every change. Send an `Idempotency-Key` header (required). List your freezes with `GET /disputes`.","tags":["Refunds"],"security":[{"bearerAuth":[]}],"parameters":[{"$ref":"#/components/parameters/IdempotencyKey"},{"$ref":"#/components/parameters/AvrixApiVersion"},{"$ref":"#/components/parameters/RequestId"},{"$ref":"#/components/parameters/SandboxSimulateWrite"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"required":["keyIds","reason"],"properties":{"keyIds":{"type":"array","minItems":1,"maxItems":100,"items":{"type":"string","format":"uuid"}},"reason":{"type":"string","enum":["payment_dispute","fraud_review","chargeback_inquiry"]},"disputeReference":{"type":"string","maxLength":200,"description":"Your PSP dispute id, echoed on the webhooks."},"expiresInDays":{"type":"integer","minimum":1,"maximum":90,"default":30}}}}}},"responses":{"201":{"description":"Frozen. Keys that could not be frozen are listed in `skipped`.","headers":{"X-Request-Id":{"$ref":"#/components/headers/XRequestId"},"X-Avrix-Api-Version":{"$ref":"#/components/headers/XAvrixApiVersion"},"X-Api-Version":{"$ref":"#/components/headers/XApiVersion"},"Idempotency-Replayed":{"$ref":"#/components/headers/IdempotencyReplayed"},"X-RateLimit-Limit":{"$ref":"#/components/headers/XRateLimitLimit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/XRateLimitRemaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/XRateLimitReset"},"X-RateLimit-Bucket":{"$ref":"#/components/headers/XRateLimitBucket"}},"content":{"application/json":{"schema":{"type":"object","required":["data"],"properties":{"data":{"type":"object","required":["freezeId","status","expiresAt","frozen","skipped"],"properties":{"freezeId":{"type":"string","format":"uuid"},"status":{"type":"string","const":"active"},"reason":{"type":"string"},"disputeReference":{"type":["string","null"]},"expiresAt":{"type":"string","format":"date-time"},"frozen":{"type":"array","items":{"type":"object","properties":{"keyId":{"type":"string","format":"uuid"},"orderReference":{"type":"string"}}}},"skipped":{"type":"array","items":{"type":"object","properties":{"keyId":{"type":"string","format":"uuid"},"reason":{"type":"string","enum":["not_found","not_delivered","already_frozen"]}}}}}}}},"example":{"data":{"freezeId":"6a0f8e2c-1d3b-4e5f-9a7b-2c4d6e8f0a1b","status":"active","reason":"payment_dispute","disputeReference":"dp_8812","expiresAt":"2027-01-01T10:00:00Z","frozen":[{"keyId":"3f1c2d4e-5a6b-4c7d-8e9f-0a1b2c3d4e5f","orderReference":"ORD-10042"}],"skipped":[]}}}}},"400":{"$ref":"#/components/responses/SellerApiIdempotencyKeyRequired"},"401":{"$ref":"#/components/responses/SellerApiUnauthorized"},"403":{"$ref":"#/components/responses/SellerApiForbidden"},"404":{"description":"None of the keys can be frozen (`details.skipped`)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"409":{"$ref":"#/components/responses/SellerApiIdempotencyConflict"},"413":{"$ref":"#/components/responses/SellerApiPayloadTooLarge"},"422":{"description":"Invalid body","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"429":{"$ref":"#/components/responses/SellerApiRateLimited"},"500":{"$ref":"#/components/responses/SellerApiInternalError"},"503":{"$ref":"#/components/responses/SellerApiServiceUnavailable"},"504":{"$ref":"#/components/responses/SellerApiTimeout"}},"x-avrix-scopes":["seller:refunds:write","seller:orders:write","seller:keys:pull"],"x-avrix-tier":"orders","x-avrix-rate-limit-class":"orders","x-avrix-scope-mode":"anyOf","operationId":"freezeDisputeKeys"}},"/api/seller/v1/disputes/{freezeId}/release":{"post":{"summary":"Release a dispute freeze","description":"End a freeze (the dispute was withdrawn or won): the keys are recoverable again and `key.unfrozen` is sent with `resolution: released`. Send an `Idempotency-Key` header (required). Read the freeze back with `GET /disputes/{freezeId}`.","tags":["Refunds"],"security":[{"bearerAuth":[]}],"parameters":[{"name":"freezeId","in":"path","required":true,"schema":{"type":"string","format":"uuid"},"description":"`freezeId` from POST /disputes/freeze"},{"$ref":"#/components/parameters/IdempotencyKey"},{"$ref":"#/components/parameters/AvrixApiVersion"},{"$ref":"#/components/parameters/RequestId"},{"$ref":"#/components/parameters/SandboxSimulateWrite"}],"responses":{"200":{"description":"Released","headers":{"X-Request-Id":{"$ref":"#/components/headers/XRequestId"},"X-Avrix-Api-Version":{"$ref":"#/components/headers/XAvrixApiVersion"},"X-Api-Version":{"$ref":"#/components/headers/XApiVersion"},"Idempotency-Replayed":{"$ref":"#/components/headers/IdempotencyReplayed"},"X-RateLimit-Limit":{"$ref":"#/components/headers/XRateLimitLimit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/XRateLimitRemaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/XRateLimitReset"},"X-RateLimit-Bucket":{"$ref":"#/components/headers/XRateLimitBucket"}},"content":{"application/json":{"schema":{"type":"object","required":["data"],"properties":{"data":{"type":"object","required":["freezeId","status","keyIds"],"properties":{"freezeId":{"type":"string","format":"uuid"},"status":{"type":"string","const":"released"},"keyIds":{"type":"array","items":{"type":"string","format":"uuid"}}}}}},"example":{"data":{"freezeId":"b9c401d3-f745-4ea7-8f0d-9a7ba1a38f31","status":"released","keyIds":["436dc8ea-bfde-45e0-8334-6f0288f22483"]}}}}},"400":{"$ref":"#/components/responses/SellerApiIdempotencyKeyRequired"},"401":{"$ref":"#/components/responses/SellerApiUnauthorized"},"403":{"$ref":"#/components/responses/SellerApiForbidden"},"404":{"description":"Freeze not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"409":{"description":"`CONFLICT`: the freeze already ended (released, converted or expired). Also returned for the `Idempotency-Key` itself: `IDEMPOTENCY_KEY_MISMATCH` (the key was already used with a different body) and `IDEMPOTENCY_REQUEST_IN_FLIGHT` (an earlier request with this key is still running; retry after `Retry-After` seconds).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"422":{"description":"Invalid freezeId","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"429":{"$ref":"#/components/responses/SellerApiRateLimited"},"500":{"$ref":"#/components/responses/SellerApiInternalError"},"503":{"$ref":"#/components/responses/SellerApiServiceUnavailable"},"504":{"$ref":"#/components/responses/SellerApiTimeout"}},"x-avrix-scopes":["seller:refunds:write","seller:orders:write","seller:keys:pull"],"x-avrix-tier":"orders","x-avrix-rate-limit-class":"orders","x-avrix-scope-mode":"anyOf","operationId":"releaseDisputeFreeze"}},"/api/seller/v1/disputes":{"get":{"summary":"List dispute freezes","description":"Your dispute freezes, newest first, each with its keys and how it ended. Filter by `status`, `disputeReference` (the reference you sent on `POST /disputes/freeze`) or `keyId`. In the shared sandbox only the freezes your API key opened are listed. Pages with `limit` and `cursor` (the shared list contract). Scopes: any refund read scope.","tags":["Refunds"],"security":[{"bearerAuth":[]}],"parameters":[{"name":"limit","in":"query","schema":{"type":"integer","minimum":1,"maximum":100,"default":50},"description":"Page size: how many items to return (1 to 100)."},{"name":"cursor","in":"query","schema":{"type":"string"},"description":"Opaque cursor from `meta.nextCursor`. Send it back unchanged; omit it on the first call."},{"name":"status","in":"query","schema":{"type":"string","enum":["active","released","converted","expired"]},"description":"Only freezes in this status."},{"name":"disputeReference","in":"query","schema":{"type":"string","maxLength":200},"description":"The `disputeReference` you sent on `POST /disputes/freeze`."},{"name":"keyId","in":"query","schema":{"type":"string","format":"uuid"},"description":"Only freezes that include this key."},{"$ref":"#/components/parameters/AvrixApiVersion"},{"$ref":"#/components/parameters/RequestId"},{"$ref":"#/components/parameters/SandboxSimulateRateLimit"}],"responses":{"200":{"description":"Dispute freezes","headers":{"X-Request-Id":{"$ref":"#/components/headers/XRequestId"},"X-Avrix-Api-Version":{"$ref":"#/components/headers/XAvrixApiVersion"},"X-Api-Version":{"$ref":"#/components/headers/XApiVersion"},"X-RateLimit-Limit":{"$ref":"#/components/headers/XRateLimitLimit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/XRateLimitRemaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/XRateLimitReset"},"X-RateLimit-Bucket":{"$ref":"#/components/headers/XRateLimitBucket"}},"content":{"application/json":{"schema":{"type":"object","required":["data","meta"],"properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/SellerDispute"}},"meta":{"type":"object","properties":{"limit":{"type":"integer"},"nextCursor":{"type":["string","null"]},"nextUrl":{"type":["string","null"]},"hasMore":{"type":"boolean","description":"True when another page follows. Loop on `hasMore`; send `nextCursor` back as `cursor`."}}}}},"example":{"data":[{"freezeId":"6a0f8e2c-1d3b-4e5f-9a7b-2c4d6e8f0a1b","status":"active","resolution":null,"reason":"payment_dispute","disputeReference":"dp_8812","createdAt":"2026-12-02T10:00:00Z","expiresAt":"2027-01-01T10:00:00Z","endedAt":null,"keyIds":["3f1c2d4e-5a6b-4c7d-8e9f-0a1b2c3d4e5f"],"orderReferences":["ORD-10042"],"keys":[{"keyId":"3f1c2d4e-5a6b-4c7d-8e9f-0a1b2c3d4e5f","orderReference":"ORD-10042","active":true}]}],"meta":{"limit":50,"hasMore":false,"nextCursor":null,"nextUrl":null}}}}},"400":{"$ref":"#/components/responses/SellerApiUnsupportedApiVersion"},"401":{"$ref":"#/components/responses/SellerApiUnauthorized"},"403":{"$ref":"#/components/responses/SellerApiForbidden"},"422":{"$ref":"#/components/responses/SellerApiValidationFailed"},"429":{"$ref":"#/components/responses/SellerApiRateLimited"},"500":{"$ref":"#/components/responses/SellerApiInternalError"},"503":{"$ref":"#/components/responses/SellerApiServiceUnavailable"},"504":{"$ref":"#/components/responses/SellerApiTimeout"}},"x-avrix-scopes":["seller:refunds:read","seller:refunds:write","seller:finance:read","seller:orders:write","seller:keys:pull"],"x-avrix-tier":"orders","x-avrix-rate-limit-class":"orders","x-avrix-scope-mode":"anyOf","operationId":"listDisputes"}},"/api/seller/v1/disputes/{freezeId}":{"get":{"summary":"Get a dispute freeze","description":"One dispute freeze with its keys, its status and, once it ended, how. 404 when it is not yours (in the shared sandbox: not opened by your API key). Scopes: any refund read scope.","tags":["Refunds"],"security":[{"bearerAuth":[]}],"parameters":[{"name":"freezeId","in":"path","required":true,"schema":{"type":"string","format":"uuid"},"description":"The `freezeId` from `POST /disputes/freeze`."},{"$ref":"#/components/parameters/AvrixApiVersion"},{"$ref":"#/components/parameters/RequestId"},{"$ref":"#/components/parameters/SandboxSimulateRateLimit"}],"responses":{"200":{"description":"The freeze","headers":{"X-Request-Id":{"$ref":"#/components/headers/XRequestId"},"X-Avrix-Api-Version":{"$ref":"#/components/headers/XAvrixApiVersion"},"X-Api-Version":{"$ref":"#/components/headers/XApiVersion"},"X-RateLimit-Limit":{"$ref":"#/components/headers/XRateLimitLimit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/XRateLimitRemaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/XRateLimitReset"},"X-RateLimit-Bucket":{"$ref":"#/components/headers/XRateLimitBucket"}},"content":{"application/json":{"schema":{"type":"object","required":["data"],"properties":{"data":{"$ref":"#/components/schemas/SellerDispute"}}},"example":{"data":{"freezeId":"6a0f8e2c-1d3b-4e5f-9a7b-2c4d6e8f0a1b","status":"active","resolution":null,"reason":"payment_dispute","disputeReference":"dp_8812","createdAt":"2026-12-02T10:00:00Z","expiresAt":"2027-01-01T10:00:00Z","endedAt":null,"keyIds":["3f1c2d4e-5a6b-4c7d-8e9f-0a1b2c3d4e5f"],"orderReferences":["ORD-10042"],"keys":[{"keyId":"3f1c2d4e-5a6b-4c7d-8e9f-0a1b2c3d4e5f","orderReference":"ORD-10042","active":true}]}}}}},"400":{"$ref":"#/components/responses/SellerApiUnsupportedApiVersion"},"401":{"$ref":"#/components/responses/SellerApiUnauthorized"},"403":{"$ref":"#/components/responses/SellerApiForbidden"},"404":{"description":"Freeze not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"422":{"$ref":"#/components/responses/SellerApiValidationFailed"},"429":{"$ref":"#/components/responses/SellerApiRateLimited"},"500":{"$ref":"#/components/responses/SellerApiInternalError"},"503":{"$ref":"#/components/responses/SellerApiServiceUnavailable"},"504":{"$ref":"#/components/responses/SellerApiTimeout"}},"x-avrix-scopes":["seller:refunds:read","seller:refunds:write","seller:finance:read","seller:orders:write","seller:keys:pull"],"x-avrix-tier":"orders","x-avrix-rate-limit-class":"orders","x-avrix-scope-mode":"anyOf","operationId":"getDispute"}},"/api/seller/v1/orders/recover-keys":{"post":{"summary":"Recover the keys already sold under an orderReference","description":"**Scope:** `seller:orders:write` or the legacy `seller:keys:pull`. Debits the **`orders`** rate-limit class.\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`.","parameters":[{"$ref":"#/components/parameters/AvrixApiVersion"},{"$ref":"#/components/parameters/RequestId"},{"$ref":"#/components/parameters/SandboxSimulateWrite"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["orderReference"],"properties":{"orderReference":{"type":"string","maxLength":255,"description":"The order reference used when placing the order (at most 255 characters, the same limit as `POST /orders`)"}}},"example":{"orderReference":"store-order-10432"}}}},"responses":{"200":{"description":"Live keys for the reference","headers":{"X-Request-Id":{"$ref":"#/components/headers/XRequestId"},"X-Avrix-Api-Version":{"$ref":"#/components/headers/XAvrixApiVersion"},"X-Api-Version":{"$ref":"#/components/headers/XApiVersion"},"X-RateLimit-Limit":{"$ref":"#/components/headers/XRateLimitLimit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/XRateLimitRemaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/XRateLimitReset"},"X-RateLimit-Bucket":{"$ref":"#/components/headers/XRateLimitBucket"}},"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":{"$ref":"#/components/schemas/SellerDeliveredKey"},"description":"Key plaintext, in the same order as `keyIds`."},"revoked":{"type":"array","description":"Keys of this order the Content Owner revoked after sale (not in `keys`): replace or refund them.","items":{"$ref":"#/components/schemas/SellerKeyRevocation"}},"frozen":{"type":"array","description":"Live keys withheld because an open dispute froze them (`POST /disputes/freeze`); released or settled freezes return them.","items":{"type":"object","properties":{"keyId":{"type":"string","format":"uuid"},"freezeId":{"type":"string","format":"uuid"},"reason":{"type":"string"},"expiresAt":{"type":"string","format":"date-time"}}}},"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"]}}}}},"400":{"$ref":"#/components/responses/SellerApiUnsupportedApiVersion"},"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"}}}},"413":{"$ref":"#/components/responses/SellerApiPayloadTooLarge"},"422":{"description":"Validation failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"429":{"$ref":"#/components/responses/SellerApiRateLimited"},"500":{"$ref":"#/components/responses/SellerApiInternalError"},"503":{"$ref":"#/components/responses/SellerApiServiceUnavailable"},"504":{"$ref":"#/components/responses/SellerApiTimeout"}},"tags":["Orders"],"security":[{"bearerAuth":[]}],"x-avrix-scopes":["seller:orders:write","seller:keys:pull"],"x-avrix-tier":"keys","x-avrix-rate-limit-class":"orders","x-avrix-scope-mode":"anyOf","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` (the default). With the capability off, 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: a completed cancellation is replayed; a failed response such as 404 is never stored, so the same key runs again.\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":[{"$ref":"#/components/parameters/IdempotencyKey"},{"$ref":"#/components/parameters/AvrixApiVersion"},{"$ref":"#/components/parameters/RequestId"},{"$ref":"#/components/parameters/SandboxSimulateWrite"}],"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 (at most 255 characters there; a longer value matches no order)"},"reason":{"type":"string","maxLength":500,"description":"Optional cancellation reason"}}},"example":{"orderReference":"store-order-10432"}}}},"responses":{"200":{"description":"Reservations cancelled","headers":{"X-Request-Id":{"$ref":"#/components/headers/XRequestId"},"X-Avrix-Api-Version":{"$ref":"#/components/headers/XAvrixApiVersion"},"X-Api-Version":{"$ref":"#/components/headers/XApiVersion"},"Idempotency-Replayed":{"$ref":"#/components/headers/IdempotencyReplayed"},"X-RateLimit-Limit":{"$ref":"#/components/headers/XRateLimitLimit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/XRateLimitRemaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/XRateLimitReset"},"X-RateLimit-Bucket":{"$ref":"#/components/headers/XRateLimitBucket"}},"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"]}}},"example":{"data":{"orderReference":"store-order-10432","cancelled":1}}}}},"400":{"$ref":"#/components/responses/SellerApiIdempotencyKeyRequired"},"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"}}}}}}},"409":{"$ref":"#/components/responses/SellerApiIdempotencyConflict"},"413":{"$ref":"#/components/responses/SellerApiPayloadTooLarge"},"422":{"$ref":"#/components/responses/SellerApiValidationFailed"},"429":{"$ref":"#/components/responses/SellerApiRateLimited"},"500":{"$ref":"#/components/responses/SellerApiInternalError"},"503":{"$ref":"#/components/responses/SellerApiServiceUnavailable"},"504":{"$ref":"#/components/responses/SellerApiTimeout"}},"security":[{"bearerAuth":[]}],"x-avrix-scopes":["seller:orders:write","seller:keys:pull"],"x-avrix-tier":"orders","x-avrix-rate-limit-class":"orders","x-avrix-scope-mode":"anyOf","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, which must now be pinned; it was 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`** for an all-or-nothing cart, which runs in two steps. First every line is validated without touching inventory: any failure yields **422** `VALIDATION_FAILED` with aggregated `details.issues`, and nothing is pulled or announced. Then every line is pulled before any line is billed, delivered or announced: a line refused at that point (for example **409** `NO_AVAILABLE_KEYS`) releases what the earlier lines took, and the request answers **that line's own code and status** with `details.strictCart` = `{ outcome, failedItemIndex, items[{ index, orderReference, status }] }`. `outcome` is `rolled_back` when every earlier line was released, and `rollback_incomplete` when at least one could not be released automatically: the cart still did not go through and the response carries no keys, so keep the `requestId` for support before you retry. **Since 2026-09-01 (UTC) the stamped default is the 2026-09-01 contract and an omitted `strict` defaults to `true`**; 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, CONSUMER_GEO_ATTEST_REQUIRED, CONSUMER_RISK_HIGH, CONSUMER_RISK_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":[{"$ref":"#/components/parameters/IdempotencyKey"},{"$ref":"#/components/parameters/AvrixApiVersion"},{"$ref":"#/components/parameters/RequestId"},{"$ref":"#/components/parameters/SandboxSimulate"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["items"],"properties":{"strict":{"type":"boolean","description":"Cart atomicity control. When true the cart is all-or-nothing: every line is validated and pre-checked (422 with per-line `issues` if any fails, nothing pulled), then every line is pulled before any line is billed, delivered or announced. A line refused at pull time (for example two lines of one SKU that together exceed the stock) releases what the earlier lines took and the request answers that line's own code and status, with `details.strictCart` = `{ outcome, failedItemIndex, items[{ index, orderReference, status: failed | rolled_back | not_attempted }] }`. A refused strict cart stores nothing, so a retry with the same `Idempotency-Key` runs it again. **Default depends on your contract date:** omitted `strict` behaves as `true` on contract dates >= 2026-09-01, the stamped default for unpinned requests since 2026-09-01 UTC; only a request pinned to `X-Avrix-Api-Version: 2026-04-29` keeps `false` (partial success). `meta.strict` echoes the mode that ran. RECOMMENDED: send `strict` explicitly."},"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. Treat it as opaque: its length and contents may change, so store and forward it as-is and never parse it."}}}},"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, for the whole cart. Required when GET /allocations.consumerGeoAttestRequired is true for that publisher. It covers every line of this cart (and a retry of it) and no other order, and is spent only when a line is fulfilled. A line-level consumerGeoAttestId overrides it for that line. 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":"The cart ran. With `strict: true` (the default on contract date `2026-09-01` and later) every line is `fulfilled` or `pre-order`: a strict cart that cannot be completed in full answers an error status, never a 200. With `strict: false` every line stands alone, so the response can mix lines that went through with refused lines (`type: failed`, with the line's own `code`, `error` and `httpStatus`). `meta.strict` and `meta.contractDate` say which mode ran. The response is stored for replay only when every line went through; otherwise a retry with the same `Idempotency-Key` replays the lines that went through and runs the refused ones again.","headers":{"X-Request-Id":{"$ref":"#/components/headers/XRequestId"},"X-Avrix-Api-Version":{"$ref":"#/components/headers/XAvrixApiVersion"},"X-Api-Version":{"$ref":"#/components/headers/XApiVersion"},"Idempotency-Replayed":{"$ref":"#/components/headers/IdempotencyReplayed"},"X-RateLimit-Limit":{"$ref":"#/components/headers/XRateLimitLimit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/XRateLimitRemaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/XRateLimitReset"},"X-RateLimit-Bucket":{"$ref":"#/components/headers/XRateLimitBucket"}},"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","failed"],"description":"Whether keys were delivered (`fulfilled`) or reserved (`pre-order`); `failed` for a refused line of a non-strict cart, with `code`, `error` and `httpStatus`."},"keys":{"type":"array","items":{"$ref":"#/components/schemas/SellerDeliveredKey"},"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","deprecated":true,"description":"Deprecated: use `orderId`. On contract date `2026-12-01` and later this is always the same value as `orderId`. On older dates it is the id of the order's first key pull, which differs from `orderId` for an order placed before this change shipped (changelog, `2026-12-01`) and for a pre-order delivered later. Both values keep resolving on every order lookup."},"orderId":{"type":"string","description":"The order's id (`ord_` plus eight characters). One value for the life of the order: the same in the create response, `GET /orders`, `GET /orders/{orderId}`, the bulk line and the `order.fulfilled` webhook. Store this one. Every endpoint that addresses an order (`GET /orders/{orderId}`, `GET /orders?orderReadableId=`, `POST /orders/{orderId}/fulfill`, key replacement) accepts it."},"economics":{"anyOf":[{"$ref":"#/components/schemas/SellerOrderEconomics"},{"type":"null"}],"description":"What the delivered keys were billed at, summed from the order's API sale rows. Null when the order has none: a wholesale or complimentary allocation (billed per allocation, not per sale), or nothing delivered yet."},"fulfilledAt":{"type":"string","format":"date-time"},"transactionIds":{"type":"array","items":{"type":"string","format":"uuid"},"description":"Present on every successful line (omitted on failed lines). Ids of the API sale transaction rows recorded for this line — one per delivered key, the same `id` as `GET /finance/api-sales`. Empty (`[]`) for pre-order lines and when the allocation's business model is not `api`."},"warnings":{"type":"array","items":{"type":"string"},"description":"Settlement warnings for this delivery, same vocabulary and meaning as `POST /orders` `warnings` (e.g. `vat_declared_rate_below_expected`). Absent when nothing was flagged."},"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"}}}},"fulfillmentState":{"type":"string","enum":["fulfilled","pre_order"],"description":"Whether the order delivered keys now (fulfilled) or was recorded as a pre-order awaiting release (pre_order). Present on successful lines."},"keyIds":{"type":"array","items":{"type":"string","format":"uuid"},"description":"Key UUIDs of the delivered keys (for refunds / returns)."}}}}}},"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."}}}}},"example":{"data":{"items":[{"skuCode":"EXAMPLE-STEAM-WW","skuId":"3d9827bf-292b-4aa8-8519-8b7637afdc9e","quantity":12,"orderReference":"store-order-10432","type":"fulfilled","keys":["XXXXX-XXXXX-XXXXX-XXXXX"],"pulled":12,"reserved":1,"allocationId":"07f2b10b-8ee3-4cd2-8e1f-0d8617bf5939","orderId":"ord_zam675ya","economics":{"currencyCode":"EUR","currencyExponent":2,"quantity":12,"unitPriceCents":2450,"unitPriceMinor":2450,"initialUnitPriceCents":2450,"initialUnitPriceMinor":2450,"totalPriceCents":2450,"totalPriceMinor":2450,"promo":{"sourceType":"event","sourceId":"4d8c1993-1a1c-4c4b-84f0-1c92bb67ceda"},"publisherShareCents":2450,"publisherShareMinor":2450,"sellerShareCents":2450,"sellerShareMinor":2450,"platformFeeCents":2450,"platformFeeMinor":2450,"revenueSharePercent":20,"vatMinor":2450,"netMinor":2450,"transactionIds":["6b326fae-9f0b-47b2-8a6c-12aa676e8e08"]},"fulfilledAt":"2026-11-02T09:30:00Z","transactionIds":["b09e0789-dc06-4c13-837f-519cc2fa290e"],"warnings":["example_warning"],"contractTermId":"199570a7-be83-4f4d-8804-172acdb86960","contractTermVersion":1,"releaseDate":"2026-11-02T09:30:00Z","httpStatus":200,"fulfillmentState":"fulfilled","keyIds":["396ce3df-8814-4799-8f56-bee878af2c20"]}]},"meta":{"contractDate":"2026-11-02T09:30:00Z","strict":true}}}}},"400":{"$ref":"#/components/responses/SellerApiIdempotencyKeyRequired"},"401":{"$ref":"#/components/responses/SellerApiUnauthorized"},"402":{"description":"A strict cart was refused at a line whose payment is not cleared (`PAYMENT_NOT_CLEARED`, `INSUFFICIENT_WALLET_BALANCE`). `details.strictCart` reports every line; nothing of the cart stands. A non-strict cart reports the same refusal on the line, inside a 200.","headers":{"X-Request-Id":{"$ref":"#/components/headers/XRequestId"},"X-Avrix-Api-Version":{"$ref":"#/components/headers/XAvrixApiVersion"},"X-Api-Version":{"$ref":"#/components/headers/XApiVersion"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"403":{"$ref":"#/components/responses/SellerApiForbidden"},"404":{"description":"A strict cart was refused at a line whose SKU or allocation is not found or not sellable (`SKU_NOT_FOUND`, `PRODUCT_NOT_SELLABLE`, `ALLOCATION_NOT_FOUND`, `ALLOCATION_INACTIVE`). `details.strictCart` reports every line; nothing of the cart stands. A non-strict cart reports the same refusal on the line, inside a 200.","headers":{"X-Request-Id":{"$ref":"#/components/headers/XRequestId"},"X-Avrix-Api-Version":{"$ref":"#/components/headers/XAvrixApiVersion"},"X-Api-Version":{"$ref":"#/components/headers/XApiVersion"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"409":{"description":"A strict cart was refused at a line that hit a conflict: `NO_AVAILABLE_KEYS`, `ALLOCATION_EXCEEDED`, `CATALOG_PRICE_MISMATCH`, `ORDER_REFERENCE_CONFLICT` and the other 409 codes of `POST /orders`, with `details.strictCart` reporting every line (`failed`, `rolled_back` or `not_attempted`). Nothing of the cart stands. Also returned for the `Idempotency-Key` itself: `IDEMPOTENCY_KEY_MISMATCH` (the key was already used with a different body) and `IDEMPOTENCY_REQUEST_IN_FLIGHT` (an earlier request with this key is still running; retry after `Retry-After` seconds). A non-strict cart reports a line conflict on the line, inside a 200.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"413":{"$ref":"#/components/responses/SellerApiPayloadTooLarge"},"422":{"description":"`VALIDATION_FAILED`: malformed body or cart schema failure, or the validation step of a **strict** cart found an invalid line (`details.issues`, one entry per line and field; nothing was pulled). A strict cart refused at pull time for a 422 reason of the order path (territory, price or declaration codes) answers that code here, with `details.strictCart`.","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"},"503":{"description":"A strict cart was refused at a line that hit a temporary failure (`BILLING_RECORD_FAILED`, `KEY_DECRYPT_FAILED`, `PREORDER_STATE_UNAVAILABLE`, `SERVICE_UNAVAILABLE`), with `details.strictCart` as on 409. Also `IDEMPOTENCY_STORE_UNAVAILABLE` when the claim for the cart or for a line cannot be recorded, and for sandbox keys `SANDBOX_ENVIRONMENT_UNAVAILABLE`. Retry after `Retry-After` seconds with the same `Idempotency-Key`: a refused strict cart stores nothing, so the retry runs the whole cart again.","headers":{"X-Request-Id":{"$ref":"#/components/headers/XRequestId"},"X-Avrix-Api-Version":{"$ref":"#/components/headers/XAvrixApiVersion"},"X-Api-Version":{"$ref":"#/components/headers/XApiVersion"},"Retry-After":{"$ref":"#/components/headers/RetryAfter"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"504":{"description":"`HOT_PATH_TIMEOUT`: the database did not answer in time, for the cart or for the line a strict cart was refused at (then with `details.strictCart`). Retry after `Retry-After` seconds with the same `Idempotency-Key`.","headers":{"X-Request-Id":{"$ref":"#/components/headers/XRequestId"},"X-Avrix-Api-Version":{"$ref":"#/components/headers/XAvrixApiVersion"},"X-Api-Version":{"$ref":"#/components/headers/XApiVersion"},"Retry-After":{"$ref":"#/components/headers/RetryAfter"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}},"security":[{"bearerAuth":[]}],"x-avrix-scopes":["seller:orders:write","seller:keys:pull"],"x-avrix-tier":"orders","x-avrix-rate-limit-class":"orders","x-avrix-scope-mode":"anyOf","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).\n\n**Paging:** the shared list contract, see `https://docs.avrix.io/seller-api/pagination`. On contract date `2026-12-01` and later a `cursor` this API did not return is refused with `422 VALIDATION_FAILED` (`details.issues[].field` is `cursor`); earlier dates serve the first page. The history pages past the newest 100 deliveries; earlier releases stopped there.","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","format":"uuid"},"description":"Webhook endpoint ID"},{"name":"limit","in":"query","description":"Page size: how many items to return (1 to 100).","schema":{"type":"integer","default":50,"minimum":1,"maximum":100}},{"name":"status","in":"query","description":"Return only deliveries in this state.","schema":{"type":"string","enum":["pending","succeeded","failed"]}},{"name":"cursor","in":"query","required":false,"schema":{"type":"string"},"description":"Opaque cursor from `meta.nextCursor` of the previous page."},{"$ref":"#/components/parameters/AvrixApiVersion"},{"$ref":"#/components/parameters/RequestId"},{"$ref":"#/components/parameters/SandboxSimulateRateLimit"}],"responses":{"200":{"description":"Delivery list","headers":{"X-Request-Id":{"$ref":"#/components/headers/XRequestId"},"X-Avrix-Api-Version":{"$ref":"#/components/headers/XAvrixApiVersion"},"X-Api-Version":{"$ref":"#/components/headers/XApiVersion"},"X-RateLimit-Limit":{"$ref":"#/components/headers/XRateLimitLimit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/XRateLimitRemaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/XRateLimitReset"},"X-RateLimit-Bucket":{"$ref":"#/components/headers/XRateLimitBucket"}},"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"},"eventLogId":{"type":["string","null"],"description":"The event's own id (`eventLogId` in the body, `X-Avrix-Event-Log-Id` header, `id` in `GET /events`). Null on test sends and on deliveries older than the event log."},"status":{"type":"string"},"attempts":{"type":"integer"},"responseStatus":{"type":["integer","null"]},"lastError":{"type":["string","null"],"description":"Classified reason of the last failed attempt: timeout, dns_private_address, dns_failure, connect_refused, connection_error, redirect_limit, url_not_allowed, secret_decrypt_failed, endpoint_deleted, contract_not_active, skipped_on_enable (closed unsent by `POST /webhooks/{id}/enable` with `replayFrom`), no_previous_secret (a `previous_secret_only` test challenge on an endpoint with no previous secret in its rotation overlap), or http_<status> when the endpoint answered non-2xx. Null after a success. responseStatus is only ever the endpoint's own status; a transport failure leaves it null."},"createdAt":{"type":"string","format":"date-time"},"lastAttemptAt":{"type":["string","null"],"format":"date-time"},"nextRetryAt":{"type":["string","null"],"format":"date-time"}}}},"meta":{"type":"object","additionalProperties":true,"properties":{"endpointDeleted":{"type":"boolean","description":"True when the endpoint was deleted. Its deliveries stay readable here and on GET /events; it receives nothing new."},"limit":{"type":"integer","description":"The page size this response was cut at."},"count":{"type":"integer","description":"Number of items in `data`."},"hasMore":{"type":"boolean","description":"True when another page follows. Loop on `hasMore`; send `nextCursor` back as `cursor`."},"nextCursor":{"type":["string","null"],"description":"Opaque position after the last item of this page; send it back as `cursor`. Null on the last page."},"nextUrl":{"type":["string","null"],"description":"Absolute URL of the next page: this request with `cursor` set to `nextCursor`. Null when there is no next page."}}}}},"example":{"data":[{"id":"92a9bb64-8dab-4140-817d-5b8bb6518b38","endpointId":"5f76e184-de23-4fa6-8b8f-8e2a3ac60ec0","eventId":"03e4f2bb-ba20-494c-841e-c6e02fd813b0","eventType":"order.fulfilled","status":"succeeded","attempts":1,"responseStatus":200,"createdAt":"2026-11-02T09:30:00Z","lastAttemptAt":"2026-11-02T09:30:00Z","nextRetryAt":"2026-11-02T09:30:00Z"}],"meta":{"endpointDeleted":true,"limit":50,"count":12,"hasMore":true,"nextCursor":"eyJ2IjoyLCJ0IjoiMjAyNi0xMS0wMlQwOTozMDowMFoifQ","nextUrl":"https://api.avrix.io/api/seller/v1/webhooks/10530c96-45a3-4e5e-83cc-3921dd4bb0ab/deliveries?cursor=eyJ2IjoyLCJ0IjoiMjAyNi0xMS0wMlQwOTozMDowMFoifQ"}}}}},"400":{"$ref":"#/components/responses/SellerApiUnsupportedApiVersion"},"401":{"$ref":"#/components/responses/SellerApiUnauthorized"},"403":{"$ref":"#/components/responses/SellerApiForbidden"},"404":{"description":"`NOT_FOUND`: no webhook endpoint with this id belongs to your company (for a sandbox key: to this key).","headers":{"X-Request-Id":{"$ref":"#/components/headers/XRequestId"},"X-Avrix-Api-Version":{"$ref":"#/components/headers/XAvrixApiVersion"},"X-Api-Version":{"$ref":"#/components/headers/XApiVersion"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"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"},"503":{"$ref":"#/components/responses/SellerApiServiceUnavailable"},"504":{"$ref":"#/components/responses/SellerApiTimeout"}},"security":[{"bearerAuth":[]}],"x-avrix-scopes":["seller:webhooks:read"],"x-avrix-tier":"webhooks","x-avrix-rate-limit-class":"webhooks-mgmt","x-avrix-scope-mode":"anyOf","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"],"parameters":[{"$ref":"#/components/parameters/AvrixApiVersion"},{"$ref":"#/components/parameters/RequestId"},{"$ref":"#/components/parameters/SandboxSimulateWrite"}],"responses":{"201":{"description":"Attest created","headers":{"X-Request-Id":{"$ref":"#/components/headers/XRequestId"},"X-Avrix-Api-Version":{"$ref":"#/components/headers/XAvrixApiVersion"},"X-Api-Version":{"$ref":"#/components/headers/XApiVersion"},"X-RateLimit-Limit":{"$ref":"#/components/headers/XRateLimitLimit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/XRateLimitRemaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/XRateLimitReset"},"X-RateLimit-Bucket":{"$ref":"#/components/headers/XRateLimitBucket"}},"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"}}},"example":{"data":{"attestId":"9cb5ed4c-feaf-4583-8dc6-7224202f31f8","expiresAt":"2026-11-02T09:30:00Z","pixelUrl":"https://api.avrix.io/api/seller/v1/example"},"meta":{}}}}},"400":{"$ref":"#/components/responses/SellerApiUnsupportedApiVersion"},"401":{"$ref":"#/components/responses/SellerApiUnauthorized"},"403":{"$ref":"#/components/responses/SellerApiForbidden"},"429":{"$ref":"#/components/responses/SellerApiRateLimited"},"500":{"$ref":"#/components/responses/SellerApiInternalError"},"503":{"$ref":"#/components/responses/SellerApiServiceUnavailable"},"504":{"$ref":"#/components/responses/SellerApiTimeout"}},"security":[{"bearerAuth":[]}],"x-avrix-scopes":[],"x-avrix-tier":"meta","x-avrix-rate-limit-class":"orders","x-avrix-scope-mode":"any","operationId":"createGeoAttest"}},"/api/seller/v1/geo/attest/{attestId}":{"get":{"summary":"Read a buyer network confirmation","description":"Where a buyer network confirmation (`POST /geo/attest`) stands, so your checkout can tell whether the pixel has loaded before it sends `consumerGeoAttestId`. `pending` until the buyer's browser loads the pixel; `completed` once it did and the confirmation can be used; `consumed` after an order spent it; `expired` after `expiresAt`; `store_server` when the pixel loaded from an address on your key's allowlist, which is refused (mint a new one from the checkout page).\n\nOnly the key that created the confirmation can read it; any other id answers **404** `NOT_FOUND`. Any key scope. Nothing about the buyer (address, country) is returned.","tags":["Seller meta"],"operationId":"getGeoAttest","security":[{"bearerAuth":[]}],"x-avrix-scopes":[],"x-avrix-tier":"general","x-avrix-rate-limit-class":"general","x-avrix-scope-mode":"any","parameters":[{"name":"attestId","in":"path","required":true,"schema":{"type":"string","format":"uuid"},"description":"`attestId` from POST /geo/attest"},{"$ref":"#/components/parameters/AvrixApiVersion"},{"$ref":"#/components/parameters/RequestId"},{"$ref":"#/components/parameters/SandboxSimulateRateLimit"}],"responses":{"200":{"description":"Confirmation status","headers":{"X-Request-Id":{"$ref":"#/components/headers/XRequestId"},"X-Avrix-Api-Version":{"$ref":"#/components/headers/XAvrixApiVersion"},"X-Api-Version":{"$ref":"#/components/headers/XApiVersion"},"X-RateLimit-Limit":{"$ref":"#/components/headers/XRateLimitLimit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/XRateLimitRemaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/XRateLimitReset"},"X-RateLimit-Bucket":{"$ref":"#/components/headers/XRateLimitBucket"}},"content":{"application/json":{"schema":{"type":"object","required":["data","meta"],"properties":{"data":{"$ref":"#/components/schemas/SellerConsumerGeoAttestStatus"},"meta":{"type":"object","required":["requestId"],"properties":{"requestId":{"type":"string"}}}}},"example":{"data":{"attestId":"7e1d3c5b-9a8f-4e6d-8c2b-0a1f2e3d4c5b","status":"completed","expiresAt":"2026-12-02T09:45:00.000Z","completedAt":"2026-12-02T09:31:12.000Z","consumedAt":null,"consumedOrderReference":null},"meta":{"requestId":"req_7f3a91c2"}}}}},"400":{"$ref":"#/components/responses/SellerApiUnsupportedApiVersion"},"401":{"$ref":"#/components/responses/SellerApiUnauthorized"},"403":{"$ref":"#/components/responses/SellerApiForbidden"},"404":{"description":"No confirmation with this id was created by this API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"code":"NOT_FOUND","message":"No buyer network confirmation with this id was created by this API key","details":{"attestId":"7e1d3c5b-9a8f-4e6d-8c2b-0a1f2e3d4c5b"},"requestId":"req_7f3a91c2"}}}},"422":{"$ref":"#/components/responses/SellerApiValidationFailed"},"429":{"$ref":"#/components/responses/SellerApiRateLimited"},"500":{"$ref":"#/components/responses/SellerApiInternalError"},"503":{"$ref":"#/components/responses/SellerApiServiceUnavailable"},"504":{"$ref":"#/components/responses/SellerApiTimeout"}}}},"/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 `*`. Always answers 200 with the image, whatever happened to the confirmation, so read the outcome from your next preview, hold or order. The response carries the standard `X-Request-Id`, `X-Avrix-Api-Version` and `X-Api-Version` headers and `Cache-Control: no-store`. Completing from the store server is rejected later as CONSUMER_IP_INVALID.","security":[],"tags":["Seller meta"],"parameters":[{"name":"attestId","in":"path","required":true,"description":"Attestation id returned when the attestation was started.","schema":{"type":"string","format":"uuid"}},{"$ref":"#/components/parameters/RequestId"}],"responses":{"200":{"description":"1×1 GIF (completion is best-effort)","headers":{"X-Request-Id":{"$ref":"#/components/headers/XRequestId"},"X-Avrix-Api-Version":{"$ref":"#/components/headers/XAvrixApiVersion"},"X-Api-Version":{"$ref":"#/components/headers/XApiVersion"}},"content":{"image/gif":{"schema":{"type":"string","format":"binary"}}}},"401":{"description":"Not returned by this operation: it reads no API key. The entry is kept so that clients generated from earlier versions of this document keep their error types.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"403":{"description":"Not returned by this operation: it reads no API key. The entry is kept so that clients generated from earlier versions of this document keep their error types.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"429":{"description":"Not returned by this operation: it always answers 200 with the image, whatever happened to the confirmation. The entry is kept so that clients generated from earlier versions of this document keep their error types.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}},"headers":{"X-RateLimit-Limit":{"description":"Not sent by this operation: it never answers `429`. The entry is kept so that clients generated from earlier versions of this document keep their header types.","required":false,"schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Not sent by this operation: it never answers `429`. The entry is kept so that clients generated from earlier versions of this document keep their header types.","required":false,"schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"Not sent by this operation: it never answers `429`. The entry is kept so that clients generated from earlier versions of this document keep their header types.","required":false,"schema":{"type":"integer","format":"int64"}}}},"500":{"description":"Not returned by this operation: it always answers 200 with the image, whatever happened to the confirmation. The entry is kept so that clients generated from earlier versions of this document keep their error types.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}},"x-avrix-scopes":[],"x-avrix-tier":"meta","x-avrix-rate-limit-class":"none","x-avrix-scope-mode":"public","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 `*`. Every response carries the standard `X-Request-Id` (equal to the body's `requestId`), `X-Avrix-Api-Version` and `X-Api-Version` headers and `Cache-Control: no-store`; a `429`, `503` or `504` also carries `Retry-After`.","security":[],"tags":["Seller meta"],"parameters":[{"name":"attestId","in":"path","required":true,"description":"Attestation id returned when the attestation was started.","schema":{"type":"string","format":"uuid"}},{"$ref":"#/components/parameters/RequestId"}],"responses":{"200":{"description":"Completed","headers":{"X-Request-Id":{"$ref":"#/components/headers/XRequestId"},"X-Avrix-Api-Version":{"$ref":"#/components/headers/XAvrixApiVersion"},"X-Api-Version":{"$ref":"#/components/headers/XApiVersion"}},"content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"completed":{"type":"boolean"}}}}},"example":{"data":{"completed":true}}}}},"401":{"description":"Not returned by this operation: it reads no API key. The entry is kept so that clients generated from earlier versions of this document keep their error types.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"403":{"description":"Not returned by this operation: it reads no API key. The entry is kept so that clients generated from earlier versions of this document keep their error types.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"404":{"description":"`NOT_FOUND`: no confirmation with this id exists.","headers":{"X-Request-Id":{"$ref":"#/components/headers/XRequestId"},"X-Avrix-Api-Version":{"$ref":"#/components/headers/XAvrixApiVersion"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"422":{"description":"`VALIDATION_FAILED`: `attestId` is not a UUID. `CONSUMER_GEO_ATTEST_EXPIRED`: the confirmation was not completed within its lifetime; request a new one with `POST /geo/attest`. `CONSUMER_GEO_ATTEST_INVALID`: the call came from the store's own server and not from the buyer's browser.","headers":{"X-Request-Id":{"$ref":"#/components/headers/XRequestId"},"X-Avrix-Api-Version":{"$ref":"#/components/headers/XAvrixApiVersion"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"429":{"description":"`RATE_LIMIT_EXCEEDED`: more than 30 completions a minute from one client IP. Wait `Retry-After` seconds and try again. This per-address limit sends no `X-RateLimit-*` headers.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}},"headers":{"X-Request-Id":{"$ref":"#/components/headers/XRequestId"},"Retry-After":{"$ref":"#/components/headers/RetryAfter"},"X-RateLimit-Limit":{"description":"Not sent by this operation: its per-IP limiter answers `429` without `X-RateLimit-*` headers. The entry is kept so that clients generated from earlier versions of this document keep their header types.","required":false,"schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Not sent by this operation: its per-IP limiter answers `429` without `X-RateLimit-*` headers. The entry is kept so that clients generated from earlier versions of this document keep their header types.","required":false,"schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"Not sent by this operation: its per-IP limiter answers `429` without `X-RateLimit-*` headers. The entry is kept so that clients generated from earlier versions of this document keep their header types.","required":false,"schema":{"type":"integer","format":"int64"}}}},"500":{"$ref":"#/components/responses/SellerApiInternalError"},"503":{"description":"`SERVICE_UNAVAILABLE`: the confirmation could not be read or recorded because a platform dependency is temporarily unavailable. Try again after `Retry-After` seconds; an already completed confirmation answers 200.","headers":{"X-Request-Id":{"$ref":"#/components/headers/XRequestId"},"Retry-After":{"$ref":"#/components/headers/RetryAfter"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"504":{"description":"`HOT_PATH_TIMEOUT`: the database did not answer in time. Try again after `Retry-After` seconds.","headers":{"X-Request-Id":{"$ref":"#/components/headers/XRequestId"},"Retry-After":{"$ref":"#/components/headers/RetryAfter"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}},"x-avrix-scopes":[],"x-avrix-tier":"meta","x-avrix-rate-limit-class":"none","x-avrix-scope-mode":"public","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 true), `backorderEnabled` (durable customer-order backorders; default true — `backorderOnUnavailable` is rejected only while this is false), `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"]}},{"$ref":"#/components/parameters/AvrixApiVersion"},{"$ref":"#/components/parameters/RequestId"},{"$ref":"#/components/parameters/SandboxSimulateRateLimit"}],"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"}},"X-Request-Id":{"$ref":"#/components/headers/XRequestId"},"X-Avrix-Api-Version":{"$ref":"#/components/headers/XAvrixApiVersion"},"X-Api-Version":{"$ref":"#/components/headers/XApiVersion"},"X-RateLimit-Limit":{"$ref":"#/components/headers/XRateLimitLimit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/XRateLimitRemaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/XRateLimitReset"},"X-RateLimit-Bucket":{"$ref":"#/components/headers/XRateLimitBucket"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/SellerWhoamiResponse"},"example":{"data":{"persona":"seller","sandbox":true,"requestEnvironment":"sandbox","hasActiveBma":true,"settlement":{"mode":"automated_invoice","invoiceWithinDays":null},"warnings":[],"capabilities":{"checkoutHoldEnabled":true,"checkoutHoldConfigured":true,"hotDropRedisConfigured":true,"idempotencyBackend":"redis","territoryEnforcementEnabled":true,"consumerGeoEnforcementEnabled":false,"catalogPriceStrictMode":true,"keylessEnabled":false,"backorderEnabled":true,"activationPolicy":"enforce_known","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},"productionAccess":{"status":"not_requested","enforced":true,"requestedAt":null,"approvedAt":null,"steps":[{"step":"api_model_activated","done":true},{"step":"production_key_created","done":false},{"step":"production_access_approved","done":false}]}},"meta":{"requestId":"req_01EXAMPLE","diagnostics":false}}}}},"400":{"$ref":"#/components/responses/SellerApiUnsupportedApiVersion"},"401":{"$ref":"#/components/responses/SellerApiUnauthorized"},"403":{"$ref":"#/components/responses/SellerApiForbidden"},"422":{"$ref":"#/components/responses/SellerApiValidationFailed"},"429":{"$ref":"#/components/responses/SellerApiRateLimited"},"500":{"$ref":"#/components/responses/SellerApiInternalError"},"503":{"$ref":"#/components/responses/SellerApiServiceUnavailable"},"504":{"$ref":"#/components/responses/SellerApiTimeout"}},"security":[{"bearerAuth":[]}],"x-avrix-scopes":[],"x-avrix-tier":"meta","x-avrix-rate-limit-class":"general","x-avrix-scope-mode":"any","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 token (`avrix_oat_*`, about 3600 seconds) for a **seller API key**. The key is the OAuth client: `client_id` is the key's id (uuid) and `client_secret` is the key's secret. Also served at `/api/seller/v1/oauth/token`. Disabled when OAuth token minting is not enabled on the deployment (**501**).\n\n**Request.** `grant_type=client_credentials`, as a form-encoded body (`application/x-www-form-urlencoded`, the standard client-credentials call) or as JSON (the original call, unchanged). Send the client credentials either with HTTP Basic (`Authorization: Basic base64(client_id:client_secret)`) or as `client_id` and `client_secret` in the body, not both: a request that sends both is refused with `422` on a form body, and on JSON from contract date `2026-12-01` (before that date a JSON body that carries `client_secret` is read as always and an `Authorization` header is ignored). A `scope` parameter is ignored.\n\n**Response.** `access_token`, `token_type` (`Bearer`), `expires_in` and `scope` (the key's scopes, space-separated; the token carries exactly these), with `Cache-Control: no-store` and `Pragma: no-cache`.\n\n**Errors** keep the Avrix error body and status codes (`401` for a refused client, `422` for a malformed request, not the `400` of RFC 6749) and add `error_description`. `error` holds the RFC 6749 error code (`invalid_client`, `invalid_request`, `unsupported_grant_type`, `unauthorized_client`, `temporarily_unavailable`, `server_error`) on form-encoded requests and on JSON from contract date `2026-12-01`; on JSON before that date it keeps the message, as before. A refused HTTP Basic client also gets `WWW-Authenticate: Basic`.\n\n**Privacy:** treat `client_secret` like a password: never log or persist it.","tags":["Seller auth"],"security":[],"parameters":[{"$ref":"#/components/parameters/RequestId"}],"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":"00000000-0000-4000-8000-000000000011","client_secret":"example_secret"}},"application/x-www-form-urlencoded":{"schema":{"type":"object","required":["grant_type"],"properties":{"grant_type":{"type":"string","enum":["client_credentials"]},"client_id":{"type":"string","format":"uuid","description":"The API key's id. Omit when sending HTTP Basic; required otherwise."},"client_secret":{"type":"string","description":"The API key's secret. Omit when sending HTTP Basic; required otherwise."},"scope":{"type":"string","description":"Ignored: the token always carries the key's scopes, returned in `scope`."}}},"example":{"grant_type":"client_credentials"}}}},"responses":{"200":{"description":"access_token issued","headers":{"X-Request-Id":{"$ref":"#/components/headers/XRequestId"},"X-Avrix-Api-Version":{"$ref":"#/components/headers/XAvrixApiVersion"},"X-Api-Version":{"$ref":"#/components/headers/XApiVersion"},"Cache-Control":{"description":"`no-store`: the response carries a credential.","schema":{"type":"string"}},"Pragma":{"description":"`no-cache`, for HTTP/1.0 caches (RFC 6749 section 5.1).","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/OAuthTokenResponse"},"example":{"access_token":"example_accesstoken","token_type":"Bearer","expires_in":1}}}},"401":{"$ref":"#/components/responses/SellerApiUnauthorized"},"403":{"description":"Not returned by this operation: a refused credential is always 401. The entry is kept so that clients generated from earlier versions of this document keep their error types.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"413":{"$ref":"#/components/responses/SellerApiPayloadTooLarge"},"422":{"description":"Validation failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"429":{"description":"Too many token requests from this client or IP address. Wait `Retry-After` seconds, then retry. This limiter is separate from the per-key rate limits and sends no `X-RateLimit-*` headers.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}},"headers":{"X-Request-Id":{"$ref":"#/components/headers/XRequestId"},"X-Avrix-Api-Version":{"$ref":"#/components/headers/XAvrixApiVersion"},"X-Api-Version":{"$ref":"#/components/headers/XApiVersion"},"Retry-After":{"$ref":"#/components/headers/RetryAfter"},"X-RateLimit-Limit":{"description":"Not sent by this operation: the token limiter is separate from the per-key rate limits and sends only `Retry-After`. The entry is kept so that clients generated from earlier versions of this document keep their header types.","required":false,"schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Not sent by this operation: the token limiter is separate from the per-key rate limits and sends only `Retry-After`. The entry is kept so that clients generated from earlier versions of this document keep their header types.","required":false,"schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"Not sent by this operation: the token limiter is separate from the per-key rate limits and sends only `Retry-After`. The entry is kept so that clients generated from earlier versions of this document keep their header types.","required":false,"schema":{"type":"integer","format":"int64"}}}},"500":{"$ref":"#/components/responses/SellerApiInternalError"},"501":{"description":"OAuth issuance disabled","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"503":{"description":"`SERVICE_UNAVAILABLE`: the token store is unavailable, so no token was minted. Retry, or authenticate with the API key itself, which does not depend on the token store.","headers":{"X-Request-Id":{"$ref":"#/components/headers/XRequestId"},"X-Avrix-Api-Version":{"$ref":"#/components/headers/XAvrixApiVersion"},"X-Api-Version":{"$ref":"#/components/headers/XApiVersion"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"504":{"$ref":"#/components/responses/SellerApiTimeout"}},"x-avrix-scopes":[],"x-avrix-tier":"auth","x-avrix-rate-limit-class":"none","x-avrix-scope-mode":"public","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_…`). **Read model:** every order also has a durable record, written when it is placed and moved by fulfil, return, refund, cancellation and backorder expiry. It is compared with the delivery rows daily and is the source of `status` once durable reads are switched on for the environment; key-level line detail always comes from the delivery rows, and the response shape does not change.\n\n**Scopes:** any one of `seller:orders:read` (the documented scope), `seller:orders:write`, `seller:products:read` or `seller:keys:pull`, the same set as `GET /orders`.","tags":["Orders"],"security":[{"bearerAuth":[]}],"parameters":[{"name":"orderId","in":"path","required":true,"schema":{"type":"string","pattern":"^ord_"},"description":"The order's id (`ord_…`): `orderId` from any order response. The id of the order's first key pull (`orderReadableId` on contract dates before `2026-12-01`) is accepted too."},{"$ref":"#/components/parameters/AvrixApiVersion"},{"$ref":"#/components/parameters/RequestId"},{"$ref":"#/components/parameters/SandboxSimulateRateLimit"}],"responses":{"200":{"description":"Order aggregate for the given readable id (`ord_…`): a superset of the order's `GET /orders` row, with `keyIds`, `totalCents`, `currencyCode`, `currencyExponent`, `createdAt`, `fulfilledAt` and `updatedAt`. No plaintext keys.","headers":{"X-Request-Id":{"$ref":"#/components/headers/XRequestId"},"X-Avrix-Api-Version":{"$ref":"#/components/headers/XAvrixApiVersion"},"X-Api-Version":{"$ref":"#/components/headers/XApiVersion"},"X-RateLimit-Limit":{"$ref":"#/components/headers/XRateLimitLimit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/XRateLimitRemaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/XRateLimitReset"},"X-RateLimit-Bucket":{"$ref":"#/components/headers/XRateLimitBucket"}},"content":{"application/json":{"schema":{"type":"object","required":["data"],"properties":{"data":{"$ref":"#/components/schemas/SellerOrderAggregate"},"meta":{"type":"object","properties":{"requestId":{"type":"string","description":"Same as the X-Request-Id response header."}}}}},"example":{"data":{"orderReference":"store-order-10432","fulfilled":[{"skuCode":"EXAMPLE-STEAM-WW","allocationId":"91adfcfc-0bff-490a-8bbe-1ad817322a5a","fulfilledQuantity":12,"firstKeyPullId":"ce39fabe-113e-4b51-8980-4460786f3353","orderReadableId":"ord_szczrqk3"}],"preOrderActive":[{"skuCode":"EXAMPLE-STEAM-WW","allocationId":"c5251732-837e-4176-8436-27dd881dc616","reservedQuantity":12,"reservedUntil":"2026-11-02T09:30:00Z"}],"status":"preordered","refunds":[{"refundId":"f7f84e79-cf50-449e-8bcd-714c2547c3d8","status":"pending","keyIds":["f15fc6a1-273d-4dfe-8b0c-d040c2aa1e6b"],"refundReference":"rfnd_10432","refundIds":["d3802e11-eb23-499b-88f0-b64584b1d33d"]}],"keyIds":["5d368e7a-acb5-41f4-8539-666b8f3d2332"],"totalMinor":2450,"currencyCode":"null","currencyExponent":2,"createdAt":"2026-11-02T09:30:00Z","fulfilledAt":"2026-11-02T09:30:00Z","updatedAt":"2026-11-02T09:30:00Z","orderId":"ord_zvaja384","economics":{"currencyCode":"EUR","currencyExponent":2,"quantity":12,"unitPriceCents":2450,"unitPriceMinor":2450,"initialUnitPriceCents":2450,"initialUnitPriceMinor":2450,"totalPriceCents":2450,"totalPriceMinor":2450,"promo":{"sourceType":"event","sourceId":"9229c42a-f2bb-4091-8d1c-f77d0372fe98"},"publisherShareCents":2450,"publisherShareMinor":2450,"sellerShareCents":2450,"sellerShareMinor":2450,"platformFeeCents":2450,"platformFeeMinor":2450,"revenueSharePercent":20,"vatMinor":2450,"netMinor":2450,"transactionIds":["ea7e68e5-1e97-4efe-8d46-60b22342036b"]},"parentOrderReference":"store-order-10432","lineIndex":1,"replacements":[{"replacementId":"99f72f57-628e-49df-8792-355d2c5598d2","status":"pending","reason":"already_redeemed","approval":"auto","replacedKeyId":"4a2e3ef1-68b3-40ae-839f-46fd360efb8c","keyId":"03233c32-007a-40e4-87ab-6d88d130a401","requestedAt":"2026-11-02T09:30:00Z","completedAt":"2026-11-02T09:30:00Z","decidedAt":"2026-11-02T09:30:00Z"}],"revocations":[{"keyId":"e4765873-8cfe-4e8c-8a50-6690aeb25cd9","reason":"leaked","revokedAt":"2026-11-02T09:30:00Z"}]},"meta":{"requestId":"c2ed3722-baca-4e05-84f2-16b92bfe2d7a"}}}}},"400":{"$ref":"#/components/responses/SellerApiUnsupportedApiVersion"},"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"},"503":{"$ref":"#/components/responses/SellerApiServiceUnavailable"},"504":{"$ref":"#/components/responses/SellerApiTimeout"}},"x-avrix-scopes":["seller:orders:read","seller:orders:write","seller:products:read","seller:keys:pull"],"x-avrix-tier":"orders","x-avrix-rate-limit-class":"orders","x-avrix-scope-mode":"anyOf","operationId":"getOrder"}},"/api/seller/v1/orders/{orderId}/extend":{"post":{"summary":"Extend hot-drop reservation TTL","description":"**Deprecated name.** Use `POST /orders/reservations/{reservationId}/extend`, which runs the same handler. This path keeps working; nothing is scheduled for removal.\n\n**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"},"description":"The hot-drop `reservationId` (UUID) from POST /orders/reserve. An order readable id (`ord_…`, as GET /orders/{orderId} and /fulfill take) is also accepted: it names an order already placed, which cannot be extended, so it answers 409 ORDER_NOT_EXTENDABLE (404 NOT_FOUND when no such order exists)."},{"$ref":"#/components/parameters/IdempotencyKey"},{"$ref":"#/components/parameters/AvrixApiVersion"},{"$ref":"#/components/parameters/RequestId"},{"$ref":"#/components/parameters/SandboxSimulateWrite"}],"responses":{"200":{"description":"Hot-drop reservation TTL extended once (`data.reservationId`, `expiresAt`, `ttlSeconds`, `extendedOnce: true`).","headers":{"X-Request-Id":{"$ref":"#/components/headers/XRequestId"},"X-Avrix-Api-Version":{"$ref":"#/components/headers/XAvrixApiVersion"},"X-Api-Version":{"$ref":"#/components/headers/XApiVersion"},"Idempotency-Replayed":{"$ref":"#/components/headers/IdempotencyReplayed"},"X-RateLimit-Limit":{"$ref":"#/components/headers/XRateLimitLimit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/XRateLimitRemaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/XRateLimitReset"},"X-RateLimit-Bucket":{"$ref":"#/components/headers/XRateLimitBucket"}},"content":{"application/json":{"schema":{"type":"object","required":["data","meta"],"properties":{"data":{"$ref":"#/components/schemas/SellerHotDropExtendData"},"meta":{"type":"object","properties":{"requestId":{"type":"string"}}}}},"example":{"data":{"reservationId":"dcda7e11-d5f8-440e-89f3-bc44888d53fb","expiresAt":"2026-11-02T09:30:00Z","ttlSeconds":300,"extendedOnce":true},"meta":{"requestId":"9b272f1e-3248-4858-8de9-c2bcba4b4471"}}}}},"400":{"$ref":"#/components/responses/SellerApiIdempotencyKeyRequired"},"401":{"$ref":"#/components/responses/SellerApiUnauthorized"},"403":{"$ref":"#/components/responses/SellerApiForbidden"},"404":{"description":"NOT_FOUND: an `ord_…` id that names no order of yours.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"409":{"description":"RESERVATION_EXTEND_EXHAUSTED (already extended once) or ORDER_NOT_EXTENDABLE (an `ord_…` id of a placed order). Also returned for the `Idempotency-Key` itself: `IDEMPOTENCY_KEY_MISMATCH` (the key was already used with a different body) and `IDEMPOTENCY_REQUEST_IN_FLIGHT` (an earlier request with this key is still running; retry after `Retry-After` seconds).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"410":{"description":"`NOT_FOUND`: the hot-drop reservation is unknown or has expired. Reserve again with `POST /orders/reserve`. `POST /orders/commit` reports the same condition as `RESERVATION_GONE`.","headers":{"X-Request-Id":{"$ref":"#/components/headers/XRequestId"},"X-Avrix-Api-Version":{"$ref":"#/components/headers/XAvrixApiVersion"},"X-Api-Version":{"$ref":"#/components/headers/XApiVersion"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"422":{"$ref":"#/components/responses/SellerApiValidationFailed"},"429":{"$ref":"#/components/responses/SellerApiRateLimited"},"500":{"$ref":"#/components/responses/SellerApiInternalError"},"503":{"description":"Coordination service unavailable. Also returned when a platform dependency is temporarily unavailable (`SERVICE_UNAVAILABLE`) and, on a write that sends an `Idempotency-Key`, when the claim cannot be recorded (`IDEMPOTENCY_STORE_UNAVAILABLE`). Retry after `Retry-After` seconds.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"504":{"$ref":"#/components/responses/SellerApiTimeout"}},"security":[{"bearerAuth":[]}],"x-avrix-scopes":["seller:orders:write","seller:keys:pull"],"x-avrix-tier":"orders","x-avrix-rate-limit-class":"orders","x-avrix-scope-mode":"anyOf","operationId":"extendOrder","deprecated":true}},"/api/seller/v1/orders/reservations/{reservationId}/extend":{"post":{"summary":"Extend a hot-drop reservation","description":"Extend a hot-drop reservation once, by the reservation's own id in the path. The same handler, idempotency and responses as `POST /orders/{orderId}/extend`, whose `orderId` parameter has always held the reservation id; that path is the deprecated name of this operation.","tags":["Orders"],"parameters":[{"name":"reservationId","in":"path","required":true,"description":"The reservation to extend: `reservationId` from `POST /orders/reserve`.","schema":{"type":"string","format":"uuid"}},{"$ref":"#/components/parameters/IdempotencyKey"},{"$ref":"#/components/parameters/AvrixApiVersion"},{"$ref":"#/components/parameters/RequestId"},{"$ref":"#/components/parameters/SandboxSimulateWrite"}],"responses":{"200":{"description":"Hot-drop reservation TTL extended once (`data.reservationId`, `expiresAt`, `ttlSeconds`, `extendedOnce: true`).","headers":{"X-Request-Id":{"$ref":"#/components/headers/XRequestId"},"X-Avrix-Api-Version":{"$ref":"#/components/headers/XAvrixApiVersion"},"X-Api-Version":{"$ref":"#/components/headers/XApiVersion"},"Idempotency-Replayed":{"$ref":"#/components/headers/IdempotencyReplayed"},"X-RateLimit-Limit":{"$ref":"#/components/headers/XRateLimitLimit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/XRateLimitRemaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/XRateLimitReset"},"X-RateLimit-Bucket":{"$ref":"#/components/headers/XRateLimitBucket"}},"content":{"application/json":{"schema":{"type":"object","required":["data","meta"],"properties":{"data":{"$ref":"#/components/schemas/SellerHotDropExtendData"},"meta":{"type":"object","properties":{"requestId":{"type":"string"}}}}},"example":{"data":{"reservationId":"41e12737-e8b9-41ba-8557-68059f757174","expiresAt":"2026-11-02T09:30:00Z","ttlSeconds":300,"extendedOnce":true},"meta":{"requestId":"cb8148e3-7fff-461b-8b6b-aa4d6fc24eca"}}}}},"400":{"$ref":"#/components/responses/SellerApiIdempotencyKeyRequired"},"401":{"$ref":"#/components/responses/SellerApiUnauthorized"},"403":{"$ref":"#/components/responses/SellerApiForbidden"},"404":{"description":"NOT_FOUND: an `ord_…` id that names no order of yours.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"409":{"description":"RESERVATION_EXTEND_EXHAUSTED (already extended once) or ORDER_NOT_EXTENDABLE (an `ord_…` id of a placed order). Also returned for the `Idempotency-Key` itself: `IDEMPOTENCY_KEY_MISMATCH` (the key was already used with a different body) and `IDEMPOTENCY_REQUEST_IN_FLIGHT` (an earlier request with this key is still running; retry after `Retry-After` seconds).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"410":{"description":"`NOT_FOUND`: the hot-drop reservation is unknown or has expired. Reserve again with `POST /orders/reserve`. `POST /orders/commit` reports the same condition as `RESERVATION_GONE`.","headers":{"X-Request-Id":{"$ref":"#/components/headers/XRequestId"},"X-Avrix-Api-Version":{"$ref":"#/components/headers/XAvrixApiVersion"},"X-Api-Version":{"$ref":"#/components/headers/XApiVersion"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"422":{"$ref":"#/components/responses/SellerApiValidationFailed"},"429":{"$ref":"#/components/responses/SellerApiRateLimited"},"500":{"$ref":"#/components/responses/SellerApiInternalError"},"503":{"description":"Coordination service unavailable. Also returned when a platform dependency is temporarily unavailable (`SERVICE_UNAVAILABLE`) and, on a write that sends an `Idempotency-Key`, when the claim cannot be recorded (`IDEMPOTENCY_STORE_UNAVAILABLE`). Retry after `Retry-After` seconds.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"504":{"$ref":"#/components/responses/SellerApiTimeout"}},"security":[{"bearerAuth":[]}],"x-avrix-scopes":["seller:orders:write","seller:keys:pull"],"x-avrix-tier":"orders","x-avrix-rate-limit-class":"orders","x-avrix-scope-mode":"anyOf","operationId":"extendReservation"}},"/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`"},{"$ref":"#/components/parameters/IdempotencyKey"},{"$ref":"#/components/parameters/AvrixApiVersion"},{"$ref":"#/components/parameters/RequestId"},{"$ref":"#/components/parameters/SandboxSimulateWrite"}],"responses":{"200":{"description":"Revoked (or already terminal)","headers":{"X-Request-Id":{"$ref":"#/components/headers/XRequestId"},"X-Avrix-Api-Version":{"$ref":"#/components/headers/XAvrixApiVersion"},"X-Api-Version":{"$ref":"#/components/headers/XApiVersion"},"Idempotency-Replayed":{"$ref":"#/components/headers/IdempotencyReplayed"},"X-RateLimit-Limit":{"$ref":"#/components/headers/XRateLimitLimit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/XRateLimitRemaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/XRateLimitReset"},"X-RateLimit-Bucket":{"$ref":"#/components/headers/XRateLimitBucket"}},"content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/SellerKeylessFulfillmentRevokeResult"},"meta":{"type":"object","properties":{"requestId":{"type":"string"}}}}},"example":{"data":{"fulfillmentId":"41a05ae6-2010-4211-8a10-937c8a41550e","revoked":false,"status":"issued"},"meta":{"requestId":"4088ffc3-3e4f-4478-8cf7-b417a50f3242"}}}}},"400":{"$ref":"#/components/responses/SellerApiIdempotencyKeyRequired"},"401":{"$ref":"#/components/responses/SellerApiUnauthorized"},"403":{"$ref":"#/components/responses/SellerApiForbidden"},"404":{"description":"Fulfillment not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"409":{"$ref":"#/components/responses/SellerApiIdempotencyConflict"},"422":{"description":"Validation error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"429":{"$ref":"#/components/responses/SellerApiRateLimited"},"500":{"$ref":"#/components/responses/SellerApiInternalError"},"503":{"$ref":"#/components/responses/SellerApiServiceUnavailable"},"504":{"$ref":"#/components/responses/SellerApiTimeout"}},"security":[{"bearerAuth":[]}],"x-avrix-scopes":["seller:orders:manage"],"x-avrix-tier":"orders","x-avrix-rate-limit-class":"orders","x-avrix-scope-mode":"anyOf","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`. Keeps the original expiry. Not allowed after buyer activation (`409` `ALREADY_ACTIVATED`), expiry (`409` `EXPIRED`), or when the key is refunded, returned, revoked or frozen (`409` `KEY_NOT_REPLACEABLE`).\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"},{"$ref":"#/components/parameters/IdempotencyKey"},{"$ref":"#/components/parameters/AvrixApiVersion"},{"$ref":"#/components/parameters/RequestId"},{"$ref":"#/components/parameters/SandboxSimulateWrite"}],"responses":{"200":{"description":"New keyless delivery reference","headers":{"X-Request-Id":{"$ref":"#/components/headers/XRequestId"},"X-Avrix-Api-Version":{"$ref":"#/components/headers/XAvrixApiVersion"},"X-Api-Version":{"$ref":"#/components/headers/XApiVersion"},"Idempotency-Replayed":{"$ref":"#/components/headers/IdempotencyReplayed"},"X-RateLimit-Limit":{"$ref":"#/components/headers/XRateLimitLimit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/XRateLimitRemaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/XRateLimitReset"},"X-RateLimit-Bucket":{"$ref":"#/components/headers/XRateLimitBucket"}},"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"}}}}},"example":{"data":{"items":[{"fulfillmentId":"c37a4cd8-4967-437f-879b-5fe2112e5896","keyId":"bded396a-62c7-403d-8217-ad11583be077","redemptionUrl":"https://api.avrix.io/api/seller/v1/example","expiresAt":"2026-11-02T09:30:00Z"}],"provider":"hosted_redemption","redemptionUrl":"https://api.avrix.io/api/seller/v1/example","providerRef":null,"fulfillmentId":"8fc0a7a4-ce09-454a-828c-93c7359ae99a","expiresAt":"2026-11-02T09:30:00Z","status":"issued"},"meta":{"requestId":"d7fc28a2-27e3-4cf6-89be-7a2882b9ad25"}}}}},"400":{"$ref":"#/components/responses/SellerApiIdempotencyKeyRequired"},"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/redeemed or past the original expiry. Also returned for the `Idempotency-Key` itself: `IDEMPOTENCY_KEY_MISMATCH` (the key was already used with a different body) and `IDEMPOTENCY_REQUEST_IN_FLIGHT` (an earlier request with this key is still running; retry after `Retry-After` seconds).","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"},"503":{"$ref":"#/components/responses/SellerApiServiceUnavailable"},"504":{"$ref":"#/components/responses/SellerApiTimeout"}},"security":[{"bearerAuth":[]}],"x-avrix-scopes":["seller:orders:manage"],"x-avrix-tier":"orders","x-avrix-rate-limit-class":"orders","x-avrix-scope-mode":"anyOf","operationId":"createRegenerate"}},"/api/seller/v1/availability/changes":{"get":{"summary":"Availability change feed","description":"Per-seller cursor feed of availability changes, so a mirror keeps stock and Buy buttons current without calling `GET /availability` per SKU.\n\n- `stock_down` / `stock_up`: one allocation's remaining count moved (order, return, resize, top-up). `remaining` is the count after the change.\n- `unsellable` / `sellable`: the SKU crossed the sellable boundary for you (same readiness as `GET /allocations`); `reasons` lists the blockers. The same transitions are pushed as `sku.sellability_changed`.\n\nA state is recorded once: an unchanged count or sellability writes no entry.\n\n**Cursor loop:** start from the snapshot's `meta.availabilityCursor`, pass it as `cursor`, apply the page, persist `meta.nextCursor` and poll again right away while `meta.hasMore` is true. At the head the cursor you sent comes back unchanged. The feed is advisory; order preview and commit remain the authority.\n\n**Retention:** at least 30 days, like `GET /catalog/changes`. On contract date `2026-12-01` and later a `cursor` beyond retention is answered `409 CATALOG_RESYNC_REQUIRED`.\n\nPaging keys and the cursor rules are on `https://docs.avrix.io/seller-api/pagination`.","tags":["Allocations"],"security":[{"bearerAuth":[]}],"parameters":[{"name":"cursor","in":"query","required":false,"schema":{"type":"string"},"description":"Opaque position from `meta.nextCursor` or the snapshot's `meta.availabilityCursor`. Returns entries strictly after it; omit to read from the start of the retained feed. A `/catalog/changes` cursor is refused (422)."},{"name":"limit","in":"query","required":false,"schema":{"type":"integer","minimum":1,"maximum":5000,"default":500},"description":"Maximum entries to return (default 500, max 5000)"},{"$ref":"#/components/parameters/AvrixApiVersion"},{"$ref":"#/components/parameters/RequestId"},{"$ref":"#/components/parameters/SandboxSimulateRateLimit"}],"responses":{"200":{"description":"Availability changes","headers":{"X-Request-Id":{"$ref":"#/components/headers/XRequestId"},"X-Avrix-Api-Version":{"$ref":"#/components/headers/XAvrixApiVersion"},"X-Api-Version":{"$ref":"#/components/headers/XApiVersion"},"X-RateLimit-Limit":{"$ref":"#/components/headers/XRateLimitLimit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/XRateLimitRemaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/XRateLimitReset"},"X-RateLimit-Bucket":{"$ref":"#/components/headers/XRateLimitBucket"}},"content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"changes":{"type":"array","items":{"type":"object","properties":{"skuId":{"type":"string","format":"uuid"},"skuCode":{"type":["string","null"]},"productId":{"type":["string","null"],"format":"uuid"},"allocationId":{"type":["string","null"],"format":"uuid","description":"Stock entries: the allocation whose count moved. `null` on sellability entries."},"type":{"type":"string","enum":["stock_up","stock_down","sellable","unsellable"]},"remaining":{"type":["integer","null"],"description":"Stock entries: the allocation's remaining count after the change."},"reasons":{"type":"array","items":{"type":"string"},"description":"`unsellable` entries: readiness blockers (e.g. `NO_TERRITORY_PRICING`, `NO_ACTIVE_ALLOCATION`). Empty otherwise."},"occurredAt":{"type":"string","format":"date-time"}},"required":["skuId","type","reasons","occurredAt"]}}},"required":["changes"]},"meta":{"type":"object","properties":{"requestId":{"type":"string"},"nextCursor":{"type":["string","null"],"description":"Position of the last entry in this page; the cursor you sent when the page is empty; `null` only for an empty page with no cursor sent."},"hasMore":{"type":"boolean","description":"True when the page was cut at `limit`; poll again right away."},"limit":{"type":"integer","description":"The page size this response was cut at."},"nextUrl":{"type":["string","null"],"description":"Absolute URL of the next page: this request with `cursor` set to `nextCursor`. Null when there is no next page."}},"required":["nextCursor","hasMore"]}},"required":["data","meta"]},"example":{"data":{"changes":[{"skuId":"00441f16-3d2c-4024-8cd9-9d8072c03562","skuCode":"EXAMPLE-STEAM-WW","productId":"c5e89940-5398-4936-8230-d76126110948","allocationId":"7e6893d4-763f-458a-8186-61cdb11cc83d","type":"stock_up","remaining":12,"reasons":[],"occurredAt":"2026-11-02T09:30:00Z"}]},"meta":{"requestId":"29d4d5f7-46ff-49d2-8884-57806233f58f","nextCursor":"eyJ2IjoyLCJ0IjoiMjAyNi0xMS0wMlQwOTozMDowMFoifQ","hasMore":true,"limit":50,"nextUrl":"https://api.avrix.io/api/seller/v1/availability/changes?cursor=eyJ2IjoyLCJ0IjoiMjAyNi0xMS0wMlQwOTozMDowMFoifQ"}}}}},"400":{"$ref":"#/components/responses/SellerApiUnsupportedApiVersion"},"401":{"$ref":"#/components/responses/SellerApiUnauthorized"},"403":{"$ref":"#/components/responses/SellerApiForbidden"},"409":{"description":"`CATALOG_RESYNC_REQUIRED`: the feed cannot continue from this position. With a sandbox key, the store moved to its isolated sandbox environment and the `cursor` (or a `since` before the move) belongs to the shared sandbox feed. Product, SKU and allocation ids changed; take a fresh `GET /catalog/snapshot` and continue from its cursors. Public sandbox fixture codes are unchanged. From contract date `2026-12-01` on, with any key: the `cursor` (or `since`) is older than the feed's retention and changes after it were deleted (`details.reason` is `retention_expired`). Take a fresh `GET /catalog/snapshot` and continue from its `meta.changesCursor` and `meta.availabilityCursor`. Earlier dates keep serving the retained rows after such a position.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"examples":{"CATALOG_RESYNC_REQUIRED":{"value":{"code":"CATALOG_RESYNC_REQUIRED","message":"Your sandbox moved to its own isolated environment: product, SKU and allocation ids changed. Take a fresh GET /catalog/snapshot and continue from its cursors. Public sandbox fixture codes are unchanged.","error":"Your sandbox moved to its own isolated environment: product, SKU and allocation ids changed. Take a fresh GET /catalog/snapshot and continue from its cursors. Public sandbox fixture codes are unchanged.","timestamp":"2026-10-12T09:30:00.000Z","recoverable":false,"doc_url":"https://docs.avrix.io/seller-api/errors#catalog-resync-required","requestId":"req_av1203_example","details":{"field":"cursor"}}},"CATALOG_RESYNC_REQUIRED_RETENTION":{"value":{"code":"CATALOG_RESYNC_REQUIRED","message":"This feed position is older than the feed's retention: changes after it were deleted and cannot be replayed. Take a fresh GET /catalog/snapshot and continue from its meta.changesCursor and meta.availabilityCursor.","error":"This feed position is older than the feed's retention: changes after it were deleted and cannot be replayed. Take a fresh GET /catalog/snapshot and continue from its meta.changesCursor and meta.availabilityCursor.","timestamp":"2026-12-02T09:30:00.000Z","recoverable":false,"doc_url":"https://docs.avrix.io/seller-api/errors#catalog-resync-required","requestId":"req_av2038_example","details":{"field":"cursor","reason":"retention_expired"}}}}}}},"422":{"description":"Invalid query parameters. On contract date `2026-12-01` and later the body uses the shared `details.issues[]` form (`validationTarget: \"query\"`), and an unreadable `cursor` or a `limit` that is not a whole number from 1 to 5000 is refused here.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"429":{"$ref":"#/components/responses/SellerApiRateLimited"},"500":{"$ref":"#/components/responses/SellerApiInternalError"},"503":{"$ref":"#/components/responses/SellerApiServiceUnavailable"},"504":{"$ref":"#/components/responses/SellerApiTimeout"}},"x-avrix-scopes":["seller:products:read"],"x-avrix-tier":"catalog","x-avrix-rate-limit-class":"catalog","x-avrix-scope-mode":"anyOf","operationId":"listAvailabilityChanges"}},"/api/seller/v1/availability/{skuCode}":{"get":{"summary":"Availability by SKU code","description":"Single-SKU alias over `GET /availability`. Cacheable by your own HTTP cache via `Authorization` + `Accept-Language` (no shared CDN cache). Returns allocation + inventory headroom.\n\n**Bundles:** includes `skuType` + `bundleItems` when configured.","tags":["Allocations"],"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,"deprecated":true,"description":"Alias of `countryCode` (the original availability spelling, still accepted). Sending both with different values fails validation; a request that uses only this spelling gets an `X-Avrix-Deprecated-Parameter` response header naming the replacement.","schema":{"type":"string","pattern":"^[A-Za-z]{2}$"}},{"name":"quantity","in":"query","required":false,"schema":{"type":"integer","minimum":1},"description":"Optional quantity to check: the response says whether that many keys can be sold now."},{"$ref":"#/components/parameters/AvrixApiVersion"},{"$ref":"#/components/parameters/RequestId"},{"$ref":"#/components/parameters/SandboxSimulateRateLimit"}],"responses":{"200":{"description":"Availability row","headers":{"Server-Timing":{"description":"Phase breakdown of this response in milliseconds: `db` (grant, readiness and inventory reads), `redis` (checkout-hold ledger), `sellability` (per-country answer, when `country=` was sent) and `total`. Use it to attribute a slow response; the same phases are logged server-side above the platform threshold.","schema":{"type":"string"}},"X-Request-Id":{"$ref":"#/components/headers/XRequestId"},"X-Avrix-Api-Version":{"$ref":"#/components/headers/XAvrixApiVersion"},"X-Api-Version":{"$ref":"#/components/headers/XApiVersion"},"X-RateLimit-Limit":{"$ref":"#/components/headers/XRateLimitLimit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/XRateLimitRemaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/XRateLimitReset"},"X-RateLimit-Bucket":{"$ref":"#/components/headers/XRateLimitBucket"}},"content":{"application/json":{"schema":{"type":"object","additionalProperties":true,"properties":{"data":{"$ref":"#/components/schemas/SellerAvailability"}}},"example":{"data":{"available":12,"allocationRemaining":12,"inventoryAvailable":12,"allocationId":"cf56d0af-ff29-4d57-8a54-a2b309cbfe57","allocationReadableId":"alc_sjp8rabm","skuId":"bd0749e8-231f-42d6-8436-64684772e184","skuCode":"EXAMPLE-STEAM-WW","heldQuantity":12,"sellableNow":12,"maxFulfillableQuantity":12,"cannotFullyFulfill":true,"allOrNothingWillFail":true,"requestable":true,"backordered":true,"country":"DE","dedicatedAvailable":12,"sharedPoolAvailable":12,"backorderEligible":true}}}}},"400":{"$ref":"#/components/responses/SellerApiUnsupportedApiVersion"},"401":{"$ref":"#/components/responses/SellerApiUnauthorized"},"403":{"$ref":"#/components/responses/SellerApiForbidden"},"404":{"description":"SKU not allocated","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"422":{"$ref":"#/components/responses/SellerApiValidationFailed"},"429":{"$ref":"#/components/responses/SellerApiRateLimited"},"500":{"$ref":"#/components/responses/SellerApiInternalError"},"503":{"$ref":"#/components/responses/SellerApiServiceUnavailable"},"504":{"$ref":"#/components/responses/SellerApiTimeout"}},"security":[{"bearerAuth":[]}],"x-avrix-scopes":["seller:products:read"],"x-avrix-tier":"catalog","x-avrix-rate-limit-class":"catalog","x-avrix-scope-mode":"anyOf","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`). `meta.window` carries the event's `startsAt`/`endsAt` and `meta.active` says whether the window is open now (the same predicate that prices settlement). Apply a share's discounts to your storefront only while `meta.active` is `true`.\n\n**Outside the window:** on contract date `2026-12-01` and later the rows are returned before and after the window too, with `meta.active: false`, so you can stage a sale as soon as you accept. Earlier contract dates answer an empty `data` outside the window.\n\n**Not paginated:** the response is the complete discount table of the share. `limit` and `cursor` are deprecated: they were never read, and a request that sends them is answered as if they were absent.","tags":["Promotions"],"parameters":[{"name":"shareId","in":"path","required":true,"description":"Promotion share id.","schema":{"type":"string","format":"uuid"}},{"name":"limit","in":"query","schema":{"type":"integer","default":50,"minimum":1,"maximum":100},"deprecated":true,"description":"Deprecated: accepted and ignored. This operation is not paged and always returns the complete list."},{"name":"cursor","in":"query","schema":{"type":"string"},"deprecated":true,"description":"Deprecated: accepted and ignored. This operation is not paged and always returns the complete list."},{"$ref":"#/components/parameters/AvrixApiVersion"},{"$ref":"#/components/parameters/RequestId"},{"$ref":"#/components/parameters/SandboxSimulateRateLimit"}],"responses":{"200":{"description":"Rows. Outside the window: rows with `meta.active: false` on contract date `2026-12-01` and later; empty `data` on earlier dates.","headers":{"X-Request-Id":{"$ref":"#/components/headers/XRequestId"},"X-Avrix-Api-Version":{"$ref":"#/components/headers/XAvrixApiVersion"},"X-Api-Version":{"$ref":"#/components/headers/XApiVersion"},"X-RateLimit-Limit":{"$ref":"#/components/headers/XRateLimitLimit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/XRateLimitRemaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/XRateLimitReset"},"X-RateLimit-Bucket":{"$ref":"#/components/headers/XRateLimitBucket"}},"content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/SellerPromotionShareDiscount"}},"meta":{"type":["object","null"],"description":"The promotion window and whether it is open now.","properties":{"window":{"type":"object","properties":{"startsAt":{"type":["string","null"],"format":"date-time"},"endsAt":{"type":["string","null"],"format":"date-time"}}},"active":{"type":"boolean"}}}}},"example":{"data":[{"productId":"974bfe5b-1439-4ed3-8e31-361b217838e5","sku":"EXAMPLE-STEAM-WW","discountPct":12,"skuId":"cc719e53-780f-452c-87dc-21dcb2e8e19e","priceEffect":"list_price"}],"meta":{"window":{"startsAt":"2026-11-02T09:30:00Z","endsAt":"2026-11-02T09:30:00Z"},"active":true}}}}},"400":{"description":"`BAD_REQUEST` on contract dates before `2026-12-01`: the share has not been accepted yet (the discount table exists only for an accepted share), or it could not be read. From `2026-12-01` these are `409 CONFLICT` and `503`/`504`. Also returned for an `X-Avrix-Api-Version` this API does not serve (`UNSUPPORTED_API_VERSION`).","headers":{"X-Request-Id":{"$ref":"#/components/headers/XRequestId"},"X-Avrix-Api-Version":{"$ref":"#/components/headers/XAvrixApiVersion"},"X-Api-Version":{"$ref":"#/components/headers/XApiVersion"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"401":{"$ref":"#/components/responses/SellerApiUnauthorized"},"403":{"$ref":"#/components/responses/SellerApiForbidden"},"404":{"description":"Share not visible","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"409":{"description":"Contract date `2026-12-01` and later: `CONFLICT`, the share is not accepted. `details.reason` is `NOT_ACCEPTED` and `details.currentStatus` names the share's state.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"422":{"$ref":"#/components/responses/SellerApiValidationFailed"},"429":{"$ref":"#/components/responses/SellerApiRateLimited"},"500":{"$ref":"#/components/responses/SellerApiInternalError"},"503":{"$ref":"#/components/responses/SellerApiServiceUnavailable"},"504":{"$ref":"#/components/responses/SellerApiTimeout"}},"security":[{"bearerAuth":[]}],"x-avrix-scopes":["seller:promotions:read"],"x-avrix-tier":"promotions","x-avrix-rate-limit-class":"catalog","x-avrix-scope-mode":"anyOf","operationId":"listPromotionsSharesDiscounts"}},"/api/seller/v1/regions":{"get":{"summary":"List regions visible to seller","description":"The sales regions of the SKUs you hold an active allocation for. `allowedCountries` lists the countries that make up each region. A release can exclude some of them: what a given release may be sold in is `releases[].allowedCountries` on `GET /products/{productId}`, and that is what the order checks use.\n\n**Not paginated:** the response is the complete list, with no `meta`. `limit`, `cursor` and `partner` are deprecated: they were never read, and a request that sends them is answered as if they were absent.","tags":["Reference data"],"parameters":[{"name":"limit","in":"query","schema":{"type":"integer","default":50,"minimum":1,"maximum":100},"deprecated":true,"description":"Deprecated: accepted and ignored. This operation is not paged and always returns the complete list."},{"name":"cursor","in":"query","schema":{"type":"string"},"deprecated":true,"description":"Deprecated: accepted and ignored. This operation is not paged and always returns the complete list."},{"name":"partner","in":"query","schema":{"type":"string","maxLength":32,"pattern":"^[a-zA-Z0-9_-]+$"},"deprecated":true,"description":"Deprecated: accepted and ignored. It never filtered the result."},{"$ref":"#/components/parameters/AvrixApiVersion"},{"$ref":"#/components/parameters/RequestId"},{"$ref":"#/components/parameters/SandboxSimulateRateLimit"}],"responses":{"200":{"description":"Regions visible via active allocations (`{ data: SellerRegionSummary[] }`).","headers":{"X-Request-Id":{"$ref":"#/components/headers/XRequestId"},"X-Avrix-Api-Version":{"$ref":"#/components/headers/XAvrixApiVersion"},"X-Api-Version":{"$ref":"#/components/headers/XApiVersion"},"X-RateLimit-Limit":{"$ref":"#/components/headers/XRateLimitLimit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/XRateLimitRemaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/XRateLimitReset"},"X-RateLimit-Bucket":{"$ref":"#/components/headers/XRateLimitBucket"}},"content":{"application/json":{"schema":{"type":"object","required":["data"],"properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/SellerRegionSummary"}}}},"example":{"data":[{"code":"EU","name":"Example Game","allowedCountries":["DE"],"deniedCountries":["DE"]}]}}}},"400":{"$ref":"#/components/responses/SellerApiUnsupportedApiVersion"},"401":{"$ref":"#/components/responses/SellerApiUnauthorized"},"403":{"$ref":"#/components/responses/SellerApiForbidden"},"422":{"$ref":"#/components/responses/SellerApiValidationFailed"},"429":{"$ref":"#/components/responses/SellerApiRateLimited"},"500":{"$ref":"#/components/responses/SellerApiInternalError"},"503":{"$ref":"#/components/responses/SellerApiServiceUnavailable"},"504":{"$ref":"#/components/responses/SellerApiTimeout"}},"security":[{"bearerAuth":[]}],"x-avrix-scopes":["seller:products:read"],"x-avrix-tier":"catalog","x-avrix-rate-limit-class":"catalog","x-avrix-scope-mode":"anyOf","operationId":"listRegions"}},"/api/seller/v1/regions/{code}":{"get":{"summary":"Region detail","description":"One region by its code (case-insensitive), when it is among the regions returned by `GET /regions`. **404** `NOT_FOUND` when the region does not exist or none of your active allocations is in it.\n\n`partner` is deprecated: it was never read, and a request that sends it is answered as if it were absent.","tags":["Reference data"],"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_-]+$"},"deprecated":true,"description":"Deprecated: accepted and ignored. It never filtered the result."},{"$ref":"#/components/parameters/AvrixApiVersion"},{"$ref":"#/components/parameters/RequestId"},{"$ref":"#/components/parameters/SandboxSimulateRateLimit"}],"responses":{"200":{"description":"Region detail","headers":{"X-Request-Id":{"$ref":"#/components/headers/XRequestId"},"X-Avrix-Api-Version":{"$ref":"#/components/headers/XAvrixApiVersion"},"X-Api-Version":{"$ref":"#/components/headers/XApiVersion"},"X-RateLimit-Limit":{"$ref":"#/components/headers/XRateLimitLimit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/XRateLimitRemaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/XRateLimitReset"},"X-RateLimit-Bucket":{"$ref":"#/components/headers/XRateLimitBucket"}},"content":{"application/json":{"schema":{"type":"object","required":["data"],"properties":{"data":{"$ref":"#/components/schemas/SellerRegionDetail"}}},"example":{"data":{"code":"EU","name":"Example Game","allowedCountries":["DE"],"deniedCountries":["DE"]}}}}},"400":{"$ref":"#/components/responses/SellerApiUnsupportedApiVersion"},"401":{"$ref":"#/components/responses/SellerApiUnauthorized"},"403":{"$ref":"#/components/responses/SellerApiForbidden"},"404":{"description":"Unknown / not visible","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"422":{"$ref":"#/components/responses/SellerApiValidationFailed"},"429":{"$ref":"#/components/responses/SellerApiRateLimited"},"500":{"$ref":"#/components/responses/SellerApiInternalError"},"503":{"$ref":"#/components/responses/SellerApiServiceUnavailable"},"504":{"$ref":"#/components/responses/SellerApiTimeout"}},"security":[{"bearerAuth":[]}],"x-avrix-scopes":["seller:products:read"],"x-avrix-tier":"catalog","x-avrix-rate-limit-class":"catalog","x-avrix-scope-mode":"anyOf","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`.\n\n**Paging:** the shared list contract, see `https://docs.avrix.io/seller-api/pagination`. On contract date `2026-12-01` and later a `cursor` this API did not return is refused with `422 VALIDATION_FAILED` (`details.issues[].field` is `cursor`); earlier dates serve the first page.","tags":["Seller meta"],"parameters":[{"name":"limit","in":"query","description":"Page size: how many items to return (1 to 100).","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`, `reinstatement`, `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","description":"`json` (default) or `csv`. `csv` answers `text/csv` as an attachment.","schema":{"type":"string","enum":["json","csv"],"default":"json"}},{"name":"kind","in":"query","required":false,"deprecated":true,"schema":{"type":"string"},"description":"Deprecated alias of `kinds`."},{"$ref":"#/components/parameters/AvrixApiVersion"},{"$ref":"#/components/parameters/RequestId"},{"$ref":"#/components/parameters/SandboxSimulateRateLimit"}],"responses":{"200":{"description":"Settlement entries (or legacy rows when `kinds` is limited to legacy kinds).","headers":{"X-Request-Id":{"$ref":"#/components/headers/XRequestId"},"X-Avrix-Api-Version":{"$ref":"#/components/headers/XAvrixApiVersion"},"X-Api-Version":{"$ref":"#/components/headers/XApiVersion"},"X-RateLimit-Limit":{"$ref":"#/components/headers/XRateLimitLimit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/XRateLimitRemaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/XRateLimitReset"},"X-RateLimit-Bucket":{"$ref":"#/components/headers/XRateLimitBucket"},"X-Next-Cursor":{"$ref":"#/components/headers/XNextCursor"}},"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"]},"hasMore":{"type":"boolean","description":"True when another page follows. Loop on `hasMore`; send `nextCursor` back as `cursor`."},"nextUrl":{"type":["string","null"],"description":"Absolute URL of the next page: this request with `cursor` set to `nextCursor`. Null when there is no next page."}}}}},"example":{"data":[{"id":"e2cb4f3e-126e-4f0f-82d9-0b41234513ec","kind":"sale","occurredAt":"2026-11-02T09:30:00Z","stockMovement":12,"orderReference":"store-order-10432","keyId":"de6aa234-da2d-4804-8713-560cdb663e5f","keyPullId":"0b99fd3a-4b82-4a21-8318-56f877c4e2f2","skuId":"34544abf-96b1-42bd-826c-daf5b990f2c6","productId":"47a44a90-e4dd-45f5-81e9-d17d61b11ab4","counterparty":{"publisherCompanyId":"acme-games"},"contractTermId":"314615e6-4f40-48c2-826d-e48f14f92d30","promo":{"sourceType":"event","sourceId":"2db2e14a-d038-4d4b-87c1-c909b19ab04a"},"requestedCountry":"DE","detectedCountry":"DE","warnings":["COUNTRY_MISMATCH"],"economics":{"currencyCode":"EUR","currencyExponent":2,"unitPriceCents":2450,"unitPriceMinor":2450,"initialUnitPriceCents":2450,"initialUnitPriceMinor":2450,"publisherShareCents":2450,"publisherShareMinor":2450,"sellerShareCents":2450,"sellerShareMinor":2450,"platformFeeCents":2450,"platformFeeMinor":2450},"adjustmentReference":"adj_10432"}],"meta":{"limit":50,"nextCursor":"eyJ2IjoyLCJ0IjoiMjAyNi0xMS0wMlQwOTozMDowMFoifQ","hasMore":true,"nextUrl":"https://api.avrix.io/api/seller/v1/example?cursor=eyJ2IjoyfQ"}}},"text/csv":{"schema":{"type":"string"}}}},"400":{"$ref":"#/components/responses/SellerApiUnsupportedApiVersion"},"401":{"$ref":"#/components/responses/SellerApiUnauthorized"},"403":{"$ref":"#/components/responses/SellerApiForbidden"},"422":{"$ref":"#/components/responses/SellerApiValidationFailed"},"429":{"$ref":"#/components/responses/SellerApiRateLimited"},"500":{"$ref":"#/components/responses/SellerApiInternalError"},"503":{"$ref":"#/components/responses/SellerApiServiceUnavailable"},"504":{"$ref":"#/components/responses/SellerApiTimeout"}},"security":[{"bearerAuth":[]}],"x-avrix-scopes":["seller:finance:read","seller:products:read"],"x-avrix-tier":"orders","x-avrix-rate-limit-class":"orders","x-avrix-scope-mode":"anyOf","operationId":"listActivity"}},"/api/seller/v1/events":{"get":{"summary":"Event feed","description":"Forward-only feed of your events. 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`.\n\n**Contract date `2026-12-01` and later: the event log.** One row per event, whether or not any webhook endpoint subscribes to it, kept 30 days. Each row's `id` is the `eventLogId` every webhook delivery of that event carries, so the feed and your webhook handler deduplicate on the same value. Filter with `eventType` (one or more event names), `resourceType` and `resourceId`. A store with no webhook endpoint can follow its events from here alone. The feed reads a few seconds behind the present so that an event recorded a moment before a later one is never skipped.\n\n**Earlier contract dates: webhook deliveries.** One row per delivery to each of your endpoints (nothing when you have none), as before; `eventType`, `resourceType` and `resourceId` stay unknown there and are refused with `422 VALIDATION_FAILED` naming them, so a filter is never silently dropped.\n\n**Paging:** the shared list contract, see `https://docs.avrix.io/seller-api/pagination`. On contract date `2026-12-01` and later a `cursor` this API did not return is refused with `422 VALIDATION_FAILED` (`details.issues[].field` is `cursor`); earlier dates serve the first page.","tags":["Webhooks"],"parameters":[{"name":"limit","in":"query","description":"Page size: how many items to return (1 to 100).","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"}},{"name":"eventType","in":"query","required":false,"description":"Contract date `2026-12-01` and later: only these event types. A comma-separated list, or the parameter repeated, of names from `GET /webhooks/event-types`; at most 20. An unknown name is refused with `422 VALIDATION_FAILED` (`details.issues[].field` is `eventType`). On earlier dates the parameter is unknown, as it was before it existed: `422 VALIDATION_FAILED` naming it.","schema":{"type":"string"},"example":"order.cancelled,return.decided"},{"name":"resourceType","in":"query","required":false,"description":"Contract date `2026-12-01` and later: only events about this kind of resource (the event reference lists which events name which resource). On earlier dates the parameter is unknown, as it was before it existed: `422 VALIDATION_FAILED` naming it.","schema":{"type":"string","enum":["order","chargeback","catalog_export","allocation","allocation_request","dispute_freeze","product","sku","contract_term","connection","connection_request","access_proposal","return_request","promotion","invoice","report","api_key","webhook_endpoint","platform_notice"]}},{"name":"resourceId","in":"query","required":false,"description":"Contract date `2026-12-01` and later: only events about this resource, by the id the Seller API names it with (for orders, your `orderReference`). Combine with `resourceType`. On earlier dates the parameter is unknown, as it was before it existed: `422 VALIDATION_FAILED` naming it.","schema":{"type":"string","maxLength":256}},{"$ref":"#/components/parameters/AvrixApiVersion"},{"$ref":"#/components/parameters/RequestId"},{"$ref":"#/components/parameters/SandboxSimulateRateLimit"}],"responses":{"200":{"description":"Contract date `2026-12-01` and later: events from your event log (`SellerEventLogItem`). Earlier dates: webhook deliveries across all your endpoints (`SellerWebhookDeliveryCursorItem`). Both with `meta.nextCursor` / `meta.nextSince`.","headers":{"X-Request-Id":{"$ref":"#/components/headers/XRequestId"},"X-Avrix-Api-Version":{"$ref":"#/components/headers/XAvrixApiVersion"},"X-Api-Version":{"$ref":"#/components/headers/XApiVersion"},"X-RateLimit-Limit":{"$ref":"#/components/headers/XRateLimitLimit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/XRateLimitRemaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/XRateLimitReset"},"X-RateLimit-Bucket":{"$ref":"#/components/headers/XRateLimitBucket"}},"content":{"application/json":{"schema":{"type":"object","required":["data","meta"],"properties":{"data":{"type":"array","description":"Events (contract date `2026-12-01` and later) or webhook deliveries (earlier dates), oldest first.","items":{"oneOf":[{"$ref":"#/components/schemas/SellerWebhookDeliveryCursorItem"},{"$ref":"#/components/schemas/SellerEventLogItem"}]}},"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."},"headCursor":{"type":["string","null"],"description":"Resume position, present at the head too (null only when nothing was returned and no cursor was sent). Store it after every page and pass it as `cursor` on your next poll. Make the first call without `cursor`; `cursor` accepts only values this API returned."},"limit":{"type":"integer","description":"The page size this response was cut at."},"hasMore":{"type":"boolean","description":"True when another page follows. Loop on `hasMore`; send `nextCursor` back as `cursor`."},"nextUrl":{"type":["string","null"],"description":"Absolute URL of the next page: this request with `cursor` set to `nextCursor`. Null when there is no next page."},"retentionDays":{"type":"integer","description":"How many days the event log keeps events (at least 30). Present on contract date `2026-12-01` and later."},"retainedFrom":{"type":"string","format":"date-time","description":"The oldest instant the event log still promises to hold. Present on contract date `2026-12-01` and later."},"positionBeforeRetention":{"type":"boolean","description":"True when `cursor` or `since` points before `retainedFrom`: events between that position and `retainedFrom` may already have been deleted. Re-synchronise from the resources themselves (orders, allocations, catalog), then continue from `headCursor`. Present on contract date `2026-12-01` and later."}}}}},"example":{"data":[{"id":"f8b1b162-6475-452f-8e91-7bee491e5680","endpointId":"b5d5559b-0e6f-477e-8994-ea6aa3862d27","eventId":"e5170dbb-5d4a-4d60-8fcf-31bf4789a7bb","eventType":"order.fulfilled","status":"succeeded","attempts":1,"responseStatus":200,"payload":{},"createdAt":"2026-11-02T09:30:00Z","lastAttemptAt":"2026-11-02T09:30:00Z","nextRetryAt":"2026-11-02T09:30:00Z"}],"meta":{"requestId":"aa82c471-bca2-4e15-8e85-ebb8a8ee9cf7","nextSince":"2026-11-02T09:30:00Z","nextCursor":"eyJ2IjoyLCJ0IjoiMjAyNi0xMS0wMlQwOTozMDowMFoifQ","headCursor":"eyJ2IjoyLCJ0IjoiMjAyNi0xMS0wMlQwOTozMDowMFoifQ","limit":50,"hasMore":true,"nextUrl":"https://api.avrix.io/api/seller/v1/events?cursor=eyJ2IjoyLCJ0IjoiMjAyNi0xMS0wMlQwOTozMDowMFoifQ"}}}}},"400":{"$ref":"#/components/responses/SellerApiUnsupportedApiVersion"},"401":{"$ref":"#/components/responses/SellerApiUnauthorized"},"403":{"$ref":"#/components/responses/SellerApiForbidden"},"422":{"description":"Invalid since, pagination or (contract date `2026-12-01` and later) filter","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"429":{"$ref":"#/components/responses/SellerApiRateLimited"},"500":{"$ref":"#/components/responses/SellerApiInternalError"},"503":{"$ref":"#/components/responses/SellerApiServiceUnavailable"},"504":{"$ref":"#/components/responses/SellerApiTimeout"}},"security":[{"bearerAuth":[]}],"x-avrix-scopes":["seller:webhooks:read"],"x-avrix-tier":"webhooks","x-avrix-rate-limit-class":"orders","x-avrix-scope-mode":"anyOf","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`.","parameters":[{"$ref":"#/components/parameters/AvrixApiVersion"},{"$ref":"#/components/parameters/RequestId"},{"$ref":"#/components/parameters/SandboxSimulateRateLimit"}],"responses":{"200":{"description":"Seller finance overview payload","headers":{"X-Request-Id":{"$ref":"#/components/headers/XRequestId"},"X-Avrix-Api-Version":{"$ref":"#/components/headers/XAvrixApiVersion"},"X-Api-Version":{"$ref":"#/components/headers/XApiVersion"},"X-RateLimit-Limit":{"$ref":"#/components/headers/XRateLimitLimit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/XRateLimitRemaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/XRateLimitReset"},"X-RateLimit-Bucket":{"$ref":"#/components/headers/XRateLimitBucket"}},"content":{"application/json":{"schema":{"type":"object","required":["data"],"properties":{"data":{"type":"object","properties":{"outstandingByCurrency":{"type":"array","items":{"type":"object","required":["currencyCode","currencyExponent","cents","amountMinor"],"properties":{"currencyCode":{"type":"string"},"currencyExponent":{"type":"integer","minimum":0,"maximum":3,"description":"Number of minor-unit digits for `currencyCode`: 2 for USD, 0 for JPY, 3 for KWD. amount = minor units / 10^currencyExponent. Additive."},"cents":{"type":"integer","deprecated":true,"description":"Deprecated name of `amountMinor` (same value). Kept on the wire; see Naming conventions in the Versioning and compatibility guide."},"amountMinor":{"type":"integer","description":"Same amount as `cents`, under the `...Minor` name every Seller API amount uses: integer minor units of the currency beside it (see `currencyExponent`)."}}},"description":"One entry per currency; never summed across currencies."},"publisherRelationshipCount":{"type":"integer","description":"Publishers you hold a live grant with or sold for this period (at least the reported relationships)."},"draftReportsCount":{"type":"integer"},"paidThisMonthByCurrency":{"type":"array","items":{"type":"object","required":["currencyCode","currencyExponent","cents","amountMinor"],"properties":{"currencyCode":{"type":"string"},"currencyExponent":{"type":"integer","minimum":0,"maximum":3,"description":"Number of minor-unit digits for `currencyCode`: 2 for USD, 0 for JPY, 3 for KWD. amount = minor units / 10^currencyExponent. Additive."},"cents":{"type":"integer","deprecated":true,"description":"Deprecated name of `amountMinor` (same value). Kept on the wire; see Naming conventions in the Versioning and compatibility guide."},"amountMinor":{"type":"integer","description":"Same amount as `cents`, under the `...Minor` name every Seller API amount uses: integer minor units of the currency beside it (see `currencyExponent`)."}}},"description":"One entry per currency; never summed across currencies."},"paidThisMonthPaymentCount":{"type":"integer"},"recentReports":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"counterpartyCompanyId":{"type":["string","null"]},"reportMonth":{"type":"string","description":"YYYY-MM"},"periodStart":{"type":["string","null"]},"periodEnd":{"type":["string","null"]},"modelType":{"type":"string","enum":["api","revenue_share"],"x-extensible-enum":true,"description":"Business model the report covers: `api` (per-sale API catalog) or `revenue_share`. New values may be added."},"status":{"type":"string","enum":["draft","submitted","approved","disputed","rejected","overdue"],"x-extensible-enum":true,"description":"Monthly sales report state: `draft` -> `submitted` -> `approved`, or `disputed` / `rejected` on review; `overdue` when it was not submitted in time. Only an `approved` report settles. New values may be added; treat an unknown one as not settled."},"currencyCode":{"type":"string"},"totalNetRevenue":{"type":["number","null"],"description":"Deprecated: the only Seller API amount in major units (a decimal). Use `totalNetRevenueMinor`. Kept unchanged on the wire.","deprecated":true},"totalNetRevenueMinor":{"type":["integer","null"],"description":"The report total in integer minor units of `currencyCode` (`totalNetRevenue` multiplied by 10^`currencyExponent`, rounded). Null when the report has no total yet."},"currencyExponent":{"type":"integer","minimum":0,"maximum":3,"description":"Number of minor-unit digits for `currencyCode`: 2 for USD, 0 for JPY, 3 for KWD."},"submittedAt":{"type":["string","null"],"format":"date-time"},"createdAt":{"type":["string","null"],"format":"date-time"},"updatedAt":{"type":["string","null"],"format":"date-time"}}}},"attentionReports":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"counterpartyCompanyId":{"type":["string","null"]},"reportMonth":{"type":"string","description":"YYYY-MM"},"periodStart":{"type":["string","null"]},"periodEnd":{"type":["string","null"]},"modelType":{"type":"string","enum":["api","revenue_share"],"x-extensible-enum":true,"description":"Business model the report covers: `api` (per-sale API catalog) or `revenue_share`. New values may be added."},"status":{"type":"string","enum":["draft","submitted","approved","disputed","rejected","overdue"],"x-extensible-enum":true,"description":"Monthly sales report state: `draft` -> `submitted` -> `approved`, or `disputed` / `rejected` on review; `overdue` when it was not submitted in time. Only an `approved` report settles. New values may be added; treat an unknown one as not settled."},"currencyCode":{"type":"string"},"totalNetRevenue":{"type":["number","null"],"description":"Deprecated: the only Seller API amount in major units (a decimal). Use `totalNetRevenueMinor`. Kept unchanged on the wire.","deprecated":true},"totalNetRevenueMinor":{"type":["integer","null"],"description":"The report total in integer minor units of `currencyCode` (`totalNetRevenue` multiplied by 10^`currencyExponent`, rounded). Null when the report has no total yet."},"currencyExponent":{"type":"integer","minimum":0,"maximum":3,"description":"Number of minor-unit digits for `currencyCode`: 2 for USD, 0 for JPY, 3 for KWD."},"submittedAt":{"type":["string","null"],"format":"date-time"},"createdAt":{"type":["string","null"],"format":"date-time"},"updatedAt":{"type":["string","null"],"format":"date-time"}}},"description":"Reports waiting on you, most urgent status first."},"currentPeriod":{"type":["object","null"],"description":"API sales recorded this UTC month, before any monthly report. The statement for the period lists them.","properties":{"period":{"type":"string"},"apiSalesCount":{"type":"integer"},"byCurrency":{"type":"array","items":{"type":"object","properties":{"currencyCode":{"type":"string"},"currencyExponent":{"type":"integer","minimum":0,"maximum":3,"description":"Number of minor-unit digits for `currencyCode`: 2 for USD, 0 for JPY, 3 for KWD. amount = minor units / 10^currencyExponent. Additive."},"salesCount":{"type":"integer"},"grossCents":{"type":"integer","deprecated":true,"description":"Deprecated name of `grossMinor` (same value). Kept on the wire; see Naming conventions in the Versioning and compatibility guide."},"grossMinor":{"type":"integer","description":"Same amount as `grossCents`, under the `...Minor` name every Seller API amount uses: integer minor units of the currency beside it (see `currencyExponent`)."},"sellerShareCents":{"type":"integer","deprecated":true,"description":"Deprecated name of `sellerShareMinor` (same value). Kept on the wire; see Naming conventions in the Versioning and compatibility guide."},"sellerShareMinor":{"type":"integer","description":"Same amount as `sellerShareCents`, under the `...Minor` name every Seller API amount uses: integer minor units of the currency beside it (see `currencyExponent`)."},"publisherShareCents":{"type":"integer","deprecated":true,"description":"Deprecated name of `publisherShareMinor` (same value). Kept on the wire; see Naming conventions in the Versioning and compatibility guide."},"publisherShareMinor":{"type":"integer","description":"Same amount as `publisherShareCents`, under the `...Minor` name every Seller API amount uses: integer minor units of the currency beside it (see `currencyExponent`)."}}}},"truncated":{"type":"boolean","description":"True when the month has more sales than one summary read counts; use the statement for exact totals."},"activityTotals":{"type":["array","null"],"items":{"$ref":"#/components/schemas/SellerLedgerBalance"},"description":"The month's ledger balance per currency: sales, refunds, chargebacks and reinstatements by when they happened. Equal to `GET /finance/ledger?period=` `meta.balances` and to the statement's `activityTotals` for the same month. `byCurrency` above counts sales only, by when they were recorded, and is kept for existing clients. Null when the balance could not be read."}}},"notices":{"type":"array","items":{"type":"object","required":["code","message","href"],"properties":{"code":{"type":"string","enum":["API_SALES_NOT_YET_REPORTED","INVOICES_FOLLOW_APPROVAL"]},"message":{"type":"string"},"href":{"type":"string","description":"Where the period's sales are, e.g. /api/seller/v1/finance/statements?period=2026-09."}}},"description":"Why report-driven fields (balances, reports, payments) are still empty for a period that has sales."}}}}},"example":{"data":{"outstandingByCurrency":[{"currencyCode":"EUR","currencyExponent":2,"cents":2450,"amountMinor":2450}],"publisherRelationshipCount":12,"draftReportsCount":12,"paidThisMonthByCurrency":[{"currencyCode":"EUR","currencyExponent":2,"cents":2450,"amountMinor":2450}],"paidThisMonthPaymentCount":12,"recentReports":[{"id":"7d5ef76b-571c-4e28-8dfe-9df6d0175702","counterpartyCompanyId":"1fc2ec87-3071-4ea4-81ba-ff938ca7780b","reportMonth":"2026-10","periodStart":"2026-10-01T00:00:00Z","periodEnd":"2026-10-31T23:59:59Z","modelType":"api","status":"draft","currencyCode":"EUR","totalNetRevenue":2450,"submittedAt":"2026-11-02T09:30:00Z","createdAt":"2026-11-02T09:30:00Z","updatedAt":"2026-11-02T09:30:00Z"}],"attentionReports":[{"id":"6c024eb6-4692-4248-894e-20b96c2a708d","counterpartyCompanyId":"e59900e0-8218-4cbf-8441-f0aa6e1870ec","reportMonth":"2026-10","periodStart":"2026-10-01T00:00:00Z","periodEnd":"2026-10-31T23:59:59Z","modelType":"api","status":"draft","currencyCode":"EUR","totalNetRevenue":2450,"submittedAt":"2026-11-02T09:30:00Z","createdAt":"2026-11-02T09:30:00Z","updatedAt":"2026-11-02T09:30:00Z"}],"currentPeriod":{"period":"2026-10","apiSalesCount":12,"byCurrency":[{"currencyCode":"EUR","currencyExponent":2,"salesCount":12,"grossCents":2450,"sellerShareCents":2450,"publisherShareCents":2450}],"truncated":false},"notices":[{"code":"API_SALES_NOT_YET_REPORTED","message":"Example text.","href":"https://api.avrix.io/api/seller/v1/example"}]}}}}},"400":{"$ref":"#/components/responses/SellerApiUnsupportedApiVersion"},"401":{"$ref":"#/components/responses/SellerApiUnauthorized"},"403":{"$ref":"#/components/responses/SellerApiForbidden"},"422":{"$ref":"#/components/responses/SellerApiValidationFailed"},"429":{"$ref":"#/components/responses/SellerApiRateLimited"},"500":{"$ref":"#/components/responses/SellerApiInternalError"},"503":{"$ref":"#/components/responses/SellerApiServiceUnavailable"},"504":{"$ref":"#/components/responses/SellerApiTimeout"}},"security":[{"bearerAuth":[]}],"x-avrix-scopes":["seller:finance:read"],"x-avrix-tier":"finance","x-avrix-rate-limit-class":"finance","x-avrix-scope-mode":"anyOf","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 the opaque value of `meta.nextCursor`, sent back unchanged. **Reference correction:** an earlier reference called it a numeric offset string; offset cursors issued before 2026-08 are still read. 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), entryType, reversesTransactionId, vatMinor, netMinor, appliedRatePercent, rateReason, evidenceRank, requestedCountry, promoSourceType, promoSourceId, initialSalePriceCents. Columns are only ever appended, so parse by header name. The settlement columns (vatMinor through requestedCountry) are empty when the row has no settlement. promoSourceType and promoSourceId name the promotion behind the price, also on refund, chargeback and reinstatement rows; initialSalePriceCents is empty on those correction rows and on secondary-currency promo sales.\n\n**Paging:** the shared list contract, see `https://docs.avrix.io/seller-api/pagination`. On contract date `2026-12-01` and later a `cursor` this API did not return is refused with `422 VALIDATION_FAILED` (`details.issues[].field` is `cursor`); earlier dates serve the first page.","parameters":[{"name":"limit","in":"query","description":"Page size: how many items to return (1 to 100).","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","description":"Return only sales at or after this time (inclusive).","schema":{"type":"string","format":"date-time"}},{"name":"to","in":"query","description":"Return only sales at or before this time (inclusive).","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."},{"name":"orderReference","in":"query","required":false,"schema":{"type":"string","minLength":1,"maxLength":512},"description":"Only the sale rows of this order reference."},{"$ref":"#/components/parameters/AvrixApiVersion"},{"$ref":"#/components/parameters/RequestId"},{"$ref":"#/components/parameters/SandboxSimulateRateLimit"}],"responses":{"200":{"description":"Rows and pagination meta","headers":{"X-Request-Id":{"$ref":"#/components/headers/XRequestId"},"X-Avrix-Api-Version":{"$ref":"#/components/headers/XAvrixApiVersion"},"X-Api-Version":{"$ref":"#/components/headers/XApiVersion"},"X-RateLimit-Limit":{"$ref":"#/components/headers/XRateLimitLimit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/XRateLimitRemaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/XRateLimitReset"},"X-RateLimit-Bucket":{"$ref":"#/components/headers/XRateLimitBucket"},"X-Next-Cursor":{"$ref":"#/components/headers/XNextCursor"}},"content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/SellerApiSaleTransaction"}},"meta":{"$ref":"#/components/schemas/PaginationMeta"}}},"example":{"data":[{"id":"a60b9fab-3d09-442a-844d-e617db65231f","publisherCompanyId":"acme-games","keyPullId":"af8b0aa1-3d3e-4e80-88b8-38305d982075","keyId":"679d14b2-55aa-4442-83f1-05f0c49546a6","skuId":"642ce6d2-a2eb-40b6-8860-bfd734921fd2","productId":"b531da56-0323-49cb-8df5-d5c908c73f9d","salePriceCents":2450,"initialSalePriceCents":2450,"promo":{"sourceType":"event","sourceId":"f20e5306-668f-421c-8d92-24024cc9d657"},"currencyCode":"EUR","currencyExponent":2,"publisherShareCents":2450,"sellerShareCents":2450,"platformFeeCents":2450,"revenueSharePercent":20,"saleTimestamp":"2026-11-02T09:30:00Z","aggregationStatus":"pending","reportId":"a2f58066-18cc-4865-84e4-8481f1133908","orderReference":"store-order-10432","customerRegionCode":"DE","detectedCountryCode":"off","countryMismatch":true,"warnings":["COUNTRY_MISMATCH"],"contractTermId":"5fb782c2-bc79-4364-83c0-eb0285111cbe","contractTermVersion":1,"adjustmentStatus":"none","declaredRetail":{"retailCurrencyCode":"EUR","currencyExponent":2,"grossMinor":2450,"netMinor":2450,"taxAmountMinor":2450,"taxRatePercent":20,"priceIncludesTax":true,"paymentMethodFamily":"card","paymentProcessorReference":"pi_10432","checkoutSessionId":"cs_10432","purchaseOrderNumber":"PO-10432"},"integrationOrderContext":{"schemaVersion":1,"consumerIp":"203.0.113.10","salesCountryCode":"CO","currencyCode":"EUR","currencyExponent":2,"salesPriceGrossMinor":2450,"salesPriceNetMinor":2450,"appliedDiscountPercentage":20,"appliedDiscountAmountMinor":2450,"immediateFulfilment":true,"mustFulfil":true,"buyerLocale":"de-DE","priceIncludesTax":true,"salesTaxAmountMinor":2450,"salesTaxRatePercent":20,"customerVatNumber":"DE123456789","purchaseOrderNumber":"PO-10432","customerType":"b2c","paymentMethodFamily":"card","paymentProcessorReference":"pi_10432","checkoutSessionId":"cs_10432","salesChannel":"web","lineIndex":1,"parentOrderReference":"store-order-10432","externalNetworkOrderId":"00f6fd41-72b0-4249-88a0-75af0a3d6bfa","consumerIpHash":"3f9a1c7e2b4d6a80","consumerIpRedacted":true},"taxMetadata":{"declaredTaxAmountMinor":2450,"declaredTaxRatePercent":20,"priceIncludesTax":true,"authoritative":false},"settlement":{"basis":"purchaser_country_capped","vatMinor":2450,"netMinor":2450,"appliedRatePercent":20,"declaredRatePercent":20,"evidenceRank":1,"requestedCountry":"DE"},"entryType":"sale","reversesTransactionId":"974af312-319e-48e4-8153-7b12ebb53569"}],"meta":{"total":2450,"limit":50,"hasMore":true,"nextCursor":"eyJ2IjoyLCJ0IjoiMjAyNi0xMS0wMlQwOTozMDowMFoifQ","nextUrl":"https://api.avrix.io/api/seller/v1/finance/api-sales?cursor=eyJ2IjoyLCJ0IjoiMjAyNi0xMS0wMlQwOTozMDowMFoifQ","localePreference":"en"}}},"text/csv":{"schema":{"type":"string","description":"`format=csv`: one row per sale; columns as named in the header row and in the description. The next page's cursor is in `X-Next-Cursor`."}}}},"400":{"$ref":"#/components/responses/SellerApiUnsupportedApiVersion"},"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"},"503":{"$ref":"#/components/responses/SellerApiServiceUnavailable"},"504":{"$ref":"#/components/responses/SellerApiTimeout"}},"security":[{"bearerAuth":[]}],"x-avrix-scopes":["seller:finance:read"],"x-avrix-tier":"finance","x-avrix-rate-limit-class":"finance","x-avrix-scope-mode":"anyOf","tags":["Finance"],"operationId":"listFinanceApiSales"}},"/api/seller/v1/finance/invoices":{"get":{"summary":"List the invoices you owe","description":"The invoices you owe, newest issue date first: mostly each vendor's monthly invoice (`kind: vendor_payable`), plus documents of the earlier per-report and per-allocation billing. Read one with `GET /finance/invoices/{invoiceId}`, its payment with `GET /finance/payments`, and the sales it covers with `GET /finance/invoices/{invoiceId}/reconciliation`. Requires `seller:finance:read`.\n\n**Filters** (all optional, combined with AND): `status`, `kind`, `invoiceType`, `publisherCompanyId`, `reportMonth`, `issuedFrom` / `issuedTo` (issue date, `issuedTo` exclusive), `updatedSince` (sync changes since your last run).\n\n**Credit notes** carry a positive total; `invoiceType: credit_note` is what says the money comes back to you. A corrected invoice names the one it replaces in `replacesInvoiceId`; the replaced one has `status: superseded` and `supersededByInvoiceId`.\n\n**Paging:** the shared list contract, see `https://docs.avrix.io/seller-api/pagination`. On contract date `2026-12-01` and later a `cursor` this API did not return is refused with `422 VALIDATION_FAILED` (`details.issues[].field` is `cursor`); earlier dates serve the first page.","parameters":[{"name":"limit","in":"query","description":"Page size: how many items to return (1 to 100).","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":"status","in":"query","description":"Only invoices in these states. Comma-separated; any of: `awaiting_commission_document`, `payable`, `disputed`, `overdue`, `paid`, `superseded`, `sent`, `cancelled`, `credited`. An unknown value is refused with `422 VALIDATION_FAILED`.","schema":{"type":"string","example":"awaiting_commission_document,payable"}},{"name":"kind","in":"query","description":"Only invoices of these kinds. Comma-separated; any of: `vendor_payable`, `avrix_commission`, `legacy_allocation`, `legacy_report`. An unknown value is refused with `422 VALIDATION_FAILED`.","schema":{"type":"string","example":"vendor_payable,avrix_commission"}},{"name":"invoiceType","in":"query","description":"Only these invoice types. Comma-separated; any of: `proforma`, `final`, `credit_note`. An unknown value is refused with `422 VALIDATION_FAILED`.","schema":{"type":"string","example":"proforma,final"}},{"name":"publisherCompanyId","in":"query","description":"Only invoices from this vendor (company id).","schema":{"type":"string","maxLength":128}},{"name":"reportMonth","in":"query","description":"Only invoices for this sales month, `YYYY-MM`.","schema":{"type":"string","pattern":"^\\d{4}-(0[1-9]|1[0-2])$"}},{"name":"issuedFrom","in":"query","description":"Issued at or after this instant.","schema":{"type":"string","format":"date-time"}},{"name":"issuedTo","in":"query","description":"Issued before this instant.","schema":{"type":"string","format":"date-time"}},{"name":"updatedSince","in":"query","description":"Changed at or after this instant (`updatedAt`).","schema":{"type":"string","format":"date-time"}},{"$ref":"#/components/parameters/AvrixApiVersion"},{"$ref":"#/components/parameters/RequestId"},{"$ref":"#/components/parameters/SandboxSimulateRateLimit"}],"responses":{"200":{"description":"Invoices and pagination meta","headers":{"X-Request-Id":{"$ref":"#/components/headers/XRequestId"},"X-Avrix-Api-Version":{"$ref":"#/components/headers/XAvrixApiVersion"},"X-Api-Version":{"$ref":"#/components/headers/XApiVersion"},"X-RateLimit-Limit":{"$ref":"#/components/headers/XRateLimitLimit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/XRateLimitRemaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/XRateLimitReset"},"X-RateLimit-Bucket":{"$ref":"#/components/headers/XRateLimitBucket"}},"content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"type":"object","required":["id","invoiceNumber","status","invoiceType","totalCents","totalMinor","currencyCode","currencyExponent","issuedAt","dueAt","salesReportId","paidAt","platformInvoiceNumber","kind","publisherCompanyId","supplierInvoiceNumber","reportMonth","subtotalCents","subtotalMinor","taxCents","taxMinor","paidCents","paidMinor","outstandingCents","outstandingMinor","paymentTermsDays","paymentState","replacesInvoiceId","supersededByInvoiceId","updatedAt","reconciliationAvailable","reconciliationPath","detailPath"],"properties":{"id":{"type":"string","format":"uuid"},"invoiceNumber":{"type":"string","deprecated":true,"description":"Deprecated: the platform number here, while invoice events send the vendor's own number under this name when there is one. Use `platformInvoiceNumber` or `supplierInvoiceNumber`. Value unchanged."},"platformInvoiceNumber":{"type":"string","description":"The number Avrix gave the invoice. Always set; the same value on `GET /finance/invoices` and on invoice events."},"status":{"type":"string","enum":["draft","awaiting_commission_document","payable","disputed","superseded","expired","sent","paid","overdue","cancelled","credited"],"x-extensible-enum":true,"description":"Where the invoice stands. Monthly invoices: `awaiting_commission_document` (issued, not payable until the commission document is attached), `payable`, `overdue` (past `dueAt` unpaid; still payable), `disputed` (you contested it; payment paused), `paid`, `superseded` (replaced by a corrected invoice, see `supersededByInvoiceId`). Invoices of the earlier billing model also use `sent`, `cancelled` and `credited`. `draft` and `expired` can also appear. New values may be added; treat an unknown value as not payable and read the invoice again."},"invoiceType":{"type":"string","enum":["proforma","final","credit_note"],"x-extensible-enum":true,"description":"`final` for an invoice you pay, `credit_note` for money that comes back to you (its total is positive), `proforma` for an advance document of the earlier billing model. New values may be added."},"totalCents":{"type":"integer","description":"Deprecated name of `totalMinor` (same value). Kept on the wire; see Naming conventions in the Versioning and compatibility guide. Invoice total in minor units of `currencyCode`.","deprecated":true},"totalMinor":{"type":"integer","description":"Invoice total in minor units of `currencyCode`. Same amount as `totalCents`, under the `...Minor` name every Seller API amount uses: integer minor units of the currency beside it (see `currencyExponent`)."},"currencyCode":{"type":"string"},"currencyExponent":{"type":"integer","minimum":0,"maximum":3,"description":"Number of minor-unit digits for `currencyCode`: 2 for USD, 0 for JPY, 3 for KWD. amount = minor units / 10^currencyExponent. Additive."},"issuedAt":{"type":"string","format":"date-time"},"dueAt":{"type":["string","null"],"format":"date-time"},"salesReportId":{"type":["string","null"]},"paidAt":{"type":["string","null"],"format":"date-time"},"kind":{"type":"string","enum":["vendor_payable","avrix_commission","legacy_allocation","legacy_report"],"description":"`vendor_payable` is the vendor's monthly invoice to you. `legacy_report` and `legacy_allocation` are documents of the earlier per-report and per-allocation billing. `avrix_commission` is listed for completeness; it is billed to the vendor and never appears in your list."},"publisherCompanyId":{"type":"string","description":"The vendor's company id."},"supplierInvoiceNumber":{"type":["string","null"],"description":"The vendor's own number for the invoice, as printed on their document, when the vendor uses one; null otherwise. `invoiceNumber` is the Avrix number. The same value on `GET /finance/invoices` and on invoice events."},"reportMonth":{"type":["string","null"],"description":"The sales month the invoice bills (`YYYY-MM`), for monthly invoices."},"subtotalCents":{"type":"integer","description":"Deprecated name of `subtotalMinor` (same value). Kept on the wire; see Naming conventions in the Versioning and compatibility guide. Amount before tax, in minor units of `currencyCode`.","deprecated":true},"subtotalMinor":{"type":"integer","description":"Amount before tax, in minor units of `currencyCode`. Same amount as `subtotalCents`, under the `...Minor` name every Seller API amount uses: integer minor units of the currency beside it (see `currencyExponent`)."},"taxCents":{"type":"integer","description":"Deprecated name of `taxMinor` (same value). Kept on the wire; see Naming conventions in the Versioning and compatibility guide. Tax, in minor units of `currencyCode`. `subtotalCents + taxCents = totalCents`.","deprecated":true},"taxMinor":{"type":"integer","description":"Tax, in minor units of `currencyCode`. `subtotalCents + taxCents = totalCents`. Same amount as `taxCents`, under the `...Minor` name every Seller API amount uses: integer minor units of the currency beside it (see `currencyExponent`)."},"paidCents":{"type":["integer","null"],"description":"Deprecated name of `paidMinor` (same value). Kept on the wire; see Naming conventions in the Versioning and compatibility guide. Amount recorded as paid so far, in minor units. Null for invoices of the earlier billing model.","deprecated":true},"paidMinor":{"type":["integer","null"],"description":"Amount recorded as paid so far, in minor units. Null for invoices of the earlier billing model. Same amount as `paidCents`, under the `...Minor` name every Seller API amount uses: integer minor units of the currency beside it (see `currencyExponent`)."},"outstandingCents":{"type":["integer","null"],"description":"Deprecated name of `outstandingMinor` (same value). Kept on the wire; see Naming conventions in the Versioning and compatibility guide. Amount still to pay, in minor units. Null for invoices of the earlier billing model.","deprecated":true},"outstandingMinor":{"type":["integer","null"],"description":"Amount still to pay, in minor units. Null for invoices of the earlier billing model. Same amount as `outstandingCents`, under the `...Minor` name every Seller API amount uses: integer minor units of the currency beside it (see `currencyExponent`)."},"paymentTermsDays":{"type":["integer","null"],"description":"Days between issue and due date that the agreement sets."},"paymentState":{"type":["string","null"],"enum":["unpaid","in_progress","paid","reversed",null],"description":"State of the settlement that pays this invoice (see `GET /finance/payments`); null when the invoice has none, which is the case for invoices of the earlier billing model and for one still waiting for the commission document."},"replacesInvoiceId":{"type":["string","null"],"format":"uuid","description":"On a corrected invoice: the invoice it replaces."},"supersededByInvoiceId":{"type":["string","null"],"format":"uuid","description":"On a replaced invoice (`status: superseded`): the corrected invoice to pay instead."},"updatedAt":{"type":"string","format":"date-time","description":"Last change to the invoice. Filter with `updatedSince` to sync changes."},"reconciliationAvailable":{"type":"boolean","description":"True when `reconciliationPath` answers 200: the invoice has a settlement."},"reconciliationPath":{"type":["string","null"],"description":"Path of this invoice's reconciliation file, when it has one."},"detailPath":{"type":"string","description":"Path of `GET /finance/invoices/{invoiceId}` for this invoice."}}}},"meta":{"allOf":[{"$ref":"#/components/schemas/PaginationMeta"},{"type":"object","properties":{"notices":{"type":"array","items":{"type":"object","required":["code","message","href"],"properties":{"code":{"type":"string","enum":["API_SALES_NOT_YET_REPORTED","INVOICES_FOLLOW_APPROVAL"]},"message":{"type":"string"},"href":{"type":"string","description":"Where the period's sales are, e.g. /api/seller/v1/finance/statements?period=2026-09."}}},"description":"On an empty first page while the month already has API sales: invoices are issued after the period's report is approved."}}}]}}},"example":{"data":[{"id":"0f22d074-7c8c-4450-8673-fc01aa3dac00","invoiceNumber":"INV-2026-10-0042","status":"draft","invoiceType":"proforma","totalCents":2450,"totalMinor":2450,"currencyCode":"EUR","currencyExponent":2,"issuedAt":"2026-11-02T09:30:00Z","dueAt":"2026-11-02T09:30:00Z","salesReportId":"e4295d17-8009-419e-8af4-0299aeaa068e","paidAt":"2026-11-02T09:30:00Z","platformInvoiceNumber":"example_platforminvoicenumber","kind":"vendor_payable","publisherCompanyId":"acme-games","supplierInvoiceNumber":"example_supplierinvoicenumber","reportMonth":"2026-10","subtotalCents":2450,"subtotalMinor":2450,"taxCents":2450,"taxMinor":2450,"paidCents":2450,"paidMinor":2450,"outstandingCents":2450,"outstandingMinor":2450,"paymentTermsDays":1,"paymentState":"unpaid","replacesInvoiceId":"0775ef96-1516-4700-8b89-48e68867134a","supersededByInvoiceId":"3e91337b-9f5b-4ea3-871f-fe576eac6152","updatedAt":"2026-11-02T09:30:00Z","reconciliationAvailable":true,"reconciliationPath":"example_reconciliationpath","detailPath":"example_detailpath"}],"meta":{"total":2450,"limit":50,"hasMore":true,"nextCursor":"eyJ2IjoyLCJ0IjoiMjAyNi0xMS0wMlQwOTozMDowMFoifQ","nextUrl":"https://api.avrix.io/api/seller/v1/finance/invoices?cursor=eyJ2IjoyLCJ0IjoiMjAyNi0xMS0wMlQwOTozMDowMFoifQ","localePreference":"en","notices":[{"code":"API_SALES_NOT_YET_REPORTED","message":"Example text.","href":"https://api.avrix.io/api/seller/v1/example"}]}}}}},"400":{"$ref":"#/components/responses/SellerApiUnsupportedApiVersion"},"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"},"503":{"$ref":"#/components/responses/SellerApiServiceUnavailable"},"504":{"$ref":"#/components/responses/SellerApiTimeout"}},"security":[{"bearerAuth":[]}],"x-avrix-scopes":["seller:finance:read"],"x-avrix-tier":"finance","x-avrix-rate-limit-class":"finance","x-avrix-scope-mode":"anyOf","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.","security":[{"bearerAuth":[]}],"x-avrix-scopes":["seller:refunds:read","seller:refunds:write","seller:finance:read","seller:orders:write","seller:keys:pull"],"x-avrix-tier":"standard","x-avrix-rate-limit-class":"orders","x-avrix-scope-mode":"anyOf","parameters":[{"name":"refundId","in":"path","required":true,"description":"Refund id (`refundId` from `POST /refunds`).","schema":{"type":"string","format":"uuid"}},{"$ref":"#/components/parameters/AvrixApiVersion"},{"$ref":"#/components/parameters/RequestId"},{"$ref":"#/components/parameters/SandboxSimulateRateLimit"}],"responses":{"200":{"description":"Refund detail","headers":{"X-Request-Id":{"$ref":"#/components/headers/XRequestId"},"X-Avrix-Api-Version":{"$ref":"#/components/headers/XAvrixApiVersion"},"X-Api-Version":{"$ref":"#/components/headers/XApiVersion"},"X-RateLimit-Limit":{"$ref":"#/components/headers/XRateLimitLimit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/XRateLimitRemaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/XRateLimitReset"},"X-RateLimit-Bucket":{"$ref":"#/components/headers/XRateLimitBucket"}},"content":{"application/json":{"schema":{"type":"object","required":["data"],"properties":{"data":{"$ref":"#/components/schemas/SellerRefund"}}},"example":{"data":{"id":"d1bf6244-6a59-457a-83ec-4573c5d70b47","status":"pending","type":"refund","keyId":"a0de64ed-64f7-4e76-85ba-b8e914a26cd4","skuId":"d904c994-f566-46d9-89df-b1291d3ef86c","productId":"d0304eaa-1faa-4ced-834d-553fe348c225","orderReference":"store-order-10432","adjustmentReference":"adj_10432","reversalTransactionId":"0a4de534-795c-43f9-8eb7-796d32003797","salePriceCents":2450,"salePriceMinor":2450,"currencyCode":"EUR","currencyExponent":2,"saleTimestamp":"2026-11-02T09:30:00Z","adjustedAt":"2026-11-02T09:30:00Z","occurredAt":"2026-11-02T09:30:00Z"}}}}},"400":{"$ref":"#/components/responses/SellerApiUnsupportedApiVersion"},"401":{"$ref":"#/components/responses/SellerApiUnauthorized"},"403":{"$ref":"#/components/responses/SellerApiForbidden"},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"422":{"$ref":"#/components/responses/SellerApiValidationFailed"},"429":{"$ref":"#/components/responses/SellerApiRateLimited"},"500":{"$ref":"#/components/responses/SellerApiInternalError"},"503":{"$ref":"#/components/responses/SellerApiServiceUnavailable"},"504":{"$ref":"#/components/responses/SellerApiTimeout"}},"operationId":"getRefund","tags":["Refunds"]}},"/api/seller/v1/refunds/preview":{"post":{"summary":"Check refund eligibility","description":"Answers, per key, whether `POST /refunds` would accept it: whether it can be refunded or charged back, why not, the refund window and its end (`refundableUntil`), what a refund would do to the key (`keyDisposition`) and any open dispute freeze. Changes nothing, so it takes no `Idempotency-Key`. Select keys as on `POST /refunds` (`keyIds`, or `quantity` with `orderReference`), or send `orderReference` alone for every live key of the order (at most 100). The rolling 30-day refund limit per allocation is not evaluated here (`REFUND_LIMIT_REACHED` on `POST /refunds`). Scopes: any refund read scope.","tags":["Refunds"],"security":[{"bearerAuth":[]}],"parameters":[{"$ref":"#/components/parameters/AvrixApiVersion"},{"$ref":"#/components/parameters/RequestId"},{"$ref":"#/components/parameters/SandboxSimulateWrite"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"required":["type"],"properties":{"type":{"type":"string","enum":["refund","chargeback"],"description":"`refund`: you refunded the buyer. `chargeback`: the buyer's payment was charged back."},"keyIds":{"type":"array","minItems":1,"maxItems":100,"items":{"type":"string","format":"uuid"}},"quantity":{"type":"integer","minimum":1,"maximum":100,"description":"With `orderReference`: the newest `quantity` live keys, as `POST /refunds` picks them."},"orderReference":{"type":"string","minLength":1,"maxLength":255}}},"example":{"type":"refund","orderReference":"ORD-10042"}}}},"responses":{"200":{"description":"Eligibility per key","headers":{"X-Request-Id":{"$ref":"#/components/headers/XRequestId"},"X-Avrix-Api-Version":{"$ref":"#/components/headers/XAvrixApiVersion"},"X-Api-Version":{"$ref":"#/components/headers/XApiVersion"},"X-RateLimit-Limit":{"$ref":"#/components/headers/XRateLimitLimit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/XRateLimitRemaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/XRateLimitReset"},"X-RateLimit-Bucket":{"$ref":"#/components/headers/XRateLimitBucket"}},"content":{"application/json":{"schema":{"type":"object","required":["data"],"properties":{"data":{"$ref":"#/components/schemas/RefundPreview"}}},"example":{"data":{"type":"refund","orderReference":"ORD-10042","eligible":true,"checkedAt":"2026-12-02T10:00:00Z","keys":[{"keyId":"3f1c2d4e-5a6b-4c7d-8e9f-0a1b2c3d4e5f","orderReference":"ORD-10042","eligible":true,"reason":null,"keyStatus":"revealed","businessModel":"wholesale","keyDisposition":"quarantined","soldAt":"2026-11-30T09:12:00Z","windowDays":14,"refundableUntil":"2026-12-14T09:12:00Z","frozen":null}]}}}}},"400":{"$ref":"#/components/responses/SellerApiUnsupportedApiVersion"},"401":{"$ref":"#/components/responses/SellerApiUnauthorized"},"403":{"$ref":"#/components/responses/SellerApiForbidden"},"404":{"description":"No live keys under this `orderReference`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"413":{"$ref":"#/components/responses/SellerApiPayloadTooLarge"},"422":{"$ref":"#/components/responses/SellerApiValidationFailed"},"429":{"$ref":"#/components/responses/SellerApiRateLimited"},"500":{"$ref":"#/components/responses/SellerApiInternalError"},"503":{"$ref":"#/components/responses/SellerApiServiceUnavailable"},"504":{"$ref":"#/components/responses/SellerApiTimeout"}},"x-avrix-scopes":["seller:refunds:read","seller:refunds:write","seller:finance:read","seller:orders:write","seller:keys:pull"],"x-avrix-tier":"orders","x-avrix-rate-limit-class":"orders","x-avrix-scope-mode":"anyOf","operationId":"previewRefund"}},"/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` or `seller:orders:write`; the legacy `seller:keys:pull` is also accepted. 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":[{"$ref":"#/components/parameters/IdempotencyKey"},{"$ref":"#/components/parameters/AvrixApiVersion"},{"$ref":"#/components/parameters/RequestId"},{"$ref":"#/components/parameters/SandboxSimulateWrite"}],"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","headers":{"X-Request-Id":{"$ref":"#/components/headers/XRequestId"},"X-Avrix-Api-Version":{"$ref":"#/components/headers/XAvrixApiVersion"},"X-Api-Version":{"$ref":"#/components/headers/XApiVersion"},"Idempotency-Replayed":{"$ref":"#/components/headers/IdempotencyReplayed"},"X-RateLimit-Limit":{"$ref":"#/components/headers/XRateLimitLimit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/XRateLimitRemaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/XRateLimitReset"},"X-RateLimit-Bucket":{"$ref":"#/components/headers/XRateLimitBucket"}},"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."}}}}},"example":{"data":{"chargebackReference":"chbk_10432","outcome":"won","resolved":1}}}}},"400":{"$ref":"#/components/responses/SellerApiIdempotencyKeyRequired"},"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":"The chargeback is not in the `chargeback_open` state; `details.currentState` gives the state it is in. Also returned for the `Idempotency-Key` itself: `IDEMPOTENCY_KEY_MISMATCH` (the key was already used with a different body) and `IDEMPOTENCY_REQUEST_IN_FLIGHT` (an earlier request with this key is still running; retry after `Retry-After` seconds).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"413":{"$ref":"#/components/responses/SellerApiPayloadTooLarge"},"422":{"description":"Validation failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"429":{"$ref":"#/components/responses/SellerApiRateLimited"},"500":{"$ref":"#/components/responses/SellerApiInternalError"},"503":{"$ref":"#/components/responses/SellerApiServiceUnavailable"},"504":{"$ref":"#/components/responses/SellerApiTimeout"}},"security":[{"bearerAuth":[]}],"x-avrix-scopes":["seller:refunds:write","seller:orders:write","seller:keys:pull"],"x-avrix-tier":"orders","x-avrix-rate-limit-class":"orders","x-avrix-scope-mode":"anyOf","tags":["Refunds"],"operationId":"resolveChargeback"}},"/api/seller/v1/returns":{"get":{"summary":"List return requests","description":"Your return requests to Content Owners, newest first. Filter by `status`. In the shared sandbox only requests on keys your API key pulled are listed. Pages with `limit` and `cursor` (the shared list contract). Scopes: any refund read scope.","tags":["Refunds"],"security":[{"bearerAuth":[]}],"parameters":[{"name":"limit","in":"query","schema":{"type":"integer","minimum":1,"maximum":100,"default":50},"description":"Page size: how many items to return (1 to 100)."},{"name":"cursor","in":"query","schema":{"type":"string"},"description":"Opaque cursor from `meta.nextCursor`. Send it back unchanged; omit it on the first call."},{"name":"status","in":"query","schema":{"type":"string","enum":["pending","info_requested","approved","rejected","cancelled","resolved"]},"description":"Only requests in this status."},{"$ref":"#/components/parameters/AvrixApiVersion"},{"$ref":"#/components/parameters/RequestId"},{"$ref":"#/components/parameters/SandboxSimulateRateLimit"}],"responses":{"200":{"description":"Return requests","headers":{"X-Request-Id":{"$ref":"#/components/headers/XRequestId"},"X-Avrix-Api-Version":{"$ref":"#/components/headers/XAvrixApiVersion"},"X-Api-Version":{"$ref":"#/components/headers/XApiVersion"},"X-RateLimit-Limit":{"$ref":"#/components/headers/XRateLimitLimit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/XRateLimitRemaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/XRateLimitReset"},"X-RateLimit-Bucket":{"$ref":"#/components/headers/XRateLimitBucket"}},"content":{"application/json":{"schema":{"type":"object","required":["data","meta"],"properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/SellerReturnRequest"}},"meta":{"type":"object","properties":{"limit":{"type":"integer"},"nextCursor":{"type":["string","null"]},"nextUrl":{"type":["string","null"]},"hasMore":{"type":"boolean","description":"True when another page follows. Loop on `hasMore`; send `nextCursor` back as `cursor`."}}}}},"example":{"data":[{"returnRequestId":"0b6e4f1a-2c3d-4e5f-8a9b-1c2d3e4f5a6b","status":"pending","reasonCode":"key_invalid","details":"The buyer reports the key is rejected on activation.","requestedResolution":"replacement","resolution":null,"publisherCompanyId":"co_7f3a9c","currencyCode":"EUR","keyCount":1,"decisionNote":null,"decidedAt":null,"respondBy":"2026-12-09T10:00:00Z","reversalStatus":"not_required","createdAt":"2026-12-02T10:00:00Z","updatedAt":"2026-12-02T10:00:00Z"}],"meta":{"limit":50,"hasMore":false,"nextCursor":null,"nextUrl":null}}}}},"400":{"$ref":"#/components/responses/SellerApiUnsupportedApiVersion"},"401":{"$ref":"#/components/responses/SellerApiUnauthorized"},"403":{"$ref":"#/components/responses/SellerApiForbidden"},"422":{"$ref":"#/components/responses/SellerApiValidationFailed"},"429":{"$ref":"#/components/responses/SellerApiRateLimited"},"500":{"$ref":"#/components/responses/SellerApiInternalError"},"503":{"$ref":"#/components/responses/SellerApiServiceUnavailable"},"504":{"$ref":"#/components/responses/SellerApiTimeout"}},"x-avrix-scopes":["seller:refunds:read","seller:refunds:write","seller:finance:read","seller:orders:write","seller:keys:pull"],"x-avrix-tier":"orders","x-avrix-rate-limit-class":"orders","x-avrix-scope-mode":"anyOf","operationId":"listReturnRequests"},"post":{"summary":"File a return request","description":"Ask the Content Owner to refund or replace delivered keys (for example a key that does not activate). The Content Owner decides: you get `return.information_requested` when they ask a question and `return.decided` when they approve or reject. The Content Owner is taken from the keys; file one request per Content Owner. Attach files with `POST /returns/{returnRequestId}/evidence`. A refund you already gave your buyer is declared on `POST /refunds` instead. Requires an `Idempotency-Key` and `seller:refunds:write` or `seller:orders:write` (or the legacy `seller:keys:pull`).","tags":["Refunds"],"security":[{"bearerAuth":[]}],"parameters":[{"$ref":"#/components/parameters/IdempotencyKey"},{"$ref":"#/components/parameters/AvrixApiVersion"},{"$ref":"#/components/parameters/RequestId"},{"$ref":"#/components/parameters/SandboxSimulateWrite"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"required":["keyIds","reasonCode","requestedResolution"],"properties":{"keyIds":{"type":"array","minItems":1,"maxItems":100,"items":{"type":"string","format":"uuid"}},"reasonCode":{"type":"string","enum":["key_invalid","key_already_redeemed","wrong_product","region_locked","description_mismatch","customer_refund","unused_keys"],"description":"Why the keys are returned. `key_invalid`: the key does not activate. `key_already_redeemed`: the key was already redeemed when the buyer tried it. `wrong_product`: the key is for a different product. `region_locked`: the key cannot be activated in the buyer's region. `description_mismatch`: the product is not as described. `customer_refund`: you refunded the buyer. `unused_keys`: keys you did not sell; always resolved as a refund."},"requestedResolution":{"type":"string","enum":["refund","replacement"],"description":"What you ask the Content Owner for. `refund`: the sale is refunded. `replacement`: a new key for each returned key."},"details":{"type":"string","maxLength":4000,"description":"What went wrong, for the Content Owner."}}},"example":{"keyIds":["3f1c2d4e-5a6b-4c7d-8e9f-0a1b2c3d4e5f"],"reasonCode":"key_invalid","requestedResolution":"replacement","details":"The buyer reports the key is rejected on activation."}}}},"responses":{"201":{"description":"Filed","headers":{"X-Request-Id":{"$ref":"#/components/headers/XRequestId"},"X-Avrix-Api-Version":{"$ref":"#/components/headers/XAvrixApiVersion"},"X-Api-Version":{"$ref":"#/components/headers/XApiVersion"},"Idempotency-Replayed":{"$ref":"#/components/headers/IdempotencyReplayed"},"X-RateLimit-Limit":{"$ref":"#/components/headers/XRateLimitLimit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/XRateLimitRemaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/XRateLimitReset"},"X-RateLimit-Bucket":{"$ref":"#/components/headers/XRateLimitBucket"}},"content":{"application/json":{"schema":{"type":"object","required":["data"],"properties":{"data":{"$ref":"#/components/schemas/SellerReturnRequestDetail"}}},"example":{"data":{"returnRequestId":"0b6e4f1a-2c3d-4e5f-8a9b-1c2d3e4f5a6b","status":"pending","reasonCode":"key_invalid","details":"The buyer reports the key is rejected on activation.","requestedResolution":"replacement","resolution":null,"publisherCompanyId":"co_7f3a9c","currencyCode":"EUR","keyCount":1,"decisionNote":null,"decidedAt":null,"respondBy":"2026-12-09T10:00:00Z","reversalStatus":"not_required","createdAt":"2026-12-02T10:00:00Z","updatedAt":"2026-12-02T10:00:00Z","keys":[{"keyId":"3f1c2d4e-5a6b-4c7d-8e9f-0a1b2c3d4e5f","open":true,"replacementKeyId":null,"unitPriceCents":4999,"unitPriceMinor":4999}],"messages":[],"evidence":[]}}}}},"400":{"$ref":"#/components/responses/SellerApiIdempotencyKeyRequired"},"401":{"$ref":"#/components/responses/SellerApiUnauthorized"},"403":{"$ref":"#/components/responses/SellerApiForbidden"},"404":{"description":"Not found: the return request is not yours, or (on `POST /returns`) a key is not one you sold (`details.reason: key_not_owned`)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"409":{"description":"The request is not in a state that allows this (`CONFLICT`, `details.reason: illegal_transition`), or a key is already in an open return request (`details.reason: key_in_open_request`). Also the `Idempotency-Key` conflicts: `IDEMPOTENCY_KEY_MISMATCH`, `IDEMPOTENCY_REQUEST_IN_FLIGHT`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"413":{"$ref":"#/components/responses/SellerApiPayloadTooLarge"},"422":{"description":"Invalid body (`VALIDATION_FAILED`), or the keys cannot be returned (`KEY_NOT_RETURNABLE`, the precise cause in `details.reason`, for example `claim_window_expired`, `key_status_ineligible`, `publisher_mismatch`, `mixed_business_model`, `resolution_not_allowed`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"429":{"$ref":"#/components/responses/SellerApiRateLimited"},"500":{"$ref":"#/components/responses/SellerApiInternalError"},"503":{"$ref":"#/components/responses/SellerApiServiceUnavailable"},"504":{"$ref":"#/components/responses/SellerApiTimeout"}},"x-avrix-scopes":["seller:refunds:write","seller:orders:write","seller:keys:pull"],"x-avrix-tier":"orders","x-avrix-rate-limit-class":"orders","x-avrix-scope-mode":"anyOf","operationId":"fileReturnRequest"}},"/api/seller/v1/returns/{returnRequestId}":{"get":{"summary":"Get a return request","description":"One return request with its keys, the message thread with the Content Owner and the evidence attached. 404 when it is not yours. Scopes: any refund read scope.","tags":["Refunds"],"security":[{"bearerAuth":[]}],"parameters":[{"name":"returnRequestId","in":"path","required":true,"schema":{"type":"string","format":"uuid"},"description":"The `returnRequestId` from `POST /returns` or `GET /returns`."},{"$ref":"#/components/parameters/AvrixApiVersion"},{"$ref":"#/components/parameters/RequestId"},{"$ref":"#/components/parameters/SandboxSimulateRateLimit"}],"responses":{"200":{"description":"The return request","headers":{"X-Request-Id":{"$ref":"#/components/headers/XRequestId"},"X-Avrix-Api-Version":{"$ref":"#/components/headers/XAvrixApiVersion"},"X-Api-Version":{"$ref":"#/components/headers/XApiVersion"},"X-RateLimit-Limit":{"$ref":"#/components/headers/XRateLimitLimit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/XRateLimitRemaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/XRateLimitReset"},"X-RateLimit-Bucket":{"$ref":"#/components/headers/XRateLimitBucket"}},"content":{"application/json":{"schema":{"type":"object","required":["data"],"properties":{"data":{"$ref":"#/components/schemas/SellerReturnRequestDetail"}}},"example":{"data":{"returnRequestId":"0b6e4f1a-2c3d-4e5f-8a9b-1c2d3e4f5a6b","status":"pending","reasonCode":"key_invalid","details":"The buyer reports the key is rejected on activation.","requestedResolution":"replacement","resolution":null,"publisherCompanyId":"co_7f3a9c","currencyCode":"EUR","keyCount":1,"decisionNote":null,"decidedAt":null,"respondBy":"2026-12-09T10:00:00Z","reversalStatus":"not_required","createdAt":"2026-12-02T10:00:00Z","updatedAt":"2026-12-02T10:00:00Z","keys":[{"keyId":"3f1c2d4e-5a6b-4c7d-8e9f-0a1b2c3d4e5f","open":true,"replacementKeyId":null,"unitPriceCents":4999,"unitPriceMinor":4999}],"messages":[],"evidence":[]}}}}},"400":{"$ref":"#/components/responses/SellerApiUnsupportedApiVersion"},"401":{"$ref":"#/components/responses/SellerApiUnauthorized"},"403":{"$ref":"#/components/responses/SellerApiForbidden"},"404":{"description":"Return request not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"422":{"$ref":"#/components/responses/SellerApiValidationFailed"},"429":{"$ref":"#/components/responses/SellerApiRateLimited"},"500":{"$ref":"#/components/responses/SellerApiInternalError"},"503":{"$ref":"#/components/responses/SellerApiServiceUnavailable"},"504":{"$ref":"#/components/responses/SellerApiTimeout"}},"x-avrix-scopes":["seller:refunds:read","seller:refunds:write","seller:finance:read","seller:orders:write","seller:keys:pull"],"x-avrix-tier":"orders","x-avrix-rate-limit-class":"orders","x-avrix-scope-mode":"anyOf","operationId":"getReturnRequest"}},"/api/seller/v1/returns/{returnRequestId}/reply":{"post":{"summary":"Answer the Content Owner","description":"Answer the Content Owner's question on a return request in `info_requested`; it goes back to `pending` and the Content Owner's response time starts again. `message` is optional; attach files with `POST /returns/{returnRequestId}/evidence` before replying. Requires an `Idempotency-Key`.","tags":["Refunds"],"security":[{"bearerAuth":[]}],"parameters":[{"name":"returnRequestId","in":"path","required":true,"schema":{"type":"string","format":"uuid"},"description":"The `returnRequestId` from `POST /returns` or `GET /returns`."},{"$ref":"#/components/parameters/IdempotencyKey"},{"$ref":"#/components/parameters/AvrixApiVersion"},{"$ref":"#/components/parameters/RequestId"},{"$ref":"#/components/parameters/SandboxSimulateWrite"}],"requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"properties":{"message":{"type":"string","maxLength":4000}}},"example":{"message":"Screenshot of the activation error attached."}}}},"responses":{"200":{"description":"Replied","headers":{"X-Request-Id":{"$ref":"#/components/headers/XRequestId"},"X-Avrix-Api-Version":{"$ref":"#/components/headers/XAvrixApiVersion"},"X-Api-Version":{"$ref":"#/components/headers/XApiVersion"},"Idempotency-Replayed":{"$ref":"#/components/headers/IdempotencyReplayed"},"X-RateLimit-Limit":{"$ref":"#/components/headers/XRateLimitLimit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/XRateLimitRemaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/XRateLimitReset"},"X-RateLimit-Bucket":{"$ref":"#/components/headers/XRateLimitBucket"}},"content":{"application/json":{"schema":{"type":"object","required":["data"],"properties":{"data":{"$ref":"#/components/schemas/SellerReturnRequestDetail"}}},"example":{"data":{"returnRequestId":"0b6e4f1a-2c3d-4e5f-8a9b-1c2d3e4f5a6b","status":"pending","reasonCode":"key_invalid","details":"The buyer reports the key is rejected on activation.","requestedResolution":"replacement","resolution":null,"publisherCompanyId":"co_7f3a9c","currencyCode":"EUR","keyCount":1,"decisionNote":null,"decidedAt":null,"respondBy":"2026-12-09T10:00:00Z","reversalStatus":"not_required","createdAt":"2026-12-02T10:00:00Z","updatedAt":"2026-12-02T10:00:00Z","keys":[{"keyId":"3f1c2d4e-5a6b-4c7d-8e9f-0a1b2c3d4e5f","open":true,"replacementKeyId":null,"unitPriceCents":4999,"unitPriceMinor":4999}],"messages":[{"messageId":"9c8b7a6d-5e4f-4a3b-8c2d-1e0f9a8b7c6d","from":"content_owner","body":"Please send a screenshot of the activation error.","createdAt":"2026-12-03T09:00:00Z"},{"messageId":"1a2b3c4d-5e6f-4a7b-8c9d-0e1f2a3b4c5d","from":"seller","body":"Screenshot of the activation error attached.","createdAt":"2026-12-03T11:00:00Z"}],"evidence":[]}}}}},"400":{"$ref":"#/components/responses/SellerApiIdempotencyKeyRequired"},"401":{"$ref":"#/components/responses/SellerApiUnauthorized"},"403":{"$ref":"#/components/responses/SellerApiForbidden"},"404":{"description":"Not found: the return request is not yours, or (on `POST /returns`) a key is not one you sold (`details.reason: key_not_owned`)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"409":{"description":"The request is not in a state that allows this (`CONFLICT`, `details.reason: illegal_transition`), or a key is already in an open return request (`details.reason: key_in_open_request`). Also the `Idempotency-Key` conflicts: `IDEMPOTENCY_KEY_MISMATCH`, `IDEMPOTENCY_REQUEST_IN_FLIGHT`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"413":{"$ref":"#/components/responses/SellerApiPayloadTooLarge"},"422":{"description":"Invalid body (`VALIDATION_FAILED`), or the keys cannot be returned (`KEY_NOT_RETURNABLE`, the precise cause in `details.reason`, for example `claim_window_expired`, `key_status_ineligible`, `publisher_mismatch`, `mixed_business_model`, `resolution_not_allowed`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"429":{"$ref":"#/components/responses/SellerApiRateLimited"},"500":{"$ref":"#/components/responses/SellerApiInternalError"},"503":{"$ref":"#/components/responses/SellerApiServiceUnavailable"},"504":{"$ref":"#/components/responses/SellerApiTimeout"}},"x-avrix-scopes":["seller:refunds:write","seller:orders:write","seller:keys:pull"],"x-avrix-tier":"orders","x-avrix-rate-limit-class":"orders","x-avrix-scope-mode":"anyOf","operationId":"replyToReturnRequest"}},"/api/seller/v1/returns/{returnRequestId}/cancel":{"post":{"summary":"Cancel a return request","description":"Withdraw a return request while it is `pending` or `info_requested`. No body. Requires an `Idempotency-Key`.","tags":["Refunds"],"security":[{"bearerAuth":[]}],"parameters":[{"name":"returnRequestId","in":"path","required":true,"schema":{"type":"string","format":"uuid"},"description":"The `returnRequestId` from `POST /returns` or `GET /returns`."},{"$ref":"#/components/parameters/IdempotencyKey"},{"$ref":"#/components/parameters/AvrixApiVersion"},{"$ref":"#/components/parameters/RequestId"},{"$ref":"#/components/parameters/SandboxSimulateWrite"}],"responses":{"200":{"description":"Cancelled","headers":{"X-Request-Id":{"$ref":"#/components/headers/XRequestId"},"X-Avrix-Api-Version":{"$ref":"#/components/headers/XAvrixApiVersion"},"X-Api-Version":{"$ref":"#/components/headers/XApiVersion"},"Idempotency-Replayed":{"$ref":"#/components/headers/IdempotencyReplayed"},"X-RateLimit-Limit":{"$ref":"#/components/headers/XRateLimitLimit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/XRateLimitRemaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/XRateLimitReset"},"X-RateLimit-Bucket":{"$ref":"#/components/headers/XRateLimitBucket"}},"content":{"application/json":{"schema":{"type":"object","required":["data"],"properties":{"data":{"$ref":"#/components/schemas/SellerReturnRequestDetail"}}},"example":{"data":{"returnRequestId":"0b6e4f1a-2c3d-4e5f-8a9b-1c2d3e4f5a6b","status":"cancelled","reasonCode":"key_invalid","details":"The buyer reports the key is rejected on activation.","requestedResolution":"replacement","resolution":null,"publisherCompanyId":"co_7f3a9c","currencyCode":"EUR","keyCount":1,"decisionNote":null,"decidedAt":null,"respondBy":null,"reversalStatus":"not_required","createdAt":"2026-12-02T10:00:00Z","updatedAt":"2026-12-02T10:00:00Z","keys":[{"keyId":"3f1c2d4e-5a6b-4c7d-8e9f-0a1b2c3d4e5f","open":true,"replacementKeyId":null,"unitPriceCents":4999,"unitPriceMinor":4999}],"messages":[],"evidence":[]}}}}},"400":{"$ref":"#/components/responses/SellerApiIdempotencyKeyRequired"},"401":{"$ref":"#/components/responses/SellerApiUnauthorized"},"403":{"$ref":"#/components/responses/SellerApiForbidden"},"404":{"description":"Not found: the return request is not yours, or (on `POST /returns`) a key is not one you sold (`details.reason: key_not_owned`)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"409":{"description":"The request is not in a state that allows this (`CONFLICT`, `details.reason: illegal_transition`), or a key is already in an open return request (`details.reason: key_in_open_request`). Also the `Idempotency-Key` conflicts: `IDEMPOTENCY_KEY_MISMATCH`, `IDEMPOTENCY_REQUEST_IN_FLIGHT`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"413":{"$ref":"#/components/responses/SellerApiPayloadTooLarge"},"422":{"description":"Invalid body (`VALIDATION_FAILED`), or the keys cannot be returned (`KEY_NOT_RETURNABLE`, the precise cause in `details.reason`, for example `claim_window_expired`, `key_status_ineligible`, `publisher_mismatch`, `mixed_business_model`, `resolution_not_allowed`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"429":{"$ref":"#/components/responses/SellerApiRateLimited"},"500":{"$ref":"#/components/responses/SellerApiInternalError"},"503":{"$ref":"#/components/responses/SellerApiServiceUnavailable"},"504":{"$ref":"#/components/responses/SellerApiTimeout"}},"x-avrix-scopes":["seller:refunds:write","seller:orders:write","seller:keys:pull"],"x-avrix-tier":"orders","x-avrix-rate-limit-class":"orders","x-avrix-scope-mode":"anyOf","operationId":"cancelReturnRequest"}},"/api/seller/v1/returns/{returnRequestId}/evidence":{"post":{"summary":"Attach evidence to a return request","description":"Attach one file (an image or a PDF, at most 10 MB) to a return request while it is `pending` or `info_requested`. Send `multipart/form-data` with the file in the `file` field. The Content Owner sees it with the request; `GET /returns/{returnRequestId}` lists it. The upload is recorded against the user who created the API key. Requires an `Idempotency-Key`: a retry with the same key and the same file answers with the first upload.","tags":["Refunds"],"security":[{"bearerAuth":[]}],"parameters":[{"name":"returnRequestId","in":"path","required":true,"schema":{"type":"string","format":"uuid"},"description":"The `returnRequestId` from `POST /returns` or `GET /returns`."},{"$ref":"#/components/parameters/IdempotencyKey"},{"$ref":"#/components/parameters/AvrixApiVersion"},{"$ref":"#/components/parameters/RequestId"},{"$ref":"#/components/parameters/SandboxSimulateWrite"}],"requestBody":{"required":true,"content":{"multipart/form-data":{"schema":{"type":"object","required":["file"],"properties":{"file":{"type":"string","format":"binary"}}}}}},"responses":{"201":{"description":"Attached","headers":{"X-Request-Id":{"$ref":"#/components/headers/XRequestId"},"X-Avrix-Api-Version":{"$ref":"#/components/headers/XAvrixApiVersion"},"X-Api-Version":{"$ref":"#/components/headers/XApiVersion"},"Idempotency-Replayed":{"$ref":"#/components/headers/IdempotencyReplayed"},"X-RateLimit-Limit":{"$ref":"#/components/headers/XRateLimitLimit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/XRateLimitRemaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/XRateLimitReset"},"X-RateLimit-Bucket":{"$ref":"#/components/headers/XRateLimitBucket"}},"content":{"application/json":{"schema":{"type":"object","required":["data"],"properties":{"data":{"type":"object","required":["evidenceId","returnRequestId"],"properties":{"evidenceId":{"type":"string","format":"uuid"},"returnRequestId":{"type":"string","format":"uuid"}}}}},"example":{"data":{"evidenceId":"5d4c3b2a-1f0e-4d9c-8b7a-6f5e4d3c2b1a","returnRequestId":"0b6e4f1a-2c3d-4e5f-8a9b-1c2d3e4f5a6b"}}}}},"400":{"$ref":"#/components/responses/SellerApiIdempotencyKeyRequired"},"401":{"$ref":"#/components/responses/SellerApiUnauthorized"},"403":{"$ref":"#/components/responses/SellerApiForbidden"},"404":{"description":"Return request not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"409":{"description":"The request no longer takes evidence (`CONFLICT`, `details.currentStatus`), or the API key has no owning user (`details.reason: api_key_owner_missing`). Also the `Idempotency-Key` conflicts: `IDEMPOTENCY_KEY_MISMATCH`, `IDEMPOTENCY_REQUEST_IN_FLIGHT`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"413":{"$ref":"#/components/responses/SellerApiPayloadTooLarge"},"422":{"description":"No file, or a file type or size the upload does not accept (`VALIDATION_FAILED`, field `file`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"429":{"$ref":"#/components/responses/SellerApiRateLimited"},"500":{"$ref":"#/components/responses/SellerApiInternalError"},"503":{"$ref":"#/components/responses/SellerApiServiceUnavailable"},"504":{"$ref":"#/components/responses/SellerApiTimeout"}},"x-avrix-scopes":["seller:refunds:write","seller:orders:write","seller:keys:pull"],"x-avrix-tier":"orders","x-avrix-rate-limit-class":"orders","x-avrix-scope-mode":"anyOf","operationId":"attachReturnEvidence"}},"/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.\n\nThe response carries an `ETag` computed from the archive's asset list; send it back as `If-None-Match` to get `304 Not Modified` without a download. `HEAD` returns the same headers without building the archive.\n\n**Streaming and completeness.** Each file is streamed into the archive from storage, so the first bytes arrive before the last file is read. A file that cannot be fetched is left out and the status is already `200` by then. On contract date `2026-12-01` and later the archive's last entry is `avrix-media-manifest.json`, `{\"complete\": true|false, \"entries\": [{\"filename\", \"included\"}]}`, so a store can tell a complete archive from a partial one; that archive has its own `ETag`. Earlier dates have no manifest entry.\n\n**Errors.** On `2026-12-01` and later, errors use the standard error envelope (`code`, `message`, `hint`, `doc_url`, `requestId`), a product not shared with you answers `404 PRODUCT_NOT_SHARED` (as on product detail), and a request without a key answers the Seller API `401`. Earlier dates keep the short `{code, message, requestId}` body and `NOT_FOUND`.","operationId":"downloadProductMedia","security":[{"bearerAuth":[]}],"x-avrix-scopes":["seller:products:read"],"x-avrix-tier":"catalog","x-avrix-rate-limit-class":"catalog","x-avrix-scope-mode":"anyOf","parameters":[{"name":"productId","in":"path","required":true,"description":"The product UUID, or the readable `prd_` id the product payloads return as `readableId`.","schema":{"type":"string","anyOf":[{"format":"uuid"},{"pattern":"^prd_[23456789abcdefghjkmnpqrstuvwxyz]{8}$"}]}},{"$ref":"#/components/parameters/AvrixApiVersion"},{"$ref":"#/components/parameters/RequestId"},{"$ref":"#/components/parameters/SandboxSimulateRateLimit"},{"$ref":"#/components/parameters/IfNoneMatch"}],"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"}},"X-Request-Id":{"$ref":"#/components/headers/XRequestId"},"X-Avrix-Api-Version":{"$ref":"#/components/headers/XAvrixApiVersion"},"X-Api-Version":{"$ref":"#/components/headers/XApiVersion"},"X-RateLimit-Limit":{"$ref":"#/components/headers/XRateLimitLimit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/XRateLimitRemaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/XRateLimitReset"},"X-RateLimit-Bucket":{"$ref":"#/components/headers/XRateLimitBucket"},"X-Avrix-Media-Entries":{"description":"How many files the archive is built from (not counting the manifest entry). Present on 200, 304 and HEAD. Additive.","schema":{"type":"integer","minimum":1}},"ETag":{"$ref":"#/components/headers/ETag"}}},"304":{"description":"Not modified: the asset list matches `If-None-Match`.","headers":{"X-Request-Id":{"$ref":"#/components/headers/XRequestId"},"X-Avrix-Api-Version":{"$ref":"#/components/headers/XAvrixApiVersion"},"X-Api-Version":{"$ref":"#/components/headers/XApiVersion"},"X-RateLimit-Limit":{"$ref":"#/components/headers/XRateLimitLimit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/XRateLimitRemaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/XRateLimitReset"},"X-RateLimit-Bucket":{"$ref":"#/components/headers/XRateLimitBucket"},"X-Avrix-Media-Entries":{"description":"How many files the archive is built from (not counting the manifest entry). Present on 200, 304 and HEAD. Additive.","schema":{"type":"integer","minimum":1}},"ETag":{"$ref":"#/components/headers/ETag"}}},"400":{"$ref":"#/components/responses/SellerApiUnsupportedApiVersion"},"401":{"$ref":"#/components/responses/SellerApiUnauthorized"},"403":{"$ref":"#/components/responses/SellerApiForbidden"},"404":{"description":"`NOT_FOUND`: the product does not exist or has no downloadable media. On `2026-12-01` and later, `PRODUCT_NOT_SHARED` when the product exists but is not shared with you.","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"},"503":{"$ref":"#/components/responses/SellerApiServiceUnavailable"},"504":{"$ref":"#/components/responses/SellerApiTimeout"}}},"head":{"tags":["Catalog"],"summary":"Check product media without downloading it","description":"The headers of `GET /products/{productId}/media/download` without the archive: `ETag`, `Content-Disposition`, `X-Avrix-Media-Entries` and the rate-limit headers. Nothing is fetched from storage. Send `If-None-Match` with a stored `ETag` to get `304` while the media has not changed. Counts against the catalog rate limit like the GET. A HEAD response has no body; the status codes are the GET's.","operationId":"headProductMedia","security":[{"bearerAuth":[]}],"x-avrix-scopes":["seller:products:read"],"x-avrix-tier":"catalog","x-avrix-rate-limit-class":"catalog","x-avrix-scope-mode":"anyOf","parameters":[{"name":"productId","in":"path","required":true,"description":"The product UUID, or the readable `prd_` id the product payloads return as `readableId`.","schema":{"type":"string","anyOf":[{"format":"uuid"},{"pattern":"^prd_[23456789abcdefghjkmnpqrstuvwxyz]{8}$"}]}},{"$ref":"#/components/parameters/AvrixApiVersion"},{"$ref":"#/components/parameters/RequestId"},{"$ref":"#/components/parameters/SandboxSimulateRateLimit"},{"$ref":"#/components/parameters/IfNoneMatch"}],"responses":{"200":{"description":"The archive exists; headers only.","headers":{"Content-Disposition":{"description":"attachment; filename=\"{slug}-media-{timestamp}.zip\"","schema":{"type":"string"}},"X-Request-Id":{"$ref":"#/components/headers/XRequestId"},"X-Avrix-Api-Version":{"$ref":"#/components/headers/XAvrixApiVersion"},"X-Api-Version":{"$ref":"#/components/headers/XApiVersion"},"X-RateLimit-Limit":{"$ref":"#/components/headers/XRateLimitLimit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/XRateLimitRemaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/XRateLimitReset"},"X-RateLimit-Bucket":{"$ref":"#/components/headers/XRateLimitBucket"},"X-Avrix-Media-Entries":{"description":"How many files the archive is built from (not counting the manifest entry). Present on 200, 304 and HEAD. Additive.","schema":{"type":"integer","minimum":1}},"ETag":{"$ref":"#/components/headers/ETag"}}},"304":{"description":"Not modified: the asset list matches `If-None-Match`.","headers":{"X-Request-Id":{"$ref":"#/components/headers/XRequestId"},"X-Avrix-Api-Version":{"$ref":"#/components/headers/XAvrixApiVersion"},"X-Api-Version":{"$ref":"#/components/headers/XApiVersion"},"X-RateLimit-Limit":{"$ref":"#/components/headers/XRateLimitLimit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/XRateLimitRemaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/XRateLimitReset"},"X-RateLimit-Bucket":{"$ref":"#/components/headers/XRateLimitBucket"},"X-Avrix-Media-Entries":{"description":"How many files the archive is built from (not counting the manifest entry). Present on 200, 304 and HEAD. Additive.","schema":{"type":"integer","minimum":1}},"ETag":{"$ref":"#/components/headers/ETag"}}},"400":{"$ref":"#/components/responses/SellerApiUnsupportedApiVersion"},"401":{"$ref":"#/components/responses/SellerApiUnauthorized"},"403":{"$ref":"#/components/responses/SellerApiForbidden"},"404":{"description":"`NOT_FOUND`: the product does not exist or has no downloadable media. On `2026-12-01` and later, `PRODUCT_NOT_SHARED` when the product exists but is not shared with you.","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"},"503":{"$ref":"#/components/responses/SellerApiServiceUnavailable"},"504":{"$ref":"#/components/responses/SellerApiTimeout"}}}},"/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":["Reference data"],"security":[{"bearerAuth":[]}],"x-avrix-scopes":["seller:products:read"],"x-avrix-tier":"catalog","x-avrix-rate-limit-class":"catalog","x-avrix-scope-mode":"anyOf","parameters":[{"$ref":"#/components/parameters/AvrixApiVersion"},{"$ref":"#/components/parameters/RequestId"},{"$ref":"#/components/parameters/SandboxSimulateRateLimit"}],"responses":{"200":{"description":"Active platforms","headers":{"X-Request-Id":{"$ref":"#/components/headers/XRequestId"},"X-Avrix-Api-Version":{"$ref":"#/components/headers/XAvrixApiVersion"},"X-Api-Version":{"$ref":"#/components/headers/XApiVersion"},"X-RateLimit-Limit":{"$ref":"#/components/headers/XRateLimitLimit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/XRateLimitRemaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/XRateLimitReset"},"X-RateLimit-Bucket":{"$ref":"#/components/headers/XRateLimitBucket"}},"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."}}},"example":{"data":[{"code":"steam","name":"Example Game","platformFamily":"steam"}],"version":"1","updatedAt":"2026-11-02T09:30:00Z"}}}},"400":{"$ref":"#/components/responses/SellerApiUnsupportedApiVersion"},"401":{"$ref":"#/components/responses/SellerApiUnauthorized"},"403":{"$ref":"#/components/responses/SellerApiForbidden"},"422":{"$ref":"#/components/responses/SellerApiValidationFailed"},"429":{"$ref":"#/components/responses/SellerApiRateLimited"},"500":{"$ref":"#/components/responses/SellerApiInternalError"},"503":{"$ref":"#/components/responses/SellerApiServiceUnavailable"},"504":{"$ref":"#/components/responses/SellerApiTimeout"}}}},"/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 in the changelog at least 14 days ahead (the response's `policy` text says the same).","operationId":"getWebhookEgressIps","tags":["Webhooks"],"security":[],"x-avrix-scopes":[],"x-avrix-tier":"public","x-avrix-rate-limit-class":"none","x-avrix-scope-mode":"public","parameters":[{"$ref":"#/components/parameters/RequestId"}],"responses":{"200":{"description":"Egress identity","headers":{"X-Request-Id":{"$ref":"#/components/headers/XRequestId"},"X-Avrix-Api-Version":{"$ref":"#/components/headers/XAvrixApiVersion"},"X-Api-Version":{"$ref":"#/components/headers/XApiVersion"}},"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"},"policy":{"type":"string","description":"The allowlisting answer in prose: with pinned addresses, where deliveries come from and how changes are announced; without, why no list exists and that X-Avrix-Signature is the authentication."},"verificationRequired":{"type":"boolean","const":true},"docUrl":{"type":"string"}}}}},"example":{"data":{"egressIps":["example_egressip"],"pinned":true,"verificationRequired":true,"docUrl":"https://api.avrix.io/api/seller/v1/example"}}}}},"401":{"description":"Not returned by this operation: it reads no API key. The entry is kept so that clients generated from earlier versions of this document keep their error types.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"403":{"description":"Not returned by this operation: it reads no API key. The entry is kept so that clients generated from earlier versions of this document keep their error types.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"429":{"description":"Not returned by this operation: it is not rate limited. The entry is kept so that clients generated from earlier versions of this document keep their error types.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}},"headers":{"X-RateLimit-Limit":{"description":"Not sent by this operation: it is not rate limited. The entry is kept so that clients generated from earlier versions of this document keep their header types.","required":false,"schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Not sent by this operation: it is not rate limited. The entry is kept so that clients generated from earlier versions of this document keep their header types.","required":false,"schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"Not sent by this operation: it is not rate limited. The entry is kept so that clients generated from earlier versions of this document keep their header types.","required":false,"schema":{"type":"integer","format":"int64"}}}},"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.\n\n**Paging:** `meta` carries the shared list keys (`limit`, `hasMore`, `nextCursor`, `nextUrl`) beside `data.nextCursor` and `data.truncated`, which keep their meaning. The CSV carries `X-Next-Cursor` with the same value as `X-Avrix-Statement-Next-Cursor`. See `https://docs.avrix.io/seller-api/pagination`.\n\n**CSV columns:** id, saleTimestamp, orderReference, skuId, productId, publisherCompanyId, salePriceCents, currencyCode, publisherShareCents, sellerShareCents, platformFeeCents, adjustmentStatus, then (appended, so a statement line carries what the same sale carries in the api-sales CSV) currencyExponent, keyPullId, keyId, reportId, aggregationStatus, entryType, reversesTransactionId, vatMinor, netMinor, appliedRatePercent, rateReason, requestedCountry, customerRegionCode, detectedCountryCode. Columns are only ever appended; parse by header name.\n\n**Contract date `2026-12-01` and later:** a `format` other than `json` or `csv` is refused with `422 VALIDATION_FAILED` (`details.field: format`; earlier dates answer JSON), a `limit` outside 1 to 5000 is reported against `limit` (earlier dates report it against `cursor`), and a failure of Avrix's own infrastructure answers `503` or `504` with `Retry-After` (earlier dates answer `500`). On every date a `500` carries a generic message.","operationId":"getFinanceStatement","tags":["Finance"],"security":[{"bearerAuth":[]}],"x-avrix-scopes":["seller:finance:read"],"x-avrix-tier":"general","x-avrix-rate-limit-class":"general","x-avrix-scope-mode":"anyOf","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). On contract date `2026-12-01` and later any other value is refused with 422; earlier dates answer JSON.","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}},{"$ref":"#/components/parameters/AvrixApiVersion"},{"$ref":"#/components/parameters/RequestId"},{"$ref":"#/components/parameters/SandboxSimulateRateLimit"}],"responses":{"200":{"description":"Statement for the period","headers":{"X-Request-Id":{"$ref":"#/components/headers/XRequestId"},"X-Avrix-Api-Version":{"$ref":"#/components/headers/XAvrixApiVersion"},"X-Api-Version":{"$ref":"#/components/headers/XApiVersion"},"X-RateLimit-Limit":{"$ref":"#/components/headers/XRateLimitLimit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/XRateLimitRemaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/XRateLimitReset"},"X-RateLimit-Bucket":{"$ref":"#/components/headers/XRateLimitBucket"},"X-Next-Cursor":{"$ref":"#/components/headers/XNextCursor"}},"content":{"application/json":{"schema":{"type":"object","required":["data"],"properties":{"data":{"$ref":"#/components/schemas/SellerFinanceStatement"},"meta":{"type":"object","properties":{"limit":{"type":"integer","description":"The page size this response was cut at."},"hasMore":{"type":"boolean","description":"True when another page follows. Loop on `hasMore`; send `nextCursor` back as `cursor`."},"nextCursor":{"type":["string","null"],"description":"Opaque position after the last item of this page; send it back as `cursor`. Null on the last page."},"nextUrl":{"type":["string","null"],"description":"Absolute URL of the next page: this request with `cursor` set to `nextCursor`. Null when there is no next page."}}}}},"example":{"data":{"period":"2026-10","periodStart":"2026-10-01T00:00:00Z","periodEnd":"2026-10-31T23:59:59Z","generatedAt":"2026-11-02T09:30:00Z","totals":[{"currencyCode":"EUR","currencyExponent":2,"transactionCount":3,"grossSalesCents":4900,"grossSalesMinor":4900,"refundedCents":2450,"refundedMinor":2450,"reinstatedCents":0,"reinstatedMinor":0,"netSalesCents":2450,"netSalesMinor":2450,"publisherShareCents":1960,"publisherShareMinor":1960,"sellerShareCents":245,"sellerShareMinor":245,"platformFeeCents":245,"platformFeeMinor":245}],"lines":[{"id":"6f1c2a9e-3b7d-4e21-9c84-0a5d2e7b1f30","publisherCompanyId":"acme-games","keyPullId":"c1d2e3f4-a5b6-4c7d-8e9f-0a1b2c3d4e5f","keyId":"0e8f6a1b-2c3d-4e5f-8a9b-1c2d3e4f5a6b","skuId":"69ee8d02-27c6-4f5a-8d87-fae0cdaf2100","productId":"afa398b3-94fd-4e2a-8e1d-43f1048e3383","salePriceCents":2450,"initialSalePriceCents":2450,"currencyCode":"EUR","currencyExponent":2,"publisherShareCents":1960,"sellerShareCents":245,"platformFeeCents":245,"revenueSharePercent":80,"saleTimestamp":"2026-10-04T14:12:09Z","aggregationStatus":"aggregated","reportId":"356a5c58-1b6d-4605-8073-7137f2bda6e5","orderReference":"store-order-10432","customerRegionCode":"DE","detectedCountryCode":"DE","countryMismatch":false,"warnings":[],"contractTermId":"fd6a5a98-51b2-438e-8236-b9ef5c394db5","contractTermVersion":1,"adjustmentStatus":"refunded","declaredRetail":{"retailCurrencyCode":"EUR","currencyExponent":2,"grossMinor":2450,"netMinor":2042,"taxAmountMinor":408,"taxRatePercent":20,"priceIncludesTax":true,"paymentMethodFamily":"card","paymentProcessorReference":"pi_10432","checkoutSessionId":"cs_10432","purchaseOrderNumber":"PO-10432"},"integrationOrderContext":null,"taxMetadata":{"declaredTaxAmountMinor":408,"declaredTaxRatePercent":20,"priceIncludesTax":true,"authoritative":false},"settlement":{"basis":"purchaser_country_capped","vatMinor":408,"netMinor":2042,"appliedRatePercent":20,"declaredRatePercent":20,"rateReason":"corroborated","evidenceRank":1,"requestedCountry":"DE"},"entryType":"sale","reversesTransactionId":null},{"id":"8d2e4b6a-1c3f-4a57-b0e9-5f7a3c9d2e14","publisherCompanyId":"acme-games","keyPullId":"d2e3f4a5-b6c7-4d8e-9f0a-1b2c3d4e5f60","keyId":"1f9a7b2c-3d4e-4f5a-9b0c-2d3e4f5a6b7c","skuId":"69ee8d02-27c6-4f5a-8d87-fae0cdaf2100","productId":"afa398b3-94fd-4e2a-8e1d-43f1048e3383","salePriceCents":2450,"initialSalePriceCents":2450,"currencyCode":"EUR","currencyExponent":2,"publisherShareCents":1960,"sellerShareCents":245,"platformFeeCents":245,"revenueSharePercent":80,"saleTimestamp":"2026-10-09T08:41:55Z","aggregationStatus":"aggregated","reportId":"356a5c58-1b6d-4605-8073-7137f2bda6e5","orderReference":"store-order-10519","customerRegionCode":"DE","detectedCountryCode":"DE","countryMismatch":false,"warnings":[],"contractTermId":"fd6a5a98-51b2-438e-8236-b9ef5c394db5","contractTermVersion":1,"adjustmentStatus":"none","declaredRetail":{"retailCurrencyCode":"EUR","currencyExponent":2,"grossMinor":2450,"netMinor":2042,"taxAmountMinor":408,"taxRatePercent":20,"priceIncludesTax":true,"paymentMethodFamily":"card","paymentProcessorReference":"pi_10432","checkoutSessionId":"cs_10432","purchaseOrderNumber":"PO-10432"},"integrationOrderContext":null,"taxMetadata":{"declaredTaxAmountMinor":408,"declaredTaxRatePercent":20,"priceIncludesTax":true,"authoritative":false},"settlement":{"basis":"purchaser_country_capped","vatMinor":408,"netMinor":2042,"appliedRatePercent":20,"declaredRatePercent":20,"rateReason":"corroborated","evidenceRank":1,"requestedCountry":"DE"},"entryType":"sale","reversesTransactionId":null},{"id":"2b9f7c1d-6e4a-4f83-a2c5-9d1e8b3f7a60","publisherCompanyId":"acme-games","keyPullId":"c1d2e3f4-a5b6-4c7d-8e9f-0a1b2c3d4e5f","keyId":"0e8f6a1b-2c3d-4e5f-8a9b-1c2d3e4f5a6b","skuId":"69ee8d02-27c6-4f5a-8d87-fae0cdaf2100","productId":"afa398b3-94fd-4e2a-8e1d-43f1048e3383","salePriceCents":-2450,"initialSalePriceCents":null,"currencyCode":"EUR","currencyExponent":2,"publisherShareCents":-1960,"sellerShareCents":-245,"platformFeeCents":-245,"revenueSharePercent":80,"saleTimestamp":"2026-10-06T10:03:27Z","aggregationStatus":"aggregated","reportId":"356a5c58-1b6d-4605-8073-7137f2bda6e5","orderReference":"store-order-10432","customerRegionCode":"DE","detectedCountryCode":"DE","countryMismatch":false,"warnings":[],"contractTermId":"fd6a5a98-51b2-438e-8236-b9ef5c394db5","contractTermVersion":1,"adjustmentStatus":"refunded","declaredRetail":{"retailCurrencyCode":"EUR","currencyExponent":2,"grossMinor":-2450,"netMinor":-2042,"taxAmountMinor":-408,"taxRatePercent":20,"priceIncludesTax":true,"paymentMethodFamily":"card","paymentProcessorReference":"pi_10432","checkoutSessionId":"cs_10432","purchaseOrderNumber":"PO-10432"},"integrationOrderContext":null,"taxMetadata":{"declaredTaxAmountMinor":-408,"declaredTaxRatePercent":20,"priceIncludesTax":true,"authoritative":false},"settlement":{"basis":"purchaser_country_capped","vatMinor":-408,"netMinor":-2042,"appliedRatePercent":20,"declaredRatePercent":20,"rateReason":"corroborated","evidenceRank":1,"requestedCountry":"DE"},"entryType":"sale_reversal","reversesTransactionId":"6f1c2a9e-3b7d-4e21-9c84-0a5d2e7b1f30"}],"lineCount":3,"truncated":false,"totalsScope":"returned_lines","totalLineCount":3,"nextCursor":null,"snapshotExpiresAt":"2026-11-02T09:30:00Z","activityTotals":[{"currencyCode":"EUR","currencyExponent":2,"transactionCount":3,"grossSalesCents":4900,"grossSalesMinor":4900,"refundedCents":2450,"refundedMinor":2450,"reinstatedCents":0,"reinstatedMinor":0,"netSalesCents":2450,"netSalesMinor":2450,"publisherShareCents":1960,"publisherShareMinor":1960,"sellerShareCents":245,"sellerShareMinor":245,"platformFeeCents":245,"platformFeeMinor":245}],"pendingTotals":[{"currencyCode":"EUR","currencyExponent":2,"transactionCount":0,"grossSalesCents":0,"grossSalesMinor":0,"refundedCents":0,"refundedMinor":0,"reinstatedCents":0,"reinstatedMinor":0,"netSalesCents":0,"netSalesMinor":0,"publisherShareCents":0,"publisherShareMinor":0,"sellerShareCents":0,"sellerShareMinor":0,"platformFeeCents":0,"platformFeeMinor":0}],"quarantinedTotals":[{"currencyCode":"EUR","currencyExponent":2,"transactionCount":0,"grossSalesCents":0,"grossSalesMinor":0,"refundedCents":0,"refundedMinor":0,"reinstatedCents":0,"reinstatedMinor":0,"netSalesCents":0,"netSalesMinor":0,"publisherShareCents":0,"publisherShareMinor":0,"sellerShareCents":0,"sellerShareMinor":0,"platformFeeCents":0,"platformFeeMinor":0}],"approvedSettlements":[{"reportId":"0bfe9b56-52e6-4ac2-8bcd-c21d0a6fc788","publisherCompanyId":"acme-games","contractTermId":"53cd94e3-380e-423a-8fd5-18bbf7754d01","currencyCode":"EUR","currencyExponent":2,"publisherShareMinor":1960,"status":"approved","invoices":[{"invoiceId":"fc213173-5c66-4946-8dc0-f44b5086b1c0","status":"payable","currencyCode":"EUR","currencyExponent":2,"totalMinor":1960}]}],"outstandingBalances":[{"publisherCompanyId":"acme-games","contractTermId":"cfb08fe0-3148-4900-8119-3e41a2cc7b3f","currencyCode":"EUR","currencyExponent":2,"outstandingMinor":2450}]},"meta":{"limit":50,"hasMore":false,"nextCursor":null,"nextUrl":null}}},"text/csv":{"schema":{"type":"string","description":"One row per transaction line."}}}},"400":{"$ref":"#/components/responses/SellerApiUnsupportedApiVersion"},"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"},"503":{"$ref":"#/components/responses/SellerApiServiceUnavailable"},"504":{"$ref":"#/components/responses/SellerApiTimeout"}}}},"/api/seller/v1/finance/ledger":{"get":{"tags":["Finance"],"summary":"Read the finance ledger","description":"Your money ledger for one window: every sale, refund, chargeback and reinstatement entry, oldest first, with running balances per currency. Refunds and chargebacks are their own negative entries, and an entry's amounts never change once returned. Pull and reveal entries move stock, not money, and are on `GET /activity` only.\n\nPass `period=YYYY-MM` (a UTC calendar month, the same window a statement covers) or `from` and `to` (at most 366 days). Balances start at zero at the start of the window and run per currency; `balanceAfter` on each entry includes that entry. `meta.balances` holds the closing balances of the whole window on every page: for a calendar month they equal `activityTotals` of `GET /finance/statements` for the same period, field for field.\n\nPage with `meta.nextCursor` until `meta.hasMore` is false; balances continue exactly across pages. Balances are computed per request, so an entry recorded late with an earlier timestamp moves the balances after it, never the entry itself.\n\n`format=csv` returns the same page with the columns `entryId`, `kind`, `occurredAt`, `currencyCode`, `currencyExponent`, `publisherCompanyId`, `orderReference`, `keyId`, `skuId`, `transactionId`, `adjustmentReference`, `grossCents`, `publisherShareCents`, `sellerShareCents`, `platformFeeCents`, `balanceNetSalesCents`, `balancePublisherShareCents`, `balanceSellerShareCents`, `balancePlatformFeeCents`; the next cursor is in the `X-Next-Cursor` header.\n\n**Paging:** the shared list contract, see `https://docs.avrix.io/seller-api/pagination`. On contract date `2026-12-01` and later a `cursor` this API did not return is refused with `422 VALIDATION_FAILED` (`details.issues[].field` is `cursor`); earlier dates serve the first page.","operationId":"getFinanceLedger","security":[{"bearerAuth":[]}],"parameters":[{"name":"period","in":"query","required":false,"description":"UTC calendar month, `YYYY-MM`. Send this or `from` and `to`.","schema":{"type":"string","pattern":"^\\d{4}-(0[1-9]|1[0-2])$","example":"2026-09"}},{"name":"from","in":"query","required":false,"description":"Window start, inclusive (ISO 8601).","schema":{"type":"string","format":"date-time"}},{"name":"to","in":"query","required":false,"description":"Window end, exclusive (ISO 8601). At most 366 days after `from`.","schema":{"type":"string","format":"date-time"}},{"name":"currency","in":"query","required":false,"description":"Only entries in this currency (ISO 4217).","schema":{"type":"string","pattern":"^[A-Z]{3}$"}},{"name":"cursor","in":"query","required":false,"description":"Opaque `meta.nextCursor` from the previous page. Keep the same window and currency.","schema":{"type":"string"}},{"name":"limit","in":"query","required":false,"description":"Entries per page.","schema":{"type":"integer","minimum":1,"maximum":1000,"default":500}},{"name":"format","in":"query","required":false,"description":"`json` (default) or `csv`.","schema":{"type":"string","enum":["json","csv"],"default":"json"}},{"$ref":"#/components/parameters/AvrixApiVersion"},{"$ref":"#/components/parameters/RequestId"},{"$ref":"#/components/parameters/SandboxSimulateRateLimit"}],"responses":{"200":{"description":"One page of the ledger.","headers":{"X-Request-Id":{"$ref":"#/components/headers/XRequestId"},"X-Avrix-Api-Version":{"$ref":"#/components/headers/XAvrixApiVersion"},"X-Api-Version":{"$ref":"#/components/headers/XApiVersion"},"X-RateLimit-Limit":{"$ref":"#/components/headers/XRateLimitLimit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/XRateLimitRemaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/XRateLimitReset"},"X-RateLimit-Bucket":{"$ref":"#/components/headers/XRateLimitBucket"},"X-Next-Cursor":{"$ref":"#/components/headers/XNextCursor"}},"content":{"application/json":{"schema":{"type":"object","required":["data","meta"],"properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/SellerLedgerEntry"}},"meta":{"type":"object","required":["from","to","currency","limit","hasMore","nextCursor","balances"],"properties":{"from":{"type":"string","format":"date-time"},"to":{"type":"string","format":"date-time"},"currency":{"type":["string","null"]},"limit":{"type":"integer"},"hasMore":{"type":"boolean"},"nextCursor":{"type":["string","null"]},"balances":{"type":"array","description":"Closing balances of the whole window, per currency.","items":{"$ref":"#/components/schemas/SellerLedgerBalance"}},"nextUrl":{"type":["string","null"],"description":"Absolute URL of the next page: this request with `cursor` set to `nextCursor`. Null when there is no next page."}}}}},"example":{"data":[{"entryId":"cf1c0954-f0b1-4f1e-8b63-865b0d60d866","kind":"sale","occurredAt":"2026-11-02T09:30:00Z","currencyCode":"EUR","currencyExponent":2,"publisherCompanyId":"acme-games","orderReference":"store-order-10432","keyId":"64e281c0-dc16-467e-8f29-57e621c679c4","skuId":"1c3a99a7-3fc0-4a9a-8b3b-2848e84ef893","transactionId":"d2e7d9f6-fe3c-4b76-8a0f-b8ec5644d42e","adjustmentReference":"adj_10432","grossCents":2450,"grossMinor":2450,"publisherShareCents":2450,"publisherShareMinor":2450,"sellerShareCents":2450,"sellerShareMinor":2450,"platformFeeCents":2450,"platformFeeMinor":2450,"balanceAfter":{"netSalesCents":2450,"netSalesMinor":2450,"publisherShareCents":2450,"publisherShareMinor":2450,"sellerShareCents":2450,"sellerShareMinor":2450,"platformFeeCents":2450,"platformFeeMinor":2450}}],"meta":{"from":"2026-11-02T09:30:00Z","to":"2026-11-02T09:30:00Z","currency":"EUR","limit":50,"hasMore":true,"nextCursor":"eyJ2IjoyLCJ0IjoiMjAyNi0xMS0wMlQwOTozMDowMFoifQ","balances":[{"currencyCode":"EUR","currencyExponent":2,"entryCount":12,"grossSalesCents":2450,"grossSalesMinor":2450,"refundedCents":2450,"refundedMinor":2450,"reinstatedCents":2450,"reinstatedMinor":2450,"netSalesCents":2450,"netSalesMinor":2450,"publisherShareCents":2450,"publisherShareMinor":2450,"sellerShareCents":2450,"sellerShareMinor":2450,"platformFeeCents":2450,"platformFeeMinor":2450}],"nextUrl":"https://api.avrix.io/api/seller/v1/finance/ledger?cursor=eyJ2IjoyLCJ0IjoiMjAyNi0xMS0wMlQwOTozMDowMFoifQ"}}},"text/csv":{"schema":{"type":"string","description":"One row per entry; columns as named in the header row."}}}},"400":{"$ref":"#/components/responses/SellerApiUnsupportedApiVersion"},"401":{"$ref":"#/components/responses/SellerApiUnauthorized"},"403":{"$ref":"#/components/responses/SellerApiForbidden"},"422":{"$ref":"#/components/responses/SellerApiValidationFailed"},"429":{"$ref":"#/components/responses/SellerApiRateLimited"},"500":{"$ref":"#/components/responses/SellerApiInternalError"},"503":{"$ref":"#/components/responses/SellerApiServiceUnavailable"},"504":{"$ref":"#/components/responses/SellerApiTimeout"}},"x-avrix-scopes":["seller:finance:read"],"x-avrix-tier":"finance","x-avrix-rate-limit-class":"finance","x-avrix-scope-mode":"anyOf"}},"/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"],"security":[{"bearerAuth":[]}],"x-avrix-scopes":["seller:products:read"],"x-avrix-tier":"general","x-avrix-rate-limit-class":"general","x-avrix-scope-mode":"anyOf","parameters":[{"$ref":"#/components/parameters/AvrixApiVersion"},{"$ref":"#/components/parameters/RequestId"},{"$ref":"#/components/parameters/SandboxSimulateRateLimit"}],"responses":{"200":{"description":"Consolidated integration gates","headers":{"X-Request-Id":{"$ref":"#/components/headers/XRequestId"},"X-Avrix-Api-Version":{"$ref":"#/components/headers/XAvrixApiVersion"},"X-Api-Version":{"$ref":"#/components/headers/XApiVersion"},"X-RateLimit-Limit":{"$ref":"#/components/headers/XRateLimitLimit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/XRateLimitRemaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/XRateLimitReset"},"X-RateLimit-Bucket":{"$ref":"#/components/headers/XRateLimitBucket"}},"content":{"application/json":{"schema":{"type":"object","required":["data"],"properties":{"data":{"$ref":"#/components/schemas/SellerIntegrationStatus"}}},"example":{"data":{"readyToSell":true,"gates":[{"gate":"bmaActive","satisfied":true,"hint":"Example text."}],"counts":{"sellableSkuCount":12,"sharedSkuCount":12,"allocatedSkuCount":12},"activationPolicy":"warn","activationEnforceOptIn":true,"priceCommitmentConfigured":true,"backorderEnabled":true}}}}},"400":{"$ref":"#/components/responses/SellerApiUnsupportedApiVersion"},"401":{"$ref":"#/components/responses/SellerApiUnauthorized"},"403":{"$ref":"#/components/responses/SellerApiForbidden"},"422":{"$ref":"#/components/responses/SellerApiValidationFailed"},"429":{"$ref":"#/components/responses/SellerApiRateLimited"},"500":{"$ref":"#/components/responses/SellerApiInternalError"},"503":{"$ref":"#/components/responses/SellerApiServiceUnavailable"},"504":{"$ref":"#/components/responses/SellerApiTimeout"}}}},"/api/seller/v1/orders/{orderId}/keys/{keyId}/replace":{"post":{"summary":"Replace a delivered key","description":"Replace a key the buyer could not use (`already_redeemed`, `invalid`, `wrong_region`, `revoked`) with a fresh key from the **same allocation**. The old key is quarantined for the Content Owner's review. This is not a second sale: the order keeps its reference, sale and settlement, and no allocation capacity is consumed.\n\nWithin the Content Owner's replacement policy (default: 1 replacement per order and 10 per 30 days, auto-approved) the new key comes back at once with **200** (`keys`, `keyIds`). Outside it the request waits for the Content Owner with **202** `status: pending`; after approval `key.replaced` is sent and the key is read with `POST /orders/recover-keys`. Send an `Idempotency-Key` header (required); asking again for the same key returns the same replacement. `GET /orders/{orderId}` lists every replacement under `replacements[]`.\n\nErrors: **404** `NOT_FOUND` (order, or the key is not on it), **409** `KEY_NOT_REPLACEABLE` (the key was returned, refunded or replaced), **409** `NO_AVAILABLE_KEYS` (no key left in the allocation; retry with the same Idempotency-Key once stock arrives).\n\nSandbox: `SANDBOX-REPLACE-PENDING-001` always answers 202 and is approved a moment later.","tags":["Orders"],"security":[{"bearerAuth":[]}],"parameters":[{"name":"orderId","in":"path","required":true,"schema":{"type":"string","pattern":"^ord_"},"description":"The order's id (`ord_…`): `orderId` from any order response. The id of the order's first key pull (`orderReadableId` on contract dates before `2026-12-01`) is accepted too."},{"name":"keyId","in":"path","required":true,"schema":{"type":"string","format":"uuid"},"description":"A key id from the order's `keyIds`"},{"$ref":"#/components/parameters/IdempotencyKey"},{"$ref":"#/components/parameters/AvrixApiVersion"},{"$ref":"#/components/parameters/RequestId"},{"$ref":"#/components/parameters/SandboxSimulateWrite"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"required":["reason"],"properties":{"reason":{"type":"string","enum":["already_redeemed","invalid","wrong_region","revoked"]},"note":{"type":"string","maxLength":1000,"description":"Optional context for the Content Owner (buyer report, platform message)."}}}}}},"responses":{"200":{"description":"Replaced. The new key is in `keys` (plaintext, this response only) and `keyIds`.","headers":{"X-Request-Id":{"$ref":"#/components/headers/XRequestId"},"X-Avrix-Api-Version":{"$ref":"#/components/headers/XAvrixApiVersion"},"X-Api-Version":{"$ref":"#/components/headers/XApiVersion"},"Idempotency-Replayed":{"$ref":"#/components/headers/IdempotencyReplayed"},"X-RateLimit-Limit":{"$ref":"#/components/headers/XRateLimitLimit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/XRateLimitRemaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/XRateLimitReset"},"X-RateLimit-Bucket":{"$ref":"#/components/headers/XRateLimitBucket"}},"content":{"application/json":{"schema":{"type":"object","required":["data"],"properties":{"data":{"type":"object","required":["replacementId","status","orderId","orderReference","replacedKeyId","reason","keyIds","keys"],"properties":{"replacementId":{"type":"string","format":"uuid"},"status":{"type":"string","const":"completed"},"orderId":{"type":"string"},"orderReference":{"type":"string"},"replacedKeyId":{"type":"string","format":"uuid"},"reason":{"type":"string"},"keyIds":{"type":"array","items":{"type":"string","format":"uuid"}},"keys":{"type":"array","description":"Plaintext codes (`string`) up to contract date 2026-09-01; typed key objects from 2026-10-01 (`X-Avrix-Api-Version`). Same order as `keyIds`.","items":{"$ref":"#/components/schemas/SellerDeliveredKey"}}}}}},"example":{"data":{"replacementId":"e24c8847-9bea-4510-87c5-af990d30c752","status":"completed","orderId":"ord_xw7qtfcd","orderReference":"store-order-10432","replacedKeyId":"37d9f3f5-56a5-48f1-8fc9-75e837a86afe","keyIds":["758b880b-5a7a-40f7-8b37-dc33c8ce2fce"],"keys":["XXXXX-XXXXX-XXXXX-XXXXX"],"reason":"already_redeemed"}}}}},"202":{"description":"Waiting for the Content Owner (outside the replacement policy). `key.replaced` follows the approval.","headers":{"X-Request-Id":{"$ref":"#/components/headers/XRequestId"},"X-Avrix-Api-Version":{"$ref":"#/components/headers/XAvrixApiVersion"},"X-Api-Version":{"$ref":"#/components/headers/XApiVersion"},"Idempotency-Replayed":{"$ref":"#/components/headers/IdempotencyReplayed"},"X-RateLimit-Limit":{"$ref":"#/components/headers/XRateLimitLimit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/XRateLimitRemaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/XRateLimitReset"},"X-RateLimit-Bucket":{"$ref":"#/components/headers/XRateLimitBucket"}},"content":{"application/json":{"schema":{"type":"object","required":["data"],"properties":{"data":{"type":"object","required":["replacementId","status","orderId","orderReference","replacedKeyId","reason"],"properties":{"replacementId":{"type":"string","format":"uuid"},"status":{"type":"string","const":"pending"},"orderId":{"type":"string"},"orderReference":{"type":"string"},"replacedKeyId":{"type":"string","format":"uuid"},"reason":{"type":"string"},"policy":{"type":["object","null"],"description":"The Content Owner's policy and what this order / period has used.","properties":{"autoApprove":{"type":"boolean"},"maxPerOrder":{"type":"integer"},"maxPerPeriod":{"type":"integer"},"periodDays":{"type":"integer"},"usedOnOrder":{"type":"integer"},"usedInPeriod":{"type":"integer"}}}}}}},"example":{"data":{"replacementId":"d4e4c496-6e78-4c55-8f72-53f39236461d","status":"pending","orderId":"ord_x2syqa7f","orderReference":"store-order-10432","replacedKeyId":"350192b6-9f63-4234-8d89-a9e786969b57","policy":{"autoApprove":true,"maxPerOrder":1,"maxPerPeriod":1,"periodDays":1,"usedOnOrder":1,"usedInPeriod":1},"reason":"already_redeemed"}}}}},"400":{"$ref":"#/components/responses/SellerApiIdempotencyKeyRequired"},"401":{"$ref":"#/components/responses/SellerApiUnauthorized"},"403":{"$ref":"#/components/responses/SellerApiForbidden"},"404":{"description":"Order not found, or the key is not on it","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"409":{"description":"`KEY_NOT_REPLACEABLE` or `NO_AVAILABLE_KEYS`. Also returned for the `Idempotency-Key` itself: `IDEMPOTENCY_KEY_MISMATCH` (the key was already used with a different body) and `IDEMPOTENCY_REQUEST_IN_FLIGHT` (an earlier request with this key is still running; retry after `Retry-After` seconds).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"413":{"$ref":"#/components/responses/SellerApiPayloadTooLarge"},"422":{"description":"Invalid path or body","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"429":{"$ref":"#/components/responses/SellerApiRateLimited"},"500":{"$ref":"#/components/responses/SellerApiInternalError"},"503":{"$ref":"#/components/responses/SellerApiServiceUnavailable"},"504":{"$ref":"#/components/responses/SellerApiTimeout"}},"x-avrix-scopes":["seller:orders:write","seller:keys:pull"],"x-avrix-tier":"orders","x-avrix-rate-limit-class":"orders","x-avrix-scope-mode":"anyOf","operationId":"replaceOrderKey"}},"/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 true; a Content Owner can opt out) — without them 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. The delivery is checked against what the order was placed with: on a wholesale allocation the unit price committed at placement (`expectedUnitPriceCents`), and the `integrationOrderContext` Avrix keeps with a pre-order or backorder placed on or after 2026-11-13, so a territory or price rule that needs them runs on the declaration made at placement.","tags":["Orders"],"security":[{"bearerAuth":[]}],"parameters":[{"name":"orderId","in":"path","required":true,"schema":{"type":"string","pattern":"^ord_"},"description":"The order's id (`ord_…`): `orderId` from any order response. The id of the order's first key pull (`orderReadableId` on contract dates before `2026-12-01`) is accepted too."},{"$ref":"#/components/parameters/IdempotencyKey"},{"$ref":"#/components/parameters/AvrixApiVersion"},{"$ref":"#/components/parameters/RequestId"},{"$ref":"#/components/parameters/SandboxSimulateWrite"}],"responses":{"200":{"description":"Keys revealed. Order is fulfilled.","headers":{"X-Request-Id":{"$ref":"#/components/headers/XRequestId"},"X-Avrix-Api-Version":{"$ref":"#/components/headers/XAvrixApiVersion"},"X-Api-Version":{"$ref":"#/components/headers/XApiVersion"},"Idempotency-Replayed":{"$ref":"#/components/headers/IdempotencyReplayed"},"X-RateLimit-Limit":{"$ref":"#/components/headers/XRateLimitLimit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/XRateLimitRemaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/XRateLimitReset"},"X-RateLimit-Bucket":{"$ref":"#/components/headers/XRateLimitBucket"}},"content":{"application/json":{"schema":{"type":"object","required":["data"],"properties":{"data":{"$ref":"#/components/schemas/SellerOrderFulfillData"}}},"example":{"data":{"type":"fulfilled","status":"fulfilled","orderId":"ord_b8vzz3w2","orderReference":"store-order-10432","allocationId":"7fe2e985-87f7-423f-8821-bc5e2641fc06","pulled":12,"keys":["XXXXX-XXXXX-XXXXX-XXXXX"],"keyIds":["e1bbd0fc-a640-4e0a-815d-945cd48e34c1"],"activation":{"type":"worldwide","countries":["DE"]}}}}}},"400":{"$ref":"#/components/responses/SellerApiIdempotencyKeyRequired"},"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. A wholesale allocation whose price changed since the order was placed answers with a message starting `WHOLESALE_PRICE_MISMATCH`; no key is delivered and the order keeps its status. Also returned for the `Idempotency-Key` itself: `IDEMPOTENCY_KEY_MISMATCH` (the key was already used with a different body) and `IDEMPOTENCY_REQUEST_IN_FLIGHT` (an earlier request with this key is still running; retry after `Retry-After` seconds).","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"},"503":{"$ref":"#/components/responses/SellerApiServiceUnavailable"},"504":{"$ref":"#/components/responses/SellerApiTimeout"}},"x-avrix-scopes":["seller:orders:fulfill","seller:orders:write","seller:keys:pull"],"x-avrix-tier":"orders","x-avrix-rate-limit-class":"orders","x-avrix-scope-mode":"anyOf","operationId":"fulfillOrder"}},"/api/seller/v1/promotions/calendar":{"get":{"summary":"List live and upcoming promotion windows","description":"Accepted shares and approved deals by SKU with their window and `priceEffect` (`list_price`, `settlement_price`, or `both`). Live and upcoming windows by default; filter by window (`from`, `to`, `window`), SKU, product, offer (`sourceId`) or vendor (`vendor`). `basePriceCents` on `/products/{id}/pricing` stays the undiscounted list price; the catalogue promotion fields beside it (`listPromo`, `advertisedPriceCents`, `promo`, `promotions`) say what a promotion does to it. Settlement-affecting windows change preview/commit unit price. Requires seller:promotions:read.","tags":["Promotions"],"parameters":[{"name":"from","in":"query","required":false,"schema":{"type":"string","format":"date-time"},"description":"Only windows that end at or after this instant (ISO 8601, UTC). Additive."},{"name":"to","in":"query","required":false,"schema":{"type":"string","format":"date-time"},"description":"Only windows that start at or before this instant (ISO 8601, UTC). Additive."},{"name":"skuId","in":"query","required":false,"schema":{"type":"string"},"description":"Comma-separated SKU ids (at most 50). Additive."},{"name":"productId","in":"query","required":false,"schema":{"type":"string"},"description":"Comma-separated catalog product ids (at most 50). Additive."},{"name":"sourceId","in":"query","required":false,"schema":{"type":"string"},"description":"Comma-separated share ids or deal response ids (at most 50). Additive."},{"name":"vendor","in":"query","required":false,"schema":{"type":"string","maxLength":32,"pattern":"^[a-zA-Z0-9_-]+$"},"description":"Only promotions of this vendor (company id). Additive."},{"name":"window","in":"query","required":false,"schema":{"type":"string"},"description":"Comma-separated: `live`, `upcoming`, `ended`. Default `live,upcoming`. `ended` returns windows that closed since `from`, or in the last 90 days without it. Additive."},{"$ref":"#/components/parameters/AvrixApiVersion"},{"$ref":"#/components/parameters/RequestId"},{"$ref":"#/components/parameters/SandboxSimulateRateLimit"}],"responses":{"200":{"description":"Promotion calendar","headers":{"X-Request-Id":{"$ref":"#/components/headers/XRequestId"},"X-Avrix-Api-Version":{"$ref":"#/components/headers/XAvrixApiVersion"},"X-Api-Version":{"$ref":"#/components/headers/XApiVersion"},"X-RateLimit-Limit":{"$ref":"#/components/headers/XRateLimitLimit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/XRateLimitRemaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/XRateLimitReset"},"X-RateLimit-Bucket":{"$ref":"#/components/headers/XRateLimitBucket"}},"content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/SellerPromotionCalendarEntry"}}}},"example":{"data":[{"sourceType":"event","sourceId":"227a1a5d-66b5-4389-8d0f-128176b13323","skuId":"da92ffcd-54f6-441f-8adf-b525c2a6aaeb","discountPercent":20,"priceEffect":"list_price","startDate":"2026-11-02T09:30:00Z","endDate":"2026-11-02T09:30:00Z","window":"live","vendorCompanyId":"acme-games","name":"Example Game","productId":"aeaa685f-5ae8-4100-8e8d-f6e372e542ee"}]}}}},"400":{"$ref":"#/components/responses/SellerApiUnsupportedApiVersion"},"401":{"$ref":"#/components/responses/SellerApiUnauthorized"},"403":{"$ref":"#/components/responses/SellerApiForbidden"},"422":{"$ref":"#/components/responses/SellerApiValidationFailed"},"429":{"$ref":"#/components/responses/SellerApiRateLimited"},"500":{"$ref":"#/components/responses/SellerApiInternalError"},"503":{"$ref":"#/components/responses/SellerApiServiceUnavailable"},"504":{"$ref":"#/components/responses/SellerApiTimeout"}},"security":[{"bearerAuth":[]}],"x-avrix-scopes":["seller:promotions:read"],"x-avrix-tier":"promotions","x-avrix-rate-limit-class":"finance","x-avrix-scope-mode":"anyOf","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.\n\nThe optional body `{\"pricing\": \"territory\"}` builds the export with every country price per shared SKU (`sharedSkus[].territoryPrices[]`), the payload of `GET /catalog/snapshot?pricing=territory`. An empty body builds the plain export, as before. On contract date `2026-12-01` and later a body that is not a JSON object, an unknown field or another `pricing` value answers `422 VALIDATION_FAILED`; earlier dates ignore a body they cannot use.","operationId":"createCatalogExport","tags":["Catalog"],"security":[{"bearerAuth":[]}],"x-avrix-scopes":["seller:products:read"],"x-avrix-tier":"catalog","x-avrix-rate-limit-class":"catalog","x-avrix-scope-mode":"anyOf","parameters":[{"$ref":"#/components/parameters/AvrixApiVersion"},{"$ref":"#/components/parameters/RequestId"},{"$ref":"#/components/parameters/SandboxSimulateWrite"}],"responses":{"202":{"description":"Export accepted","headers":{"X-Request-Id":{"$ref":"#/components/headers/XRequestId"},"X-Avrix-Api-Version":{"$ref":"#/components/headers/XAvrixApiVersion"},"X-Api-Version":{"$ref":"#/components/headers/XApiVersion"},"X-RateLimit-Limit":{"$ref":"#/components/headers/XRateLimitLimit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/XRateLimitRemaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/XRateLimitReset"},"X-RateLimit-Bucket":{"$ref":"#/components/headers/XRateLimitBucket"}},"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"],"description":"The export's real state: a request matching an export already built or running returns that export; a failed one is requeued (`pending`)."}}}}},"example":{"data":{"exportId":"ff866d13-7ed1-4307-8659-ab3823affe2f","status":"pending"}}}}},"400":{"$ref":"#/components/responses/SellerApiUnsupportedApiVersion"},"401":{"$ref":"#/components/responses/SellerApiUnauthorized"},"403":{"$ref":"#/components/responses/SellerApiForbidden"},"422":{"$ref":"#/components/responses/SellerApiValidationFailed"},"429":{"$ref":"#/components/responses/SellerApiRateLimited"},"500":{"$ref":"#/components/responses/SellerApiInternalError"},"503":{"$ref":"#/components/responses/SellerApiServiceUnavailable"},"504":{"$ref":"#/components/responses/SellerApiTimeout"}},"requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"properties":{"pricing":{"type":["string","null"],"enum":["territory",null],"description":"`territory`: include every country price per shared SKU. Omitted: the plain export."}}},"example":{"pricing":"territory"}}}}}},"/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"],"security":[{"bearerAuth":[]}],"x-avrix-scopes":["seller:products:read"],"x-avrix-tier":"catalog","x-avrix-rate-limit-class":"catalog","x-avrix-scope-mode":"anyOf","parameters":[{"name":"exportId","in":"path","required":true,"description":"Export id (`exportId` from `POST /catalog/exports`).","schema":{"type":"string","format":"uuid"}},{"$ref":"#/components/parameters/AvrixApiVersion"},{"$ref":"#/components/parameters/RequestId"},{"$ref":"#/components/parameters/SandboxSimulateRateLimit"}],"responses":{"200":{"description":"Export status","headers":{"X-Request-Id":{"$ref":"#/components/headers/XRequestId"},"X-Avrix-Api-Version":{"$ref":"#/components/headers/XAvrixApiVersion"},"X-Api-Version":{"$ref":"#/components/headers/XApiVersion"},"X-RateLimit-Limit":{"$ref":"#/components/headers/XRateLimitLimit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/XRateLimitRemaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/XRateLimitReset"},"X-RateLimit-Bucket":{"$ref":"#/components/headers/XRateLimitBucket"}},"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"},"attempts":{"type":"integer","description":"Build attempts so far. A failed build is retried with backoff before `status` becomes `failed`."},"error":{"type":"object","description":"Present only when `status` is `failed`.","required":["code","message","retryable"],"properties":{"code":{"type":"string","enum":["EXPORT_FAILED"]},"message":{"type":"string"},"retryable":{"type":"boolean","description":"true: POST /catalog/exports again with the same filters requeues this export."}}},"pricing":{"type":["string","null"],"enum":["territory",null],"description":"`territory` when the export carries every country price per shared SKU; `null` for the plain export. Additive."}}}}},"example":{"data":{"exportId":"a9a3fe03-9899-4a48-8f97-ddad55764aa5","status":"pending","checksum":"sha256:9f86d081884c7d659a2feaa0c55ad015a3bf4f1b2b0b822cd15d6c15b0f00a08","bytes":1,"expiresAt":"2026-11-02T09:30:00Z","downloadUrl":"https://api.avrix.io/api/seller/v1/example","totalProducts":2450,"attempts":1,"pricing":"territory"}}}}},"400":{"$ref":"#/components/responses/SellerApiUnsupportedApiVersion"},"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"}}}},"422":{"$ref":"#/components/responses/SellerApiValidationFailed"},"429":{"$ref":"#/components/responses/SellerApiRateLimited"},"500":{"$ref":"#/components/responses/SellerApiInternalError"},"503":{"$ref":"#/components/responses/SellerApiServiceUnavailable"},"504":{"$ref":"#/components/responses/SellerApiTimeout"}}}},"/api/seller/v1/me/footprint":{"get":{"tags":["Seller meta"],"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.\n\nAny Seller API key can read the footprint; changing it (`PUT /me/footprint`) requires `seller:account:manage`.","operationId":"getMeFootprint","security":[{"bearerAuth":[]}],"parameters":[{"$ref":"#/components/parameters/AvrixApiVersion"},{"$ref":"#/components/parameters/RequestId"},{"$ref":"#/components/parameters/SandboxSimulateRateLimit"}],"responses":{"200":{"description":"Your declared footprint.","headers":{"X-Request-Id":{"$ref":"#/components/headers/XRequestId"},"X-Avrix-Api-Version":{"$ref":"#/components/headers/XAvrixApiVersion"},"X-Api-Version":{"$ref":"#/components/headers/XApiVersion"},"X-RateLimit-Limit":{"$ref":"#/components/headers/XRateLimitLimit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/XRateLimitRemaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/XRateLimitReset"},"X-RateLimit-Bucket":{"$ref":"#/components/headers/XRateLimitBucket"}},"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."}}}}},"example":{"data":{"countries":["NL"],"currencies":["EUR"]}}}}},"400":{"$ref":"#/components/responses/SellerApiUnsupportedApiVersion"},"401":{"$ref":"#/components/responses/SellerApiUnauthorized"},"403":{"$ref":"#/components/responses/SellerApiForbidden"},"422":{"$ref":"#/components/responses/SellerApiValidationFailed"},"429":{"$ref":"#/components/responses/SellerApiRateLimited"},"500":{"$ref":"#/components/responses/SellerApiInternalError"},"503":{"$ref":"#/components/responses/SellerApiServiceUnavailable"},"504":{"$ref":"#/components/responses/SellerApiTimeout"}},"x-avrix-scopes":[],"x-avrix-tier":"meta","x-avrix-rate-limit-class":"general","x-avrix-scope-mode":"any"},"put":{"tags":["Seller meta"],"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.\n\n**The answer:** on contract date `2026-12-01` and later, the footprint as stored: each code once, uppercase, sorted, the same body `GET /me/footprint` returns; and a code that names no country (`ZZ`) or no current ISO 4217 currency (`XXQ`) is refused with `422 VALIDATION_FAILED`, `details.issues[].field` naming its position (`countries.1`). Earlier dates echo the request uppercased, duplicates included, and store any code of the right length.\n\n**Shared sandbox (contract date `2026-12-01` and later):** a sandbox key on the shared sandbox gets **422** `SANDBOX_ISOLATED_ENVIRONMENT_REQUIRED` and nothing changes, because every store there shares the same footprint. Earlier contract dates still run the write. Production keys and isolated sandbox environments are not affected.","operationId":"putMeFootprint","security":[{"bearerAuth":[]}],"parameters":[{"$ref":"#/components/parameters/AvrixApiVersion"},{"$ref":"#/components/parameters/RequestId"},{"$ref":"#/components/parameters/SandboxSimulateWrite"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["countries","currencies"],"properties":{"countries":{"type":"array","items":{"type":"string","pattern":"^[A-Za-z]{2}$","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,"maxItems":300},"currencies":{"type":"array","items":{"type":"string","pattern":"^[A-Za-z]{3}$","example":"EUR"},"description":"ISO 4217 currencies you sell in. At least one, for the same reason.","minItems":1,"maxItems":200}}}}}},"responses":{"200":{"description":"The footprint as stored.","headers":{"X-Request-Id":{"$ref":"#/components/headers/XRequestId"},"X-Avrix-Api-Version":{"$ref":"#/components/headers/XAvrixApiVersion"},"X-Api-Version":{"$ref":"#/components/headers/XApiVersion"},"X-RateLimit-Limit":{"$ref":"#/components/headers/XRateLimitLimit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/XRateLimitRemaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/XRateLimitReset"},"X-RateLimit-Bucket":{"$ref":"#/components/headers/XRateLimitBucket"}},"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."}}}}},"example":{"data":{"countries":["NL"],"currencies":["EUR"]}}}}},"400":{"$ref":"#/components/responses/SellerApiUnsupportedApiVersion"},"401":{"$ref":"#/components/responses/SellerApiUnauthorized"},"403":{"$ref":"#/components/responses/SellerApiForbidden"},"422":{"description":"Invalid body (`VALIDATION_FAILED`), or `SANDBOX_ISOLATED_ENVIRONMENT_REQUIRED` for a shared-sandbox key on contract date `2026-12-01` or later","headers":{"X-Request-Id":{"$ref":"#/components/headers/XRequestId"},"X-Avrix-Api-Version":{"$ref":"#/components/headers/XAvrixApiVersion"},"X-Api-Version":{"$ref":"#/components/headers/XApiVersion"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"429":{"$ref":"#/components/responses/SellerApiRateLimited"},"500":{"$ref":"#/components/responses/SellerApiInternalError"},"503":{"$ref":"#/components/responses/SellerApiServiceUnavailable"},"504":{"$ref":"#/components/responses/SellerApiTimeout"}},"x-avrix-scopes":["seller:account:manage"],"x-avrix-tier":"meta","x-avrix-rate-limit-class":"general","x-avrix-scope-mode":"anyOf"}},"/api/seller/v1/me/integration-presets":{"get":{"tags":["Seller meta"],"summary":"Read your integration presets","description":"Store-level defaults for integrationOrderContext With presets set, a production POST /orders (or bulk line) needs only skuId or skuCode, quantity, orderReference, integrationOrderContext.consumerIp and priceCommitmentToken. The server fills salesChannel, paymentMethodFamily and priceIncludesTax from the presets, uses orderReference as checkoutSessionId, takes the sale country from the buyer IP (else the price commitment, else storeCountryCode), and derives currency, gross, net, tax amount and tax rate. Explicit fields always win. Each filled field is recorded as preset or derived (declarationProvenance) on the delivery and sale records, and paymentProcessorReference becomes recommended rather than required. whoami.requiredDeclarationsByOperation lists only what is still needed. Presets belong to the store that owns the API key. Any Seller API key can read them; changing them requires seller:account:manage.","operationId":"getMeIntegrationPresets","parameters":[{"$ref":"#/components/parameters/AvrixApiVersion"},{"$ref":"#/components/parameters/RequestId"},{"$ref":"#/components/parameters/SandboxSimulateRateLimit"}],"responses":{"200":{"description":"Your presets (configured false when none are set).","headers":{"X-Request-Id":{"$ref":"#/components/headers/XRequestId"},"X-Avrix-Api-Version":{"$ref":"#/components/headers/XAvrixApiVersion"},"X-Api-Version":{"$ref":"#/components/headers/XApiVersion"},"X-RateLimit-Limit":{"$ref":"#/components/headers/XRateLimitLimit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/XRateLimitRemaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/XRateLimitReset"},"X-RateLimit-Bucket":{"$ref":"#/components/headers/XRateLimitBucket"}},"content":{"application/json":{"schema":{"type":"object","required":["data"],"properties":{"data":{"$ref":"#/components/schemas/SellerIntegrationPresets"}}},"example":{"data":{"configured":true,"salesChannel":"web","paymentMethodFamily":"card","priceIncludesTax":true,"storeCountryCode":"NL","deriveAmounts":true,"updatedAt":"2026-11-02T09:30:00Z"}}}}},"400":{"$ref":"#/components/responses/SellerApiUnsupportedApiVersion"},"401":{"$ref":"#/components/responses/SellerApiUnauthorized"},"403":{"$ref":"#/components/responses/SellerApiForbidden"},"422":{"$ref":"#/components/responses/SellerApiValidationFailed"},"429":{"$ref":"#/components/responses/SellerApiRateLimited"},"500":{"$ref":"#/components/responses/SellerApiInternalError"},"503":{"$ref":"#/components/responses/SellerApiServiceUnavailable"},"504":{"$ref":"#/components/responses/SellerApiTimeout"}},"security":[{"bearerAuth":[]}],"x-avrix-scopes":[],"x-avrix-tier":"meta","x-avrix-rate-limit-class":"general","x-avrix-scope-mode":"any"},"put":{"tags":["Seller meta"],"summary":"Replace your integration presets","description":"Store-level defaults for integrationOrderContext With presets set, a production POST /orders (or bulk line) needs only skuId or skuCode, quantity, orderReference, integrationOrderContext.consumerIp and priceCommitmentToken. The server fills salesChannel, paymentMethodFamily and priceIncludesTax from the presets, uses orderReference as checkoutSessionId, takes the sale country from the buyer IP (else the price commitment, else storeCountryCode), and derives currency, gross, net, tax amount and tax rate. Explicit fields always win. Each filled field is recorded as preset or derived (declarationProvenance) on the delivery and sale records, and paymentProcessorReference becomes recommended rather than required. whoami.requiredDeclarationsByOperation lists only what is still needed. Presets belong to the store that owns the API key. Requires seller:account:manage. A replace: send every field (null = no preset for it).","operationId":"putMeIntegrationPresets","parameters":[{"$ref":"#/components/parameters/AvrixApiVersion"},{"$ref":"#/components/parameters/RequestId"},{"$ref":"#/components/parameters/SandboxSimulateWrite"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/SellerIntegrationPresetsInput"}}}},"responses":{"200":{"description":"The saved presets.","headers":{"X-Request-Id":{"$ref":"#/components/headers/XRequestId"},"X-Avrix-Api-Version":{"$ref":"#/components/headers/XAvrixApiVersion"},"X-Api-Version":{"$ref":"#/components/headers/XApiVersion"},"X-RateLimit-Limit":{"$ref":"#/components/headers/XRateLimitLimit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/XRateLimitRemaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/XRateLimitReset"},"X-RateLimit-Bucket":{"$ref":"#/components/headers/XRateLimitBucket"}},"content":{"application/json":{"schema":{"type":"object","required":["data"],"properties":{"data":{"$ref":"#/components/schemas/SellerIntegrationPresets"}}},"example":{"data":{"configured":true,"salesChannel":"web","paymentMethodFamily":"card","priceIncludesTax":true,"storeCountryCode":"NL","deriveAmounts":true,"updatedAt":"2026-11-02T09:30:00Z"}}}}},"400":{"$ref":"#/components/responses/SellerApiUnsupportedApiVersion"},"401":{"$ref":"#/components/responses/SellerApiUnauthorized"},"403":{"$ref":"#/components/responses/SellerApiForbidden"},"422":{"$ref":"#/components/responses/SellerApiValidationFailed"},"429":{"$ref":"#/components/responses/SellerApiRateLimited"},"500":{"$ref":"#/components/responses/SellerApiInternalError"},"503":{"$ref":"#/components/responses/SellerApiServiceUnavailable"},"504":{"$ref":"#/components/responses/SellerApiTimeout"}},"security":[{"bearerAuth":[]}],"x-avrix-scopes":["seller:account:manage"],"x-avrix-tier":"meta","x-avrix-rate-limit-class":"general","x-avrix-scope-mode":"anyOf"},"delete":{"tags":["Seller meta"],"summary":"Remove your integration presets","description":"Removes the presets: orders need the full declaration again.","operationId":"deleteMeIntegrationPresets","parameters":[{"$ref":"#/components/parameters/AvrixApiVersion"},{"$ref":"#/components/parameters/RequestId"},{"$ref":"#/components/parameters/SandboxSimulateWrite"}],"responses":{"200":{"description":"Presets removed (configured false).","headers":{"X-Request-Id":{"$ref":"#/components/headers/XRequestId"},"X-Avrix-Api-Version":{"$ref":"#/components/headers/XAvrixApiVersion"},"X-Api-Version":{"$ref":"#/components/headers/XApiVersion"},"X-RateLimit-Limit":{"$ref":"#/components/headers/XRateLimitLimit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/XRateLimitRemaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/XRateLimitReset"},"X-RateLimit-Bucket":{"$ref":"#/components/headers/XRateLimitBucket"}},"content":{"application/json":{"schema":{"type":"object","required":["data"],"properties":{"data":{"$ref":"#/components/schemas/SellerIntegrationPresets"}}},"example":{"data":{"configured":true,"salesChannel":"web","paymentMethodFamily":"card","priceIncludesTax":true,"storeCountryCode":"NL","deriveAmounts":true,"updatedAt":"2026-11-02T09:30:00Z"}}}}},"400":{"$ref":"#/components/responses/SellerApiUnsupportedApiVersion"},"401":{"$ref":"#/components/responses/SellerApiUnauthorized"},"403":{"$ref":"#/components/responses/SellerApiForbidden"},"429":{"$ref":"#/components/responses/SellerApiRateLimited"},"500":{"$ref":"#/components/responses/SellerApiInternalError"},"503":{"$ref":"#/components/responses/SellerApiServiceUnavailable"},"504":{"$ref":"#/components/responses/SellerApiTimeout"}},"security":[{"bearerAuth":[]}],"x-avrix-scopes":["seller:account:manage"],"x-avrix-tier":"meta","x-avrix-rate-limit-class":"general","x-avrix-scope-mode":"anyOf"}},"/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":[{"bearerAuth":[]}],"parameters":[{"name":"transactionId","in":"path","required":true,"description":"API sale transaction id (`id` from `GET /finance/api-sales`).","schema":{"type":"string","format":"uuid"}},{"$ref":"#/components/parameters/AvrixApiVersion"},{"$ref":"#/components/parameters/RequestId"},{"$ref":"#/components/parameters/SandboxSimulateRateLimit"}],"responses":{"200":{"description":"The transaction as recorded.","headers":{"X-Request-Id":{"$ref":"#/components/headers/XRequestId"},"X-Avrix-Api-Version":{"$ref":"#/components/headers/XAvrixApiVersion"},"X-Api-Version":{"$ref":"#/components/headers/XApiVersion"},"X-RateLimit-Limit":{"$ref":"#/components/headers/XRateLimitLimit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/XRateLimitRemaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/XRateLimitReset"},"X-RateLimit-Bucket":{"$ref":"#/components/headers/XRateLimitBucket"}},"content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/SellerApiSaleTransaction"}}},"example":{"data":{"id":"dccbd8ff-f8fd-4028-819c-7f8312149a95","publisherCompanyId":"acme-games","keyPullId":"e66ef578-0a56-4388-8525-f9e2bcbaa25b","keyId":"817cb628-855b-49e4-8370-1b14e3a2f74e","skuId":"9c944f34-dcd1-4324-831e-22a645789f57","productId":"bf59624f-29fd-4778-8ba0-770d60cc587c","salePriceCents":2450,"initialSalePriceCents":2450,"promo":{"sourceType":"event","sourceId":"dac88cf9-d3ea-4992-866b-c1b3ce46d678"},"currencyCode":"EUR","currencyExponent":2,"publisherShareCents":2450,"sellerShareCents":2450,"platformFeeCents":2450,"revenueSharePercent":20,"saleTimestamp":"2026-11-02T09:30:00Z","aggregationStatus":"pending","reportId":"75ecb281-7b35-4533-8792-03f966e2e2a8","orderReference":"store-order-10432","customerRegionCode":"DE","detectedCountryCode":"off","countryMismatch":true,"warnings":["COUNTRY_MISMATCH"],"contractTermId":"653e65d5-22ed-48dd-866c-6169d8e12b2f","contractTermVersion":1,"adjustmentStatus":"none","declaredRetail":{"retailCurrencyCode":"EUR","currencyExponent":2,"grossMinor":2450,"netMinor":2450,"taxAmountMinor":2450,"taxRatePercent":20,"priceIncludesTax":true,"paymentMethodFamily":"card","paymentProcessorReference":"pi_10432","checkoutSessionId":"cs_10432","purchaseOrderNumber":"PO-10432"},"integrationOrderContext":{"schemaVersion":1,"consumerIp":"203.0.113.10","salesCountryCode":"CO","currencyCode":"EUR","currencyExponent":2,"salesPriceGrossMinor":2450,"salesPriceNetMinor":2450,"appliedDiscountPercentage":20,"appliedDiscountAmountMinor":2450,"immediateFulfilment":true,"mustFulfil":true,"buyerLocale":"de-DE","priceIncludesTax":true,"salesTaxAmountMinor":2450,"salesTaxRatePercent":20,"customerVatNumber":"DE123456789","purchaseOrderNumber":"PO-10432","customerType":"b2c","paymentMethodFamily":"card","paymentProcessorReference":"pi_10432","checkoutSessionId":"cs_10432","salesChannel":"web","lineIndex":1,"parentOrderReference":"store-order-10432","externalNetworkOrderId":"142f2c61-b8b3-4afe-8542-28efa0740378","consumerIpHash":"3f9a1c7e2b4d6a80","consumerIpRedacted":true},"taxMetadata":{"declaredTaxAmountMinor":2450,"declaredTaxRatePercent":20,"priceIncludesTax":true,"authoritative":false},"settlement":{"basis":"purchaser_country_capped","vatMinor":2450,"netMinor":2450,"appliedRatePercent":20,"declaredRatePercent":20,"evidenceRank":1,"requestedCountry":"DE"},"entryType":"sale","reversesTransactionId":"007d1078-f310-4096-8168-5c97487ad70f"}}}}},"400":{"$ref":"#/components/responses/SellerApiUnsupportedApiVersion"},"401":{"$ref":"#/components/responses/SellerApiUnauthorized"},"403":{"$ref":"#/components/responses/SellerApiForbidden"},"404":{"description":"`NOT_FOUND`: no API sale with this id belongs to your company.","headers":{"X-Request-Id":{"$ref":"#/components/headers/XRequestId"},"X-Avrix-Api-Version":{"$ref":"#/components/headers/XAvrixApiVersion"},"X-Api-Version":{"$ref":"#/components/headers/XApiVersion"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"422":{"$ref":"#/components/responses/SellerApiValidationFailed"},"429":{"$ref":"#/components/responses/SellerApiRateLimited"},"500":{"$ref":"#/components/responses/SellerApiInternalError"},"503":{"$ref":"#/components/responses/SellerApiServiceUnavailable"},"504":{"$ref":"#/components/responses/SellerApiTimeout"}},"x-avrix-scopes":["seller:finance:read"],"x-avrix-tier":"finance","x-avrix-rate-limit-class":"finance","x-avrix-scope-mode":"anyOf"}},"/api/seller/v1/finance/invoices/{invoiceId}/reconciliation":{"get":{"tags":["Finance"],"summary":"Download a payout's reconciliation file","description":"The reconciliation file for one payout: the vendor invoice you paid, every balance movement it settles and, under each movement, every API sale it covers (order reference, key id, gross, VAT, net and the publisher, seller and platform shares).\n\nMovement amounts are in minor units of the payment currency and add up to `totalCents`; sale amounts are in the sale currency as recorded on the sale, with `lineExchangeRate` the rate its report line converted at. The file is final once `paymentState` is `paid`; the `payout.file_ready` webhook fires then.\n\n`format=csv` returns one row per sale (a movement without sales gets one row of its own). `movementAmountCents` is written on the first row of each movement only, so summing the column gives the payout total.\n\nThe CSV's last two columns, `paymentCurrencyExponent` and `saleCurrencyExponent`, give the minor-unit digits of the payment and sale amounts (columns are only ever appended).\n\nAn invoice id that is not one of your payouts returns 404 rather than 403. On contract date `2026-12-01` and later, an invoice that is yours but has no settlement (an invoice of the earlier billing model, or one still waiting for the commission document) answers `409 CONFLICT` with `details.reason: RECONCILIATION_NOT_AVAILABLE` instead; `reconciliationAvailable` on the invoice tells you in advance. Earlier dates answer 404 for both.","operationId":"getFinanceInvoiceReconciliation","security":[{"bearerAuth":[]}],"parameters":[{"name":"invoiceId","in":"path","required":true,"description":"Vendor invoice id, as returned by `GET /finance/invoices`.","schema":{"type":"string","format":"uuid"}},{"name":"format","in":"query","required":false,"description":"`json` (default) or `csv`.","schema":{"type":"string","enum":["json","csv"],"default":"json"}},{"$ref":"#/components/parameters/AvrixApiVersion"},{"$ref":"#/components/parameters/RequestId"},{"$ref":"#/components/parameters/SandboxSimulateRateLimit"}],"responses":{"200":{"description":"The payout's reconciliation file.","headers":{"X-Request-Id":{"$ref":"#/components/headers/XRequestId"},"X-Avrix-Api-Version":{"$ref":"#/components/headers/XAvrixApiVersion"},"X-Api-Version":{"$ref":"#/components/headers/XApiVersion"},"X-RateLimit-Limit":{"$ref":"#/components/headers/XRateLimitLimit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/XRateLimitRemaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/XRateLimitReset"},"X-RateLimit-Bucket":{"$ref":"#/components/headers/XRateLimitBucket"}},"content":{"application/json":{"schema":{"type":"object","required":["data"],"properties":{"data":{"$ref":"#/components/schemas/SellerPayoutReconciliation"}}},"example":{"data":{"invoiceId":"d9c14540-3062-4c40-811a-fa9ae9083921","invoiceNumber":"INV-2026-10-0042","settlementPackageId":"4cf0a96b-d91c-488d-8f79-78ee3f242dca","sellerCompanyId":"c61c807f-fcc4-4c77-849c-ec922d65634c","publisherCompanyId":"acme-games","paymentCurrency":"EUR","paymentCurrencyExponent":2,"paymentState":"paid","paymentMethod":"wire_transfer","paymentReference":"NL-SEPA-2026-11-0042","settledAt":"2026-11-20T10:00:00Z","totalCents":1960,"totalMinor":1960,"saleCount":3,"movements":[{"movementId":"5a7c9e1b-3d5f-4a7b-9c1d-3e5f7a9b1c3d","movementType":"report_accrual","sourceType":"sales_report","amountCents":3920,"amountMinor":3920,"reportId":"7b9d1f3a-5c7e-4b9d-8f1a-3c5e7a9b1d3f","reportMonth":"2026-10","sales":[{"transactionId":"6f1c2a9e-3b7d-4e21-9c84-0a5d2e7b1f30","entryType":"sale","orderReference":"store-order-10432","keyId":"0e8f6a1b-2c3d-4e5f-8a9b-1c2d3e4f5a6b","skuId":"58891c3c-0f7b-490c-830f-cc3ab1b3d391","saleTimestamp":"2026-10-04T14:12:09Z","currencyCode":"EUR","currencyExponent":2,"grossMinor":2450,"vatMinor":0,"netMinor":2450,"publisherShareMinor":1960,"sellerShareMinor":245,"platformFeeMinor":245,"lineExchangeRate":1,"adjustmentStatus":"refunded"},{"transactionId":"8d2e4b6a-1c3f-4a57-b0e9-5f7a3c9d2e14","entryType":"sale","orderReference":"store-order-10432","keyId":"1f9a7b2c-3d4e-4f5a-9b0c-2d3e4f5a6b7c","skuId":"58891c3c-0f7b-490c-830f-cc3ab1b3d391","saleTimestamp":"2026-10-09T08:41:55Z","currencyCode":"EUR","currencyExponent":2,"grossMinor":2450,"vatMinor":0,"netMinor":2450,"publisherShareMinor":1960,"sellerShareMinor":245,"platformFeeMinor":245,"lineExchangeRate":1,"adjustmentStatus":"none"}]},{"movementId":"6b8d0f2c-4e6a-4b8c-8d0e-4f6a8b0c2d4e","movementType":"adjustment","sourceType":"api_sale_refund","amountCents":-1960,"amountMinor":-1960,"reportId":null,"reportMonth":null,"sales":[{"transactionId":"2b9f7c1d-6e4a-4f83-a2c5-9d1e8b3f7a60","entryType":"sale_reversal","orderReference":"store-order-10432","keyId":"0e8f6a1b-2c3d-4e5f-8a9b-1c2d3e4f5a6b","skuId":"58891c3c-0f7b-490c-830f-cc3ab1b3d391","saleTimestamp":"2026-10-06T10:03:27Z","currencyCode":"EUR","currencyExponent":2,"grossMinor":-2450,"vatMinor":0,"netMinor":-2450,"publisherShareMinor":-1960,"sellerShareMinor":-245,"platformFeeMinor":-245,"lineExchangeRate":1,"adjustmentStatus":"refunded"}]}]}}},"text/csv":{"schema":{"type":"string","description":"One row per sale; columns as named in the header row."}}}},"400":{"$ref":"#/components/responses/SellerApiUnsupportedApiVersion"},"401":{"$ref":"#/components/responses/SellerApiUnauthorized"},"403":{"$ref":"#/components/responses/SellerApiForbidden"},"404":{"description":"`NOT_FOUND`: no payout reconciliation exists for this invoice id in your company.","headers":{"X-Request-Id":{"$ref":"#/components/headers/XRequestId"},"X-Avrix-Api-Version":{"$ref":"#/components/headers/XAvrixApiVersion"},"X-Api-Version":{"$ref":"#/components/headers/XApiVersion"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"409":{"description":"`CONFLICT` with `details.reason: RECONCILIATION_NOT_AVAILABLE` (contract date `2026-12-01` and later): the invoice is yours but has no reconciliation file. `details.invoicePath` points at the invoice.","headers":{"X-Request-Id":{"$ref":"#/components/headers/XRequestId"},"X-Avrix-Api-Version":{"$ref":"#/components/headers/XAvrixApiVersion"},"X-Api-Version":{"$ref":"#/components/headers/XApiVersion"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"422":{"$ref":"#/components/responses/SellerApiValidationFailed"},"429":{"$ref":"#/components/responses/SellerApiRateLimited"},"500":{"$ref":"#/components/responses/SellerApiInternalError"},"503":{"$ref":"#/components/responses/SellerApiServiceUnavailable"},"504":{"$ref":"#/components/responses/SellerApiTimeout"}},"x-avrix-scopes":["seller:finance:read"],"x-avrix-tier":"finance","x-avrix-rate-limit-class":"finance","x-avrix-scope-mode":"anyOf"}},"/api/seller/v1/finance/invoices/{invoiceId}":{"get":{"tags":["Finance"],"summary":"Get an invoice you owe","description":"One invoice with what it bills (`lines`, one per balance movement), the settlement that pays it (`payment`), payments recorded against an invoice of the earlier billing model (`paymentRecords`), your disputes, the document to download, and its history. The id is the one every `invoice.*` event carries.\n\nAn invoice that is not yours, or not yet issued, answers 404.","operationId":"getFinanceInvoice","security":[{"bearerAuth":[]}],"parameters":[{"name":"invoiceId","in":"path","required":true,"description":"Invoice id, from `GET /finance/invoices` or an `invoice.*` event.","schema":{"type":"string","format":"uuid"}},{"$ref":"#/components/parameters/AvrixApiVersion"},{"$ref":"#/components/parameters/RequestId"},{"$ref":"#/components/parameters/SandboxSimulateRateLimit"}],"responses":{"200":{"description":"The invoice.","headers":{"X-Request-Id":{"$ref":"#/components/headers/XRequestId"},"X-Avrix-Api-Version":{"$ref":"#/components/headers/XAvrixApiVersion"},"X-Api-Version":{"$ref":"#/components/headers/XApiVersion"},"X-RateLimit-Limit":{"$ref":"#/components/headers/XRateLimitLimit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/XRateLimitRemaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/XRateLimitReset"},"X-RateLimit-Bucket":{"$ref":"#/components/headers/XRateLimitBucket"}},"content":{"application/json":{"schema":{"type":"object","required":["data"],"properties":{"data":{"$ref":"#/components/schemas/SellerFinanceInvoiceDetail"}}},"example":{"data":{"id":"f0674f47-5753-40ea-8f6b-8eada648f27a","invoiceNumber":"INV-2026-10-0042","status":"awaiting_commission_document","invoiceType":"final","totalCents":2450,"totalMinor":2450,"currencyCode":"EUR","currencyExponent":2,"issuedAt":"2026-11-02T09:30:00Z","dueAt":"2026-11-02T09:30:00Z","salesReportId":"d5485d46-3454-4757-838b-e6fc09d6fab4","paidAt":"2026-11-02T09:30:00Z","kind":"vendor_payable","publisherCompanyId":"acme-games","supplierInvoiceNumber":"example_supplierinvoicenumber","reportMonth":"2026-10","subtotalCents":2450,"subtotalMinor":2450,"taxCents":2450,"taxMinor":2450,"paidCents":2450,"paidMinor":2450,"outstandingCents":2450,"outstandingMinor":2450,"paymentTermsDays":1,"paymentState":"unpaid","replacesInvoiceId":"84fee5cc-4fb5-40ed-8502-3c88b84a8c05","supersededByInvoiceId":"0979ad81-9eae-4fec-855b-7cdd276d5b1e","updatedAt":"2026-11-02T09:30:00Z","reconciliationAvailable":true,"reconciliationPath":"example_reconciliationpath","detailPath":"example_detailpath","lines":[{"allocationId":"75440ab8-54f1-4dd4-8d12-1d411835e81f","movementId":"14621c88-8345-4383-8d99-00611e4191fb","movementType":"report_accrual","sourceType":"sales_report","reportId":"fa852f64-0efd-46f5-834a-ee95375adae5","reportMonth":"2026-10","contractTermId":"73602396-3ca3-4058-8a3f-56662dc34dcc","amountCents":2450,"amountMinor":2450,"currencyCode":"EUR","currencyExponent":2}],"payment":{"paymentState":"unpaid","paymentMethod":"wire_transfer","paymentReference":"example_paymentreference","amountCents":2450,"amountMinor":2450,"currencyCode":"EUR","currencyExponent":2,"dueAt":"2026-11-02T09:30:00Z","settledAt":"2026-11-02T09:30:00Z"},"paymentRecords":[{"paymentRecordId":"d015c72a-71af-436b-8590-7996b41e0151","paymentType":"wire_transfer","status":"pending","amountCents":2450,"amountMinor":2450,"currencyCode":"EUR","currencyExponent":2,"bankReference":"example_bankreference","paymentDate":"2026-11-02T09:30:00Z","confirmedAt":"2026-11-02T09:30:00Z","createdAt":"2026-11-02T09:30:00Z"}],"disputes":[{"disputeId":"588c65a8-ed47-4075-8546-6f656fbb884e","status":"open","reasonCode":"amount_mismatch","explanation":"example_explanation","vendorResponse":"example_vendorresponse","raisedAt":"2026-11-02T09:30:00Z","respondedAt":"2026-11-02T09:30:00Z","resolvedAt":"2026-11-02T09:30:00Z","replacementInvoiceId":"2557b374-c889-4b5c-82b4-9cc62c974940"}],"documents":[{"documentId":"7c3c682a-1b99-48c8-892d-0b997e5fed09","fileName":"Example name","byteSize":1,"contentHash":"example_contenthash","origin":"example_origin","frozenAt":"2026-11-02T09:30:00Z","createdAt":"2026-11-02T09:30:00Z","downloadPath":"example_downloadpath"}],"history":[{"eventType":"issued","occurredAt":"2026-11-02T09:30:00Z"}]}}}}},"400":{"$ref":"#/components/responses/SellerApiUnsupportedApiVersion"},"401":{"$ref":"#/components/responses/SellerApiUnauthorized"},"403":{"$ref":"#/components/responses/SellerApiForbidden"},"404":{"description":"`NOT_FOUND`: no issued invoice with this id is addressed to your company.","headers":{"X-Request-Id":{"$ref":"#/components/headers/XRequestId"},"X-Avrix-Api-Version":{"$ref":"#/components/headers/XAvrixApiVersion"},"X-Api-Version":{"$ref":"#/components/headers/XApiVersion"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"422":{"$ref":"#/components/responses/SellerApiValidationFailed"},"429":{"$ref":"#/components/responses/SellerApiRateLimited"},"500":{"$ref":"#/components/responses/SellerApiInternalError"},"503":{"$ref":"#/components/responses/SellerApiServiceUnavailable"},"504":{"$ref":"#/components/responses/SellerApiTimeout"}},"x-avrix-scopes":["seller:finance:read"],"x-avrix-tier":"finance","x-avrix-rate-limit-class":"finance","x-avrix-scope-mode":"anyOf"}},"/api/seller/v1/finance/invoices/{invoiceId}/document":{"get":{"tags":["Finance"],"summary":"Get a download link for an invoice document","description":"A signed link to the invoice document the vendor issued to you, the same file the console offers. The link works without your API key for five minutes (`expiresAt`); ask again for a fresh one. Check the file against `contentHash`.\n\n404 when the invoice is not yours, and also when it has no document you can download (invoices of the earlier billing model); then `details.reason` is `no_document`.","operationId":"getFinanceInvoiceDocument","security":[{"bearerAuth":[]}],"parameters":[{"name":"invoiceId","in":"path","required":true,"description":"Invoice id.","schema":{"type":"string","format":"uuid"}},{"$ref":"#/components/parameters/AvrixApiVersion"},{"$ref":"#/components/parameters/RequestId"},{"$ref":"#/components/parameters/SandboxSimulateRateLimit"}],"responses":{"200":{"description":"A short-lived download link.","headers":{"X-Request-Id":{"$ref":"#/components/headers/XRequestId"},"X-Avrix-Api-Version":{"$ref":"#/components/headers/XAvrixApiVersion"},"X-Api-Version":{"$ref":"#/components/headers/XApiVersion"},"X-RateLimit-Limit":{"$ref":"#/components/headers/XRateLimitLimit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/XRateLimitRemaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/XRateLimitReset"},"X-RateLimit-Bucket":{"$ref":"#/components/headers/XRateLimitBucket"}},"content":{"application/json":{"schema":{"type":"object","required":["data"],"properties":{"data":{"$ref":"#/components/schemas/SellerFinanceInvoiceDocumentLink"}}},"example":{"data":{"invoiceId":"39870f59-424d-464e-891d-a7cc37ab0864","documentId":"08e33a09-eaaa-46fe-8650-386a08faaef7","fileName":"Example name","byteSize":1,"contentHash":"example_contenthash","contentType":"application/pdf","url":"https://api.avrix.io/api/seller/v1/example","expiresAt":"2026-11-02T09:30:00Z"}}}}},"400":{"$ref":"#/components/responses/SellerApiUnsupportedApiVersion"},"401":{"$ref":"#/components/responses/SellerApiUnauthorized"},"403":{"$ref":"#/components/responses/SellerApiForbidden"},"404":{"description":"`NOT_FOUND`: no such invoice, or (`details.reason: no_document`) no document to download.","headers":{"X-Request-Id":{"$ref":"#/components/headers/XRequestId"},"X-Avrix-Api-Version":{"$ref":"#/components/headers/XAvrixApiVersion"},"X-Api-Version":{"$ref":"#/components/headers/XApiVersion"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"422":{"$ref":"#/components/responses/SellerApiValidationFailed"},"429":{"$ref":"#/components/responses/SellerApiRateLimited"},"500":{"$ref":"#/components/responses/SellerApiInternalError"},"503":{"$ref":"#/components/responses/SellerApiServiceUnavailable"},"504":{"$ref":"#/components/responses/SellerApiTimeout"}},"x-avrix-scopes":["seller:finance:read"],"x-avrix-tier":"finance","x-avrix-rate-limit-class":"finance","x-avrix-scope-mode":"anyOf"}},"/api/seller/v1/finance/payments":{"get":{"tags":["Finance"],"summary":"List your invoice payments","description":"Your side of each vendor invoice's settlement, newest first: what you pay, by which method and reference, whether it is paid and when it cleared. One row per invoice that has a settlement (`invoiceId`). The commission the vendor pays Avrix is the vendor's and is not shown.\n\nPaging: the shared list contract (`https://docs.avrix.io/seller-api/pagination`). A `cursor` this API did not return is refused with `422 VALIDATION_FAILED` on every contract date.","operationId":"listFinancePayments","security":[{"bearerAuth":[]}],"parameters":[{"name":"limit","in":"query","description":"Page size (1–100, default 50).","schema":{"type":"integer","default":50,"minimum":1,"maximum":100}},{"name":"cursor","in":"query","description":"Opaque position from `meta.nextCursor`; omit it on the first call. A value this API did not return is refused with `422 VALIDATION_FAILED`.","schema":{"type":"string"}},{"name":"paymentState","in":"query","description":"Only settlements in these states. Comma-separated; any of: `unpaid`, `in_progress`, `paid`, `reversed`. An unknown value is refused with `422 VALIDATION_FAILED`.","schema":{"type":"string","example":"unpaid,in_progress"}},{"name":"invoiceId","in":"query","description":"Only the settlement of this invoice.","schema":{"type":"string","format":"uuid"}},{"name":"publisherCompanyId","in":"query","description":"Only settlements with this vendor.","schema":{"type":"string","maxLength":128}},{"name":"settledFrom","in":"query","description":"Settled at or after this instant.","schema":{"type":"string","format":"date-time"}},{"name":"settledTo","in":"query","description":"Settled before this instant.","schema":{"type":"string","format":"date-time"}},{"$ref":"#/components/parameters/AvrixApiVersion"},{"$ref":"#/components/parameters/RequestId"},{"$ref":"#/components/parameters/SandboxSimulateRateLimit"}],"responses":{"200":{"description":"Settlements and pagination meta.","headers":{"X-Request-Id":{"$ref":"#/components/headers/XRequestId"},"X-Avrix-Api-Version":{"$ref":"#/components/headers/XAvrixApiVersion"},"X-Api-Version":{"$ref":"#/components/headers/XApiVersion"},"X-RateLimit-Limit":{"$ref":"#/components/headers/XRateLimitLimit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/XRateLimitRemaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/XRateLimitReset"},"X-RateLimit-Bucket":{"$ref":"#/components/headers/XRateLimitBucket"}},"content":{"application/json":{"schema":{"type":"object","required":["data","meta"],"properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/SellerFinancePayment"}},"meta":{"$ref":"#/components/schemas/PaginationMeta"}}},"example":{"data":[{"paymentId":"4a682301-0fb0-46ea-8187-b40581e6f645","invoiceId":"cad747be-6f05-4f1d-8448-bc19e264461d","publisherCompanyId":"acme-games","amountCents":2450,"amountMinor":2450,"currencyCode":"EUR","currencyExponent":2,"paymentState":"unpaid","paymentMethod":null,"paymentReference":"example_paymentreference","dueAt":"2026-11-02T09:30:00Z","settledAt":"2026-11-02T09:30:00Z","createdAt":"2026-11-02T09:30:00Z","updatedAt":"2026-11-02T09:30:00Z","invoicePath":"example_invoicepath"}],"meta":{"total":2450,"limit":50,"hasMore":true,"nextCursor":"eyJ2IjoyLCJ0IjoiMjAyNi0xMS0wMlQwOTozMDowMFoifQ","nextUrl":"https://api.avrix.io/api/seller/v1/finance/payments?cursor=eyJ2IjoyLCJ0IjoiMjAyNi0xMS0wMlQwOTozMDowMFoifQ","localePreference":"en"}}}}},"400":{"$ref":"#/components/responses/SellerApiUnsupportedApiVersion"},"401":{"$ref":"#/components/responses/SellerApiUnauthorized"},"403":{"$ref":"#/components/responses/SellerApiForbidden"},"422":{"$ref":"#/components/responses/SellerApiValidationFailed"},"429":{"$ref":"#/components/responses/SellerApiRateLimited"},"500":{"$ref":"#/components/responses/SellerApiInternalError"},"503":{"$ref":"#/components/responses/SellerApiServiceUnavailable"},"504":{"$ref":"#/components/responses/SellerApiTimeout"}},"x-avrix-scopes":["seller:finance:read"],"x-avrix-tier":"finance","x-avrix-rate-limit-class":"finance","x-avrix-scope-mode":"anyOf"}},"/api/seller/v1/finance/reports":{"get":{"tags":["Finance"],"summary":"List your monthly sales reports","description":"Your monthly sales reports, newest first: one per vendor and month, with totals in minor units and where each stands (`confirmation`). The `report.ready` event names a report; read it here. An approved report is what the vendor's monthly invoice bills.\n\nPaging: the shared list contract (`https://docs.avrix.io/seller-api/pagination`). A `cursor` this API did not return is refused with `422 VALIDATION_FAILED` on every contract date.","operationId":"listFinanceReports","security":[{"bearerAuth":[]}],"parameters":[{"name":"limit","in":"query","description":"Page size (1–100, default 50).","schema":{"type":"integer","default":50,"minimum":1,"maximum":100}},{"name":"cursor","in":"query","description":"Opaque position from `meta.nextCursor`; omit it on the first call. A value this API did not return is refused with `422 VALIDATION_FAILED`.","schema":{"type":"string"}},{"name":"status","in":"query","description":"Only reports in these states. Comma-separated; any of: `draft`, `overdue`, `submitted`, `approved`, `disputed`, `rejected`. An unknown value is refused with `422 VALIDATION_FAILED`.","schema":{"type":"string","example":"draft,overdue"}},{"name":"modelType","in":"query","description":"Only reports of these models. Comma-separated; any of: `api`, `revenue_share`. An unknown value is refused with `422 VALIDATION_FAILED`.","schema":{"type":"string","example":"api,revenue_share"}},{"name":"reportMonth","in":"query","description":"Only reports for this month, `YYYY-MM`.","schema":{"type":"string","pattern":"^\\d{4}-(0[1-9]|1[0-2])$"}},{"name":"publisherCompanyId","in":"query","description":"Only reports with this vendor.","schema":{"type":"string","maxLength":128}},{"$ref":"#/components/parameters/AvrixApiVersion"},{"$ref":"#/components/parameters/RequestId"},{"$ref":"#/components/parameters/SandboxSimulateRateLimit"}],"responses":{"200":{"description":"Reports and pagination meta.","headers":{"X-Request-Id":{"$ref":"#/components/headers/XRequestId"},"X-Avrix-Api-Version":{"$ref":"#/components/headers/XAvrixApiVersion"},"X-Api-Version":{"$ref":"#/components/headers/XApiVersion"},"X-RateLimit-Limit":{"$ref":"#/components/headers/XRateLimitLimit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/XRateLimitRemaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/XRateLimitReset"},"X-RateLimit-Bucket":{"$ref":"#/components/headers/XRateLimitBucket"}},"content":{"application/json":{"schema":{"type":"object","required":["data","meta"],"properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/SellerFinanceReport"}},"meta":{"$ref":"#/components/schemas/PaginationMeta"}}},"example":{"data":[{"id":"e265878b-0000-465f-8716-bec11344c28e","reportMonth":"2026-10","status":"draft","modelType":"api","publisherCompanyId":"acme-games","currencyCode":"EUR","currencyExponent":2,"periodStart":"2026-10-01T00:00:00Z","periodEnd":"2026-10-31T23:59:59Z","deadline":"example_deadline","submittedAt":"2026-11-02T09:30:00Z","createdAt":"2026-11-02T09:30:00Z","updatedAt":"2026-11-02T09:30:00Z","revokedAt":"2026-11-02T09:30:00Z","totals":{"grossCents":2450,"grossMinor":2450,"netCents":2450,"netMinor":2450,"reversalsCents":2450,"reversalsMinor":2450,"vatCents":2450,"vatMinor":2450,"sellerShareCents":2450,"sellerShareMinor":2450,"publisherShareCents":2450,"publisherShareMinor":2450},"confirmation":{"state":"awaiting_seller","nextActor":"seller","deadline":"example_deadline","overdue":true,"submittedAt":"2026-11-02T09:30:00Z","confirmIn":"console"},"detailPath":"example_detailpath","linesPath":"example_linespath"}],"meta":{"total":2450,"limit":50,"hasMore":true,"nextCursor":"eyJ2IjoyLCJ0IjoiMjAyNi0xMS0wMlQwOTozMDowMFoifQ","nextUrl":"https://api.avrix.io/api/seller/v1/finance/reports?cursor=eyJ2IjoyLCJ0IjoiMjAyNi0xMS0wMlQwOTozMDowMFoifQ","localePreference":"en"}}}}},"400":{"$ref":"#/components/responses/SellerApiUnsupportedApiVersion"},"401":{"$ref":"#/components/responses/SellerApiUnauthorized"},"403":{"$ref":"#/components/responses/SellerApiForbidden"},"422":{"$ref":"#/components/responses/SellerApiValidationFailed"},"429":{"$ref":"#/components/responses/SellerApiRateLimited"},"500":{"$ref":"#/components/responses/SellerApiInternalError"},"503":{"$ref":"#/components/responses/SellerApiServiceUnavailable"},"504":{"$ref":"#/components/responses/SellerApiTimeout"}},"x-avrix-scopes":["seller:finance:read"],"x-avrix-tier":"finance","x-avrix-rate-limit-class":"finance","x-avrix-scope-mode":"anyOf"}},"/api/seller/v1/finance/reports/{reportId}":{"get":{"tags":["Finance"],"summary":"Get a monthly sales report","description":"One monthly report: totals in minor units of its currency, the exchange rates it froze and the convention that chose them (`fx`), any rates you attested, its confirmation state and deadline, and disputes. The lines are on `GET /finance/reports/{reportId}/lines`.\n\nA report that is not yours answers 404.","operationId":"getFinanceReport","security":[{"bearerAuth":[]}],"parameters":[{"name":"reportId","in":"path","required":true,"description":"Report id, from `GET /finance/reports`, an invoice line or a `report.ready` event.","schema":{"type":"string","format":"uuid"}},{"$ref":"#/components/parameters/AvrixApiVersion"},{"$ref":"#/components/parameters/RequestId"},{"$ref":"#/components/parameters/SandboxSimulateRateLimit"}],"responses":{"200":{"description":"The report.","headers":{"X-Request-Id":{"$ref":"#/components/headers/XRequestId"},"X-Avrix-Api-Version":{"$ref":"#/components/headers/XAvrixApiVersion"},"X-Api-Version":{"$ref":"#/components/headers/XApiVersion"},"X-RateLimit-Limit":{"$ref":"#/components/headers/XRateLimitLimit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/XRateLimitRemaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/XRateLimitReset"},"X-RateLimit-Bucket":{"$ref":"#/components/headers/XRateLimitBucket"}},"content":{"application/json":{"schema":{"type":"object","required":["data"],"properties":{"data":{"$ref":"#/components/schemas/SellerFinanceReportDetail"}}},"example":{"data":{"id":"f510b4db-800c-4579-8793-0c20f79f77c1","reportMonth":"2026-10","status":"draft","modelType":"api","publisherCompanyId":"acme-games","currencyCode":"EUR","currencyExponent":2,"periodStart":"2026-10-01T00:00:00Z","periodEnd":"2026-10-31T23:59:59Z","deadline":"example_deadline","submittedAt":"2026-11-02T09:30:00Z","createdAt":"2026-11-02T09:30:00Z","updatedAt":"2026-11-02T09:30:00Z","revokedAt":"2026-11-02T09:30:00Z","totals":{"grossCents":2450,"grossMinor":2450,"netCents":2450,"netMinor":2450,"reversalsCents":2450,"reversalsMinor":2450,"vatCents":2450,"vatMinor":2450,"sellerShareCents":2450,"sellerShareMinor":2450,"publisherShareCents":2450,"publisherShareMinor":2450},"confirmation":{"state":"awaiting_seller","nextActor":"seller","deadline":"example_deadline","overdue":true,"submittedAt":"2026-11-02T09:30:00Z","confirmIn":"console"},"detailPath":"example_detailpath","linesPath":"example_linespath","rejectionReason":null,"fxConvention":"example_fxconvention","fx":[{"saleCurrency":"EUR","reportCurrency":"EUR","rate":"example_rate","source":"identity","asOf":"example_asof","fixingTime":"2026-11-02T09:30:00Z","convention":"example_convention","identity":true}],"fxAttestations":[{"sourceCurrency":"EUR","paymentCurrency":"EUR","rate":"example_rate","note":"Example text.","attestedAt":"2026-11-02T09:30:00Z"}],"disputes":[{"disputeId":"ce583771-e6c3-4b40-85fb-23b2bbe4da44","status":"active","reason":null,"filedByCompanyId":"036115c2-4593-4c06-8d8b-ab835f30dd17","filedAt":"2026-11-02T09:30:00Z","resolvedAt":"2026-11-02T09:30:00Z"}]}}}}},"400":{"$ref":"#/components/responses/SellerApiUnsupportedApiVersion"},"401":{"$ref":"#/components/responses/SellerApiUnauthorized"},"403":{"$ref":"#/components/responses/SellerApiForbidden"},"404":{"description":"`NOT_FOUND`: no report with this id is yours.","headers":{"X-Request-Id":{"$ref":"#/components/headers/XRequestId"},"X-Avrix-Api-Version":{"$ref":"#/components/headers/XAvrixApiVersion"},"X-Api-Version":{"$ref":"#/components/headers/XApiVersion"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"422":{"$ref":"#/components/responses/SellerApiValidationFailed"},"429":{"$ref":"#/components/responses/SellerApiRateLimited"},"500":{"$ref":"#/components/responses/SellerApiInternalError"},"503":{"$ref":"#/components/responses/SellerApiServiceUnavailable"},"504":{"$ref":"#/components/responses/SellerApiTimeout"}},"x-avrix-scopes":["seller:finance:read"],"x-avrix-tier":"finance","x-avrix-rate-limit-class":"finance","x-avrix-scope-mode":"anyOf"}},"/api/seller/v1/finance/reports/{reportId}/lines":{"get":{"tags":["Finance"],"summary":"List the lines of a monthly sales report","description":"The lines of one report, paged: per product and sale currency, the sale amounts in `saleCurrency`, the rate used, and both shares in the report currency.\n\nPaging: the shared list contract (`https://docs.avrix.io/seller-api/pagination`). A `cursor` this API did not return is refused with `422 VALIDATION_FAILED`.","operationId":"listFinanceReportLines","security":[{"bearerAuth":[]}],"parameters":[{"name":"reportId","in":"path","required":true,"description":"Report id.","schema":{"type":"string","format":"uuid"}},{"name":"limit","in":"query","description":"Page size (1–100, default 50).","schema":{"type":"integer","default":50,"minimum":1,"maximum":100}},{"name":"cursor","in":"query","description":"Opaque position from `meta.nextCursor`; omit it on the first call. A value this API did not return is refused with `422 VALIDATION_FAILED`.","schema":{"type":"string"}},{"$ref":"#/components/parameters/AvrixApiVersion"},{"$ref":"#/components/parameters/RequestId"},{"$ref":"#/components/parameters/SandboxSimulateRateLimit"}],"responses":{"200":{"description":"Report lines and pagination meta.","headers":{"X-Request-Id":{"$ref":"#/components/headers/XRequestId"},"X-Avrix-Api-Version":{"$ref":"#/components/headers/XAvrixApiVersion"},"X-Api-Version":{"$ref":"#/components/headers/XApiVersion"},"X-RateLimit-Limit":{"$ref":"#/components/headers/XRateLimitLimit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/XRateLimitRemaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/XRateLimitReset"},"X-RateLimit-Bucket":{"$ref":"#/components/headers/XRateLimitBucket"}},"content":{"application/json":{"schema":{"type":"object","required":["data","meta"],"properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/SellerFinanceReportLine"}},"meta":{"$ref":"#/components/schemas/PaginationMeta"}}},"example":{"data":[{"lineId":"fecf3e85-611e-46d5-8f42-a01a0364be30","entryType":"sale","skuId":"22292467-0af3-40a5-853f-827f1a0a6ded","productId":"3e403ca5-4577-4dd8-80a1-744c133b5df3","publisherCompanyId":"acme-games","quantity":12,"saleCurrency":"EUR","saleCurrencyExponent":2,"unitPriceCents":2450,"unitPriceMinor":2450,"grossCents":2450,"grossMinor":2450,"netCents":2450,"netMinor":2450,"vatCents":2450,"vatMinor":2450,"deductionsCents":2450,"deductionsMinor":2450,"currencyCode":"EUR","currencyExponent":2,"exchangeRate":"example_exchangerate","netConvertedCents":2450,"netConvertedMinor":2450,"publisherShareCents":2450,"publisherShareMinor":2450,"sellerShareCents":2450,"sellerShareMinor":2450,"appliedRatePercent":20,"region":"EU","requestedCountry":"DE","platform":"steam","promotionLabel":"example_promotionlabel","promotionReference":"example_promotionreference"}],"meta":{"total":2450,"limit":50,"hasMore":true,"nextCursor":"eyJ2IjoyLCJ0IjoiMjAyNi0xMS0wMlQwOTozMDowMFoifQ","nextUrl":"https://api.avrix.io/api/seller/v1/finance/reports/5da9bbcf-350e-45a0-8e09-b66de7ddc0ce/lines?cursor=eyJ2IjoyLCJ0IjoiMjAyNi0xMS0wMlQwOTozMDowMFoifQ","localePreference":"en"}}}}},"400":{"$ref":"#/components/responses/SellerApiUnsupportedApiVersion"},"401":{"$ref":"#/components/responses/SellerApiUnauthorized"},"403":{"$ref":"#/components/responses/SellerApiForbidden"},"404":{"description":"`NOT_FOUND`: no report with this id is yours.","headers":{"X-Request-Id":{"$ref":"#/components/headers/XRequestId"},"X-Avrix-Api-Version":{"$ref":"#/components/headers/XAvrixApiVersion"},"X-Api-Version":{"$ref":"#/components/headers/XApiVersion"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"422":{"$ref":"#/components/responses/SellerApiValidationFailed"},"429":{"$ref":"#/components/responses/SellerApiRateLimited"},"500":{"$ref":"#/components/responses/SellerApiInternalError"},"503":{"$ref":"#/components/responses/SellerApiServiceUnavailable"},"504":{"$ref":"#/components/responses/SellerApiTimeout"}},"x-avrix-scopes":["seller:finance:read"],"x-avrix-tier":"finance","x-avrix-rate-limit-class":"finance","x-avrix-scope-mode":"anyOf"}},"/api/seller/v1/sandbox/certification":{"get":{"summary":"Get the sandbox certification report","description":"Evaluates the 28 cases of the Certification guide from the calling sandbox key's own traffic over the last 30 days: requests, webhook deliveries (including test-fire receiver challenges) and sandbox fault scenarios. Each case is `pass`, `fail`, `not_run` or `needs_partner_evidence`, with the request or delivery ids that support it.\n\nCases about behaviour inside your systems (a PSP refund, durable key storage, a delisted product, a rejected signature) stay `needs_partner_evidence` until you submit evidence in the Console and Avrix accepts it. A source that could not be read is reported in `collectionErrors` and never yields `pass`.\n\n**Sandbox keys only**: a production key answers **422** `SANDBOX_KEY_REQUIRED`. Any key scope can read the report. The report is computed on each call. It does not enable production access by itself; see the Certification guide for the approval step.","tags":["Sandbox"],"operationId":"getSandboxCertification","security":[{"bearerAuth":[]}],"x-avrix-scopes":[],"x-avrix-tier":"general","x-avrix-rate-limit-class":"general","x-avrix-scope-mode":"any","parameters":[{"$ref":"#/components/parameters/AvrixApiVersion"},{"$ref":"#/components/parameters/RequestId"},{"$ref":"#/components/parameters/SandboxSimulateRateLimit"}],"responses":{"200":{"description":"Certification report","headers":{"X-Request-Id":{"$ref":"#/components/headers/XRequestId"},"X-Avrix-Api-Version":{"$ref":"#/components/headers/XAvrixApiVersion"},"X-Api-Version":{"$ref":"#/components/headers/XApiVersion"},"X-RateLimit-Limit":{"$ref":"#/components/headers/XRateLimitLimit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/XRateLimitRemaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/XRateLimitReset"},"X-RateLimit-Bucket":{"$ref":"#/components/headers/XRateLimitBucket"}},"content":{"application/json":{"schema":{"type":"object","required":["data","meta"],"properties":{"data":{"$ref":"#/components/schemas/SellerSandboxCertificationReport"},"meta":{"type":"object","required":["requestId"],"properties":{"requestId":{"type":"string"}}}}},"example":{"data":{"reportVersion":1,"generatedAt":"2026-10-12T09:30:00.000Z","apiKeyId":"5b2f0d1e-7c3a-4e8b-9f61-2a4c8d0e1b37","environment":{"mode":"isolated","environmentId":"0c9e6f4a-1d2b-4c3e-8a7f-5b6d9e0f1a2c"},"window":{"from":"2026-09-12T09:30:00.000Z","to":"2026-10-12T09:30:00.000Z"},"summary":{"pass":4,"fail":0,"not_run":20,"needs_partner_evidence":4},"collectionErrors":[],"cases":[{"number":1,"name":"Cold-start sync","group":"catalog","status":"not_run","evidenceQuality":"complete","reason":"Take GET /catalog/snapshot, then follow GET /catalog/changes with its cursor.","observations":[],"partnerEvidence":"none"},{"number":2,"name":"Incremental sync","group":"catalog","status":"not_run","evidenceQuality":"complete","reason":"Poll GET /catalog/changes at least twice with the cursor it returns.","observations":[],"partnerEvidence":"none"},{"number":3,"name":"Tombstone handling","group":"catalog","status":"not_run","evidenceQuality":"complete","reason":"Follow GET /catalog/changes across a churn window.","observations":[],"partnerEvidence":"none"},{"number":4,"name":"Allocation merge","group":"catalog","status":"not_run","evidenceQuality":"complete","reason":"Read GET /allocations and merge it into your catalog.","observations":[],"partnerEvidence":"none"},{"number":5,"name":"Unsellable SKU excluded","group":"catalog","status":"not_run","evidenceQuality":"complete","reason":"No request touched SANDBOX-NOALLOC-001 yet.","observations":[],"partnerEvidence":"none"},{"number":6,"name":"Non-live product excluded","group":"catalog","status":"not_run","evidenceQuality":"complete","reason":"No request touched SANDBOX-LIFECYCLE-001 yet.","observations":[],"partnerEvidence":"none"},{"number":7,"name":"Happy path","group":"orders","status":"pass","evidenceQuality":"complete","reason":"An order for SANDBOX-ALWAYS-001 was fulfilled.","observations":[{"at":"2026-10-12T08:10:04.000Z","requestId":"req_7f3a91c2","detail":"POST /api/seller/v1/orders → 200 (SANDBOX-ALWAYS-001)"},{"at":"2026-10-12T08:10:09.000Z","requestId":"req_7f3a91c3","detail":"POST /api/seller/v1/orders → 200 (SANDBOX-ALWAYS-001)"}],"partnerEvidence":"none"},{"number":8,"name":"Preview gating","group":"orders","status":"not_run","evidenceQuality":"complete","reason":"Call POST /orders/preview before charging.","observations":[],"partnerEvidence":"none"},{"number":9,"name":"Sold out after payment","group":"orders","status":"not_run","evidenceQuality":"complete","reason":"Order SANDBOX-NOKEYS-001 after a (test) payment.","observations":[],"partnerEvidence":"none"},{"number":10,"name":"Price drift","group":"orders","status":"not_run","evidenceQuality":"complete","reason":"Order SANDBOX-PRICE-MIS-001 with a wrong expectedUnitPriceCents.","observations":[],"partnerEvidence":"none"},{"number":11,"name":"Territory rejection","group":"orders","status":"not_run","evidenceQuality":"complete","reason":"Order SANDBOX-TERR-BLOCK-001 for a US buyer.","observations":[],"partnerEvidence":"none"},{"number":12,"name":"Idempotent replay","group":"orders","status":"pass","evidenceQuality":"complete","reason":"A retry with the same key and body returned the original order.","observations":[{"at":"2026-10-12T08:10:09.000Z","requestId":"req_7f3a91c3","detail":"POST /api/seller/v1/orders → 200 (SANDBOX-ALWAYS-001)"}],"partnerEvidence":"none"},{"number":13,"name":"Idempotency conflict","group":"orders","status":"pass","evidenceQuality":"complete","reason":"Reusing a key with a different body was refused with IDEMPOTENCY_KEY_MISMATCH.","observations":[{"at":"2026-10-12T08:11:30.000Z","requestId":"req_7f3a91c4","detail":"POST /api/seller/v1/orders → 409 IDEMPOTENCY_KEY_MISMATCH"}],"partnerEvidence":"none"},{"number":14,"name":"Unknown outcome","group":"orders","status":"not_run","evidenceQuality":"complete","reason":"Run the timeout_then_success or error_after_commit scenario and recover it.","observations":[],"partnerEvidence":"none"},{"number":15,"name":"Key persistence","group":"fulfilment","status":"needs_partner_evidence","evidenceQuality":"complete","reason":"Show that keys are written to durable storage before you answer the buyer.","observations":[],"partnerEvidence":"none"},{"number":16,"name":"Key non-recovery","group":"fulfilment","status":"needs_partner_evidence","evidenceQuality":"complete","reason":"Show that your fulfilment never depends on GET /orders returning plaintext keys.","observations":[],"partnerEvidence":"none"},{"number":17,"name":"Valid signature","group":"webhooks","status":"pass","evidenceQuality":"complete","reason":"A correctly signed delivery was accepted.","observations":[{"at":"2026-10-12T08:20:00.000Z","deliveryId":"8d4e2b1a-6c3f-4a5e-9b7d-1f2e3c4d5a6b","detail":"order.fulfilled → 200"}],"partnerEvidence":"none"},{"number":18,"name":"Invalid signature","group":"webhooks","status":"needs_partner_evidence","evidenceQuality":"complete","reason":"Your endpoint refused the mis-signed delivery. Show that it was refused for the signature, not for another reason.","observations":[{"at":"2026-10-12T08:21:00.000Z","deliveryId":"9e5f3c2b-7d4a-4b6f-8c8e-2a3f4d5e6b7c","detail":"order.fulfilled mis-signed delivery → 401"}],"partnerEvidence":"none"},{"number":19,"name":"Stale timestamp","group":"webhooks","status":"not_run","evidenceQuality":"complete","reason":"Fire a test event with challenge \"stale_timestamp\" (POST /webhooks/{id}/test).","observations":[],"partnerEvidence":"none"},{"number":20,"name":"Duplicate delivery","group":"webhooks","status":"not_run","evidenceQuality":"complete","reason":"Fire a test event with challenge \"duplicate\" and acknowledge both deliveries.","observations":[],"partnerEvidence":"none"},{"number":21,"name":"Webhook before response","group":"webhooks","status":"not_run","evidenceQuality":"complete","reason":"Run the webhook_delay_duplicate scenario on an order.","observations":[],"partnerEvidence":"none"},{"number":22,"name":"Secret rotation","group":"webhooks","status":"not_run","evidenceQuality":"complete","reason":"Rotate the secret, then fire a \"valid\" and a \"previous_secret_only\" test event during the overlap.","observations":[],"partnerEvidence":"none"},{"number":23,"name":"Key return","group":"refunds","status":"not_run","evidenceQuality":"complete","reason":"Return keys with POST /refunds using the keyIds from the order response.","observations":[],"partnerEvidence":"none"},{"number":24,"name":"Refund recorded","group":"refunds","status":"not_run","evidenceQuality":"complete","reason":"After a refund, read it with GET /refunds.","observations":[],"partnerEvidence":"none"},{"number":25,"name":"Rate limit","group":"operations","status":"not_run","evidenceQuality":"complete","reason":"Trigger a 429 (X-Avrix-Sandbox-Simulate: rate_limit) and honour Retry-After.","observations":[],"partnerEvidence":"none"},{"number":26,"name":"Server error","group":"operations","status":"not_run","evidenceQuality":"complete","reason":"Trigger a 5xx (X-Avrix-Sandbox-Simulate: internal_error or a scenario) and retry.","observations":[],"partnerEvidence":"none"},{"number":27,"name":"Request correlation","group":"operations","status":"needs_partner_evidence","evidenceQuality":"complete","reason":"Show requestId logged on every error in your logs.","observations":[],"partnerEvidence":"none"},{"number":28,"name":"Reconciliation","group":"operations","status":"not_run","evidenceQuality":"complete","reason":"List GET /orders at least twice, an hour or more apart.","observations":[],"partnerEvidence":"none"}],"notCovered":[{"area":"promotions","reason":"Answering event shares and deals, and promotion events. Rehearse them on SANDBOX-PROMO-001 (Sandbox guide, Promotions)."},{"area":"finance_statements","reason":"Invoices, statements and payouts. Sandbox sales are kept out of settlement, so there is nothing to certify against."},{"area":"key_management","reason":"Creating, rotating and revoking API keys and IP allowlists. Check them against the Authentication guide."},{"area":"allocation_requests","reason":"Asking a vendor for more stock and handling the decision. Rehearse it with POST /sandbox/allocations/requests/{requestId}/resolve."},{"area":"partner_access","reason":"Accepting or declining an access proposal. Rehearse it on the proposal the isolated sandbox offers (POST /sandbox/reset offers a new one)."}]},"meta":{"requestId":"req_av1203_example"}}}}},"400":{"$ref":"#/components/responses/SellerApiUnsupportedApiVersion"},"401":{"$ref":"#/components/responses/SellerApiUnauthorized"},"403":{"$ref":"#/components/responses/SellerApiForbidden"},"422":{"description":"`SANDBOX_KEY_REQUIRED`: the report is built from sandbox traffic; call it with a sandbox key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"examples":{"SANDBOX_KEY_REQUIRED":{"value":{"code":"SANDBOX_KEY_REQUIRED","message":"The certification report is built from sandbox traffic; call it with a sandbox API key.","error":"The certification report is built from sandbox traffic; call it with a sandbox API key.","timestamp":"2026-10-12T09:30:00.000Z","recoverable":false,"doc_url":"https://docs.avrix.io/seller-api/errors#sandbox-key-required","requestId":"req_av1203_example"}}}}}},"429":{"$ref":"#/components/responses/SellerApiRateLimited"},"500":{"$ref":"#/components/responses/SellerApiInternalError"},"503":{"description":"`SANDBOX_ENVIRONMENT_UNAVAILABLE`: your store's isolated sandbox environment is being prepared or repaired. Retry after the `Retry-After` header (also `details.retryAfterSeconds`). Also returned when a platform dependency is temporarily unavailable (`SERVICE_UNAVAILABLE`) and, on a write that sends an `Idempotency-Key`, when the claim cannot be recorded (`IDEMPOTENCY_STORE_UNAVAILABLE`). Retry after `Retry-After` seconds.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"examples":{"SANDBOX_ENVIRONMENT_UNAVAILABLE":{"value":{"code":"SANDBOX_ENVIRONMENT_UNAVAILABLE","message":"Your sandbox environment is being prepared or repaired. Retry shortly.","error":"Your sandbox environment is being prepared or repaired. Retry shortly.","timestamp":"2026-10-12T09:30:00.000Z","recoverable":true,"doc_url":"https://docs.avrix.io/seller-api/errors#sandbox-environment-unavailable","requestId":"req_av1203_example","details":{"retryable":true,"retryAfterSeconds":30}}}}}}},"504":{"$ref":"#/components/responses/SellerApiTimeout"}},"x-codeSamples":[{"lang":"curl","label":"Certification report","source":"curl -s \"https://api.avrix.io/api/seller/v1/sandbox/certification\" \\\n  -H \"Authorization: Bearer avrix_sk_sbx_your_key_here\""}]}},"/api/seller/v1/sandbox/reset":{"post":{"summary":"Reset your isolated sandbox environment","description":"Puts your store's isolated sandbox environment back in a known state, so a test suite can start from the same place every run:\n\n- open fault scenarios expire and the stock they held is released;\n- pending allocation requests are cancelled;\n- the selling footprint is restored to the sandbox default;\n- every fixture pool is topped up, and the `SANDBOX-ALLOC-REQUEST-001` allocation is back to 5 unsold units;\n- the rehearsal fixtures are re-armed: the promotion share on `SANDBOX-PROMO-001` is pending again, missing deals are re-created, the zero-day refund window on `SANDBOX-REFUND-EXPIRED-001` is restored and, if none is open, a new access proposal is offered.\n\nOrders, keys already sold, refunds and finance records are kept. The call does not wait for webhooks.\n\n**Sandbox keys in an isolated environment only**: a production key answers **422** `SANDBOX_KEY_REQUIRED` and nothing is read or changed; on the shared sandbox the call answers **422** `SANDBOX_ISOLATED_ENVIRONMENT_REQUIRED`, because the shared data belongs to every store on it. Send an empty body or none. `Idempotency-Key` is optional.","tags":["Sandbox"],"operationId":"resetSandbox","security":[{"bearerAuth":[]}],"x-avrix-scopes":[],"x-avrix-tier":"general","x-avrix-rate-limit-class":"general","x-avrix-scope-mode":"any","parameters":[{"$ref":"#/components/parameters/IdempotencyKeyOptional"},{"$ref":"#/components/parameters/AvrixApiVersion"},{"$ref":"#/components/parameters/RequestId"},{"$ref":"#/components/parameters/SandboxSimulateWrite"}],"requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"properties":{}},"example":{}}}},"responses":{"200":{"description":"Environment reset","headers":{"X-Request-Id":{"$ref":"#/components/headers/XRequestId"},"X-Avrix-Api-Version":{"$ref":"#/components/headers/XAvrixApiVersion"},"X-Api-Version":{"$ref":"#/components/headers/XApiVersion"},"Idempotency-Replayed":{"$ref":"#/components/headers/IdempotencyReplayed"},"X-RateLimit-Limit":{"$ref":"#/components/headers/XRateLimitLimit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/XRateLimitRemaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/XRateLimitReset"},"X-RateLimit-Bucket":{"$ref":"#/components/headers/XRateLimitBucket"}},"content":{"application/json":{"schema":{"type":"object","required":["data"],"properties":{"data":{"$ref":"#/components/schemas/SellerSandboxResetSummary"}}},"example":{"data":{"environment":{"mode":"isolated","environmentId":"0c9e6f4a-1d2b-4c3e-8a7f-5b6d9e0f1a2c"},"resetAt":"2026-12-02T09:30:00.000Z","scenariosExpired":1,"keysReleased":4,"allocationRequestsCancelled":["3b1f8a52-6c0d-4e7a-9b21-5d4c3e2f1a09"],"keysAdded":25,"footprintRestored":true,"rehearsal":{"refundWindow":true,"promotions":{"shareId":"8e2c4b6a-1f3d-4a5e-9c7b-2d1e0f9a8b7c","shareRearmed":true,"dealsCreated":[]},"accessProposal":{"proposalId":"6a4d2c1b-9e8f-4a7b-8c6d-5e4f3a2b1c0d","status":"created"}},"missingFixtures":[]}}}}},"400":{"$ref":"#/components/responses/SellerApiUnsupportedApiVersion"},"401":{"$ref":"#/components/responses/SellerApiUnauthorized"},"403":{"$ref":"#/components/responses/SellerApiForbidden"},"409":{"$ref":"#/components/responses/SellerApiIdempotencyConflict"},"413":{"$ref":"#/components/responses/SellerApiPayloadTooLarge"},"422":{"description":"`SANDBOX_KEY_REQUIRED` for a production key, `SANDBOX_ISOLATED_ENVIRONMENT_REQUIRED` on the shared sandbox, or `VALIDATION_FAILED` for a non-empty body","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"code":"SANDBOX_ISOLATED_ENVIRONMENT_REQUIRED","message":"POST /sandbox/reset changes data every store on the shared sandbox reads, so it runs only in your store's isolated sandbox environment.","details":{"operation":"POST /sandbox/reset","sandboxMode":"shared"},"requestId":"req_7f3a91c2"}}}},"429":{"$ref":"#/components/responses/SellerApiRateLimited"},"500":{"$ref":"#/components/responses/SellerApiInternalError"},"503":{"$ref":"#/components/responses/SellerApiServiceUnavailable"},"504":{"$ref":"#/components/responses/SellerApiTimeout"}}}},"/api/seller/v1/sandbox/allocations/requests/{requestId}/resolve":{"post":{"summary":"Decide your pending allocation request (sandbox)","description":"The sandbox vendor approves or declines one of your store's pending allocation requests (`POST /allocations/requests`) through the vendor's own path, so you receive `allocation.request_decided` (and, on approval, `allocation.updated`) without waiting for a person. On approval `grantDelta` defaults to the quantity you asked for.\n\nAn approval follows the same stock rule as in production: the allocation cannot promise more keys than the vendor holds. Rehearse approvals on `SANDBOX-ALLOC-REQUEST-001`, an allocation of 5 over 30 keys in stock (`POST /sandbox/reset` brings it back to 5 unsold); the other fixtures' allocations already promise more keys than they hold, so an approval there answers **409** `CONFLICT` with `details.reason: ALLOCATION_CEILING_EXCEEDS_STOCK`.\n\n**Sandbox keys only**: a production key answers **422** `SANDBOX_KEY_REQUIRED` and nothing is read or changed. An approval needs an isolated environment (on the shared sandbox it answers **422** `SANDBOX_ISOLATED_ENVIRONMENT_REQUIRED`, because the allocation would grow for every store on it); a decline works on both. A request that is not your store's answers **404** `NOT_FOUND`; one that is no longer pending answers **409** `CONFLICT` with its current `details.status`. `Idempotency-Key` is optional.","tags":["Sandbox"],"operationId":"resolveSandboxAllocationRequest","security":[{"bearerAuth":[]}],"x-avrix-scopes":[],"x-avrix-tier":"general","x-avrix-rate-limit-class":"general","x-avrix-scope-mode":"any","parameters":[{"name":"requestId","in":"path","required":true,"schema":{"type":"string","format":"uuid"},"description":"Allocation request id (`id` from POST /allocations/requests)"},{"$ref":"#/components/parameters/IdempotencyKeyOptional"},{"$ref":"#/components/parameters/AvrixApiVersion"},{"$ref":"#/components/parameters/RequestId"},{"$ref":"#/components/parameters/SandboxSimulateWrite"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"required":["decision"],"properties":{"decision":{"type":"string","enum":["approved","denied"],"description":"`approved`: the sandbox vendor approves the request and adds keys to the allocation. `denied`: the sandbox vendor declines it."},"grantDelta":{"type":"integer","minimum":1,"maximum":100000,"description":"Keys to add on approval. Defaults to the requested quantity; ignored on a decline."},"note":{"type":"string","minLength":1,"maxLength":500,"description":"The vendor's note, as the store would see it."}}},"example":{"decision":"approved","grantDelta":50}}}},"responses":{"200":{"description":"Request decided","headers":{"X-Request-Id":{"$ref":"#/components/headers/XRequestId"},"X-Avrix-Api-Version":{"$ref":"#/components/headers/XAvrixApiVersion"},"X-Api-Version":{"$ref":"#/components/headers/XApiVersion"},"Idempotency-Replayed":{"$ref":"#/components/headers/IdempotencyReplayed"},"X-RateLimit-Limit":{"$ref":"#/components/headers/XRateLimitLimit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/XRateLimitRemaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/XRateLimitReset"},"X-RateLimit-Bucket":{"$ref":"#/components/headers/XRateLimitBucket"}},"content":{"application/json":{"schema":{"type":"object","required":["data"],"properties":{"data":{"type":"object","required":["requestId","status","resolution","allocationId","grantDelta","decidedAt"],"properties":{"requestId":{"type":"string","format":"uuid"},"status":{"type":"string","description":"The request's status after the decision: `resolved`."},"resolution":{"type":["string","null"],"enum":["approved","denied",null],"description":"The decision."},"allocationId":{"type":["string","null"],"format":"uuid","description":"The allocation the request was for."},"grantDelta":{"type":["integer","null"],"description":"Keys added to the allocation's limit on approval; null on a decline."},"decidedAt":{"type":["string","null"],"format":"date-time"}}}}},"example":{"data":{"requestId":"3b1f8a52-6c0d-4e7a-9b21-5d4c3e2f1a09","status":"resolved","resolution":"approved","allocationId":"9d8c7b6a-5f4e-4d3c-8b2a-1f0e9d8c7b6a","grantDelta":50,"decidedAt":"2026-12-02T09:30:00.000Z"}}}}},"400":{"$ref":"#/components/responses/SellerApiUnsupportedApiVersion"},"401":{"$ref":"#/components/responses/SellerApiUnauthorized"},"403":{"$ref":"#/components/responses/SellerApiForbidden"},"404":{"description":"No allocation request with this id belongs to your sandbox store","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"code":"NOT_FOUND","message":"No allocation request with this id belongs to your sandbox store.","details":{"requestId":"3b1f8a52-6c0d-4e7a-9b21-5d4c3e2f1a09"},"requestId":"req_7f3a91c2"}}}},"409":{"description":"The request is no longer pending (`CONFLICT`, with its `details.status`), the vendor could not approve it (`CONFLICT`, `details.reason`, for example `ALLOCATION_CEILING_EXCEEDS_STOCK`), or the Idempotency-Key was reused with a different body","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"code":"CONFLICT","message":"This allocation request is no longer pending.","details":{"requestId":"3b1f8a52-6c0d-4e7a-9b21-5d4c3e2f1a09","status":"resolved"},"requestId":"req_7f3a91c2"}}}},"413":{"$ref":"#/components/responses/SellerApiPayloadTooLarge"},"422":{"description":"`SANDBOX_KEY_REQUIRED` for a production key, `SANDBOX_ISOLATED_ENVIRONMENT_REQUIRED` for an approval on the shared sandbox, or `VALIDATION_FAILED` for an invalid id or body","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"code":"SANDBOX_KEY_REQUIRED","message":"POST /sandbox/allocations/requests/{requestId}/resolve is a sandbox control. Call it with a sandbox API key; it never changes production data.","details":{"operation":"POST /sandbox/allocations/requests/{requestId}/resolve"},"requestId":"req_7f3a91c2"}}}},"429":{"$ref":"#/components/responses/SellerApiRateLimited"},"500":{"$ref":"#/components/responses/SellerApiInternalError"},"503":{"$ref":"#/components/responses/SellerApiServiceUnavailable"},"504":{"$ref":"#/components/responses/SellerApiTimeout"}}}},"/api/seller/v1/sandbox/allocations/{allocationId}/stock-events":{"post":{"summary":"Send a stock event for your allocation (sandbox)","description":"Delivers `allocation.low_stock` or `allocation.depleted` for one of your allocations to the calling key's webhook endpoints, without consuming stock, so you can rehearse your low-stock handling. The payload carries the allocation's real ids; its counts are simulated and the allocation itself does not change, so `GET /allocations/{id}` keeps showing the real numbers. Works on the shared sandbox and in an isolated environment.\n\n**Sandbox keys only**: a production key answers **422** `SANDBOX_KEY_REQUIRED` and nothing is read or changed. `Idempotency-Key` is optional.","tags":["Sandbox"],"operationId":"sendSandboxAllocationStockEvent","security":[{"bearerAuth":[]}],"x-avrix-scopes":[],"x-avrix-tier":"general","x-avrix-rate-limit-class":"general","x-avrix-scope-mode":"any","parameters":[{"name":"allocationId","in":"path","required":true,"schema":{"type":"string","format":"uuid"},"description":"Allocation id (`id` on GET /allocations)"},{"$ref":"#/components/parameters/IdempotencyKeyOptional"},{"$ref":"#/components/parameters/AvrixApiVersion"},{"$ref":"#/components/parameters/RequestId"},{"$ref":"#/components/parameters/SandboxSimulateWrite"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"required":["event"],"properties":{"event":{"type":"string","enum":["low_stock","depleted"],"description":"`low_stock`: sends `allocation.low_stock`. `depleted`: sends `allocation.depleted`."}}},"example":{"event":"low_stock"}}}},"responses":{"202":{"description":"Event queued for delivery","headers":{"X-Request-Id":{"$ref":"#/components/headers/XRequestId"},"X-Avrix-Api-Version":{"$ref":"#/components/headers/XAvrixApiVersion"},"X-Api-Version":{"$ref":"#/components/headers/XApiVersion"},"Idempotency-Replayed":{"$ref":"#/components/headers/IdempotencyReplayed"},"X-RateLimit-Limit":{"$ref":"#/components/headers/XRateLimitLimit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/XRateLimitRemaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/XRateLimitReset"},"X-RateLimit-Bucket":{"$ref":"#/components/headers/XRateLimitBucket"}},"content":{"application/json":{"schema":{"type":"object","required":["data"],"properties":{"data":{"type":"object","required":["allocationId","eventType","payload"],"properties":{"allocationId":{"type":"string","format":"uuid"},"eventType":{"type":"string","enum":["allocation.low_stock","allocation.depleted"],"description":"The event that was sent: `allocation.low_stock` or `allocation.depleted`."},"payload":{"type":"object","additionalProperties":true,"description":"The event payload as delivered. The ids are real; the counts are simulated."}}}}},"example":{"data":{"allocationId":"9d8c7b6a-5f4e-4d3c-8b2a-1f0e9d8c7b6a","eventType":"allocation.low_stock","payload":{"allocationId":"9d8c7b6a-5f4e-4d3c-8b2a-1f0e9d8c7b6a","publisherCompanyId":"sbxv-4f2a9c1e7b","skuId":"2c4e6a8b-0d1f-4e3a-9b5c-7d9e1f3a5b7c","quantityLimit":500,"quantityPulled":450,"remaining":50,"reason":"pulled"}}}}}},"400":{"$ref":"#/components/responses/SellerApiUnsupportedApiVersion"},"401":{"$ref":"#/components/responses/SellerApiUnauthorized"},"403":{"$ref":"#/components/responses/SellerApiForbidden"},"404":{"description":"Allocation not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"code":"NOT_FOUND","message":"Allocation not found","details":{"allocationId":"9d8c7b6a-5f4e-4d3c-8b2a-1f0e9d8c7b6a"},"requestId":"req_7f3a91c2"}}}},"409":{"$ref":"#/components/responses/SellerApiIdempotencyConflict"},"413":{"$ref":"#/components/responses/SellerApiPayloadTooLarge"},"422":{"description":"`SANDBOX_KEY_REQUIRED` for a production key, or `VALIDATION_FAILED` for an invalid id or body","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"code":"SANDBOX_KEY_REQUIRED","message":"POST /sandbox/allocations/{allocationId}/stock-events is a sandbox control. Call it with a sandbox API key; it never changes production data.","details":{"operation":"POST /sandbox/allocations/{allocationId}/stock-events"},"requestId":"req_7f3a91c2"}}}},"429":{"$ref":"#/components/responses/SellerApiRateLimited"},"500":{"$ref":"#/components/responses/SellerApiInternalError"},"503":{"$ref":"#/components/responses/SellerApiServiceUnavailable"},"504":{"$ref":"#/components/responses/SellerApiTimeout"}}}},"/api/seller/v1/sandbox/promotions/deals/{responseId}/window":{"post":{"summary":"Start or end a deal now (sandbox)","description":"Moves a sandbox vendor's deal so it starts (`action: start`) or ends (`action: end`) now instead of on its dates. For a deal you approved, `promotion.started` or `promotion.ended` is sent to the calling key's endpoints; the regular window job does not send it again. Starting a deal you have not answered closes it for answers, as a real start does, so you can also rehearse the refused late answer.\n\n**Sandbox keys in an isolated environment only**: a production key answers **422** `SANDBOX_KEY_REQUIRED` and nothing is read or changed; on the shared sandbox the call answers **422** `SANDBOX_ISOLATED_ENVIRONMENT_REQUIRED`, because every store there holds the same deals. A deal that is not yours answers **404** `NOT_FOUND`. `Idempotency-Key` is optional.","tags":["Sandbox"],"operationId":"moveSandboxDealWindow","security":[{"bearerAuth":[]}],"x-avrix-scopes":[],"x-avrix-tier":"general","x-avrix-rate-limit-class":"general","x-avrix-scope-mode":"any","parameters":[{"name":"responseId","in":"path","required":true,"schema":{"type":"string","format":"uuid"},"description":"Deal id (`responseId` on GET /promotions/deals)"},{"$ref":"#/components/parameters/IdempotencyKeyOptional"},{"$ref":"#/components/parameters/AvrixApiVersion"},{"$ref":"#/components/parameters/RequestId"},{"$ref":"#/components/parameters/SandboxSimulateWrite"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"required":["action"],"properties":{"action":{"type":"string","enum":["start","end"],"description":"`start`: the deal starts now. `end`: the deal ends now."}}},"example":{"action":"start"}}}},"responses":{"200":{"description":"Deal window moved","headers":{"X-Request-Id":{"$ref":"#/components/headers/XRequestId"},"X-Avrix-Api-Version":{"$ref":"#/components/headers/XAvrixApiVersion"},"X-Api-Version":{"$ref":"#/components/headers/XApiVersion"},"Idempotency-Replayed":{"$ref":"#/components/headers/IdempotencyReplayed"},"X-RateLimit-Limit":{"$ref":"#/components/headers/XRateLimitLimit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/XRateLimitRemaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/XRateLimitReset"},"X-RateLimit-Bucket":{"$ref":"#/components/headers/XRateLimitBucket"}},"content":{"application/json":{"schema":{"type":"object","required":["data"],"properties":{"data":{"type":"object","required":["responseId","status","startDate","endDate","eventType"],"properties":{"responseId":{"type":"string","format":"uuid"},"status":{"type":"string","description":"Your answer's status on the deal (`pending`, `approved`, `rejected`)."},"startDate":{"type":"string","format":"date-time"},"endDate":{"type":"string","format":"date-time"},"eventType":{"type":["string","null"],"enum":["promotion.started","promotion.ended",null],"description":"The event sent to your endpoints, or null when the deal was not approved (no event is sent then)."}}}}},"example":{"data":{"responseId":"5c3a1e9f-7b6d-4c2a-8e0f-1a2b3c4d5e6f","status":"approved","startDate":"2026-12-02T09:29:00.000Z","endDate":"2026-12-09T09:30:00.000Z","eventType":"promotion.started"}}}}},"400":{"$ref":"#/components/responses/SellerApiUnsupportedApiVersion"},"401":{"$ref":"#/components/responses/SellerApiUnauthorized"},"403":{"$ref":"#/components/responses/SellerApiForbidden"},"404":{"description":"Deal not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"code":"NOT_FOUND","message":"Deal not found","details":{"responseId":"5c3a1e9f-7b6d-4c2a-8e0f-1a2b3c4d5e6f"},"requestId":"req_7f3a91c2"}}}},"409":{"description":"The deal was not sent by the vendor (`CONFLICT`, with the deal's `details.status`), or the Idempotency-Key was reused with a different body","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"code":"CONFLICT","message":"Only a deal the vendor has sent can be moved.","details":{"responseId":"5c3a1e9f-7b6d-4c2a-8e0f-1a2b3c4d5e6f","status":"draft"},"requestId":"req_7f3a91c2"}}}},"413":{"$ref":"#/components/responses/SellerApiPayloadTooLarge"},"422":{"description":"`SANDBOX_KEY_REQUIRED` for a production key, `SANDBOX_ISOLATED_ENVIRONMENT_REQUIRED` on the shared sandbox, or `VALIDATION_FAILED` for an invalid id or body","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"code":"SANDBOX_ISOLATED_ENVIRONMENT_REQUIRED","message":"POST /sandbox/promotions/deals/{responseId}/window changes data every store on the shared sandbox reads, so it runs only in your store's isolated sandbox environment.","details":{"operation":"POST /sandbox/promotions/deals/{responseId}/window","sandboxMode":"shared"},"requestId":"req_7f3a91c2"}}}},"429":{"$ref":"#/components/responses/SellerApiRateLimited"},"500":{"$ref":"#/components/responses/SellerApiInternalError"},"503":{"$ref":"#/components/responses/SellerApiServiceUnavailable"},"504":{"$ref":"#/components/responses/SellerApiTimeout"}}}}},"components":{"headers":{"Deprecation":{"description":"RFC 9745. Present only when the operation, or a parameter or header this request used, is deprecated with a date, or when this unpinned request is served a contract date that is about to stop being the default. The value is the date the deprecation took effect, as `@` and Unix seconds (for example `@1798761600`). A `Link` header with `rel=\"deprecation\"` points at the page that explains it. Requests that use nothing deprecated never carry it. See `https://docs.avrix.io/seller-api/versioning#deprecation-communication`.","schema":{"type":"string","pattern":"^@-?\\d+$","examples":["@1798761600"]}},"Sunset":{"description":"RFC 8594. Present next to `Deprecation` when a removal date is scheduled: the HTTP-date after which the deprecated operation, parameter or default contract date stops working as it does today. A `Link` header with `rel=\"sunset\"` points at the details. Never sent without a changelog entry naming the same date.","schema":{"type":"string","examples":["Mon, 05 Jul 2027 00:00:00 GMT"]}},"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"]}},"XRequestId":{"description":"The id of this request: the `X-Request-Id` you sent, otherwise a generated UUID. Quote it when you contact support, and pass it to `GET /requests/{requestId}`.","schema":{"type":"string"}},"XAvrixApiVersion":{"description":"The contract date this response was served on: the date you pinned with the `X-Avrix-Api-Version` request header (`next` shows as the date it resolved to), otherwise the stamped default.","schema":{"type":"string","format":"date"}},"XApiVersion":{"description":"Legacy major version marker, always `1`. Deprecated: it never changes. Read `X-Avrix-Api-Version` for the contract date.","deprecated":true,"schema":{"type":"string","enum":["1"]}},"XRateLimitLimit":{"description":"Requests allowed per window in the rate-limit bucket this request was counted against. A bucket belongs to one key (production) or one company (sandbox), one route class and one kind (read, cached read or write); on the key-free `GET /whoami-ip` it belongs to your IP address. Sent, with `X-RateLimit-Remaining` and `X-RateLimit-Reset`, on every response to a request that was counted against a limit: successes, `304`, errors returned after the request was counted (validation, not found, conflicts, `5xx`, replayed idempotent responses) and `429`. A request refused before it is counted (for example `400 UNSUPPORTED_API_VERSION`, `401`, or a scope or IP allowlist `403`) carries none of the three, and operations that read no API key send none, except `GET /whoami-ip`. A sandbox `429` simulated with `X-Avrix-Sandbox-Simulate: rate_limit` is answered before the request is counted and carries none of the three.","required":true,"schema":{"type":"integer"}},"XRateLimitRemaining":{"description":"Requests left in the current window of that bucket. `0` when the limiter refused the request with `429`. Sent whenever `X-RateLimit-Limit` is.","required":true,"schema":{"type":"integer"}},"XRateLimitReset":{"description":"Unix timestamp in seconds when the current window of that bucket resets. Sent whenever `X-RateLimit-Limit` is.","required":true,"schema":{"type":"integer","format":"int64"}},"XRateLimitBucket":{"description":"The rate-limit bucket the `X-RateLimit-*` numbers on this response belong to, as `<class>:<kind>`. The class is `catalog`, `orders`, `finance`, `webhooks-mgmt` or `general` (the operation's `x-avrix-rate-limit-class`); the kind is `read`, `read-cached` or `write`, or `snapshot` for the hourly full-snapshot budget of a production key (`catalog:snapshot`). Requests answered with the same value spend from the same budget. `GET /whoami` lists every bucket of the calling key with its limit and window (`data.key.rateLimits.buckets`). Sent with the three `X-RateLimit-*` headers on responses to requests counted by the Seller API limiter; not sent by `GET /whoami-ip`, whose limit is per calling address.","schema":{"type":"string","pattern":"^(catalog|orders|finance|webhooks-mgmt|general):(read|read-cached|write|snapshot)$","example":"orders:write"}},"RetryAfter":{"description":"Seconds to wait before you retry the same request. Sent with every 429, with retryable 503 and 504 responses, and with 409 `IDEMPOTENCY_REQUEST_IN_FLIGHT`.","schema":{"type":"integer","minimum":1}},"WWWAuthenticate":{"description":"Sent with 401 responses: `Bearer realm=\"Avrix Seller API\"`.","schema":{"type":"string"}},"ETag":{"description":"Weak entity tag of the response body. Send it back in `If-None-Match` to receive `304 Not Modified` while nothing has changed.","schema":{"type":"string"}},"XNextCursor":{"description":"With `format=csv` only: the cursor for the next page, because a CSV body has no `meta` object. Absent on the last page. Not in the browser-exposed header list, so a browser client cannot read it.","schema":{"type":"string"}}},"securitySchemes":{"bearerAuth":{"type":"http","scheme":"bearer","bearerFormat":"API Key","description":"A Seller API key, sent as `Authorization: Bearer <key>`. The key's prefix selects the environment on the same host: `avrix_sk_live_...` for production, `avrix_sk_sbx_...` for sandbox. An access token from `POST /api/seller/oauth/token` (`avrix_oat_...`) is sent the same way. The scopes each operation accepts are listed in its `x-avrix-scopes`."}},"responses":{"SellerApiUnauthorized":{"description":"Missing or invalid `Authorization` Bearer token, expired key, or invalid company.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}},"headers":{"X-Request-Id":{"$ref":"#/components/headers/XRequestId"},"X-Avrix-Api-Version":{"$ref":"#/components/headers/XAvrixApiVersion"},"X-Api-Version":{"$ref":"#/components/headers/XApiVersion"},"WWW-Authenticate":{"$ref":"#/components/headers/WWWAuthenticate"}}},"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`). A key that lacks the scope the operation needs is refused with `INSUFFICIENT_SCOPE` on contract date `2026-12-01` and later: `details.requiredScopes` lists every scope the operation accepts (holding any one is enough, preferred first, as in `x-avrix-scopes`), `details.missingScope` names the preferred one and `details.scopeMode` is `anyOf`, or `any` when any Seller API scope is enough. On earlier contract dates the same refusal is `FORBIDDEN` with the `details.missingScope` and `details.requiredScopes` it has always carried. A key with no scopes at all also carries `details.reason: \"scopes_required\"`. Nothing was changed.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"examples":{"insufficientScopeContractDate20261201":{"summary":"Missing scope, contract date 2026-12-01 and later","value":{"code":"INSUFFICIENT_SCOPE","message":"API key missing required scope: seller:refunds:write or seller:keys:pull","details":{"missingScope":"seller:refunds:write","requiredScopes":["seller:refunds:write","seller:orders:write","seller:keys:pull"],"scopeMode":"anyOf"},"timestamp":"2026-12-01T10:15:00.000Z","error":"API key missing required scope: seller:refunds:write or seller:keys:pull","recoverable":false,"hint":"API key is missing a required scope (empty scopes are denied). Create a key with explicit scopes.","doc_url":"https://docs.avrix.io/seller-api/errors#insufficient-scope","requestId":"0198c2f4-7b1e-8c3a-9d2f-5e6a7b8c9d02"}},"missingScopeEarlierContractDates":{"summary":"Missing scope, contract dates before 2026-12-01","value":{"code":"FORBIDDEN","message":"API key missing required scope: seller:refunds:write or seller:keys:pull","details":{"missingScope":"seller:refunds:write","requiredScopes":["seller:refunds:write","seller:keys:pull"]},"timestamp":"2026-11-12T10:15:00.000Z","error":"API key missing required scope: seller:refunds:write or seller:keys:pull","recoverable":false,"hint":"Check API key scopes and permissions","doc_url":"https://docs.avrix.io/seller-api/errors#forbidden","requestId":"0198c2f4-7b1e-8c3a-9d2f-5e6a7b8c9d02"}}}}},"headers":{"X-Request-Id":{"$ref":"#/components/headers/XRequestId"},"X-Avrix-Api-Version":{"$ref":"#/components/headers/XAvrixApiVersion"},"X-Api-Version":{"$ref":"#/components/headers/XApiVersion"}}},"SellerApiRateLimited":{"description":"The rate limit of the bucket this request is counted against was exceeded. Wait `Retry-After` seconds, then retry. `X-RateLimit-Reset` (Unix seconds) says when the window resets. `X-RateLimit-Bucket` and `details.rateLimitBucket` name the bucket (`<class>:<kind>`); `details.limit` and `details.retryAfterSeconds` repeat the limit and the wait.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}},"headers":{"X-Request-Id":{"$ref":"#/components/headers/XRequestId"},"X-Avrix-Api-Version":{"$ref":"#/components/headers/XAvrixApiVersion"},"X-Api-Version":{"$ref":"#/components/headers/XApiVersion"},"Retry-After":{"$ref":"#/components/headers/RetryAfter"},"X-RateLimit-Limit":{"description":"Requests allowed per window in the bucket that refused the request. Sent with every `429` from the limiter. Not sent on a sandbox `429` simulated with `X-Avrix-Sandbox-Simulate: rate_limit`, which is answered before the request is counted.","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"`0`: nothing is left in the current window of that bucket. Sent with every `429` from the limiter. Not sent on a sandbox `429` simulated with `X-Avrix-Sandbox-Simulate: rate_limit`, which is answered before the request is counted.","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"Unix timestamp in seconds when the current window of that bucket resets. Sent with every `429` from the limiter. Not sent on a sandbox `429` simulated with `X-Avrix-Sandbox-Simulate: rate_limit`, which is answered before the request is counted.","schema":{"type":"integer","format":"int64"}},"X-RateLimit-Bucket":{"description":"The bucket that refused the request, as `<class>:<kind>` (see the `XRateLimitBucket` header component). Sent with every `429` from the Seller API limiter. Not sent on a sandbox `429` simulated with `X-Avrix-Sandbox-Simulate: rate_limit`, which is answered before the request is counted.","schema":{"type":"string","pattern":"^(catalog|orders|finance|webhooks-mgmt|general):(read|read-cached|write|snapshot)$"}}}},"SellerApiInternalError":{"description":"Unexpected server error.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}},"headers":{"X-Request-Id":{"$ref":"#/components/headers/XRequestId"},"X-Avrix-Api-Version":{"$ref":"#/components/headers/XAvrixApiVersion"},"X-Api-Version":{"$ref":"#/components/headers/XApiVersion"}}},"SellerApiIdempotencyKeyRequired":{"description":"The `Idempotency-Key` header is missing or malformed. The code is `IDEMPOTENCY_KEY_REQUIRED` on contract date `2026-12-01` and later, with `details.idempotency` (`key_missing` or `key_invalid`), `details.maxLength` and `details.pattern`; on earlier contract dates the same refusal is `BAD_REQUEST`. Nothing was changed. An `X-Avrix-Api-Version` this API does not serve is refused with the same status (`UNSUPPORTED_API_VERSION`, with `details.supportedVersions`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"examples":{"contractDate20261201":{"summary":"Contract date 2026-12-01 and later","value":{"code":"IDEMPOTENCY_KEY_REQUIRED","message":"Idempotency-Key header is required for this operation.","details":{"header":"Idempotency-Key","idempotency":"key_missing","maxLength":64,"pattern":"^[a-zA-Z0-9_-]+$"},"timestamp":"2026-12-01T10:15:00.000Z","error":"Idempotency-Key header is required for this operation.","recoverable":false,"hint":"Send an Idempotency-Key header with this request: 1 to 64 characters from A-Z, a-z, 0-9, hyphen and underscore (a UUID fits). `details.idempotency` says whether the header was missing (`key_missing`) or malformed (`key_invalid`). Keep the key and reuse it when you retry the same write.","doc_url":"https://docs.avrix.io/seller-api/errors#idempotency-key-required","requestId":"0198c2f4-7b1e-8c3a-9d2f-5e6a7b8c9d01"}},"earlierContractDates":{"summary":"Contract dates before 2026-12-01","value":{"code":"BAD_REQUEST","message":"Idempotency-Key header is required for this operation.","details":{"header":"Idempotency-Key"},"timestamp":"2026-11-12T10:15:00.000Z","error":"Idempotency-Key header is required for this operation.","recoverable":false,"hint":"Verify request body and parameters","doc_url":"https://docs.avrix.io/seller-api/errors#bad-request","requestId":"0198c2f4-7b1e-8c3a-9d2f-5e6a7b8c9d01"}}}}},"headers":{"X-Request-Id":{"$ref":"#/components/headers/XRequestId"},"X-Avrix-Api-Version":{"$ref":"#/components/headers/XAvrixApiVersion"},"X-Api-Version":{"$ref":"#/components/headers/XApiVersion"}}},"SellerApiUnsupportedApiVersion":{"description":"`UNSUPPORTED_API_VERSION`: the `X-Avrix-Api-Version` request header names a contract date this API does not serve. `details.supportedVersions` lists the dates you can pin and `details.requestedVersion` repeats what you sent. Send a listed date, or omit the header to be served on the stamped default. `INVALID_REQUEST_ID` (contract date `2026-12-01` and later): the `X-Request-Id` request header is not 8 to 128 characters from `A-Z`, `a-z`, `0-9`, `_`, `.`, `:` and `-`; `details` gives the format. Send a valid id or omit the header. Nothing was read or changed in either case.","headers":{"X-Request-Id":{"$ref":"#/components/headers/XRequestId"},"X-Avrix-Api-Version":{"$ref":"#/components/headers/XAvrixApiVersion"},"X-Api-Version":{"$ref":"#/components/headers/XApiVersion"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"SellerApiValidationFailed":{"description":"`VALIDATION_FAILED`: a path parameter, a query parameter or the JSON body was refused. `details.issues` names each field with what is wrong, and `details.validationTarget` says which part of the request it was (`path`, `query` or `json_body`). On a GET this includes a query parameter the operation does not take. Nothing was changed; correct the request before you send it again.","headers":{"X-Request-Id":{"$ref":"#/components/headers/XRequestId"},"X-Avrix-Api-Version":{"$ref":"#/components/headers/XAvrixApiVersion"},"X-Api-Version":{"$ref":"#/components/headers/XApiVersion"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"SellerApiIdempotencyConflict":{"description":"The `Idempotency-Key` cannot be used for this request. `IDEMPOTENCY_KEY_MISMATCH`: the key was already used with a different body; use a new key for a new request. `IDEMPOTENCY_REQUEST_IN_FLIGHT`: an earlier request with this key is still running; wait `Retry-After` seconds and send the same request again.","headers":{"X-Request-Id":{"$ref":"#/components/headers/XRequestId"},"X-Avrix-Api-Version":{"$ref":"#/components/headers/XAvrixApiVersion"},"X-Api-Version":{"$ref":"#/components/headers/XApiVersion"},"Retry-After":{"$ref":"#/components/headers/RetryAfter"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"SellerApiPayloadTooLarge":{"description":"`PAYLOAD_TOO_LARGE`: the request body is larger than 100 KB. Nothing was read or changed.","headers":{"X-Request-Id":{"$ref":"#/components/headers/XRequestId"},"X-Avrix-Api-Version":{"$ref":"#/components/headers/XAvrixApiVersion"},"X-Api-Version":{"$ref":"#/components/headers/XApiVersion"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"SellerApiServiceUnavailable":{"description":"Something this request needs is temporarily unavailable. Wait `Retry-After` seconds and send the same request again; on a write, keep the same `Idempotency-Key`. `SERVICE_UNAVAILABLE`: the database or another platform dependency did not accept the call. `IDEMPOTENCY_STORE_UNAVAILABLE` (writes that send an `Idempotency-Key`): the claim could not be recorded, so nothing was done. `SANDBOX_ENVIRONMENT_UNAVAILABLE` (sandbox keys): your store's isolated sandbox environment is being prepared or repaired.","headers":{"X-Request-Id":{"$ref":"#/components/headers/XRequestId"},"X-Avrix-Api-Version":{"$ref":"#/components/headers/XAvrixApiVersion"},"X-Api-Version":{"$ref":"#/components/headers/XApiVersion"},"Retry-After":{"$ref":"#/components/headers/RetryAfter"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"SellerApiTimeout":{"description":"`HOT_PATH_TIMEOUT`: the database did not answer in time. Wait `Retry-After` seconds and send the same request again; on a write, keep the same `Idempotency-Key`, so an attempt that did complete is replayed and not repeated.","headers":{"X-Request-Id":{"$ref":"#/components/headers/XRequestId"},"X-Avrix-Api-Version":{"$ref":"#/components/headers/XAvrixApiVersion"},"X-Api-Version":{"$ref":"#/components/headers/XApiVersion"},"Retry-After":{"$ref":"#/components/headers/RetryAfter"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}},"schemas":{"WebhookPlatformNotice":{"description":"An announcement about the Seller API itself: a contract change, a deprecation, a change of the default contract date, the switch of rate limits to enforced, or planned maintenance. Sent to every endpoint subscribed to `platform.notice`; it carries no data about your company.","allOf":[{"$ref":"#/components/schemas/WebhookEnvelope"},{"type":"object","required":["eventType","noticeId","category","actionRequired","title","summary","effectiveAt","contractDate","affects","url","publishedAt"],"properties":{"eventType":{"type":"string","const":"platform.notice"},"noticeId":{"type":"string","pattern":"^[a-z0-9][a-z0-9-]*$","maxLength":100,"description":"Stable id of the notice: the same on every delivery to every endpoint. Deduplicate on it, not on `eventId`, when several of your endpoints subscribe."},"category":{"type":"string","enum":["api_change","deprecation","contract_date","rate_limits","maintenance","other"],"description":"What the notice is about. New values may be added; treat an unknown one as `other`."},"actionRequired":{"type":"boolean","description":"True when an integration may have to change something before `effectiveAt`."},"title":{"type":"string","maxLength":140},"summary":{"type":"string","maxLength":1000,"description":"Plain text."},"effectiveAt":{"type":["string","null"],"format":"date-time","description":"When the change takes effect; null when there is no single date."},"contractDate":{"type":["string","null"],"pattern":"^\\d{4}-\\d{2}-\\d{2}$","description":"The contract date the notice concerns, if any."},"affects":{"type":"array","maxItems":50,"items":{"type":"string"},"description":"Operations (for example `POST /orders`) or event names the notice concerns. Empty when it concerns the whole API."},"url":{"type":"string","format":"uri","description":"Public page with the details, normally the changelog entry."},"publishedAt":{"type":"string","format":"date-time"}}}]},"WebhookOrderCancelled":{"description":"A pre-order, backorder or reserved order was cancelled before delivery (`POST /orders/cancel`); no keys were delivered. The same event is delivered as `order.returned` to endpoints that subscribe to that older name, with the same `eventLogId`.","allOf":[{"$ref":"#/components/schemas/WebhookEnvelope"},{"type":"object","required":["eventType","orderReference","cancelled"],"properties":{"eventType":{"type":"string","const":"order.cancelled"},"orderReference":{"type":"string"},"orderId":{"type":"string","description":"Readable order id, when the cancelled order has one."},"cancelled":{"type":"integer","description":"Number of reservations cancelled."},"reason":{"type":["string","null"]}}}]},"WebhookAllocationRequestDecided":{"description":"An allocation request you filed was decided: approved or denied by the Content Owner, or granted automatically by the Content Owner's rules.","allOf":[{"$ref":"#/components/schemas/WebhookEnvelope"},{"type":"object","required":["eventType","requestId","resolution","automatic","skuId","publisherCompanyId","requestedQuantity","grantedQuantity","decidedAt"],"properties":{"eventType":{"type":"string","const":"allocation.request_decided"},"requestId":{"type":"string","description":"The request, as `POST /allocations/requests` returned it."},"resolution":{"type":"string","enum":["approved","denied","auto_granted"]},"automatic":{"type":"boolean","description":"True when the Content Owner's rules decided without a person (`auto_granted`)."},"skuId":{"type":"string"},"publisherCompanyId":{"type":"string","description":"The Content Owner's company id."},"allocationId":{"type":["string","null"],"description":"The allocation the grant went to; null when denied."},"requestedQuantity":{"type":"integer"},"grantedQuantity":{"type":"integer","minimum":0,"description":"Keys granted; 0 when denied."},"decisionNote":{"type":["string","null"],"description":"The Content Owner's note, when they wrote one."},"decidedAt":{"type":"string","format":"date-time"}}}]},"WebhookProductAdded":{"description":"A product entered your catalog: an agreement or a share now lets you sell it. Read it with `GET /products/{id}`. Recorded in the same database transaction as the catalog change, so it is never lost when the change commits.","allOf":[{"$ref":"#/components/schemas/WebhookEnvelope"},{"type":"object","required":["eventType","productId","publisherCompanyId"],"properties":{"eventType":{"type":"string","const":"product.added"},"productId":{"type":"string"},"publisherCompanyId":{"type":"string","description":"The Content Owner's company id."}}}]},"WebhookContractExpiring":{"description":"An agreement term reaches its end date soon and has not been renewed. Sent about 30, 14 and 7 days ahead (`windowDays`).","allOf":[{"$ref":"#/components/schemas/WebhookEnvelope"},{"type":"object","required":["eventType","connectionId","publisherCompanyId","contractType","termId","validUntil","windowDays","changedAt"],"properties":{"eventType":{"type":"string","const":"contract.expiring"},"connectionId":{"type":"string"},"publisherCompanyId":{"type":"string","description":"The Content Owner's company id."},"contractType":{"type":"string","description":"The agreement type of the term: `api`, `wholesale` or another type `GET /contracts` lists."},"termId":{"type":"string","description":"The agreement term, as `GET /contracts` names it."},"changedAt":{"type":"string","format":"date-time"},"validUntil":{"type":["string","null"],"format":"date-time","description":"When the term ends."},"windowDays":{"type":["integer","null"],"description":"Days left in the notice window that triggered this event."}}}]},"WebhookContractExpired":{"description":"An agreement term passed its end date without renewal. New allocations and orders under it fail until a new term is active.","allOf":[{"$ref":"#/components/schemas/WebhookEnvelope"},{"type":"object","required":["eventType","connectionId","publisherCompanyId","contractType","termId","validUntil","changedAt"],"properties":{"eventType":{"type":"string","const":"contract.expired"},"connectionId":{"type":"string"},"publisherCompanyId":{"type":"string","description":"The Content Owner's company id."},"contractType":{"type":"string","description":"The agreement type of the term: `api`, `wholesale` or another type `GET /contracts` lists."},"termId":{"type":"string","description":"The agreement term, as `GET /contracts` names it."},"changedAt":{"type":"string","format":"date-time"},"validUntil":{"type":["string","null"],"format":"date-time","description":"When the term ended."}}}]},"WebhookContractTerminated":{"description":"An agreement term ended at the close of its notice period.","allOf":[{"$ref":"#/components/schemas/WebhookEnvelope"},{"type":"object","required":["eventType","connectionId","publisherCompanyId","contractType","termId","changedAt"],"properties":{"eventType":{"type":"string","const":"contract.terminated"},"connectionId":{"type":"string"},"publisherCompanyId":{"type":"string","description":"The Content Owner's company id."},"contractType":{"type":"string","description":"The agreement type of the term: `api`, `wholesale` or another type `GET /contracts` lists."},"termId":{"type":"string","description":"The agreement term, as `GET /contracts` names it."},"changedAt":{"type":"string","format":"date-time"}}}]},"WebhookConnectionSuspended":{"description":"The Content Owner suspended your connection. Its shares and allocations are paused until it is reactivated.","allOf":[{"$ref":"#/components/schemas/WebhookEnvelope"},{"type":"object","required":["eventType","connectionId","publisherCompanyId","initiatedBy","changedAt"],"properties":{"eventType":{"type":"string","const":"connection.suspended"},"connectionId":{"type":"string"},"publisherCompanyId":{"type":"string","description":"The Content Owner's company id."},"initiatedBy":{"type":"string","enum":["publisher","seller","platform"],"description":"Who made the change: the Content Owner (`publisher`), your company (`seller`), or the platform (`platform`, the connection has no agreement left)."},"changedAt":{"type":"string","format":"date-time"}}}]},"WebhookConnectionReactivated":{"description":"A suspended connection was reactivated.","allOf":[{"$ref":"#/components/schemas/WebhookEnvelope"},{"type":"object","required":["eventType","connectionId","publisherCompanyId","initiatedBy","changedAt"],"properties":{"eventType":{"type":"string","const":"connection.reactivated"},"connectionId":{"type":"string"},"publisherCompanyId":{"type":"string","description":"The Content Owner's company id."},"initiatedBy":{"type":"string","enum":["publisher","seller","platform"],"description":"Who made the change: the Content Owner (`publisher`), your company (`seller`), or the platform (`platform`, the connection has no agreement left)."},"changedAt":{"type":"string","format":"date-time"}}}]},"WebhookConnectionEnded":{"description":"Your connection with a Content Owner was closed, by either side or by the platform because no agreement remains.","allOf":[{"$ref":"#/components/schemas/WebhookEnvelope"},{"type":"object","required":["eventType","connectionId","publisherCompanyId","initiatedBy","changedAt"],"properties":{"eventType":{"type":"string","const":"connection.ended"},"connectionId":{"type":"string"},"publisherCompanyId":{"type":"string","description":"The Content Owner's company id."},"initiatedBy":{"type":"string","enum":["publisher","seller","platform"],"description":"Who made the change: the Content Owner (`publisher`), your company (`seller`), or the platform (`platform`, the connection has no agreement left)."},"changedAt":{"type":"string","format":"date-time"}}}]},"WebhookConnectionRequestDecided":{"description":"A Content Owner approved or rejected a connection request your company sent. Not sent for a Content Owner's invitation, which you answer yourself.","allOf":[{"$ref":"#/components/schemas/WebhookEnvelope"},{"type":"object","required":["eventType","requestId","decision","publisherCompanyId","connectionId","reviewNote","requestedAt","decidedAt"],"properties":{"eventType":{"type":"string","const":"connection.request_decided"},"requestId":{"type":"string","format":"uuid","description":"The request, as `GET /partners` names it in `connectionRequest.requestId`."},"decision":{"type":"string","enum":["approved","rejected"],"description":"What the Content Owner decided."},"publisherCompanyId":{"type":"string","description":"The Content Owner's company id."},"connectionId":{"type":["string","null"],"format":"uuid","description":"`approved`: the connection the approval created, as `GET /partners` lists it from now on. Its agreements still need signing; `contract.activated` follows when one becomes active. `rejected`: null."},"reviewNote":{"type":["string","null"],"description":"`rejected`: the note the Content Owner left, or null when they left none. `approved`: null."},"requestedAt":{"type":"string","format":"date-time","description":"When your company sent the request."},"decidedAt":{"type":"string","format":"date-time"}}}]},"WebhookAccessProposalCreated":{"description":"A Content Owner proposed more countries or a currency on a connection. Answer with `POST /access/proposals/{id}/accept` or `/decline`.","allOf":[{"$ref":"#/components/schemas/WebhookEnvelope"},{"type":"object","required":["eventType","proposalId","proposalType","connectionId","contractTermId","publisherCompanyId","proposedAt"],"properties":{"eventType":{"type":"string","const":"access.proposal_created"},"proposalId":{"type":"string","description":"The proposal, as `GET /access/proposals` names it."},"proposalType":{"type":"string","enum":["territory_added","currency_added"],"description":"`territory_added` (more countries) or `currency_added` (a currency), as `GET /access/proposals` names it."},"connectionId":{"type":"string"},"contractTermId":{"type":"string"},"publisherCompanyId":{"type":"string","description":"The Content Owner's company id."},"effectiveFrom":{"type":["string","null"],"format":"date-time","description":"When the proposed access would start, when the Content Owner set a date."},"proposedAt":{"type":"string","format":"date-time"}}}]},"WebhookReturnDecided":{"description":"The Content Owner approved or rejected a key return request you filed.","allOf":[{"$ref":"#/components/schemas/WebhookEnvelope"},{"type":"object","required":["eventType","returnRequestId","decision","publisherCompanyId","decidedAt"],"properties":{"eventType":{"type":"string","const":"return.decided"},"returnRequestId":{"type":"string"},"decision":{"type":"string","enum":["approved","rejected"]},"resolution":{"type":["string","null"],"enum":["refund","replacement",null],"description":"How an approved return is settled; null when rejected."},"publisherCompanyId":{"type":"string","description":"The Content Owner's company id."},"keyCount":{"type":["integer","null"],"description":"Keys in the request, when known."},"decisionNote":{"type":["string","null"],"description":"The Content Owner's note, when they wrote one."},"decidedAt":{"type":"string","format":"date-time"}}}]},"WebhookReturnInformationRequested":{"description":"The Content Owner needs more information about a key return request you filed.","allOf":[{"$ref":"#/components/schemas/WebhookEnvelope"},{"type":"object","required":["eventType","returnRequestId","publisherCompanyId","requestedAt"],"properties":{"eventType":{"type":"string","const":"return.information_requested"},"returnRequestId":{"type":"string"},"publisherCompanyId":{"type":"string","description":"The Content Owner's company id."},"requestedAt":{"type":"string","format":"date-time"}}}]},"WebhookPromotionOffered":{"description":"A vendor offered you a promotion: a platform event share or a custom deal. Answer before `respondBy`.","allOf":[{"$ref":"#/components/schemas/WebhookEnvelope"},{"$ref":"#/components/schemas/WebhookPromotionEventFields"},{"type":"object","required":["eventType"],"properties":{"eventType":{"type":"string","const":"promotion.offered"}}}]},"WebhookPromotionChanged":{"description":"The vendor changed the products or discounts of a promotion offered to you. When `answerAgain` is true your acceptance was reset to `pending`: read the offer again and answer it.","allOf":[{"$ref":"#/components/schemas/WebhookEnvelope"},{"$ref":"#/components/schemas/WebhookPromotionEventFields"},{"type":"object","required":["eventType"],"properties":{"eventType":{"type":"string","const":"promotion.changed"},"changes":{"type":"object","properties":{"addedCount":{"type":"integer"},"removedCount":{"type":"integer"},"updatedCount":{"type":"integer"}}},"answerAgain":{"type":"boolean","description":"True when you had accepted and must answer again."}}}]},"WebhookPromotionAccepted":{"description":"Your company accepted a promotion, over the API or in the console.","allOf":[{"$ref":"#/components/schemas/WebhookEnvelope"},{"$ref":"#/components/schemas/WebhookPromotionEventFields"},{"type":"object","required":["eventType"],"properties":{"eventType":{"type":"string","const":"promotion.accepted"}}}]},"WebhookPromotionDeclined":{"description":"Your company declined a promotion, over the API or in the console.","allOf":[{"$ref":"#/components/schemas/WebhookEnvelope"},{"$ref":"#/components/schemas/WebhookPromotionEventFields"},{"type":"object","required":["eventType"],"properties":{"eventType":{"type":"string","const":"promotion.declined"}}}]},"WebhookPromotionWithdrawn":{"description":"The vendor withdrew a promotion that was offered to you or that you had accepted. Its discounts stop at once.","allOf":[{"$ref":"#/components/schemas/WebhookEnvelope"},{"$ref":"#/components/schemas/WebhookPromotionEventFields"},{"type":"object","required":["eventType"],"properties":{"eventType":{"type":"string","const":"promotion.withdrawn"}}}]},"WebhookPromotionExpired":{"description":"A promotion offered to you was not answered by `respondBy` and can no longer be accepted.","allOf":[{"$ref":"#/components/schemas/WebhookEnvelope"},{"$ref":"#/components/schemas/WebhookPromotionEventFields"},{"type":"object","required":["eventType"],"properties":{"eventType":{"type":"string","const":"promotion.expired"}}}]},"WebhookPromotionStarted":{"description":"An accepted promotion's window opened: its discounted prices apply from now. Sent within about 15 minutes of `startDate`.","allOf":[{"$ref":"#/components/schemas/WebhookEnvelope"},{"$ref":"#/components/schemas/WebhookPromotionEventFields"},{"type":"object","required":["eventType"],"properties":{"eventType":{"type":"string","const":"promotion.started"}}}]},"WebhookPromotionEnded":{"description":"An accepted promotion's window closed: list and settlement prices are back to normal. Sent within about 15 minutes of `endDate`.","allOf":[{"$ref":"#/components/schemas/WebhookEnvelope"},{"$ref":"#/components/schemas/WebhookPromotionEventFields"},{"type":"object","required":["eventType"],"properties":{"eventType":{"type":"string","const":"promotion.ended"}}}]},"WebhookInvoiceIssued":{"description":"A Content Owner issued a monthly invoice to you. `status` says whether it is payable now (`payable`) or waits for the commission document (`awaiting_commission_document`).","allOf":[{"$ref":"#/components/schemas/WebhookEnvelope"},{"type":"object","required":["eventType","invoiceId","publisherCompanyId","status","currencyCode","currencyExponent"],"properties":{"eventType":{"type":"string","const":"invoice.issued"},"invoiceId":{"type":"string","description":"The invoice, as `GET /finance/invoices` names it."},"invoiceNumber":{"type":["string","null"],"description":"Deprecated: the vendor's own number when there is one, otherwise the platform number, while `GET /finance/invoices` sends the platform number under this name. Use `supplierInvoiceNumber` or `platformInvoiceNumber`. Value unchanged.","deprecated":true},"platformInvoiceNumber":{"type":["string","null"],"description":"The number Avrix gave the invoice; the same value `GET /finance/invoices` returns as `platformInvoiceNumber`."},"supplierInvoiceNumber":{"type":["string","null"],"description":"The vendor's own number for the invoice, when the vendor uses one; null otherwise. The same value on `GET /finance/invoices` and on invoice events."},"publisherCompanyId":{"type":"string","description":"The Content Owner's company id."},"status":{"type":"string","description":"The invoice status at the time of the event, as `GET /finance/invoices` shows it. Values as on `GET /finance/invoices`.","enum":["draft","awaiting_commission_document","payable","disputed","superseded","expired","sent","paid","overdue","cancelled","credited"],"x-extensible-enum":true},"totalCents":{"type":["integer","null"],"description":"Deprecated name of `totalMinor` (same value). Kept on the wire; see Naming conventions in the Versioning and compatibility guide. Invoice total in minor units of `currencyCode`.","deprecated":true},"totalMinor":{"type":["integer","null"],"description":"Invoice total in minor units of `currencyCode`. Same amount as `totalCents`, under the `...Minor` name every Seller API amount uses: integer minor units of the currency beside it (see `currencyExponent`)."},"currencyCode":{"type":"string"},"currencyExponent":{"type":"integer","minimum":0,"maximum":3,"description":"Number of minor-unit digits for `currencyCode`: 2 for USD, 0 for JPY, 3 for KWD."},"issuedAt":{"type":["string","null"],"format":"date-time"},"dueAt":{"type":["string","null"],"format":"date-time"},"replacesInvoiceId":{"type":"string","format":"uuid","description":"Only on a corrected invoice: the invoice it replaces."}}}]},"WebhookInvoicePaid":{"description":"Your payment of a monthly invoice was recorded.","allOf":[{"$ref":"#/components/schemas/WebhookEnvelope"},{"type":"object","required":["eventType","invoiceId","publisherCompanyId","status","currencyCode","currencyExponent","paidAt"],"properties":{"eventType":{"type":"string","const":"invoice.paid"},"invoiceId":{"type":"string","description":"The invoice, as `GET /finance/invoices` names it."},"invoiceNumber":{"type":["string","null"],"description":"Deprecated: the vendor's own number when there is one, otherwise the platform number, while `GET /finance/invoices` sends the platform number under this name. Use `supplierInvoiceNumber` or `platformInvoiceNumber`. Value unchanged.","deprecated":true},"platformInvoiceNumber":{"type":["string","null"],"description":"The number Avrix gave the invoice; the same value `GET /finance/invoices` returns as `platformInvoiceNumber`."},"supplierInvoiceNumber":{"type":["string","null"],"description":"The vendor's own number for the invoice, when the vendor uses one; null otherwise. The same value on `GET /finance/invoices` and on invoice events."},"publisherCompanyId":{"type":"string","description":"The Content Owner's company id."},"status":{"type":"string","description":"The invoice status at the time of the event, as `GET /finance/invoices` shows it. Values as on `GET /finance/invoices`.","enum":["draft","awaiting_commission_document","payable","disputed","superseded","expired","sent","paid","overdue","cancelled","credited"],"x-extensible-enum":true},"totalCents":{"type":["integer","null"],"description":"Deprecated name of `totalMinor` (same value). Kept on the wire; see Naming conventions in the Versioning and compatibility guide. Invoice total in minor units of `currencyCode`.","deprecated":true},"totalMinor":{"type":["integer","null"],"description":"Invoice total in minor units of `currencyCode`. Same amount as `totalCents`, under the `...Minor` name every Seller API amount uses: integer minor units of the currency beside it (see `currencyExponent`)."},"currencyCode":{"type":"string"},"currencyExponent":{"type":"integer","minimum":0,"maximum":3,"description":"Number of minor-unit digits for `currencyCode`: 2 for USD, 0 for JPY, 3 for KWD."},"issuedAt":{"type":["string","null"],"format":"date-time"},"dueAt":{"type":["string","null"],"format":"date-time"},"paidAt":{"type":"string","format":"date-time"},"replacesInvoiceId":{"type":"string","format":"uuid","description":"Only on a corrected invoice: the invoice it replaces."}}}]},"WebhookInvoiceOverdue":{"description":"A monthly invoice passed its due date unpaid. It stays payable; `status` is `overdue`.","allOf":[{"$ref":"#/components/schemas/WebhookEnvelope"},{"type":"object","required":["eventType","invoiceId","publisherCompanyId","status","currencyCode","currencyExponent"],"properties":{"eventType":{"type":"string","const":"invoice.overdue"},"invoiceId":{"type":"string","description":"The invoice, as `GET /finance/invoices` names it."},"invoiceNumber":{"type":["string","null"],"description":"The Content Owner's invoice number."},"publisherCompanyId":{"type":"string","description":"The Content Owner's company id."},"status":{"type":"string","description":"The invoice status at the time of the event, as `GET /finance/invoices` shows it."},"totalCents":{"type":["integer","null"],"description":"Deprecated name of `totalMinor` (same value). Kept on the wire; see Naming conventions in the Versioning and compatibility guide. Invoice total in minor units of `currencyCode`.","deprecated":true},"totalMinor":{"type":["integer","null"],"description":"Invoice total in minor units of `currencyCode`. Same amount as `totalCents`, under the `...Minor` name every Seller API amount uses: integer minor units of the currency beside it (see `currencyExponent`)."},"currencyCode":{"type":"string"},"currencyExponent":{"type":"integer","minimum":0,"maximum":3,"description":"Number of minor-unit digits for `currencyCode`: 2 for USD, 0 for JPY, 3 for KWD."},"issuedAt":{"type":["string","null"],"format":"date-time"},"dueAt":{"type":["string","null"],"format":"date-time"},"replacesInvoiceId":{"type":"string","format":"uuid","description":"Only on a corrected invoice: the invoice it replaces."},"platformInvoiceNumber":{"type":["string","null"],"description":"The number Avrix gave the invoice; the same value `GET /finance/invoices` returns as `platformInvoiceNumber`."},"supplierInvoiceNumber":{"type":["string","null"],"description":"The vendor's own number for the invoice, when the vendor uses one; null otherwise. The same value on `GET /finance/invoices` and on invoice events."}}}]},"WebhookInvoiceDisputed":{"description":"You disputed a monthly invoice. Payment is paused until the vendor answers; `status` is `disputed`.","allOf":[{"$ref":"#/components/schemas/WebhookEnvelope"},{"type":"object","required":["eventType","invoiceId","publisherCompanyId","status","currencyCode","currencyExponent","disputeId"],"properties":{"eventType":{"type":"string","const":"invoice.disputed"},"invoiceId":{"type":"string","description":"The invoice, as `GET /finance/invoices` names it."},"invoiceNumber":{"type":["string","null"],"description":"The Content Owner's invoice number."},"publisherCompanyId":{"type":"string","description":"The Content Owner's company id."},"status":{"type":"string","description":"The invoice status at the time of the event, as `GET /finance/invoices` shows it."},"totalCents":{"type":["integer","null"],"description":"Deprecated name of `totalMinor` (same value). Kept on the wire; see Naming conventions in the Versioning and compatibility guide. Invoice total in minor units of `currencyCode`.","deprecated":true},"totalMinor":{"type":["integer","null"],"description":"Invoice total in minor units of `currencyCode`. Same amount as `totalCents`, under the `...Minor` name every Seller API amount uses: integer minor units of the currency beside it (see `currencyExponent`)."},"currencyCode":{"type":"string"},"currencyExponent":{"type":"integer","minimum":0,"maximum":3,"description":"Number of minor-unit digits for `currencyCode`: 2 for USD, 0 for JPY, 3 for KWD."},"issuedAt":{"type":["string","null"],"format":"date-time"},"dueAt":{"type":["string","null"],"format":"date-time"},"replacesInvoiceId":{"type":"string","format":"uuid","description":"Only on a corrected invoice: the invoice it replaces."},"disputeId":{"type":"string","format":"uuid","description":"The dispute, as `GET /finance/invoices/{invoiceId}` lists it under `disputes`."},"platformInvoiceNumber":{"type":["string","null"],"description":"The number Avrix gave the invoice; the same value `GET /finance/invoices` returns as `platformInvoiceNumber`."},"supplierInvoiceNumber":{"type":["string","null"],"description":"The vendor's own number for the invoice, when the vendor uses one; null otherwise. The same value on `GET /finance/invoices` and on invoice events."}}}]},"WebhookInvoiceDisputeUpdated":{"description":"The vendor answered your dispute of a monthly invoice, or you withdrew it. `outcome` says how; `status` says whether the invoice is payable again (`payable` after `rejected` or `withdrawn`) or waits for a corrected invoice (`disputed` after `accepted`).","allOf":[{"$ref":"#/components/schemas/WebhookEnvelope"},{"type":"object","required":["eventType","invoiceId","publisherCompanyId","status","currencyCode","currencyExponent","disputeId","outcome"],"properties":{"eventType":{"type":"string","const":"invoice.dispute_updated"},"invoiceId":{"type":"string","description":"The invoice, as `GET /finance/invoices` names it."},"invoiceNumber":{"type":["string","null"],"description":"The Content Owner's invoice number."},"publisherCompanyId":{"type":"string","description":"The Content Owner's company id."},"status":{"type":"string","description":"The invoice status at the time of the event, as `GET /finance/invoices` shows it."},"totalCents":{"type":["integer","null"],"description":"Deprecated name of `totalMinor` (same value). Kept on the wire; see Naming conventions in the Versioning and compatibility guide. Invoice total in minor units of `currencyCode`.","deprecated":true},"totalMinor":{"type":["integer","null"],"description":"Invoice total in minor units of `currencyCode`. Same amount as `totalCents`, under the `...Minor` name every Seller API amount uses: integer minor units of the currency beside it (see `currencyExponent`)."},"currencyCode":{"type":"string"},"currencyExponent":{"type":"integer","minimum":0,"maximum":3,"description":"Number of minor-unit digits for `currencyCode`: 2 for USD, 0 for JPY, 3 for KWD."},"issuedAt":{"type":["string","null"],"format":"date-time"},"dueAt":{"type":["string","null"],"format":"date-time"},"replacesInvoiceId":{"type":"string","format":"uuid","description":"Only on a corrected invoice: the invoice it replaces."},"disputeId":{"type":"string","format":"uuid","description":"The dispute, as `GET /finance/invoices/{invoiceId}` lists it under `disputes`."},"outcome":{"type":"string","enum":["accepted","rejected","withdrawn","escalated"],"description":"`accepted`: a corrected invoice follows and names this one in `replacesInvoiceId`. `rejected` or `withdrawn`: the invoice stands. `escalated`: Avrix support reviews it."},"platformInvoiceNumber":{"type":["string","null"],"description":"The number Avrix gave the invoice; the same value `GET /finance/invoices` returns as `platformInvoiceNumber`."},"supplierInvoiceNumber":{"type":["string","null"],"description":"The vendor's own number for the invoice, when the vendor uses one; null otherwise. The same value on `GET /finance/invoices` and on invoice events."}}}]},"WebhookApiKeyCreated":{"description":"An API key was created for your company, in the console or with `POST /keys`. Carries no secret.","allOf":[{"$ref":"#/components/schemas/WebhookEnvelope"},{"type":"object","required":["eventType","keyId","apiKeyId","via","changedAt"],"properties":{"eventType":{"type":"string","const":"api_key.created"},"keyId":{"type":"string","format":"uuid","description":"Deprecated name of `apiKeyId` (same value): `keyId` names a game key everywhere else.","deprecated":true},"apiKeyId":{"type":"string","format":"uuid","description":"The API key (credential) the event is about. `keyId` names a game key everywhere else in the API; this is the same value under the credential's own name."},"keyName":{"type":["string","null"],"description":"The key's name when the event knows it (`api_key.created`); null otherwise."},"environment":{"type":["string","null"],"enum":["production","sandbox",null],"description":"The key's environment when the event knows it; null otherwise."},"via":{"type":"string","enum":["console","api"],"description":"Whether the change was made in the console or through the Seller API."},"changedAt":{"type":"string","format":"date-time"}}}]},"WebhookApiKeyRotated":{"description":"An API key's secret was replaced, in the console or with `POST /keys/{id}/rotate`. The key id stays the same. Carries no secret.","allOf":[{"$ref":"#/components/schemas/WebhookEnvelope"},{"type":"object","required":["eventType","keyId","apiKeyId","via","changedAt"],"properties":{"eventType":{"type":"string","const":"api_key.rotated"},"keyId":{"type":"string","format":"uuid","description":"Deprecated name of `apiKeyId` (same value): `keyId` names a game key everywhere else.","deprecated":true},"apiKeyId":{"type":"string","format":"uuid","description":"The API key (credential) the event is about. `keyId` names a game key everywhere else in the API; this is the same value under the credential's own name."},"keyName":{"type":["string","null"],"description":"The key's name when the event knows it (`api_key.created`); null otherwise."},"environment":{"type":["string","null"],"enum":["production","sandbox",null],"description":"The key's environment when the event knows it; null otherwise."},"via":{"type":"string","enum":["console","api"],"description":"Whether the change was made in the console or through the Seller API."},"changedAt":{"type":"string","format":"date-time"}}}]},"WebhookApiKeyRevoked":{"description":"An API key was revoked, in the console or with `DELETE /keys/{id}`, and can no longer call the Seller API. Revoking every key sends one event per key.","allOf":[{"$ref":"#/components/schemas/WebhookEnvelope"},{"type":"object","required":["eventType","keyId","apiKeyId","via","changedAt"],"properties":{"eventType":{"type":"string","const":"api_key.revoked"},"keyId":{"type":"string","format":"uuid","description":"Deprecated name of `apiKeyId` (same value): `keyId` names a game key everywhere else.","deprecated":true},"apiKeyId":{"type":"string","format":"uuid","description":"The API key (credential) the event is about. `keyId` names a game key everywhere else in the API; this is the same value under the credential's own name."},"keyName":{"type":["string","null"],"description":"The key's name when the event knows it (`api_key.created`); null otherwise."},"environment":{"type":["string","null"],"enum":["production","sandbox",null],"description":"The key's environment when the event knows it; null otherwise."},"via":{"type":"string","enum":["console","api"],"description":"Whether the change was made in the console or through the Seller API."},"changedAt":{"type":"string","format":"date-time"}}}]},"WebhookSandboxCertificationPassed":{"description":"A sandbox key's certification report (`GET /sandbox/certification`) passed every case: the first time it does, and again only if it passes after a report with a failed case. Sent to the endpoints registered with that sandbox key. Passing does not enable production access by itself.","allOf":[{"$ref":"#/components/schemas/WebhookEnvelope"},{"type":"object","required":["eventType","keyId","keyName","environment","reportVersion","caseCount","firstPass","passedAt"],"properties":{"eventType":{"type":"string","const":"sandbox.certification_passed"},"keyId":{"type":"string","format":"uuid","description":"The sandbox key the report is for, as `GET /keys` lists it. Never the secret."},"keyName":{"type":["string","null"],"description":"The key's name."},"environment":{"type":"string","const":"sandbox"},"reportVersion":{"type":"integer","minimum":1,"description":"`reportVersion` of the report that passed."},"caseCount":{"type":"integer","minimum":1,"description":"How many cases the report evaluated; every one passed."},"firstPass":{"type":"boolean","description":"True the first time the key's report passes; false when it passes again after a report with a failed case."},"passedAt":{"type":"string","format":"date-time","description":"When the passing report was built."}}}]},"SellerIntegrationPresets":{"type":"object","required":["configured","salesChannel","paymentMethodFamily","priceIncludesTax","storeCountryCode","deriveAmounts"],"properties":{"configured":{"type":"boolean","description":"False when the store has no presets: orders then need every field in whoami.requiredDeclarationsByOperation."},"salesChannel":{"type":["string","null"],"description":"Default integrationOrderContext.salesChannel (web, mobile_app, partner_embed or marketplace:<slug>).","example":"web"},"paymentMethodFamily":{"type":["string","null"],"enum":["card","wallet","paypal","ideal","bancontact","sepa_debit","invoice","store_credit","gift_card","crypto","other",null],"example":"card"},"priceIncludesTax":{"type":["boolean","null"],"description":"Default priceIncludesTax. When null, the VAT reference for the sale country decides."},"storeCountryCode":{"type":["string","null"],"description":"Fallback sale country when the buyer IP cannot be located and the price commitment carries none.","example":"NL"},"deriveAmounts":{"type":"boolean","description":"When true (default), the server derives currencyCode, salesPriceGrossMinor, salesPriceNetMinor, salesTaxAmountMinor and salesTaxRatePercent from priceCommitmentToken, quantity and the VAT reference for the sale country. Not for countries whose reference is subnational (for example US sales tax): declare the rate there."},"updatedAt":{"type":["string","null"],"format":"date-time","description":"When the presets were last saved. Null when none are saved (and on the `DELETE` answer)."}}},"SellerIntegrationPresetsInput":{"type":"object","additionalProperties":false,"required":["salesChannel","paymentMethodFamily","priceIncludesTax","storeCountryCode"],"properties":{"salesChannel":{"type":["string","null"],"description":"Default integrationOrderContext.salesChannel (web, mobile_app, partner_embed or marketplace:<slug>).","example":"web"},"paymentMethodFamily":{"type":["string","null"],"enum":["card","wallet","paypal","ideal","bancontact","sepa_debit","invoice","store_credit","gift_card","crypto","other",null],"example":"card"},"priceIncludesTax":{"type":["boolean","null"],"description":"Default priceIncludesTax. When null, the VAT reference for the sale country decides."},"storeCountryCode":{"type":["string","null"],"description":"Fallback sale country when the buyer IP cannot be located and the price commitment carries none.","example":"NL"},"deriveAmounts":{"type":"boolean","description":"When true (default), the server derives currencyCode, salesPriceGrossMinor, salesPriceNetMinor, salesTaxAmountMinor and salesTaxRatePercent from priceCommitmentToken, quantity and the VAT reference for the sale country. Not for countries whose reference is subnational (for example US sales tax): declare the rate there."}}},"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."},"pending":{"type":"integer","description":"Queues (`webhookDelivery`, `outboxJobs`): rows still to deliver or run. For `webhookDelivery` this leaves out deliveries buffered for a disabled endpoint."},"buffered":{"type":"integer","description":"`webhookDelivery`: deliveries held for disabled endpoints until they are re-enabled. Informational; never degrades the status."},"dueLagSeconds":{"type":["integer","null"],"description":"Queues: how long the oldest row that is already due has waited past its due time. Rows waiting out a retry backoff, or buffered for a disabled endpoint, are not late. null when nothing is due."},"failedLast24h":{"type":"integer","description":"Queues: rows that reached terminal failure in the last 24 hours."},"oldestPendingAgeSeconds":{"type":"integer","description":"Queues: age since creation of the oldest pending row (includes rows in backoff, not deliveries buffered for a disabled endpoint)."}}},"SellerPartner":{"type":"object","description":"A vendor connection (the console Partners page: `active`, `suspended`, `terminating`, `terminated`) or a connection request (`pending`, `rejected`), with the vendor's public profile fields. On a connection row `connectionId` is `distribution.company_connections.id`; on a request row it is the request id and `connectionRequest` is set. Avatar URLs use the same resolution as the console (icon, then light or dark logo, then the legacy `logo_url`). The `publisher*` fields describe the vendor; the names are kept for compatibility.","required":["connectionId","sellerCompanyId","publisherCompanyId","publisherCompanyName","status","connectionCreatedAt","connectionUpdatedAt","automatedSalesReportInvoicing","contracts"],"properties":{"connectionId":{"type":"string","format":"uuid","description":"Connection id: pass it to `GET /partners/{connectionId}/offers` and `/agreements`. On a connection request row (`status` `pending` or `rejected`) it is the request id, which those operations answer with `404`; the connection gets its own id when the vendor approves."},"sellerCompanyId":{"type":"string","maxLength":32,"description":"Company id (slug-safe identifier, max 32 chars)"},"publisherCompanyId":{"type":"string","maxLength":32,"description":"The vendor's company id (slug-safe identifier, at most 32 characters; not a UUID). Pass it as `partner` to filter `GET /products` and `GET /catalog/checksum`."},"publisherCompanyName":{"type":"string"},"status":{"type":"string","description":"Connection status (`active`, `suspended`, `terminating`, `terminated`) or connection request status (`pending`, `rejected`). `terminating` and `pending` are listed by default from contract date `2026-12-01`, and on any date with `status`; `rejected` only with `status`. Ignore values you do not know.","enum":["active","suspended","terminated","terminating","pending","rejected"]},"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"},"connectionRequest":{"$ref":"#/components/schemas/SellerPartnerConnectionRequest"}}},"SellerPartnerConnectionRequest":{"type":"object","description":"Set only on a connection request row of `GET /partners` (`status` `pending` or `rejected`). A request to connect, sent by you or by the vendor (an invitation). Read only: requests are sent, answered, reminded and cancelled in the console.","required":["requestId","initiatedBy","waitingOn","requestedAt","decidedAt","reviewNote"],"properties":{"requestId":{"type":"string","format":"uuid","description":"The request id; also the row's `connectionId` while there is no connection."},"initiatedBy":{"type":"string","enum":["seller","vendor"],"description":"`seller`: you asked the vendor. `vendor`: the vendor invited you."},"waitingOn":{"type":["string","null"],"enum":["seller","vendor",null],"description":"Whose answer a `pending` request waits for; null once it was rejected."},"requestedAt":{"type":"string","format":"date-time"},"decidedAt":{"type":["string","null"],"format":"date-time","description":"When the request was rejected; null while pending."},"reviewNote":{"type":["string","null"],"description":"The note the vendor left when rejecting, as the console shows it to you."},"consoleUrl":{"type":"string","format":"uri","description":"Console page where you follow or answer the request, opened in the company that owns the API key."}},"example":{"requestId":"6f1d3c2a-8b7e-4c1d-9a2f-3e4b5c6d7e8f","initiatedBy":"seller","waitingOn":"vendor","requestedAt":"2026-11-10T09:30:00.000Z","decidedAt":null,"reviewNote":null,"consoleUrl":"https://app.avrix.io/network/partners/requests/6f1d3c2a-8b7e-4c1d-9a2f-3e4b5c6d7e8f?company=acme-store"}},"SellerPartnerAgreement":{"type":"object","description":"One agreed term on a vendor connection (`GET /partners/{connectionId}/agreements`). Fields a term does not state are null.","required":["termId","contractType","status","version","effectiveFrom","expiresAt","activatedAt","renewalPolicy","terminationNoticeAt","terminationEffectiveAt","territory","sellerRevenueSharePercent","paymentCurrency","paymentTermsDays","reportingFrequency","reportingDeadlineDays","permittedSaleCurrencies"],"properties":{"termId":{"type":"string","format":"uuid","description":"The agreement term id: `contracts.activeTerms[].termId` on `GET /partners`, `contractTermId` in events and on `GET /access/proposals`."},"contractType":{"type":"string","enum":["mca","api","revenue_share","wholesale","pre_order"],"description":"`mca` is the master agreement; the others are business-model agreements (BMA)."},"status":{"type":"string","enum":["active","terminating","paused"],"description":"`terminating`: notice given, still in force until `terminationEffectiveAt`. `paused`: signed but suspended; orders under it are refused until it resumes."},"version":{"type":"integer","minimum":1},"effectiveFrom":{"type":["string","null"],"format":"date-time","description":"Start of the agreement."},"expiresAt":{"type":["string","null"],"format":"date-time","description":"End date; null when it runs until terminated. `contract.expiring` warns ahead of it."},"activatedAt":{"type":["string","null"],"format":"date-time"},"renewalPolicy":{"type":"string","enum":["none","auto_renew"],"description":"`auto_renew`: renews itself at `expiresAt` unless a party gives notice."},"terminationNoticeAt":{"type":["string","null"],"format":"date-time","description":"When notice was given; null when none."},"terminationEffectiveAt":{"type":["string","null"],"format":"date-time","description":"When a `terminating` agreement ends."},"territory":{"type":["object","null"],"description":"Where this agreement lets you sell: the countries orders are checked against. Null on the master agreement.","required":["worldwide","countries"],"properties":{"worldwide":{"type":"boolean"},"countries":{"type":"array","items":{"type":"string","pattern":"^[A-Z]{2}$"},"description":"ISO 3166-1 alpha-2 codes, sorted; empty when `worldwide` is true or nothing is granted."}}},"sellerRevenueSharePercent":{"type":["number","null"],"minimum":0,"maximum":100,"description":"Your share of net revenue, 0 to 100, on `api` and `revenue_share` agreements."},"paymentCurrency":{"type":["string","null"],"pattern":"^[A-Z]{3}$","description":"ISO 4217 settlement currency."},"paymentTermsDays":{"type":["integer","null"],"minimum":0,"description":"Days to pay after the invoice; 0 is prepaid."},"reportingFrequency":{"type":["string","null"],"description":"`weekly`, `monthly`, `quarterly` or `on_demand`. Ignore values you do not know."},"reportingDeadlineDays":{"type":["integer","null"],"minimum":0,"description":"Days after a period ends by which the sales report is due."},"permittedSaleCurrencies":{"type":["string","null"],"description":"The sale-currency rule on an `api` agreement: `primary_only`, `all_catalog_currencies` or `custom`. Per-currency detail is on `GET /whoami` (`permittedCurrenciesByPublisher`)."},"consoleUrl":{"type":"string","format":"uri","description":"Console page with this connection's agreements and the signed documents, opened in the company that owns the API key."}}},"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 keyless delivery is on for the platform (on by default; hosted redemption, up to 20 keys per line). Each Content Owner can still refuse it: see GET /allocations keyless."},"orderReadModel":{"type":"string","enum":["durable","reconstruction"],"description":"Where this environment reads orders from. `durable`: the order table, which holds every status, so `GET /orders` lists and filters every order. `reconstruction`: rebuilt from delivered keys, so the order listing holds fulfilled, returned and refunded orders only (another `status` filter answers an empty page, or 422 on contract date `2026-12-01` and later); a single order is found by `orderId` or `orderReference` in both."},"preorderEnabled":{"type":"boolean","description":"True when this company may purchase launchPhase pre_order products. Default true; a Content Owner that opted out still refuses its own pre-order products with PRODUCT_NOT_SELLABLE (reason PREORDER_DISABLED)."},"backorderEnabled":{"type":"boolean","description":"True when customer-order backorders are enabled (default true; false only while the platform switch is off, when backorderOnUnavailable answers 403 FEATURE_DISABLED with details.reason BACKORDER_NOT_ENABLED). When true, POST /orders accepts awaiting_stock against headroom unless the Content Owner opted out (403 BACKORDER_NOT_ALLOWED). Unfulfilled backorders expire after 14 days with order.backorder_expired."},"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 (any buyerVerificationByPublisher entry whose level is not declared_ip). Always false for sandbox keys."},"buyerRiskScoringEnabled":{"type":"boolean","description":"True when the platform scores confirmed checkouts on connections whose buyerVerificationByPublisher level is checkout_attest_risk. False means such a connection currently behaves as checkout_attest. Always false for sandbox keys."},"buyerGeolocationStatus":{"type":"string","enum":["ok","degraded","unconfigured"],"description":"Health of the buyer geolocation data on this deployment. `degraded` means buyer countries are not detected (or the data is older than 35 days): a declared VAT rate above the store-country rate then settles at the store-country rate. `unconfigured` appears only on local development deployments. Mirrors `GET /health` `components.consumerGeo.status`."},"requireProductionAllowlistEnabled":{"type":"boolean","description":"True when this deployment refuses a production key that has no IP allowlist entry and no trusted workload (`403 ALLOWLIST_REQUIRED`). False: such a key accepts any source IP."},"sandboxMagicSkuEnforcement":{"type":"boolean","description":"Sandbox keys only, and only when present (always `true`): the sandbox enforces territory and catalog-price checks on its magic SKUs for this key."}}},"SellerPartnerAccessProposal":{"type":"object","description":"A Content Owner's proposal to widen what you may sell on one connection. Nothing changes until you accept it.","required":["id","type","worldwide","countryCodes","currencyCode","reason","effectiveFrom","proposedAt"],"properties":{"id":{"type":"string","format":"uuid","description":"Answer with POST /access/proposals/{id}/accept or /decline."},"type":{"type":"string","enum":["territory_added","currency_added"]},"worldwide":{"type":"boolean","description":"territory_added only: every country."},"countryCodes":{"type":["array","null"],"items":{"type":"string","pattern":"^[A-Z]{2}$"},"description":"territory_added: the countries offered. currency_added: the countries the currency may be sold in; null is throughout your territory."},"currencyCode":{"type":["string","null"],"pattern":"^[A-Z]{3}$","description":"currency_added only."},"reason":{"type":["string","null"],"description":"The Content Owner's note."},"effectiveFrom":{"type":["string","null"],"format":"date-time","description":"Applies from this time if later than your acceptance; null applies on acceptance."},"proposedAt":{"type":"string","format":"date-time"}}},"SellerPartnerAccess":{"type":"object","description":"Partner access on one connection: the countries and currencies this Content Owner lets you sell, the dated changes still to come, and proposals waiting for your answer.","required":["publisherCompanyId","contractTermId","connectionId","enforced","territories","currencies","pending","proposals"],"properties":{"publisherCompanyId":{"type":"string"},"contractTermId":{"type":"string"},"connectionId":{"type":"string"},"enforced":{"type":"boolean","description":"True when orders are checked against this. While false, your agreement governs and this is the same grant, seeded from it."},"territories":{"type":"object","required":["worldwide","countries","locked"],"properties":{"worldwide":{"type":"boolean"},"countries":{"type":"array","items":{"type":"string","pattern":"^[A-Z]{2}$"},"description":"Granted countries when not worldwide."},"locked":{"type":"array","description":"Countries the Content Owner locked, refused with REGION_LOCKED_FOR_CONTRACT and this reason.","items":{"type":"object","required":["countryCode","reason"],"properties":{"countryCode":{"type":"string","pattern":"^[A-Z]{2}$"},"reason":{"type":["string","null"]}}}}}},"currencies":{"type":"object","required":["all","granted","removed"],"properties":{"all":{"type":"boolean","description":"Each country's priced currency."},"granted":{"type":"array","items":{"type":"object","required":["currencyCode","countryCodes"],"properties":{"currencyCode":{"type":"string","pattern":"^[A-Z]{3}$"},"countryCodes":{"type":["array","null"],"items":{"type":"string","pattern":"^[A-Z]{2}$"},"description":"Null: throughout your territory."}}}},"removed":{"type":"array","items":{"type":"string","pattern":"^[A-Z]{3}$"},"description":"Currencies the Content Owner removed; a sale in one is refused with CURRENCY_NOT_PERMITTED_BY_TERM."}}},"pending":{"type":"array","description":"Dated changes still to come. A narrowing refuses new orders from effectiveFrom; holds made before it run to their expiry.","items":{"type":"object","required":["dimension","change","value","countryCodes","effectiveFrom","reason"],"properties":{"dimension":{"type":"string","enum":["territory","currency"]},"change":{"type":"string","enum":["add","remove"]},"value":{"type":"string","description":"A country, a currency, or * (worldwide, or every priced currency)."},"countryCodes":{"type":["array","null"],"items":{"type":"string"}},"effectiveFrom":{"type":"string","format":"date-time"},"reason":{"type":["string","null"]}}}},"proposals":{"type":"array","items":{"$ref":"#/components/schemas/SellerPartnerAccessProposal"}}}},"SellerWhoamiData":{"type":"object","required":["persona","sandbox","requestEnvironment","hasActiveBma","warnings","capabilities","company","key","settlement"],"properties":{"persona":{"type":"string","enum":["seller"]},"sandbox":{"type":"boolean"},"sandboxTenant":{"type":"object","description":"Sandbox keys only (absent for production keys). The sandbox company this key's requests run against: the shared sandbox, or your store's isolated sandbox environment once it has been moved there.","properties":{"sellerCompanyId":{"type":"string","format":"uuid"}}},"sandboxCatalog":{"type":"object","description":"Sandbox keys only (absent for production keys). What the sandbox offers this key: whether its fixture catalog is ready, and the magic SKUs and buyer IPs that trigger each rehearsable outcome.","properties":{"headerRequired":{"type":"boolean","description":"True when this deployment expects `X-Avrix-Sandbox: true` on sandbox requests."},"tenantReady":{"type":"boolean","description":"True when the fixture vendor, agreement, shares and allocations are in place, so the magic SKUs answer as documented."},"magicSkus":{"type":"array","items":{"type":"object","properties":{"code":{"type":"string","description":"SKU code to order, for example `SANDBOX-ALWAYS-001`."},"scenario":{"type":"string"},"expectedOutcome":{"type":"string"}}}},"magicConsumerIps":{"type":"array","items":{"type":"object","properties":{"ip":{"type":"string","description":"Buyer IP to send as `integrationOrderContext.consumerIp`."},"scenario":{"type":"string"},"expectedOutcome":{"type":"string"}}}},"requiredDeclarations":{"type":"array","items":{"type":"string"},"description":"The settlement declarations a sandbox order must send, as dot-paths under `integrationOrderContext`."},"requiredDeclarationsByOperation":{"type":"object","description":"Every `integrationOrderContext` dot-path each operation refuses without, computed for THIS key (its environment and its strict profile) from the same constants the validators use. Committing operations (`orders`, `commit`, `bulk`, `keysPull`, `keysExport`) list `schemaVersion`, the four settlement declarations, on production keys the commercial evidence (`currencyCode`, `salesPriceNetMinor`, `priceIncludesTax`, `salesTaxAmountMinor`, `paymentMethodFamily`, `paymentProcessorReference`, `checkoutSessionId`, `salesCountryCode`, `consumerIp`), and any `integrationContextStrictProfile.additionalRequiredFieldPaths`. Quoting operations list `salesCountryCode` (sendable as top-level `countryCode`); on production keys `preview` and `hold` also list `consumerIp` (sendable as a top-level `consumerIp` on preview, or supplied by a `consumerGeoAttestId`), because the commit refuses without it and the store knows it at quote time. They accept the rest when sent and name it in `commitRequirements.missing`. A missing field on a committing operation is refused with 422 VALIDATION_FAILED naming it in `details.issues`, or with the per-field settlement code.","properties":{"preview":{"type":"array","items":{"type":"string"}},"hold":{"type":"array","items":{"type":"string"}},"reserve":{"type":"array","items":{"type":"string"}},"orders":{"type":"array","items":{"type":"string"}},"commit":{"type":"array","items":{"type":"string"}},"bulk":{"type":"array","items":{"type":"string"}},"keysPull":{"type":"array","items":{"type":"string"}},"keysExport":{"type":"array","items":{"type":"string"}}},"required":["preview","hold","reserve","orders","commit","bulk","keysPull","keysExport"],"additionalProperties":false},"requiredDeclarationsNote":{"type":"string"}}},"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`. Scope is the explicit share list: an allocated SKU without an active share raises NO_SKU_SHARE.","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":"True when a request over this key's limit is refused with 429: always for sandbox keys (flat abuse cap), and for production keys once fair-use enforcement is on."},"rateLimitMode":{"type":"string","enum":["shadow","enforced"],"description":"`shadow`: production fair-use limits are counted and reported in `X-RateLimit-*`, but nothing is refused yet. `enforced`: over-limit requests answer 429 `RATE_LIMIT_EXCEEDED` with `Retry-After`."},"rateLimits":{"type":"object","description":"The rate limits that apply to this key, from the same constants the limiter uses. `bucket` is the value of the `X-RateLimit-Bucket` response header of a request counted against it; `x-avrix-rate-limit-class` on each operation in this reference names its class.","properties":{"mode":{"type":"string","enum":["shadow","enforced"],"description":"Same as `rateLimitMode`."},"appliesTo":{"type":"string","enum":["key","company"],"description":"`key`: a production key has its own budgets. `company`: sandbox keys of one company share the budgets."},"bucketHeader":{"type":"string","enum":["X-RateLimit-Bucket"],"description":"The response header that names the bucket a response was counted against."},"buckets":{"type":"array","items":{"type":"object","properties":{"bucket":{"type":"string","description":"`<class>:<kind>`, as in `X-RateLimit-Bucket`.","example":"orders:write"},"class":{"type":"string","enum":["catalog","orders","finance","webhooks-mgmt","general"],"description":"The route class the budget belongs to. `catalog`: products, pricing, availability, snapshot and changes. `orders`: preview, holds, orders, key pulls, refunds, transactions and allocation requests. `finance`: finance reads. `webhooks-mgmt`: webhook management. `general`: everything else."},"kind":{"type":"string","enum":["read","read-cached","write","snapshot"],"description":"`read-cached`: a cacheable catalog pre-flight; a `304` or cache hit does not spend `read`. `snapshot`: full `GET /catalog/snapshot` bodies (production keys)."},"limit":{"type":"integer","description":"Requests allowed per window."},"windowSeconds":{"type":"integer","description":"Length of the sliding window: 60, or 3600 for `catalog:snapshot`."}}}},"ordersOverride":{"type":["object","null"],"description":"An orders-class limit Avrix set for this production key (for example for a launch). While `active`, it replaces the `orders` read and write limits in `buckets`, and `orders:read-cached` is ten times it. Null when none is set.","properties":{"limitPerMinute":{"type":"integer"},"startsAt":{"type":["string","null"],"format":"date-time"},"endsAt":{"type":["string","null"],"format":"date-time"},"active":{"type":"boolean"}}}}},"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. This is the settlement declaration only; `requiredDeclarationsByOperation` is the complete per-operation list for this key.","items":{"type":"string"}},"integrationPresets":{"type":"object","required":["configured"],"description":"Store integration presets (GET/PUT /me/integration-presets). When configured, requiredDeclarations is empty and requiredDeclarationsByOperation omits every field the server fills from the presets or derives.","properties":{"configured":{"type":"boolean"},"salesChannel":{"type":["string","null"]},"paymentMethodFamily":{"type":["string","null"]},"priceIncludesTax":{"type":["boolean","null"]},"storeCountryCode":{"type":["string","null"]},"deriveAmounts":{"type":"boolean"}}},"requiredDeclarationsByOperation":{"type":"object","description":"Every `integrationOrderContext` dot-path each operation refuses without, computed for THIS key (its environment and its strict profile) from the same constants the validators use. Committing operations (`orders`, `commit`, `bulk`, `keysPull`, `keysExport`) list `schemaVersion`, the four settlement declarations, on production keys the commercial evidence (`currencyCode`, `salesPriceNetMinor`, `priceIncludesTax`, `salesTaxAmountMinor`, `paymentMethodFamily`, `paymentProcessorReference`, `checkoutSessionId`, `salesCountryCode`, `consumerIp`), and any `integrationContextStrictProfile.additionalRequiredFieldPaths`. Quoting operations list `salesCountryCode` (sendable as top-level `countryCode`); on production keys `preview` and `hold` also list `consumerIp` (sendable as a top-level `consumerIp` on preview, or supplied by a `consumerGeoAttestId`), because the commit refuses without it and the store knows it at quote time. They accept the rest when sent and name it in `commitRequirements.missing`. A missing field on a committing operation is refused with 422 VALIDATION_FAILED naming it in `details.issues`, or with the per-field settlement code.","properties":{"preview":{"type":"array","items":{"type":"string"}},"hold":{"type":"array","items":{"type":"string"}},"reserve":{"type":"array","items":{"type":"string"}},"orders":{"type":"array","items":{"type":"string"}},"commit":{"type":"array","items":{"type":"string"}},"bulk":{"type":"array","items":{"type":"string"}},"keysPull":{"type":"array","items":{"type":"string"}},"keysExport":{"type":"array","items":{"type":"string"}}},"required":["preview","hold","reserve","orders","commit","bulk","keysPull","keysExport"],"additionalProperties":false},"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"]]}}}},"accessByPublisher":{"type":"array","description":"Partner access per Content Owner: territories, locks, currencies, dated narrowings (pending) and proposals awaiting your answer. Accept or decline proposals with POST /access/proposals/{id}/accept or /decline.","items":{"$ref":"#/components/schemas/SellerPartnerAccess"}},"vatDeclarationPolicyByPublisher":{"type":"array","description":"Each Content Owner's VAT declaration policy (agreement term vat_declaration_policy). Under refuse_below_reference, a sale whose declared salesTaxRatePercent is below the reference rate for the sale country is refused with 422 VAT_DECLARATION_BELOW_REFERENCE on preview and commit; under warn, which applies when the agreement states nothing, it settles at the declared rate and is flagged vat_declared_rate_below_expected.","items":{"type":"object","required":["publisherCompanyId","policy"],"properties":{"publisherCompanyId":{"type":"string"},"contractTermId":{"type":["string","null"]},"policy":{"type":"string","enum":["warn","refuse_below_reference"]}}}},"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","enum":["warn","refuse","settle_at_evidence"],"description":"The policy orders are judged under, on whatever evidence the sale carries (the checkout attest's country, else the IP lookup of the consumer IP), whether or not consumer geo enforcement is on. warn: the sale proceeds and the disagreement is recorded, lowering the evidence rank it settles at. refuse: 422 CONSUMER_GEO_MISMATCH_POLICY_REFUSED at preview, hold and commit. settle_at_evidence: with enforcement on, the sale is re-priced at the higher of the two territories' SRPs; with it off, the sale proceeds with a CONSUMER_GEO_MISMATCH geoWarning. An agreement that states no policy is reported (and applied) as refuse."},"policyStated":{"type":"boolean","description":"False when the agreement states no geo-mismatch policy and policy is the fail-closed default (refuse)."},"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"]}}}}}}},"buyerVerificationByPublisher":{"type":"array","description":"How each Content Owner verifies buyers at checkout on your connection. capabilities.consumerGeoAttestRequired is the seller-wide OR of these entries; read this block to add the checkout pixel only for the Content Owners that require it. Levels apply to production keys only; sandbox keys never require checkout confirmation.","items":{"allOf":[{"$ref":"#/components/schemas/ConnectionBuyerVerification"},{"type":"object","required":["publisherCompanyId","note"],"properties":{"publisherCompanyId":{"type":"string"},"note":{"type":"string","description":"What the level means for your integration, in plain words."}}}]}},"productionAccess":{"description":"The path to production access for the key's company (`SellerProductionAccess`); null when it could not be read.","oneOf":[{"$ref":"#/components/schemas/SellerProductionAccess"},{"type":"null"}]}}},"ConnectionBuyerVerification":{"type":"object","description":"The buyer verification level a Content Owner set for a connection (production keys only).","required":["level","riskAction"],"properties":{"level":{"type":"string","enum":["declared_ip","checkout_attest","checkout_attest_risk"],"description":"declared_ip: no checkout-page confirmation; send the buyer’s public IP in integrationOrderContext.consumerIp and the geo checks apply to it. checkout_attest: POST /geo/attest + pixel are required and consumerGeoAttestId must be sent on preview, hold, reserve and commit. checkout_attest_risk: as checkout_attest, and the confirmed checkout is also risk-scored against the Content Owner’s threshold."},"riskAction":{"type":"string","enum":["refuse","warn"],"description":"Under checkout_attest_risk: refuse means a high-risk order is refused, warn means it proceeds with a warning. Present on every level; meaningful only under checkout_attest_risk."}}},"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."}}}}},"SellerPartnerOffer":{"type":"object","description":"A title the Content Owner offered on a partner connection that the seller has not accepted or declined yet. Accepting or declining is done in the console.","required":["amendmentId","releaseId","message","proposedAt","productId","productName","editionName","platformName"],"properties":{"amendmentId":{"type":"string","format":"uuid","description":"Id of the pending offer."},"releaseId":{"type":"string","format":"uuid","description":"Platform release being offered: one title on one platform (a catalog platform release id). This is not the region-release id that `PricingRelease.releaseId` uses, so do not join the two. Correlate an offer with catalog data by `productId` + `editionName` + `platformName`."},"productId":{"type":["string","null"],"format":"uuid","description":"Product the release belongs to. Null when the release is no longer in the catalog."},"productName":{"type":["string","null"],"description":"Product name."},"editionName":{"type":["string","null"],"description":"Edition name."},"platformName":{"type":["string","null"],"description":"Platform name. Null when the release has no platform."},"message":{"type":["string","null"],"description":"Message the Content Owner attached to the offer."},"proposedAt":{"type":"string","format":"date-time","description":"When the offer was made."}}},"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"],"description":"How the governing API agreement states its catalog scope. `all`: Full catalog, the titles the Content Owner had at signing. `selected`: hand-picked titles. Either way the SKUs you may sell are the shared SKUs; titles published later reach you only through an offer you accept."},"sharesSuspended":{"type":"boolean","description":"True when a contract-sourced SKU share is suspended for this publisher–seller pair under an agreement still in force (active, paused or terminating). Shares of an ended agreement are not counted."},"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":"Deprecated name of `srpPriceMinor` (same value). Kept on the wire; see Naming conventions in the Versioning and compatibility guide. Suggested retail price in the seller company's preferred pricing country","deprecated":true},"srpPriceMinor":{"type":["integer","null"],"description":"Suggested retail price in the seller company's preferred pricing country Same amount as `srpPriceCents`, under the `...Minor` name every Seller API amount uses: integer minor units of the currency beside it (see `currencyExponent`)."},"srpCurrencyCode":{"type":["string","null"]},"srpCurrencyExponent":{"type":["integer","null"],"minimum":0,"maximum":3,"description":"Minor-unit digits of `srpCurrencyCode` (2 for USD, 0 for JPY, 3 for KWD): `srp = srpPriceCents / 10^srpCurrencyExponent`. `null` when there is no SRP. Additive."},"sellable":{"type":"boolean","description":"True when this SKU is checkout-ready (grant + share + lifecycle + pricing + payment clearance). 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, PAYMENT_NOT_CLEARED)."},"recommendedAction":{"type":["string","null"],"description":"Suggested partner action when not sellable."},"pricePerKeyCents":{"type":["integer","null"],"description":"Deprecated name of `pricePerKeyMinor` (same value). Kept on the wire; see Naming conventions in the Versioning and compatibility guide. Advisory copy of the wholesale unit price on your allocation grant for this SKU (`GET /allocations` stays the authority). Wholesale contract price per key in `currencyCode` (`wholesale` / `pre_order` grants). **`null` = no wholesale price, and it is never `0`:** always `null` under `businessModel: api`, which settles as a share of the territory list price — read that from `GET /products/{productId}/pricing` and bind it with the preview `unitPriceCents` you echo on commit.","deprecated":true},"pricePerKeyMinor":{"type":["integer","null"],"description":"Advisory copy of the wholesale unit price on your allocation grant for this SKU (`GET /allocations` stays the authority). Wholesale contract price per key in `currencyCode` (`wholesale` / `pre_order` grants). **`null` = no wholesale price, and it is never `0`:** always `null` under `businessModel: api`, which settles as a share of the territory list price — read that from `GET /products/{productId}/pricing` and bind it with the preview `unitPriceCents` you echo on commit. Same amount as `pricePerKeyCents`, under the `...Minor` name every Seller API amount uses: integer minor units of the currency beside it (see `currencyExponent`)."},"currencyCode":{"type":["string","null"],"description":"ISO 4217 currency of `pricePerKeyCents`; `null` whenever the price is `null`."},"currencyExponent":{"type":["integer","null"],"description":"ISO 4217 minor-unit exponent for `currencyCode` (0 for JPY, 2 for USD, 3 for KWD); `null` whenever the price is `null`."},"territoryPrices":{"type":"array","description":"Only on `GET /catalog/snapshot?pricing=territory`: every country list price of this SKU (same resolution as `GET /products/{productId}/pricing`), sorted by country. Empty = no price set.","items":{"type":"object","properties":{"countryCode":{"type":"string"},"basePriceCents":{"type":"integer","deprecated":true,"description":"Deprecated name of `basePriceMinor` (same value). Kept on the wire; see Naming conventions in the Versioning and compatibility guide."},"basePriceMinor":{"type":"integer","description":"Same amount as `basePriceCents`, under the `...Minor` name every Seller API amount uses: integer minor units of the currency beside it (see `currencyExponent`)."},"zone":{"description":"The platform price zone of this country (for example `Latin America (USD)` on Steam); null when the platform has no zones yet. Additive.","oneOf":[{"$ref":"#/components/schemas/PriceZone"},{"type":"null"}]},"currencyCode":{"type":"string"},"currencyExponent":{"type":"integer","minimum":0,"maximum":3,"description":"Number of minor-unit digits for `currencyCode`: 2 for USD, 0 for JPY, 3 for KWD. amount = cents / 10^currencyExponent. Additive."},"fallbackFromCurrency":{"type":["string","null"],"description":"Set when the price is a fallback: the store charges this country in this currency, which the content owner does not allow there, so the country sells at the platform's highest price in `currencyCode` instead (the highest price the same source has in that currency, over every country of the platform). Null for every other price. Additive."},"sellable":{"type":"boolean","description":"Whether a sale in this country may charge this price. False when the stored currency is not one the content owner allows for the country: a platform price (a tier copy, a Steam price) is kept in the store's currency and reported, but an order there is refused with `CURRENCY_NOT_PRICED_FOR_COUNTRY` until the owner sets a price in an allowed currency or allows this one. Additive."},"blockedReason":{"type":["string","null"],"enum":["CURRENCY_NOT_PRICED_FOR_COUNTRY",null],"description":"Why `sellable` is false; `null` when the price can sell. Additive."}},"required":["countryCode","basePriceCents","basePriceMinor","currencyCode","currencyExponent","sellable","blockedReason"]}}},"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":"Deprecated name of `listPriceFromMinor` (same value). Kept on the wire; see Naming conventions in the Versioning and compatibility guide. Lowest resolved list price in your pricing country (the country of your company's default currency; the United States when none is set) 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.","deprecated":true},"listPriceFromMinor":{"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. Same amount as `listPriceFromCents`, under the `...Minor` name every Seller API amount uses: integer minor units of the currency beside it (see `currencyExponent`)."},"listPriceCurrencyCode":{"type":["string","null"]},"listPriceCurrencyExponent":{"type":["integer","null"],"minimum":0,"maximum":3,"description":"Number of minor-unit digits for `listPriceCurrencyCode`: 2 for USD, 0 for JPY, 3 for KWD. amount = cents / 10^listPriceCurrencyExponent; `null` when `listPriceFromCents` is `null`. Additive."},"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"},"heldQuantity":{"type":["integer","null"],"description":"Sum of keys inside live checkout holds across those allocations at the time the list was cached; `null` when the hold ledger could not be read. Advisory — `GET /availability` is the fresh read."},"sellableNow":{"type":"integer","description":"`available` minus `heldQuantity`. Advisory inside the cached list."},"skuCount":{"type":"integer","description":"Number of distinct shared SKUs that contributed to the totals above"}},"required":["available","allocationRemaining","inventoryAvailable","heldQuantity","sellableNow","skuCount"]},"PartnerProductListPricingExpansion":{"type":"object","description":"Per-row pricing summary returned when `expand=pricing` is set on `GET /products`. Bundles the seller-specific wholesale band with the publisher list price band already on `PartnerProduct`. Only priced `wholesale` / `pre_order` grants contribute a wholesale band: an `api` grant has no wholesale price, and `0` is never a price.","properties":{"wholesaleFromCents":{"type":["integer","null"],"description":"Deprecated name of `wholesaleFromMinor` (same value). Kept on the wire; see Naming conventions in the Versioning and compatibility guide. Lowest wholesale price across your priced `wholesale` / `pre_order` allocations for this product; `null` when you hold none (`api` allocations never contribute, and `0` is never a price)","deprecated":true},"wholesaleFromMinor":{"type":["integer","null"],"description":"Lowest wholesale price across your priced `wholesale` / `pre_order` allocations for this product; `null` when you hold none (`api` allocations never contribute, and `0` is never a price) Same amount as `wholesaleFromCents`, under the `...Minor` name every Seller API amount uses: integer minor units of the currency beside it (see `currencyExponent`)."},"wholesaleCurrencyCode":{"type":["string","null"],"description":"Currency for `wholesaleFromCents`"},"wholesaleCurrencyExponent":{"type":["integer","null"],"minimum":0,"maximum":3,"description":"Number of minor-unit digits for `wholesaleCurrencyCode`: 2 for USD, 0 for JPY, 3 for KWD. amount = cents / 10^wholesaleCurrencyExponent; `null` when `wholesaleFromCents` is `null`."},"listPriceFromCents":{"type":["integer","null"],"description":"Deprecated name of `listPriceFromMinor` (same value). Kept on the wire; see Naming conventions in the Versioning and compatibility guide. Echo of the list-price band on `PartnerProduct.listPriceFromCents` (the lowest list price in your pricing country)","deprecated":true},"listPriceFromMinor":{"type":["integer","null"],"description":"Echo of the list-price band on `PartnerProduct.listPriceFromCents` (publisher US list / SRP) Same amount as `listPriceFromCents`, under the `...Minor` name every Seller API amount uses: integer minor units of the currency beside it (see `currencyExponent`)."},"listPriceCurrencyCode":{"type":["string","null"]},"listPriceCurrencyExponent":{"type":["integer","null"],"minimum":0,"maximum":3,"description":"Number of minor-unit digits for `listPriceCurrencyCode`: 2 for USD, 0 for JPY, 3 for KWD. amount = cents / 10^listPriceCurrencyExponent; `null` when `listPriceFromCents` is `null`."}},"required":["wholesaleFromCents","wholesaleFromMinor","wholesaleCurrencyCode","wholesaleCurrencyExponent","listPriceFromCents","listPriceFromMinor","listPriceCurrencyCode","listPriceCurrencyExponent"]},"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":"Latest product `updatedAt` in the snapshot. Usable as `?updatedSince=` on `GET /products` for metadata and lifecycle deltas only — price changes never move it; use `changesCursor` for those."},"changesCursor":{"type":"string","description":"Opaque change-feed position when this snapshot was assembled. Pass it as `cursor` to `GET /catalog/changes` to receive every later change, price changes included. Also part of the snapshot ETag."},"availabilityCursor":{"type":"string","description":"Opaque `GET /availability/changes` position when this snapshot was assembled. Pass it as `cursor` to receive every later stock and sellability change."},"pricing":{"type":"string","enum":["territory"],"description":"Present when the snapshot was requested with `pricing=territory`."},"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","changesCursor","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"]},"changesCursor":{"type":"string","description":"Opaque change-feed position. Advances on every recorded change, price changes included — which `digest` (product rows only) never sees. Pass it as `cursor` to `GET /catalog/changes`."},"generatedAt":{"type":"string","format":"date-time","description":"When this digest response was built (not part of the hashed material)"}},"required":["totalProducts","maxUpdatedAt","digest","digestAlgorithm","changesCursor","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"}},"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. Present only when the product has at least one related product you can see.","items":{"type":"object","required":["type","productId"],"properties":{"type":{"type":"string","enum":["requires","includes","upgrades","edition_of"]},"productId":{"type":"string","format":"uuid"}}}},"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"},"developer":{"type":["string","null"],"description":"The studio credited as developer, as the vendor entered it. `null` when not set. Additive."},"creditedPublisher":{"type":["string","null"],"description":"The publisher credited on the store page, as the vendor entered it. Not always the company that shares the product with you (`publisherCompanyName`): a label can be credited on a title its owner distributes. `null` when not set. Additive."}}},"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":{"deprecated":true,"description":"Deprecated: the release-level list price before SKU-level pricing. A sale charges the SKU price; read `skus[].prices`. Kept for one API version.","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"},"prices":{"type":"array","description":"The price a sale of this SKU charges, per country, from the canonical price resolver. Same resolution as `GET /products/{productId}/pricing` `skus[].prices` and `GET /catalog/snapshot?pricing=territory`.","items":{"allOf":[{"$ref":"#/components/schemas/SellerProductDetailPricing"},{"$ref":"#/components/schemas/CatalogPricePromotionFields"}]}},"promotions":{"type":"array","description":"Accepted promotions on this SKU whose window is live or upcoming, so you can stage a sale ahead. Additive.","items":{"$ref":"#/components/schemas/CatalogSkuPromotion"}}},"required":["id","skuCode","keyTypeCode","keyTypeName","skuType","externalReferences"]},"SellerProductDetailPricing":{"type":"object","properties":{"fallbackFromCurrency":{"type":["string","null"],"description":"Set when the price is a fallback: the store charges this country in this currency, which the content owner does not allow there, so the country sells at the platform's highest price in `currencyCode` instead (the highest price the same source has in that currency, over every country of the platform). Null for every other price. Additive."},"sellable":{"type":"boolean","description":"Whether a sale in this country may charge this price. False when the stored currency is not one the content owner allows for the country: a platform price (a tier copy, a Steam price) is kept in the store's currency and reported, but an order there is refused with `CURRENCY_NOT_PRICED_FOR_COUNTRY` until the owner sets a price in an allowed currency or allows this one. Additive."},"blockedReason":{"type":["string","null"],"enum":["CURRENCY_NOT_PRICED_FOR_COUNTRY",null],"description":"Why `sellable` is false; `null` when the price can sell. Additive."},"countryCode":{"type":["string","null"]},"currencyCode":{"type":"string"},"basePriceCents":{"type":"integer","deprecated":true,"description":"Deprecated name of `basePriceMinor` (same value). Kept on the wire; see Naming conventions in the Versioning and compatibility guide."},"basePriceMinor":{"type":"integer","description":"Same amount as `basePriceCents`, under the `...Minor` name every Seller API amount uses: integer minor units of the currency beside it (see `currencyExponent`)."},"currencyExponent":{"type":"integer","minimum":0,"maximum":3,"description":"Number of minor-unit digits for `currencyCode`: 2 for USD, 0 for JPY, 3 for KWD. amount = basePriceCents / 10^currencyExponent. Additive."},"zone":{"description":"The platform price zone of this country (for example `Latin America (USD)` on Steam); null when the platform has no zones yet. Additive.","oneOf":[{"$ref":"#/components/schemas/PriceZone"},{"type":"null"}]}}},"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 rollup of `launchPhase` / `tradingState` (archived, draft, discontinued, active). Identical to the release's `status` on 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":{"deprecated":true,"description":"Deprecated: the release-level list price before SKU-level pricing. A sale charges the SKU price; read `skus[].prices`. Kept for one API version.","type":"array","items":{"type":"object","properties":{"countryCode":{"type":["string","null"]},"currencyCode":{"type":"string"},"basePriceCents":{"type":"integer","description":"Deprecated name of `basePriceMinor` (same value). Kept on the wire; see Naming conventions in the Versioning and compatibility guide. Minor units of `currencyCode`.","deprecated":true},"basePriceMinor":{"type":"integer","description":"Minor units of `currencyCode`. Same amount as `basePriceCents`, under the `...Minor` name every Seller API amount uses: integer minor units of the currency beside it (see `currencyExponent`)."},"currencyExponent":{"type":"integer","minimum":0,"maximum":3,"description":"Number of minor-unit digits for `currencyCode`: 2 for USD, 0 for JPY, 3 for KWD. amount = cents / 10^currencyExponent. Additive."},"fallbackFromCurrency":{"type":["string","null"],"description":"Set when the price is a fallback: the store charges this country in this currency, which the content owner does not allow there, so the country sells at the platform's highest price in `currencyCode` instead (the highest price the same source has in that currency, over every country of the platform). Null for every other price. Additive."},"sellable":{"type":"boolean","description":"Whether a sale in this country may charge this price. False when the stored currency is not one the content owner allows for the country: a platform price (a tier copy, a Steam price) is kept in the store's currency and reported, but an order there is refused with `CURRENCY_NOT_PRICED_FOR_COUNTRY` until the owner sets a price in an allowed currency or allows this one. Additive. On contract date `2026-12-01` and later, `sellable` is the order path's answer for the SKU in this country: your selling footprint, the territory and currency your agreement grants, the SKU's territory and region locks, the catalog price and the priced currency, in the order `POST /orders/preview` and `POST /orders` check them. Whether you hold a usable allocation is not part of it (`GET /allocations`). Earlier dates keep the currency-only answer. The release-level row (deprecated) reads `false` on that date when no SKU of the release sells in the country."},"blockedReason":{"type":["string","null"],"enum":["COUNTRY_RESTRICTED","TERRITORY_NOT_ALLOWED_FOR_SKU","TERRITORY_NOT_GRANTED","TERRITORY_EXCLUDED_FOR_RELEASE","REGION_LOCKED_FOR_CONTRACT","REGION_LOCKED_FOR_SKU","SKU_REGION_UNRESOLVED","CATALOG_PRICE_NOT_SET","FOOTPRINT_COUNTRY_NOT_DECLARED","FOOTPRINT_CURRENCY_NOT_DECLARED","CURRENCY_NOT_PERMITTED_BY_TERM","CURRENCY_NOT_PRICED_FOR_COUNTRY","SRP_MISMATCH_FOR_CURRENCY",null],"description":"Why `sellable` is false; `null` when the price can sell. Earlier contract dates name only `CURRENCY_NOT_PRICED_FOR_COUNTRY`; on `2026-12-01` and later, the first refusal the order path would give for this country, the same code `POST /orders/preview` names. Additive."},"zone":{"description":"The platform price zone of this country (for example `Latin America (USD)` on Steam); null when the platform has no zones yet. Additive.","oneOf":[{"$ref":"#/components/schemas/PriceZone"},{"type":"null"}]}}}},"skus":{"type":"array","description":"Your shared SKUs on this release, each with the price a sale of it charges, per country, from the canonical price resolver. Same country filter as the request.","items":{"type":"object","properties":{"id":{"type":"string"},"skuCode":{"type":"string"},"prices":{"type":"array","items":{"type":"object","properties":{"countryCode":{"type":["string","null"]},"currencyCode":{"type":"string"},"basePriceCents":{"type":"integer","description":"Deprecated name of `basePriceMinor` (same value). Kept on the wire; see Naming conventions in the Versioning and compatibility guide. Minor units of `currencyCode`.","deprecated":true},"basePriceMinor":{"type":"integer","description":"Minor units of `currencyCode`. Same amount as `basePriceCents`, under the `...Minor` name every Seller API amount uses: integer minor units of the currency beside it (see `currencyExponent`)."},"currencyExponent":{"type":"integer","minimum":0,"maximum":3,"description":"Number of minor-unit digits for `currencyCode`: 2 for USD, 0 for JPY, 3 for KWD. amount = cents / 10^currencyExponent. Additive."},"fallbackFromCurrency":{"type":["string","null"],"description":"Set when the price is a fallback: the store charges this country in this currency, which the content owner does not allow there, so the country sells at the platform's highest price in `currencyCode` instead (the highest price the same source has in that currency, over every country of the platform). Null for every other price. Additive."},"sellable":{"type":"boolean","description":"Whether a sale in this country may charge this price. False when the stored currency is not one the content owner allows for the country: a platform price (a tier copy, a Steam price) is kept in the store's currency and reported, but an order there is refused with `CURRENCY_NOT_PRICED_FOR_COUNTRY` until the owner sets a price in an allowed currency or allows this one. Additive. On contract date `2026-12-01` and later, `sellable` is the order path's answer for the SKU in this country: your selling footprint, the territory and currency your agreement grants, the SKU's territory and region locks, the catalog price and the priced currency, in the order `POST /orders/preview` and `POST /orders` check them. Whether you hold a usable allocation is not part of it (`GET /allocations`). Earlier dates keep the currency-only answer."},"blockedReason":{"type":["string","null"],"enum":["COUNTRY_RESTRICTED","TERRITORY_NOT_ALLOWED_FOR_SKU","TERRITORY_NOT_GRANTED","TERRITORY_EXCLUDED_FOR_RELEASE","REGION_LOCKED_FOR_CONTRACT","REGION_LOCKED_FOR_SKU","SKU_REGION_UNRESOLVED","CATALOG_PRICE_NOT_SET","FOOTPRINT_COUNTRY_NOT_DECLARED","FOOTPRINT_CURRENCY_NOT_DECLARED","CURRENCY_NOT_PERMITTED_BY_TERM","CURRENCY_NOT_PRICED_FOR_COUNTRY","SRP_MISMATCH_FOR_CURRENCY",null],"description":"Why `sellable` is false; `null` when the price can sell. Earlier contract dates name only `CURRENCY_NOT_PRICED_FOR_COUNTRY`; on `2026-12-01` and later, the first refusal the order path would give for this country, the same code `POST /orders/preview` names. Additive."},"zone":{"description":"The platform price zone of this country (for example `Latin America (USD)` on Steam); null when the platform has no zones yet. Additive.","oneOf":[{"$ref":"#/components/schemas/PriceZone"},{"type":"null"}]},"listPromo":{"description":"The live promotion the vendor asks you to show to buyers on this SKU (`priceEffect` `list_price` or `both`), or null. Additive.","oneOf":[{"$ref":"#/components/schemas/ListPromoRef"},{"type":"null"}]},"advertisedPriceCents":{"type":"integer","description":"Deprecated name of `advertisedPriceMinor` (same value). Kept on the wire; see Naming conventions in the Versioning and compatibility guide. `basePriceCents` with `listPromo` applied: the price to show to buyers now. Equal to `basePriceCents` when there is no live list-price promotion. Additive.","deprecated":true},"advertisedPriceMinor":{"type":"integer","description":"`basePriceCents` with `listPromo` applied: the price to show to buyers now. Equal to `basePriceCents` when there is no live list-price promotion. Additive. Same amount as `advertisedPriceCents`, under the `...Minor` name every Seller API amount uses: integer minor units of the currency beside it (see `currencyExponent`)."},"promo":{"description":"The live promotion that lowers what an order under the API business model is billed (`priceEffect` `settlement_price` or `both`), or null. The billed price depends on the allocation and the buyer's country: `POST /orders/preview` quotes it. Additive.","oneOf":[{"$ref":"#/components/schemas/SettlementPromoRef"},{"type":"null"}]},"promoResolution":{"type":"string","enum":["applied","none","unavailable"],"description":"`applied` when `listPromo` or `promo` is set, `none` when no promotion is live, `unavailable` when promotions could not be read (then `listPromo` and `promo` say nothing). Additive."}}}},"promotions":{"type":"array","description":"Accepted promotions on this SKU whose window is live or upcoming, so you can stage a sale ahead. Additive.","items":{"$ref":"#/components/schemas/CatalogSkuPromotion"}}},"required":["id","skuCode","prices"]}},"launchPhase":{"type":"string","description":"The release's effective launch phase, exactly as GET /products/{productId} reports it (region release, release and edition settings plus the release dates)."},"tradingState":{"type":"string","description":"The release's effective trading state, exactly as GET /products/{productId} reports it."}}},"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"],"deprecated":true,"description":"Deprecated: use the aggregate's `orderId`. On contract date `2026-12-01` and later the same value as `orderId`; on older dates the id of the line's first key 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"}}},"SellerKeyReplacement":{"type":"object","description":"A key replacement on this order (`POST /orders/{orderId}/keys/{keyId}/replace`).","required":["replacementId","status","reason","approval","replacedKeyId","keyId","requestedAt"],"properties":{"replacementId":{"type":"string","format":"uuid"},"status":{"type":"string","enum":["pending","completed","rejected"]},"reason":{"type":"string","enum":["already_redeemed","invalid","wrong_region","revoked"]},"approval":{"type":"string","enum":["auto","publisher"]},"replacedKeyId":{"type":"string","format":"uuid"},"keyId":{"type":["string","null"],"format":"uuid","description":"The key delivered instead; null until completed."},"requestedAt":{"type":"string","format":"date-time"},"completedAt":{"type":["string","null"],"format":"date-time"},"decidedAt":{"type":["string","null"],"format":"date-time","description":"When the Content Owner decided (publisher approval only)."}}},"SellerKeyRevocation":{"type":"object","description":"A sold key the Content Owner revoked after sale.","required":["keyId","reason","revokedAt"],"properties":{"keyId":{"type":"string","format":"uuid"},"reason":{"type":"string","enum":["leaked","grey_market","platform_revoked","fraud","other"]},"revokedAt":{"type":"string","format":"date-time"}}},"SellerTypedKey":{"type":"object","description":"A delivered key (contract date 2026-10-01 and later).","required":["id","type","key","url","expiresAt","redemption"],"properties":{"id":{"type":"string","format":"uuid","description":"Same as the matching `keyIds` entry."},"type":{"type":"string","enum":["text","image","link","file"],"description":"`text`: a code in `key`. `link`: a redemption URL in `url`. `image` / `file`: a signed download URL in `url` (valid 1 hour; call recover-keys again for a fresh one), plus `key` when the asset also has a code."},"key":{"type":["string","null"]},"url":{"type":["string","null"]},"expiresAt":{"type":["string","null"],"format":"date-time","description":"When the key stops being redeemable, when the Content Owner set it."},"redemption":{"type":"object","required":["platformCode","url","instructions","locale"],"properties":{"platformCode":{"type":["string","null"],"description":"Platform of the SKU (e.g. `steam`, `epic`, `ps5`)."},"url":{"type":["string","null"],"description":"Where the buyer redeems, with the code filled in where the platform allows it."},"instructions":{"type":["string","null"],"description":"Activation steps for the buyer, in `locale`."},"locale":{"type":["string","null"],"description":"Best match for Accept-Language, else `en`."}}}}},"SellerDeliveredKey":{"description":"A delivered key: the plaintext code up to contract date 2026-09-01, a typed key object from 2026-10-01.","oneOf":[{"type":"string"},{"$ref":"#/components/schemas/SellerTypedKey"}]},"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","description":"The reference you sent on `POST /refunds` when you sent one, else the refund record id. Use `refundIds` for `GET /refunds/{refundId}`."},"status":{"type":"string","enum":["pending","completed","chargeback_open","chargeback_lost","chargeback_won"]},"keyIds":{"type":"array","items":{"type":"string","format":"uuid"}},"refundReference":{"type":["string","null"],"description":"The refund or chargeback reference you sent; null when none was sent."},"refundIds":{"type":"array","items":{"type":"string","format":"uuid"},"description":"The refund record ids of this refund, one per key sold under the API model (`GET /refunds/{refundId}`)."}}}},"keyIds":{"type":"array","items":{"type":"string","format":"uuid"},"description":"Inventory key ids delivered on this order, oldest first: the same ids as the order's `GET /orders` row, for refund and return correlation. Never plaintext codes. Returned by `GET /orders/{orderId}`."},"totalCents":{"type":["integer","null"],"description":"Deprecated name of `totalMinor` (same value). Kept on the wire; see Naming conventions in the Versioning and compatibility guide. Order total in minor units of `currencyCode`, the same value as `totalCents` on the order's `GET /orders` row: the durable order's total where the listing reads durable orders, otherwise the sum of the order's recorded sales. `null` when the row has none (for example a sandbox order with no recorded sale). Returned by `GET /orders/{orderId}`.","deprecated":true},"totalMinor":{"type":["integer","null"],"description":"Order total in minor units of `currencyCode`, the same value as `totalCents` on the order's `GET /orders` row: the durable order's total where the listing reads durable orders, otherwise the sum of the order's recorded sales. `null` when the row has none (for example a sandbox order with no recorded sale). Returned by `GET /orders/{orderId}`. Same amount as `totalCents`, under the `...Minor` name every Seller API amount uses: integer minor units of the currency beside it (see `currencyExponent`)."},"currencyCode":{"type":["string","null"],"description":"ISO 4217 currency of `totalCents`; `null` when `totalCents` is. Returned by `GET /orders/{orderId}`."},"currencyExponent":{"type":["integer","null"],"minimum":0,"maximum":3,"description":"Number of minor-unit digits for `currencyCode`: 2 for USD, 0 for JPY, 3 for KWD. amount = minor units / 10^currencyExponent; `null` when `currencyCode` is `null`. Returned by `GET /orders/{orderId}`."},"createdAt":{"type":["string","null"],"format":"date-time","description":"When the order was placed: the durable order's creation time where the listing reads durable orders, otherwise the first key pull. Returned by `GET /orders/{orderId}`."},"fulfilledAt":{"type":["string","null"],"format":"date-time","description":"The same value as `fulfilledAt` on the order's `GET /orders` row: the first fulfilment of a durable order (its creation time until then) where the listing reads durable orders, otherwise the latest key pull. Returned by `GET /orders/{orderId}`."},"updatedAt":{"type":["string","null"],"format":"date-time","description":"Last change to the order: the durable order row where the listing reads durable orders, otherwise the latest key pull. Returned by `GET /orders/{orderId}`."},"orderId":{"type":["string","null"],"description":"The order's id (`ord_` plus eight characters). One value for the life of the order: the same in the create response, `GET /orders`, `GET /orders/{orderId}`, the bulk line and the `order.fulfilled` webhook. Store this one. Every endpoint that addresses an order (`GET /orders/{orderId}`, `GET /orders?orderReadableId=`, `POST /orders/{orderId}/fulfill`, key replacement) accepts it. Present in both read models."},"economics":{"anyOf":[{"$ref":"#/components/schemas/SellerOrderEconomics"},{"type":"null"}],"description":"What the delivered keys were billed at, summed from the order's API sale rows. Null when the order has none: a wholesale or complimentary allocation (billed per allocation, not per sale), or nothing delivered yet."},"qtyRequested":{"type":"integer","description":"Present when orders are read from the durable order store; absent on the reconstruction read."},"qtyPending":{"type":"integer","description":"Present when orders are read from the durable order store; absent on the reconstruction read."},"qtyAssigned":{"type":"integer","description":"Present when orders are read from the durable order store; absent on the reconstruction read."},"qtyRevealed":{"type":"integer","description":"Present when orders are read from the durable order store; absent on the reconstruction read."},"parentOrderReference":{"type":["string","null"],"description":"The bulk cart this order is a line of (`integrationOrderContext.parentOrderReference` sent with `POST /orders/bulk`); null for an order placed on its own."},"lineIndex":{"type":["integer","null"],"description":"The line's position in that cart (`integrationOrderContext.lineIndex`); null when not a cart line or not sent."},"replacements":{"type":"array","description":"Key replacements on this order, oldest first. `POST /orders/recover-keys` returns the replacement keys, never the replaced ones.","items":{"$ref":"#/components/schemas/SellerKeyReplacement"}},"revocations":{"type":"array","description":"Sold keys of this order the Content Owner revoked after sale (`keys.revoked`). Replace them with `POST /orders/{orderId}/keys/{keyId}/replace` or refund the buyer.","items":{"$ref":"#/components/schemas/SellerKeyRevocation"}}}},"SellerTransaction":{"type":"object","properties":{"id":{"type":"string","deprecated":true,"description":"Deprecated name of `keyPullId`: this row is a key pull, not a sale, and is not the `transactionId` finance reads take."},"keyPullId":{"type":"string","format":"uuid","description":"The key pull this row records. Same value as `id`. One row is one key."},"transactionId":{"type":["string","null"],"format":"uuid","description":"The sale row this pull produced: the id `POST /orders` returns in `transactionIds[]` and `GET /finance/api-sales/{transactionId}` reads. Null when the pull has no sale row (a commercial model that records none, or a row not written yet)."},"readableId":{"type":"string","description":"Deprecated: `ord_` followed by the key pull id. It is not the order's id; look the order up with `orderReference`.","deprecated":true},"allocationId":{"type":"string"},"skuId":{"type":"string","format":"uuid","description":"The SKU the key was pulled for."},"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 the buyer was evidenced in at pull time: the consumer geo gate's IP lookup, or the checkout attestation's country when only that ran. Null when geo ran in `off` mode with no attestation, 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","vat_country_not_corroborated","vat_anonymizer_flag","vat_declared_rate_above_expected","vat_declared_rate_below_expected","vat_declared_rate_above_ceiling","vat_price_includes_tax_mismatch","vat_declaration_arithmetic_mismatch"]},"description":"Machine-readable reconciliation flags, the same set `GET /finance/api-sales` returns for the sale behind this pull. `COUNTRY_MISMATCH`: the buyer's evidenced country (IP lookup, or the checkout attestation when only that ran) differs from the declared `salesCountryCode`. The `vat_*` codes are what the settlement noticed at the moment of sale and did not refuse over, as returned on the order response. Empty when nothing was flagged."},"parentOrderReference":{"type":["string","null"],"description":"The bulk cart this order is a line of (`integrationOrderContext.parentOrderReference` sent with `POST /orders/bulk`); null for an order placed on its own."},"lineIndex":{"type":["integer","null"],"description":"The line's position in that cart (`integrationOrderContext.lineIndex`); null when not a cart line or not sent."}}},"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"},"status":{"type":"string","enum":["active","revoked"],"description":"`revoked` keys no longer authenticate. They stay in the list for audit until archived in the console."},"revokedAt":{"type":["string","null"],"format":"date-time","description":"When the key was revoked; null while it is active."},"scopes":{"type":"array","items":{"type":"string"},"description":"The scopes the key holds."},"environment":{"type":"string","enum":["production","sandbox"],"description":"The key's environment."},"allowedIps":{"type":"array","items":{"type":"string"},"description":"The key's source IP allowlist (IP literals or CIDR ranges); empty when the key is not IP-restricted."}}},"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`; these are documentation addresses, replace them with your own). Reserved ranges are rejected with 422: private (RFC1918), loopback, link-local, CGNAT, IPv6 ULA, multicast, and the documentation and benchmark ranges (`192.0.2.0/24`, `198.51.100.0/24`, `203.0.113.0/24`, `198.18.0.0/15`, `2001:db8::/32`). `/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`."},"scopes":{"type":"array","minItems":1,"maxItems":19,"items":{"type":"string","enum":["seller:products:read","seller:orders:preview","seller:orders:read","seller:orders:write","seller:orders:fulfill","seller:orders:manage","seller:keys:pull","seller:keys:export","seller:keys:read","seller:keys:write","seller:refunds:write","seller:refunds:read","seller:webhooks:read","seller:webhooks:write","seller:promotions:read","seller:promotions:respond","seller:allocations:write","seller:finance:read","seller:account:manage"]},"description":"The scopes the new key gets, exactly. Each must be held by the calling key; one it lacks is refused with `403 INSUFFICIENT_SCOPE` and `details.missingScopes`, and no key is created. Omit for the default set, as before. With `includeFinanceScope: true`, `seller:finance:read` is added to the list."},"expiresAt":{"type":"string","format":"date-time","description":"When the new key stops working (ISO 8601 with an offset). At least one minute ahead and no later than the calling key's expiry. Omit to inherit the calling key's expiry (none when it has none). `api_key.expiring` is sent 14 days ahead for keys meant to live longer than that, and `api_key.expired` when it passes."}}},"SellerApiKeyAllowedIpsUpdateRequest":{"type":"object","required":["allowed_ips"],"properties":{"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`; these are documentation addresses, replace them with your own). Reserved ranges are rejected with 422: private (RFC1918), loopback, link-local, CGNAT, IPv6 ULA, multicast, and the documentation and benchmark ranges (`192.0.2.0/24`, `198.51.100.0/24`, `203.0.113.0/24`, `198.18.0.0/15`, `2001:db8::/32`). `/0` networks are rejected.","example":"203.0.113.5"},"description":"Replacement IP allowlist (0–50 entries). Pass an empty array to remove the IP restriction of a production key bound to a trusted workload, or the list of a sandbox key; an empty array on any other production key is refused with 422 `PRODUCTION_ALLOWLIST_REQUIRED`, and a sandbox key takes no list (422 `SANDBOX_ALLOWLIST_NOT_ALLOWED`), as in the console. 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. Absent on a replayed answer (`secretRedacted`)."},"livemode":{"type":"boolean","description":"True for a production key, false for a sandbox key. A new key always has the environment of the key that created it."},"secretRedacted":{"type":"boolean","description":"Present (`true`) only on an answer replayed for the same `Idempotency-Key`: the secret is never stored, so `key` is absent. The first answer carried it."},"scopes":{"type":"array","items":{"type":"string"},"description":"The scopes the new key was given."},"expiresAt":{"type":["string","null"],"format":"date-time","description":"When the new key expires; null when it does not."}}},"SellerApiKeyRotated":{"type":"object","description":"Returned once when a key's secret is rotated. The previous secret stops working at once, unless the rotation asked for `overlapSeconds` (see `previousSecretExpiresAt`).","properties":{"id":{"type":"string","format":"uuid"},"secret":{"type":"string","description":"The new full secret; never returned again. Note the name: `POST /keys` returns the secret of a new key as `key`."},"previousSecretExpiresAt":{"type":["string","null"],"format":"date-time","description":"Until when the replaced secret keeps working. Null when the rotation did not ask for `overlapSeconds`."},"secretRedacted":{"type":"boolean","description":"Present (`true`) only on an answer replayed for the same `Idempotency-Key`: the secret is never stored, so `secret` is absent. The first answer carried it."},"key":{"type":"string","deprecated":true,"description":"Never returned by this operation. Earlier versions of this document declared it by mistake; read `secret`."},"name":{"type":"string","deprecated":true,"description":"Never returned by this operation. Earlier versions of this document declared it by mistake."},"livemode":{"type":"boolean","deprecated":true,"description":"Never returned by this operation. Earlier versions of this document declared it by mistake."}}},"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":"Deprecated name of `salePriceMinor` (same value). Kept on the wire; see Naming conventions in the Versioning and compatibility guide. Billed unit price for this key (settlement promo already applied — see `promo`).","deprecated":true},"salePriceMinor":{"type":"integer","description":"Billed unit price for this key (settlement promo already applied — see `promo`). Same amount as `salePriceCents`, under the `...Minor` name every Seller API amount uses: integer minor units of the currency beside it (see `currencyExponent`)."},"initialSalePriceCents":{"type":["integer","null"],"description":"Deprecated name of `initialSalePriceMinor` (same value). Kept on the wire; see Naming conventions in the Versioning and compatibility guide. Catalog list unit price before any settlement promo. Null on rows recorded before promo provenance existed, on refund, chargeback and reinstatement rows, and on secondary-currency promo sales (the pre-promo price is in the catalog currency, not the sale currency); otherwise equal to `salePriceCents` when no promo applied.","deprecated":true},"initialSalePriceMinor":{"type":["integer","null"],"description":"Catalog list unit price before any settlement promo. Null on rows recorded before promo provenance existed, on refund, chargeback and reinstatement rows, and on secondary-currency promo sales (the pre-promo price is in the catalog currency, not the sale currency); otherwise equal to `salePriceCents` when no promo applied. Same amount as `initialSalePriceCents`, under the `...Minor` name every Seller API amount uses: integer minor units of the currency beside it (see `currencyExponent`)."},"promo":{"type":["object","null"],"description":"Settlement promo that discounted `salePriceCents`, or null. Also set on refund, chargeback and reinstatement rows, naming the promotion the original sale was sold under. 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."},"currencyExponent":{"type":"integer","minimum":0,"maximum":3,"description":"Number of minor-unit digits for `currencyCode`: 2 for USD, 0 for JPY, 3 for KWD. amount = minor units / 10^currencyExponent. Applies to every `*Cents` and `*Minor` on the row, including `settlement`. Additive."},"publisherShareCents":{"type":"integer","deprecated":true,"description":"Deprecated name of `publisherShareMinor` (same value). Kept on the wire; see Naming conventions in the Versioning and compatibility guide."},"publisherShareMinor":{"type":"integer","description":"Same amount as `publisherShareCents`, under the `...Minor` name every Seller API amount uses: integer minor units of the currency beside it (see `currencyExponent`)."},"sellerShareCents":{"type":"integer","deprecated":true,"description":"Deprecated name of `sellerShareMinor` (same value). Kept on the wire; see Naming conventions in the Versioning and compatibility guide."},"sellerShareMinor":{"type":"integer","description":"Same amount as `sellerShareCents`, under the `...Minor` name every Seller API amount uses: integer minor units of the currency beside it (see `currencyExponent`)."},"platformFeeCents":{"type":"integer","deprecated":true,"description":"Deprecated name of `platformFeeMinor` (same value). Kept on the wire; see Naming conventions in the Versioning and compatibility guide."},"platformFeeMinor":{"type":"integer","description":"Same amount as `platformFeeCents`, under the `...Minor` name every Seller API amount uses: integer minor units of the currency beside it (see `currencyExponent`)."},"revenueSharePercent":{"type":["number","null"]},"saleTimestamp":{"type":"string","format":"date-time"},"aggregationStatus":{"type":"string","enum":["pending","aggregated","disputed","quarantined"],"x-extensible-enum":true,"description":"`pending`: not yet in a monthly report. `aggregated`: counted in the report `reportId` names. `disputed`: the report it belongs to is under dispute. `quarantined`: held out of reporting until a data problem is fixed. New values may be added; treat an unknown one as not yet reported."},"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 the buyer was evidenced in at pull time: the consumer geo gate's IP lookup, or the checkout attestation's country when only that ran. Null when geo ran in `off` mode with no attestation, 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","vat_country_not_corroborated","vat_anonymizer_flag","vat_declared_rate_above_expected","vat_declared_rate_below_expected","vat_declared_rate_above_ceiling","vat_price_includes_tax_mismatch","vat_declaration_arithmetic_mismatch"]},"description":"Machine-readable reconciliation flags. `COUNTRY_MISMATCH`: the buyer IP resolved to a different country than the declared `salesCountryCode`. The `vat_*` codes are what the settlement noticed at the moment of sale and did not refuse over (the same `warnings` the order response carried): `vat_declared_rate_below_expected` — you declared a rate below the reference rate for the buyer's country and the sale settled at the rate you declared; `vat_declared_rate_above_expected` / `vat_declared_rate_above_ceiling` — capped at the reference; `vat_country_not_corroborated` — settled at your store country's rate. Empty when nothing was flagged."},"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."},"refundStatus":{"type":["string","null"],"enum":["pending","completed","chargeback_open","chargeback_lost","chargeback_won",null],"description":"The refund state of this sale in the vocabulary `GET /refunds` uses for `status`; null when nothing took the sale back. `adjustmentStatus` keeps the ledger's own values (`refund_pending` is `pending`, `refunded` is `completed`). `pending` is declared but not produced today: a refund is recorded complete in the same request."},"declaredRetail":{"type":["object","null"],"description":"Normalized declared retail checkout evidence from integrationOrderContext for ERP reconciliation.","properties":{"retailCurrencyCode":{"type":["string","null"]},"currencyExponent":{"type":["integer","null"],"minimum":0,"maximum":3,"description":"Number of minor-unit digits for `retailCurrencyCode`: 2 for USD, 0 for JPY, 3 for KWD. amount = minor / 10^currencyExponent; `null` when `retailCurrencyCode` is `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."}}},"PriceZone":{"type":"object","description":"The platform price zone a country belongs to: the group of countries a platform prices together in one currency (for example Steam's Latin America zone in USD). The same label the content owner sees .","properties":{"code":{"type":"string","description":"Stable zone code, e.g. `USD_LATAM`."},"label":{"type":"string","description":"Display label, e.g. `Latin America (USD)`."}},"required":["code","label"]},"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"},"currencyExponent":{"type":"integer","minimum":0,"maximum":3,"description":"Number of minor-unit digits for `currencyCode`: 2 for USD, 0 for JPY, 3 for KWD. amount = minor units / 10^currencyExponent. Present whenever `currencyCode` is. Additive."},"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"}}},"WebhookEnvelope":{"type":"object","description":"Routing identity present on every webhook delivery. The body is flat: these fields sit next to the event's own fields; there is no `data` wrapper and no envelope-level `createdAt` (timestamps are event-specific). They are set by Avrix, cannot be overridden by event data, and mirror the `X-Avrix-Event-Id`, `X-Avrix-Event-Log-Id`, `X-Avrix-Event-Type` and `X-Avrix-Event-Version` headers. Every delivery also carries an `X-Avrix-Delivery-Id` header: the id of the delivery row, as `GET /webhooks/{id}/deliveries` lists it.","required":["eventId","eventType","eventVersion"],"properties":{"eventId":{"type":"string","description":"Id of this delivery, identical to the `X-Avrix-Event-Id` header. Each endpoint that receives an event gets its own `eventId`, and a replayed delivery carries a new one. To recognise the same event across endpoints, retries and replays, use `eventLogId`."},"eventLogId":{"type":"string","description":"The event's own id, identical to the `X-Avrix-Event-Log-Id` header: one value per event per seller, the same on every endpoint that receives it, on retries and on replays, and the `id` of the event in `GET /events` (contract date `2026-12-01` and later). Deduplicate on it. Absent on deliveries created before the event log existed and, rarely, when the event could not be recorded."},"eventType":{"type":"string","description":"Event name, identical to the `X-Avrix-Event-Type` header. Switch on this field."},"eventVersion":{"type":"string","const":"1","description":"Payload schema version as a string, identical to the `X-Avrix-Event-Version` header."},"occurredAt":{"type":"string","format":"date-time","description":"When the event happened: the event's own time where it has one, else when the delivery was created. Present on every delivery."},"replay":{"type":"object","description":"Present only on deliveries created by `POST /webhooks/{id}/deliveries/replay`. Deduplicate on `originalEventId` to make replays idempotent.","required":["sourceDeliveryId","originalEventId"],"properties":{"sourceDeliveryId":{"type":"string","description":"Id of the delivery row that was replayed."},"originalEventId":{"type":"string","description":"`eventId` of the original delivery."}}},"testEvent":{"$ref":"#/components/schemas/WebhookTestEvent"}}},"WebhookOrderFulfilled":{"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.","allOf":[{"$ref":"#/components/schemas/WebhookEnvelope"},{"type":"object","required":["eventType"],"properties":{"eventType":{"type":"string","const":"order.fulfilled"},"orderReference":{"type":["string","null"]},"skuId":{"type":["string","null"],"format":"uuid","description":"SKU sold."},"skuCode":{"type":"string","description":"SKU code of skuId."},"quantity":{"type":"integer","description":"Keys (or keyless fulfilments) delivered by this event; equal to pulled."},"fulfilledAt":{"type":["string","null"],"format":"date-time","description":"When the order was fulfilled."},"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","deprecated":true,"description":"Deprecated: use `orderId`. The id of the order's first key pull."},"orderId":{"type":"string","description":"The order's id: the `orderId` the create response returned."},"deferredReveal":{"type":"boolean"},"riskWarning":{"$ref":"#/components/schemas/RiskWarning"},"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"}},"additionalProperties":true}]},"WebhookOrderActivated":{"description":"Payload for order.activated webhook event (keyless buyer activation)","allOf":[{"$ref":"#/components/schemas/WebhookEnvelope"},{"type":"object","required":["eventType"],"properties":{"eventType":{"type":"string","const":"order.activated"},"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"}]}},"additionalProperties":true}]},"WebhookOrderReserved":{"description":"Payload for order.reserved webhook event (pre-order)","allOf":[{"$ref":"#/components/schemas/WebhookEnvelope"},{"type":"object","required":["eventType"],"properties":{"eventType":{"type":"string","const":"order.reserved"},"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)."},"status":{"type":"string","description":"`awaiting_stock` for a customer-order backorder; omitted for a release-date pre-order."},"backorderExpiresAt":{"type":"string","format":"date-time","description":"Backorders only: when the order is cancelled with `order.backorder_expired` if stock has not arrived."},"integrationOrderContextRedacted":{"allOf":[{"$ref":"#/components/schemas/IntegrationOrderContextWebhookRedacted"}],"description":"Declared retail correlation fields when integrationOrderContext was sent on the request. Omitted when absent."}},"additionalProperties":true}]},"WebhookOrderReturned":{"description":"Older name of `order.cancelled`: a pre-order, backorder or reserved order was cancelled before delivery (`POST /orders/cancel`); no keys were delivered. Endpoints subscribed to `order.returned` keep receiving it, with the same `eventLogId` as the `order.cancelled` delivery of the same cancellation. Subscribe to `order.cancelled` instead; a key return is `order.keys_returned`.","allOf":[{"$ref":"#/components/schemas/WebhookEnvelope"},{"type":"object","required":["eventType"],"properties":{"eventType":{"type":"string","const":"order.returned"},"orderReference":{"type":"string"},"orderId":{"type":"string","description":"Readable order id, when the cancelled order has one."},"cancelled":{"type":"integer"},"reason":{"type":["string","null"]}},"additionalProperties":true}]},"WebhookOrderKeysReturned":{"description":"Payload for order.keys_returned webhook event (post-fulfillment key return via POST /keys/return)","allOf":[{"$ref":"#/components/schemas/WebhookEnvelope"},{"type":"object","required":["eventType"],"properties":{"eventType":{"type":"string","const":"order.keys_returned"},"orderReference":{"type":["string","null"],"description":"The order the keys came from, when they all came from one; null when they span several (see orderReferences)."},"orderReferences":{"type":"array","items":{"type":"string"},"description":"Every order the returned keys came from."},"keyIds":{"type":"array","items":{"type":"string","format":"uuid"}},"returned":{"type":"integer"},"reason":{"type":["string","null"]}},"additionalProperties":true}]},"WebhookProductUpdated":{"description":"Payload for product.updated webhook event","allOf":[{"$ref":"#/components/schemas/WebhookEnvelope"},{"type":"object","required":["eventType"],"properties":{"eventType":{"type":"string","const":"product.updated"},"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"},"changedFields":{"type":"array","items":{"type":"string","enum":["pricing","availability","metadata","territory","relationships"]},"description":"Which facets of the product changed, with the same values as `GET /catalog/changes`: `metadata` (name, slug, type, category, credits, store copy) and `relationships` (base game or bundle link) today. Absent when the sender does not know; refetch the whole product then. Additive."}},"additionalProperties":true}]},"WebhookAllocationUpdated":{"description":"Payload for allocation.updated webhook event","allOf":[{"$ref":"#/components/schemas/WebhookEnvelope"},{"type":"object","required":["eventType"],"properties":{"eventType":{"type":"string","const":"allocation.updated"},"allocationId":{"type":"string"},"skuId":{"type":"string"},"quantityLimit":{"type":"integer"},"quantityPulled":{"type":"integer"},"remaining":{"type":"integer"},"hotDropMode":{"type":"boolean","description":"Whether the allocation is in launch mode (reserve then commit)."},"reason":{"type":"string","description":"Why the allocation changed, for example created, resized, paused, revoked, pulled, returned or hot_drop_mode_changed."},"status":{"type":"string"}},"additionalProperties":true}]},"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"}}},"SellerOrderEconomics":{"type":"object","description":"What an order was billed at: the order's API sale rows (`GET /finance/api-sales`) summed, with the same field names as the activity log's `economics`. Nothing here is computed that the sale rows do not hold. Refunds and chargebacks are not netted in; they appear under the order's `refunds` and in the finance reads. Amounts are minor units of `currencyCode` (amount = value / 10^currencyExponent).","required":["currencyCode","currencyExponent","quantity","unitPriceCents","unitPriceMinor","initialUnitPriceCents","initialUnitPriceMinor","totalPriceCents","totalPriceMinor","promo","publisherShareCents","publisherShareMinor","sellerShareCents","sellerShareMinor","platformFeeCents","platformFeeMinor","revenueSharePercent","vatMinor","netMinor","transactionIds"],"properties":{"currencyCode":{"type":"string","description":"ISO 4217 code of every amount in this block."},"currencyExponent":{"type":"integer","minimum":0,"maximum":3,"description":"Minor-unit digits for `currencyCode`: 2 for USD, 0 for JPY, 3 for KWD."},"quantity":{"type":"integer","minimum":1,"description":"Keys billed: one sale row each."},"unitPriceCents":{"type":["integer","null"],"description":"Deprecated name of `unitPriceMinor` (same value). Kept on the wire; see Naming conventions in the Versioning and compatibility guide. Billed unit price (settlement promo applied). Null when the keys were billed at different prices.","deprecated":true},"unitPriceMinor":{"type":["integer","null"],"description":"Billed unit price (settlement promo applied). Null when the keys were billed at different prices. Same amount as `unitPriceCents`, under the `...Minor` name every Seller API amount uses: integer minor units of the currency beside it (see `currencyExponent`)."},"initialUnitPriceCents":{"type":["integer","null"],"description":"Deprecated name of `initialUnitPriceMinor` (same value). Kept on the wire; see Naming conventions in the Versioning and compatibility guide. List unit price before any settlement promo. Null when unknown or not the same for every key.","deprecated":true},"initialUnitPriceMinor":{"type":["integer","null"],"description":"List unit price before any settlement promo. Null when unknown or not the same for every key. Same amount as `initialUnitPriceCents`, under the `...Minor` name every Seller API amount uses: integer minor units of the currency beside it (see `currencyExponent`)."},"totalPriceCents":{"type":"integer","description":"Deprecated name of `totalPriceMinor` (same value). Kept on the wire; see Naming conventions in the Versioning and compatibility guide. Billed price of all keys of the order.","deprecated":true},"totalPriceMinor":{"type":"integer","description":"Billed price of all keys of the order. Same amount as `totalPriceCents`, under the `...Minor` name every Seller API amount uses: integer minor units of the currency beside it (see `currencyExponent`)."},"promo":{"type":["object","null"],"required":["sourceType","sourceId"],"description":"The settlement promo that discounted the price, or null (also null when the keys were sold under different promos).","properties":{"sourceType":{"type":"string","enum":["event","custom"]},"sourceId":{"type":"string","description":"shareId (`event`) or responseId (`custom`) under /promotions."}}},"publisherShareCents":{"type":"integer","description":"Deprecated name of `publisherShareMinor` (same value). Kept on the wire; see Naming conventions in the Versioning and compatibility guide. The Content Owner's share of the order.","deprecated":true},"publisherShareMinor":{"type":"integer","description":"The Content Owner's share of the order. Same amount as `publisherShareCents`, under the `...Minor` name every Seller API amount uses: integer minor units of the currency beside it (see `currencyExponent`)."},"sellerShareCents":{"type":"integer","description":"Deprecated name of `sellerShareMinor` (same value). Kept on the wire; see Naming conventions in the Versioning and compatibility guide. Your share of the order.","deprecated":true},"sellerShareMinor":{"type":"integer","description":"Your share of the order. Same amount as `sellerShareCents`, under the `...Minor` name every Seller API amount uses: integer minor units of the currency beside it (see `currencyExponent`)."},"platformFeeCents":{"type":"integer","description":"Deprecated name of `platformFeeMinor` (same value). Kept on the wire; see Naming conventions in the Versioning and compatibility guide. The platform fee on the order.","deprecated":true},"platformFeeMinor":{"type":"integer","description":"The platform fee on the order. Same amount as `platformFeeCents`, under the `...Minor` name every Seller API amount uses: integer minor units of the currency beside it (see `currencyExponent`)."},"revenueSharePercent":{"type":["number","null"],"description":"The Agreement's revenue share percent. Null when the keys were billed under different percents."},"vatMinor":{"type":["integer","null"],"description":"Consumer VAT the settlement deducted, summed. Null when any key's sale predates the settlement basis."},"netMinor":{"type":["integer","null"],"description":"Gross less VAT, summed: the base the shares were computed on. Null as for `vatMinor`."},"transactionIds":{"type":"array","items":{"type":"string","format":"uuid"},"description":"The sale rows summed here (`GET /finance/api-sales/{transactionId}`)."}}},"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":{"$ref":"#/components/schemas/SellerDeliveredKey"},"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","deprecated":true,"description":"Deprecated: use `orderId`. On contract date `2026-12-01` and later this is always the same value as `orderId`. On older dates it is the id of the order's first key pull, which differs from `orderId` for an order placed before this change shipped (changelog, `2026-12-01`) and for a pre-order delivered later. Both values keep resolving on every order lookup."},"orderId":{"type":"string","description":"The order's id (`ord_` plus eight characters). One value for the life of the order: the same in the create response, `GET /orders`, `GET /orders/{orderId}`, the bulk line and the `order.fulfilled` webhook. Store this one. Every endpoint that addresses an order (`GET /orders/{orderId}`, `GET /orders?orderReadableId=`, `POST /orders/{orderId}/fulfill`, key replacement) accepts it."},"economics":{"anyOf":[{"$ref":"#/components/schemas/SellerOrderEconomics"},{"type":"null"}],"description":"What the delivered keys were billed at, summed from the order's API sale rows. Null when the order has none: a wholesale or complimentary allocation (billed per allocation, not per sale), or nothing delivered yet."},"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."},"riskWarning":{"$ref":"#/components/schemas/RiskWarning"},"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."},"transactionIds":{"type":"array","items":{"type":"string","format":"uuid"},"description":"Ids of the API sale transaction rows recorded for this order — one per delivered key, the same `id` as `GET /finance/api-sales` and `GET /finance/api-sales/{transactionId}`. Always present; empty (`[]`) when the allocation's business model is not `api` (no API sale row is recorded at pull time)."},"geoWarning":{"$ref":"#/components/schemas/GeoWarning","description":"Only on `api` business-model allocations, and only when the buyer IP check flagged the sale without refusing it: consumer geo in monitor mode (`whoami.capabilities.consumerGeoMonitorEnabled`) with a would-be denial, or — under enforcement — a `CONSUMER_GEO_MISMATCH` / `CONSUMER_IP_HIGH_RISK` that the Content Owner's agreement geo policy lets through (`warn` or `settle_at_evidence`). Additive: the order still succeeded. Omitted otherwise."},"fulfillmentState":{"type":"string","enum":["fulfilled","pre_order"],"description":"Whether the order delivered keys now (fulfilled) or was recorded as a pre-order awaiting release (pre_order)."},"warnings":{"type":"array","items":{"type":"string"},"description":"What the settlement noticed but did not refuse over: `vat_declared_rate_below_expected` (you declared a rate below the reference rate for the buyer's country; the sale settled at the rate you declared), `vat_declared_rate_above_expected` / `vat_declared_rate_above_ceiling` (capped at the reference), `vat_country_not_corroborated` (settled at your store country's rate), `vat_anonymizer_flag`, `vat_price_includes_tax_mismatch`, `vat_declaration_arithmetic_mismatch`. Additive, and never a reason for a non-200: the sale happened and the key was delivered. The same flags are persisted on the sale row and returned as `warnings` on `GET /finance/api-sales` and `GET /activity`. Also returned on `POST /orders/commit`, each fulfilled `POST /orders/bulk` line and `POST /keys/pull`."}}},"SellerOrderKeylessDelivery":{"type":"object","description":"Keyless delivery reference for hosted_redemption and future platform-native providers.","required":["provider","fulfillmentId"],"properties":{"linkGroupId":{"type":["string","null"],"format":"uuid","description":"Set when one link (`redemptionUrl`) covers several keys; each key is revealed on its own on the hosted page."},"items":{"type":"array","description":"One entry per key of the line, in `keyIds` order. `fulfillmentId` is what POST /orders/fulfillments/{fulfillmentId}/revoke and regenerate take.","items":{"type":"object","required":["fulfillmentId","keyId","expiresAt"],"properties":{"fulfillmentId":{"type":"string","format":"uuid"},"keyId":{"type":"string","format":"uuid"},"redemptionUrl":{"type":["string","null"],"description":"This key's own link (the line's link is `redemptionUrl`)."},"expiresAt":{"type":"string","format":"date-time"}}}},"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"]},"status":{"type":"string","enum":["awaiting_release","awaiting_stock"],"description":"`awaiting_release`: reserved until the release date. `awaiting_stock`: a backorder waiting for stock (see `backorderExpiresAt`)."},"orderId":{"type":"string","description":"The order's id (`ord_` plus eight characters). One value for the life of the order: the same in the create response, `GET /orders`, `GET /orders/{orderId}`, the bulk line and the `order.fulfilled` webhook. Store this one. Every endpoint that addresses an order (`GET /orders/{orderId}`, `GET /orders?orderReadableId=`, `POST /orders/{orderId}/fulfill`, key replacement) accepts it. Returned when the order is accepted, before any key is delivered."},"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"]},"backorderExpiresAt":{"type":"string","format":"date-time","description":"Only on a customer-order backorder (`status: awaiting_stock`, requested with `backorderOnUnavailable`). If the order is still awaiting stock at this time it is cancelled, its allocation headroom released and `order.backorder_expired` sent: refund the buyer. Default timeout 14 days."},"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."},"transactionIds":{"type":"array","items":{"type":"string","format":"uuid"},"description":"Always present and always empty (`[]`) for a pre-order: a reservation records no sale transaction. Kept for shape parity with the fulfilled variant."},"geoWarning":{"$ref":"#/components/schemas/GeoWarning","description":"Only on `api` business-model allocations, and only when the buyer IP check flagged the sale without refusing it: consumer geo in monitor mode (`whoami.capabilities.consumerGeoMonitorEnabled`) with a would-be denial, or — under enforcement — a `CONSUMER_GEO_MISMATCH` / `CONSUMER_IP_HIGH_RISK` that the Content Owner's agreement geo policy lets through (`warn` or `settle_at_evidence`). Additive: the reservation still succeeded. Omitted otherwise."},"fulfillmentState":{"type":"string","enum":["fulfilled","pre_order"],"description":"Whether the order delivered keys now (fulfilled) or was recorded as a pre-order awaiting release (pre_order)."},"warnings":{"type":"array","items":{"type":"string"},"description":"What the settlement noticed but did not refuse over: `vat_declared_rate_below_expected` (you declared a rate below the reference rate for the buyer's country; the sale settled at the rate you declared), `vat_declared_rate_above_expected` / `vat_declared_rate_above_ceiling` (capped at the reference), `vat_country_not_corroborated` (settled at your store country's rate), `vat_anonymizer_flag`, `vat_price_includes_tax_mismatch`, `vat_declaration_arithmetic_mismatch`. Additive, and never a reason for a non-200: the sale happened and the key was delivered. The same flags are persisted on the sale row and returned as `warnings` on `GET /finance/api-sales` and `GET /activity`. Also returned on `POST /orders/commit`, each fulfilled `POST /orders/bulk` line and `POST /keys/pull`."}},"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). A malformed address, or a private, loopback, link-local or carrier-NAT one, is refused at parse time with 422 `CONSUMER_IP_INVALID` on every surface. On production keys, the calling server's own address or one matching the key's IP allowlist is also refused with 422 `CONSUMER_IP_INVALID` (the buyer, not the store). 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"},"currencyExponent":{"type":"integer","minimum":0,"maximum":3,"readOnly":true,"description":"Response only: number of minor-unit digits for `currencyCode` (2 for USD, 0 for JPY, 3 for KWD), for the `*Minor` amounts. Set by Avrix on the echo (`GET /finance/api-sales`, statement lines) whenever `currencyCode` is; never send it on a request. Additive."},"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_CONSUMED","CONSUMER_GEO_ATTEST_EXPIRED","CONSUMER_GEO_ATTEST_INVALID","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","CONSUMER_RISK_HIGH","CONSUMER_RISK_UNAVAILABLE","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_KEY_REQUIRED","IDEMPOTENCY_REQUEST_IN_FLIGHT","IDEMPOTENCY_STORE_UNAVAILABLE","INSUFFICIENT_SCOPE","INSUFFICIENT_WALLET_BALANCE","INTERNAL_ERROR","INVALID_CATALOG_PRICE","INVALID_CLIENT","INVALID_REQUEST_ID","IP_NOT_ALLOWED","IP_NOT_RESOLVABLE","WORKLOAD_IDENTITY_INVALID","KEYLESS_ISSUANCE_FAILED","KEY_DECRYPT_FAILED","KEY_NOT_REPLACEABLE","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","PRODUCT_NOT_SHARED","QUANTITY_INVALID","RATE_LIMIT_EXCEEDED","EXPIRED","REGENERATE_NOT_SUPPORTED","RESERVATION_COMMIT_IN_PROGRESS","RESERVATION_EXTEND_EXHAUSTED","RESERVATION_GONE","HOLD_EXISTS","SALES_CHANNEL_NOT_PERMITTED","SALES_CHANNEL_REQUIRED","SALES_COUNTRY_MISMATCH","SALES_COUNTRY_REQUIRED","SANDBOX_MAGIC_VALUE_REJECTED","SERVICE_UNAVAILABLE","SKU_REGION_UNRESOLVED","SRP_MISMATCH_FOR_CURRENCY","TAX_DECLARATION_REQUIRED","VAT_DECLARATION_BELOW_REFERENCE","TERRITORY_EXCLUDED_FOR_RELEASE","REGION_LOCKED_FOR_CONTRACT","REGION_LOCKED_FOR_SKU","TERRITORY_NOT_ALLOWED_FOR_SKU","TERRITORY_NOT_GRANTED","TREASURY_CAPABILITY_MISSING","UNAUTHORIZED","UNSUPPORTED_API_VERSION","VALIDATION_FAILED","WHOLESALE_PRICE_MISMATCH","ALLOCATION_INACTIVE","ALLOCATION_NOT_FOUND","SKU_NOT_FOUND","SOLD_OUT","STORE_UNAVAILABLE","KEY_NOT_RETURNABLE","REFUND_QUANTITY_EXCEEDS_LIVE_KEYS","REFUND_WINDOW_EXPIRED","REFUND_LIMIT_REACHED","ORDER_NOT_EXTENDABLE","CATALOG_RESYNC_REQUIRED","SANDBOX_ENVIRONMENT_PAUSED","SANDBOX_ENVIRONMENT_UNAVAILABLE","SANDBOX_KEY_REQUIRED","SANDBOX_SCENARIO_UNAVAILABLE","SANDBOX_SIMULATE_UNKNOWN","SANDBOX_ISOLATED_ENVIRONMENT_REQUIRED","WEBHOOK_ENDPOINT_LIMIT_REACHED"]},"message":{"type":"string","description":"Human-readable error message"},"error":{"type":"string","description":"Deprecated. Use message instead. Kept for backward compatibility. On `POST /oauth/token` with a form-encoded body, and with JSON on contract date `2026-12-01` and later, it holds the RFC 6749 error code (`invalid_client`, `invalid_request`, ...) instead.","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` when the key lacks the scope an operation needs: `FORBIDDEN` on contract dates before `2026-12-01`, `INSUFFICIENT_SCOPE` with `scopeMode` on `2026-12-01` and later). Commercial refusals on the order path carry the refusing guard's own detail: `fixItUrl` for a footprint refusal, `grantSource` when partner access refused it, `declaredCountry` and `detectedCountry` for a geo refusal.","properties":{"missingScope":{"type":"string","description":"On a scope refusal: the scope the operation prefers. `403 INSUFFICIENT_SCOPE` on contract date `2026-12-01` and later; `403 FORBIDDEN` on earlier dates, where it names the scope the check was first written for"},"requiredScopes":{"type":"array","items":{"type":"string"},"description":"On a scope refusal: scopes that would be accepted; holding any one of them is enough. On contract date `2026-12-01` and later (`INSUFFICIENT_SCOPE`) it lists every scope the operation accepts, preferred first, the same list as the operation's `x-avrix-scopes`. On earlier dates (`FORBIDDEN`) it keeps the list the refusal has always reported, which can be shorter"},"scopeMode":{"type":"string","enum":["anyOf","any"],"description":"On `INSUFFICIENT_SCOPE` (contract date `2026-12-01` and later): `anyOf` when the key must hold one of `requiredScopes`; `any` when any Seller API scope is enough (`requiredScopes` then lists them all)"},"requestBodyHash":{"type":"string","description":"SHA-256 hex digest of canonical JSON body (idempotency mismatch responses only)"},"idempotency":{"type":"string","description":"When present, the idempotency condition that refused the request: `key_missing` or `key_invalid` with `IDEMPOTENCY_KEY_REQUIRED` (contract date `2026-12-01` and later), `request_in_flight` with `IDEMPOTENCY_REQUEST_IN_FLIGHT`, `store_unavailable` with `IDEMPOTENCY_STORE_UNAVAILABLE`."},"issues":{"type":"array","description":"Field-level errors for VALIDATION_FAILED (query or JSON body). On the order surfaces (POST /orders, /orders/preview, /orders/hold, /orders/reserve) a field-level refusal (VALIDATION_FAILED, SALES_COUNTRY_REQUIRED, TAX_DECLARATION_REQUIRED, SALES_CHANNEL_REQUIRED, EXPECTED_UNIT_PRICE_REQUIRED) lists every invalid or missing field of the request at once; the refusal's own field comes first and the top-level code and message are unchanged.","items":{"type":"object","properties":{"field":{"type":"string","description":"Path of the field, e.g. integrationOrderContext.salesChannel"},"message":{"type":"string"},"code":{"type":"string","description":"The coded refusal this field alone would get (e.g. SALES_CHANNEL_REQUIRED), when it has one"},"allowedValues":{"type":"array","description":"For an enum field: every value the API accepts","items":{"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","restrict_sale_to_activation_countries"]},"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","deprecated":true,"description":"Deprecated (2026-10-09): never set. Was present on SRP_MISMATCH_FOR_CURRENCY, which is no longer returned since a country is sold in the one currency it is priced in."},"grantSource":{"type":"string","enum":["partner_access"],"description":"Present on TERRITORY_NOT_GRANTED and CURRENCY_NOT_PERMITTED_BY_TERM when the refusal comes from your partner access with the Content Owner (`whoami.accessByPublisher[].enforced: true`) rather than the agreement's frozen terms. `accessByPublisher` lists what is granted; the Content Owner can propose more, which you accept with `POST /access/proposals/{id}/accept`."},"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","review_commercial_settings"],"description":"Machine-readable label for `consoleUrl`; stable across releases."},"reason":{"type":"string","enum":["PREORDER_NOT_OPEN","PREORDER_CLOSED","PREORDER_DISABLED","LIFECYCLE_NOT_LIVE","retention_expired"],"description":"On `CATALOG_RESYNC_REQUIRED`: `retention_expired` when the change-feed position is older than the feed's retention (contract date `2026-12-01` and later). Otherwise, 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."}}},"error_description":{"type":"string","description":"`POST /oauth/token` only: the message, under the name OAuth 2.0 clients read (RFC 6749 section 5.2)."}},"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 codes of the countries that make up this region. A release can exclude some of them: `releases[].allowedCountries` on the product is the list for one release."},"deniedCountries":{"type":"array","items":{"type":"string","minLength":2,"maxLength":2},"description":"Reserved. Always an empty array on the region routes."}}},"SellerRegionDetail":{"allOf":[{"$ref":"#/components/schemas/SellerRegionSummary"}]},"SellerRefund":{"type":"object","required":["id","status","type","skuId","productId","reversalTransactionId","salePriceCents","salePriceMinor","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. `pending` is reserved: no refund is recorded in that state today, so a refund you declare reads `completed` at once."},"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":"The reference you sent on `POST /refunds` (`refundReference` or `chargebackReference`). Also returned split by type as `refundReference` and `chargebackReference`."},"reversalTransactionId":{"type":["string","null"],"format":"uuid","description":"Ledger transaction that reverses this sale, when the financial reversal has been written."},"salePriceCents":{"type":"integer","deprecated":true,"description":"Deprecated name of `salePriceMinor` (same value). Kept on the wire; see Naming conventions in the Versioning and compatibility guide."},"salePriceMinor":{"type":"integer","description":"Same amount as `salePriceCents`, under the `...Minor` name every Seller API amount uses: integer minor units of the currency beside it (see `currencyExponent`)."},"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"},"refundReference":{"type":["string","null"],"description":"The `refundReference` you sent, for a refund or return; null for a chargeback or when none was sent. Filter with `GET /refunds?refundReference=`."},"chargebackReference":{"type":["string","null"],"description":"The `chargebackReference` you sent, for a chargeback; null otherwise. Filter with `GET /refunds?chargebackReference=`."}}},"WebhookTestPing":{"description":"Body of a `test.ping` delivery, queued by `POST /webhooks/{id}/test`. Carries no commerce data; use it to verify signature handling end to end.","allOf":[{"$ref":"#/components/schemas/WebhookEnvelope"},{"type":"object","required":["eventType","test","sentAt","endpointId"],"properties":{"eventType":{"type":"string","const":"test.ping"},"test":{"type":"boolean","const":true},"sentAt":{"type":"string","format":"date-time","description":"When the test delivery was queued."},"endpointId":{"type":"string","description":"Endpoint the ping was sent to."}}}]},"WebhookOrderFailed":{"description":"An order could not be fulfilled after commit.","allOf":[{"$ref":"#/components/schemas/WebhookEnvelope"},{"type":"object","required":["eventType","orderReference","allocationId","reason"],"properties":{"eventType":{"type":"string","const":"order.failed"},"orderReference":{"type":["string","null"],"description":"Your reference for the order, when one was sent."},"allocationId":{"type":"string"},"reason":{"type":"string","description":"Machine-readable failure reason."}}}]},"WebhookOrderPreorderFulfilled":{"description":"A pre-order converted to a fulfilled delivery.","allOf":[{"$ref":"#/components/schemas/WebhookEnvelope"},{"type":"object","required":["eventType","orderReference","pulled","allocationId"],"properties":{"eventType":{"type":"string","const":"order.preorder_fulfilled"},"orderReference":{"type":["string","null"]},"pulled":{"type":"integer","description":"Keys delivered."},"allocationId":{"type":"string"},"skuId":{"type":"string"},"orderId":{"type":"string","description":"Readable order id (`ord_…`), when the delivery came from an order."},"orderReadableId":{"type":"string","description":"Readable order id (`ord_…`), on the reservation-sweep path."}},"additionalProperties":true}]},"WebhookRefundCompleted":{"description":"A refund was finalized for a sale line.","allOf":[{"$ref":"#/components/schemas/WebhookEnvelope"},{"type":"object","required":["eventType","returned"],"properties":{"eventType":{"type":"string","const":"refund.completed"},"orderReference":{"type":["string","null"],"description":"The order the keys came from, when they all came from one; null when they span several (see orderReferences)."},"orderReferences":{"type":"array","items":{"type":"string"},"description":"Every order the returned keys came from."},"returned":{"type":"integer","description":"Keys quarantined by the refund."},"keyIds":{"type":"array","items":{"type":"string","format":"uuid"},"description":"Keys the refund quarantined."},"reason":{"type":["string","null"]},"adjustmentType":{"type":"string","enum":["refund","chargeback","return"],"description":"What the reversal was recorded as."},"returnRequestId":{"type":"string"},"transferId":{"type":"string"},"refundReference":{"type":["string","null"],"description":"The `refundReference` you sent (refunds and returns)."},"chargebackReference":{"type":["string","null"],"description":"The `chargebackReference` you sent (chargebacks)."},"refundIds":{"type":"array","items":{"type":"string","format":"uuid"},"description":"The refund record ids (`GET /refunds/{refundId}`)."},"keyDisposition":{"type":"string","enum":["quarantined","held","mixed"],"description":"What happened to the keys: `quarantined`, `held` (revenue share) or `mixed`."},"saleTotals":{"type":"array","description":"Sale value of the refunded API-model keys per currency, in minor units. Keys sold under other business models have no sale record and add nothing.","items":{"type":"object","required":["currencyCode","salePriceCents","salePriceMinor"],"properties":{"currencyCode":{"type":"string"},"salePriceCents":{"type":"integer","description":"Deprecated name of `salePriceMinor` (same value). Kept on the wire; see Naming conventions in the Versioning and compatibility guide.","deprecated":true},"salePriceMinor":{"type":"integer","description":"Same amount as `salePriceCents`, under the `...Minor` name every Seller API amount uses: integer minor units of the currency beside it (see `currencyExponent`)."}}}}},"additionalProperties":true}]},"WebhookChargebackResolved":{"description":"A chargeback dispute was resolved.","allOf":[{"$ref":"#/components/schemas/WebhookEnvelope"},{"type":"object","required":["eventType","chargebackReference","outcome","resolved"],"properties":{"eventType":{"type":"string","const":"chargeback.resolved"},"chargebackReference":{"type":"string","description":"Your reference for the dispute."},"outcome":{"type":"string","enum":["won","lost"]},"resolved":{"type":["integer","boolean"],"description":"Number of sale transactions resolved in this chargeback group: an integer, the same value as `data.resolved` of `POST /chargebacks/resolve`. Earlier versions of this document typed it as a boolean, and until 2026-11-13 the sandbox test event (`POST /webhooks/{id}/test` with `eventType: chargeback.resolved`) sent `true`; it now sends an integer like the live event."}}}]},"WebhookKeysPulled":{"description":"Keys were pulled through `POST /keys/pull` (the non-order path). Key plaintext is never included — persist it from the synchronous response.","allOf":[{"$ref":"#/components/schemas/WebhookEnvelope"},{"type":"object","required":["eventType","pulled","allocationId"],"properties":{"eventType":{"type":"string","const":"keys.pulled"},"pulled":{"type":"integer"},"allocationId":{"type":"string"},"deferredReveal":{"type":"boolean","description":"True when delivery used deferred key reveal."},"riskWarning":{"$ref":"#/components/schemas/RiskWarning"},"orderReadableId":{"type":"string"},"contractTermId":{"type":"string"},"contractTermVersion":{"type":"integer"}},"additionalProperties":true}]},"WebhookKeyReplaced":{"description":"A delivered key was replaced by a fresh key from the same allocation (`POST /orders/{orderId}/keys/{keyId}/replace`), at once within the Content Owner's policy or after the Content Owner approved it. No new sale and no capacity charge. Key plaintext is never included: read it from the synchronous response or `POST /orders/recover-keys`.","allOf":[{"$ref":"#/components/schemas/WebhookEnvelope"},{"type":"object","required":["eventType","replacementId","orderReference","replacedKeyId","keyId","reason"],"properties":{"eventType":{"type":"string","const":"key.replaced"},"replacementId":{"type":"string","format":"uuid"},"orderId":{"type":["string","null"],"description":"Readable order id (`ord_…`)."},"orderReference":{"type":"string"},"replacedKeyId":{"type":"string","format":"uuid","description":"The key taken out of the order (quarantined)."},"keyId":{"type":"string","format":"uuid","description":"The key delivered instead."},"skuId":{"type":"string"},"allocationId":{"type":"string"},"reason":{"type":"string","enum":["already_redeemed","invalid","wrong_region","revoked"]},"approval":{"type":"string","enum":["auto","publisher"],"description":"`auto` = within the Content Owner's policy; `publisher` = approved by the Content Owner."},"replacedAt":{"type":["string","null"],"format":"date-time"}},"additionalProperties":true}]},"WebhookKeysRevoked":{"description":"The Content Owner revoked keys that were already sold on one of your orders (a leaked batch, grey-market resale, a platform revocation, fraud). One event per order. The keys no longer work and `POST /orders/recover-keys` no longer returns them. `recommendedAction` is `replace` when the allocation still has a key for every revoked one (`POST /orders/{orderId}/keys/{keyId}/replace` accepts a revoked key), otherwise `refund`.","allOf":[{"$ref":"#/components/schemas/WebhookEnvelope"},{"type":"object","required":["eventType","orderReference","keyIds","reason","recommendedAction","revokedAt"],"properties":{"eventType":{"type":"string","const":"keys.revoked"},"orderId":{"type":["string","null"],"description":"Readable order id (`ord_…`)."},"orderReference":{"type":"string"},"keyIds":{"type":"array","items":{"type":"string","format":"uuid"}},"skuId":{"type":"string"},"allocationId":{"type":"string"},"reason":{"type":"string","enum":["leaked","grey_market","platform_revoked","fraud","other"]},"recommendedAction":{"type":"string","enum":["replace","refund"]},"revokedAt":{"type":"string","format":"date-time"}},"additionalProperties":true}]},"WebhookKeyFrozen":{"description":"Delivered keys were frozen for an open dispute (`POST /disputes/freeze`). `POST /orders/recover-keys` withholds them and they cannot be replaced until the freeze ends.","allOf":[{"$ref":"#/components/schemas/WebhookEnvelope"},{"type":"object","required":["eventType","freezeId","keyIds","reason","expiresAt"],"properties":{"eventType":{"type":"string","const":"key.frozen"},"freezeId":{"type":"string","format":"uuid"},"keyIds":{"type":"array","items":{"type":"string","format":"uuid"}},"orderReferences":{"type":"array","items":{"type":"string"}},"reason":{"type":"string","enum":["payment_dispute","fraud_review","chargeback_inquiry"]},"disputeReference":{"type":["string","null"]},"expiresAt":{"type":"string","format":"date-time"}},"additionalProperties":true}]},"WebhookKeyUnfrozen":{"description":"A dispute freeze ended. `resolution`: `released` (you released it), `expired` (reached `expiresAt`), `refunded` or `chargeback` (POST /refunds settled its keys; `status: converted`).","allOf":[{"$ref":"#/components/schemas/WebhookEnvelope"},{"type":"object","required":["eventType","freezeId","keyIds","status","resolution"],"properties":{"eventType":{"type":"string","const":"key.unfrozen"},"freezeId":{"type":"string","format":"uuid"},"keyIds":{"type":"array","items":{"type":"string","format":"uuid"}},"status":{"type":"string","enum":["released","expired","converted"]},"resolution":{"type":"string","enum":["released","expired","refunded","chargeback"]},"reason":{"type":"string"},"disputeReference":{"type":["string","null"]},"endedAt":{"type":"string","format":"date-time"}},"additionalProperties":true}]},"WebhookFulfillmentRevoked":{"description":"A keyless redemption link was revoked before redemption: by you (POST /orders/fulfillments/{fulfillmentId}/revoke), by a refund or chargeback on POST /refunds, or because the Content Owner revoked the key. The buyer can no longer reveal it.","allOf":[{"$ref":"#/components/schemas/WebhookEnvelope"},{"type":"object","required":["eventType","fulfillmentId","reason"],"properties":{"eventType":{"type":"string","const":"fulfillment.revoked"},"fulfillmentId":{"type":"string","format":"uuid"},"orderReference":{"type":["string","null"]},"keyId":{"type":["string","null"],"format":"uuid"},"linkGroupId":{"type":["string","null"],"format":"uuid"},"provider":{"type":"string"},"reason":{"type":"string","enum":["manual","refund","chargeback","revoked_key"]},"revokedAt":{"type":"string","format":"date-time"}},"additionalProperties":true}]},"WebhookAllocationReplenished":{"description":"Your low-stock threshold (`PATCH /allocations/{id}`) was crossed and the Content Owner's rules topped the allocation up automatically. `allocation.updated` (reason `replenished`) follows.","allOf":[{"$ref":"#/components/schemas/WebhookEnvelope"},{"type":"object","required":["eventType","allocationId","quantity","quantityLimit"],"properties":{"eventType":{"type":"string","const":"allocation.replenished"},"allocationId":{"type":"string","format":"uuid"},"skuId":{"type":"string"},"publisherCompanyId":{"type":"string"},"quantity":{"type":"integer","description":"Keys added to the allocation."},"quantityLimit":{"type":"integer","description":"The new ceiling."},"remaining":{"type":"integer"},"threshold":{"type":"integer"},"trigger":{"type":"string","const":"threshold"},"replenishedAt":{"type":"string","format":"date-time"}},"additionalProperties":true}]},"WebhookAllocationDepleted":{"description":"An allocation reached zero remaining capacity. Same fields as `allocation.updated`.","allOf":[{"$ref":"#/components/schemas/WebhookEnvelope"},{"type":"object","required":["eventType","allocationId","skuId"],"properties":{"eventType":{"type":"string","const":"allocation.depleted"},"allocationId":{"type":"string"},"publisherCompanyId":{"type":"string"},"skuId":{"type":"string"},"quantityLimit":{"type":"integer"},"quantityPulled":{"type":"integer"},"remaining":{"type":"integer"},"reason":{"type":"string","description":"Why the allocation changed (e.g. `pulled`, `resized`, `revoked`)."}},"additionalProperties":true}]},"WebhookAllocationLowStock":{"description":"Remaining is above zero and at or below 10% of `quantityLimit` (rounded down; `threshold` states the number). Sent with every allocation update while the allocation stays there, so expect repeats; for one event per crossing of your own threshold subscribe to `allocation.running_low`. Same fields as `allocation.updated`.","allOf":[{"$ref":"#/components/schemas/WebhookEnvelope"},{"type":"object","required":["eventType","allocationId","skuId"],"properties":{"eventType":{"type":"string","const":"allocation.low_stock"},"allocationId":{"type":"string"},"publisherCompanyId":{"type":"string"},"skuId":{"type":"string"},"quantityLimit":{"type":"integer"},"quantityPulled":{"type":"integer"},"remaining":{"type":"integer"},"threshold":{"type":"integer","minimum":0,"description":"The low-stock line this event used: 10% of `quantityLimit`, rounded down."},"reason":{"type":"string"}},"additionalProperties":true}]},"WebhookProductAnnounced":{"description":"A release crossed into the announced launch phase.","allOf":[{"$ref":"#/components/schemas/WebhookEnvelope"},{"type":"object","required":["eventType","productId","releaseId","publisherCompanyId","launchPhase","emittedAt"],"properties":{"eventType":{"type":"string","const":"product.announced"},"productId":{"type":"string"},"releaseId":{"type":"string"},"publisherCompanyId":{"type":"string"},"launchPhase":{"type":"string"},"emittedAt":{"type":"string","format":"date-time"}}}]},"WebhookProductDelisted":{"description":"A product left your catalog (archived or fully unshared). Delist it immediately; same fields as `product.updated`.","allOf":[{"$ref":"#/components/schemas/WebhookEnvelope"},{"type":"object","required":["eventType","productId","publisherCompanyId","updatedAt"],"properties":{"eventType":{"type":"string","const":"product.delisted"},"productId":{"type":"string"},"publisherCompanyId":{"type":"string"},"productName":{"type":["string","null"]},"productSlug":{"type":["string","null"]},"productStatus":{"type":"string","description":"Derived legacy rollup (`active` / `discontinued` / `archived`)."},"launchPhase":{"type":["string","null"]},"tradingState":{"type":["string","null"]},"isArchived":{"type":"boolean"},"updatedAt":{"type":"string","format":"date-time"}}}]},"WebhookReleaseAvailable":{"description":"A release crossed into the available launch phase.","allOf":[{"$ref":"#/components/schemas/WebhookEnvelope"},{"type":"object","required":["eventType","productId","releaseId","publisherCompanyId","launchPhase","emittedAt"],"properties":{"eventType":{"type":"string","const":"release.available"},"productId":{"type":"string"},"releaseId":{"type":"string"},"publisherCompanyId":{"type":"string"},"launchPhase":{"type":"string"},"emittedAt":{"type":"string","format":"date-time"}}}]},"WebhookSkuPricingUpdated":{"description":"The territory list price of a shared SKU changed. Refresh `GET /products/{productId}/pricing` and re-preview before the next charge; `effectiveAt` says when the new price applies. The same change is recorded on `GET /catalog/changes` with `changedFields: [\"pricing\"]`.","allOf":[{"$ref":"#/components/schemas/WebhookEnvelope"},{"type":"object","required":["eventType","skuId","productId","publisherCompanyId","countryCode","priceCents","priceMinor","currencyCode","currencyExponent","pricingMode","updatedAt","effectiveAt","previousPricing","newPricing"],"properties":{"eventType":{"type":"string","const":"sku.pricing_updated"},"skuId":{"type":"string","description":"SKU whose territory price changed."},"productId":{"type":"string","description":"Product the SKU belongs to; use with `GET /products/{productId}/pricing`."},"publisherCompanyId":{"type":"string"},"countryCode":{"type":"string","pattern":"^[A-Z]{2}$","description":"ISO 3166-1 alpha-2 territory the price applies to (upper-case)."},"priceCents":{"type":"integer","description":"Deprecated name of `priceMinor` (same value). Kept on the wire; see Naming conventions in the Versioning and compatibility guide. New list price in minor units of `currencyCode` (same value as `newPricing.priceCents`).","deprecated":true},"priceMinor":{"type":"integer","description":"New list price in minor units of `currencyCode` (same value as `newPricing.priceCents`). Same amount as `priceCents`, under the `...Minor` name every Seller API amount uses: integer minor units of the currency beside it (see `currencyExponent`)."},"currencyCode":{"type":"string","pattern":"^[A-Z]{3}$","description":"ISO 4217 currency of `priceCents`."},"currencyExponent":{"type":"integer","minimum":0,"maximum":3,"description":"Number of minor-unit digits for `currencyCode`: 2 for USD, 0 for JPY, 3 for KWD. amount = cents / 10^currencyExponent. Additive."},"pricingMode":{"type":["string","null"],"enum":["inherit","override_tier","override_manual","override_mixed",null],"description":"How the content owner maintains this SKU's price. Informational; `null` when the SKU has no explicit mode."},"updatedAt":{"type":"string","format":"date-time","description":"When the price was written."},"effectiveAt":{"type":"string","format":"date-time","description":"When the new price takes effect. Equals `updatedAt` for an immediate change; a future instant for a scheduled one — apply the price at that boundary, not on receipt."},"previousPricing":{"type":["object","null"],"required":["priceCents","priceMinor","currencyCode","currencyExponent"],"properties":{"priceCents":{"type":"integer","description":"Deprecated name of `priceMinor` (same value). Kept on the wire; see Naming conventions in the Versioning and compatibility guide. Minor units of this object's `currencyCode`.","deprecated":true},"priceMinor":{"type":"integer","description":"Minor units of this object's `currencyCode`. Same amount as `priceCents`, under the `...Minor` name every Seller API amount uses: integer minor units of the currency beside it (see `currencyExponent`)."},"currencyCode":{"type":"string"},"currencyExponent":{"type":"integer","minimum":0,"maximum":3,"description":"Number of minor-unit digits for this object's own `currencyCode`, which can differ from the new price's: 2 for USD, 0 for JPY, 3 for KWD. amount = cents / 10^currencyExponent. Additive."}},"description":"Price before this change; `null` when the territory had no price."},"newPricing":{"type":"object","required":["priceCents","priceMinor","currencyCode","currencyExponent"],"properties":{"priceCents":{"type":"integer","description":"Deprecated name of `priceMinor` (same value). Kept on the wire; see Naming conventions in the Versioning and compatibility guide. Minor units of this object's `currencyCode`.","deprecated":true},"priceMinor":{"type":"integer","description":"Minor units of this object's `currencyCode`. Same amount as `priceCents`, under the `...Minor` name every Seller API amount uses: integer minor units of the currency beside it (see `currencyExponent`)."},"currencyCode":{"type":"string"},"currencyExponent":{"type":"integer","minimum":0,"maximum":3,"description":"Number of minor-unit digits for this object's own `currencyCode`, which can differ from the new price's: 2 for USD, 0 for JPY, 3 for KWD. amount = cents / 10^currencyExponent. Additive."}},"description":"Price after this change (same values as `priceCents`, `currencyCode` and `currencyExponent`)."}}}]},"WebhookContractActivated":{"description":"An agreement term became active on a connection.","allOf":[{"$ref":"#/components/schemas/WebhookEnvelope"},{"type":"object","required":["eventType","connectionId","publisherCompanyId","contractType","termId","version"],"properties":{"eventType":{"type":"string","const":"contract.activated"},"connectionId":{"type":"string"},"publisherCompanyId":{"type":"string"},"contractType":{"type":"string","enum":["mca","wholesale","revenue_share","api","pre_order"]},"termId":{"type":"string"},"version":{"type":"integer"}}}]},"WebhookContractSuperseded":{"description":"An agreement term was replaced by a newer version.","allOf":[{"$ref":"#/components/schemas/WebhookEnvelope"},{"type":"object","required":["eventType","connectionId","publisherCompanyId","contractType","termId","version"],"properties":{"eventType":{"type":"string","const":"contract.superseded"},"connectionId":{"type":"string"},"publisherCompanyId":{"type":"string"},"contractType":{"type":"string","enum":["mca","wholesale","revenue_share","api","pre_order"]},"termId":{"type":"string"},"version":{"type":"integer"}}}]},"WebhookContractAmendmentAccepted":{"description":"An amendment to an agreement term was accepted.","allOf":[{"$ref":"#/components/schemas/WebhookEnvelope"},{"type":"object","required":["eventType","connectionId","publisherCompanyId","contractType","termId","version"],"properties":{"eventType":{"type":"string","const":"contract.amendment_accepted"},"connectionId":{"type":"string"},"publisherCompanyId":{"type":"string"},"contractType":{"type":"string","enum":["mca","wholesale","revenue_share","api","pre_order"]},"termId":{"type":"string"},"version":{"type":"integer"}}}]},"WebhookInvoiceCreated":{"description":"A pro-forma invoice was raised for an allocation.","allOf":[{"$ref":"#/components/schemas/WebhookEnvelope"},{"type":"object","required":["eventType","invoiceId","publisherCompanyId","sellerAllocationId","totalCents","totalMinor","currencyCode","currencyExponent","invoiceType","businessModel","createdAt"],"properties":{"eventType":{"type":"string","const":"invoice.created"},"invoiceId":{"type":"string"},"publisherCompanyId":{"type":"string"},"sellerAllocationId":{"type":"string"},"totalCents":{"type":"integer","description":"Deprecated name of `totalMinor` (same value). Kept on the wire; see Naming conventions in the Versioning and compatibility guide. Invoice total in minor units of `currencyCode`.","deprecated":true},"totalMinor":{"type":"integer","description":"Invoice total in minor units of `currencyCode`. Same amount as `totalCents`, under the `...Minor` name every Seller API amount uses: integer minor units of the currency beside it (see `currencyExponent`)."},"currencyCode":{"type":"string"},"currencyExponent":{"type":"integer","minimum":0,"maximum":3,"description":"Number of minor-unit digits for `currencyCode`: 2 for USD, 0 for JPY, 3 for KWD. amount = minor units / 10^currencyExponent. Additive."},"invoiceType":{"type":"string","const":"proforma","description":"Always `proforma`: `invoice.created` is sent for a pro-forma invoice only."},"businessModel":{"type":"string"},"createdAt":{"type":"string","format":"date-time","description":"When the invoice was raised (an event field, not an envelope field)."}}}]},"WebhookReportReady":{"description":"A monthly sales report finished aggregating and can be read.","allOf":[{"$ref":"#/components/schemas/WebhookEnvelope"},{"type":"object","required":["eventType","reportId","reportMonth","modelType","currencyCode","transactionCount","readyAt"],"properties":{"eventType":{"type":"string","const":"report.ready"},"reportId":{"type":"string"},"reportMonth":{"type":"string","description":"Report month as `YYYY-MM`."},"modelType":{"type":"string","const":"api"},"currencyCode":{"type":"string"},"transactionCount":{"type":"integer","description":"Sale rows aggregated into the report."},"readyAt":{"type":"string","format":"date-time"}}}]},"WebhookPayoutFileReady":{"description":"A payout settled; its reconciliation file is final.","allOf":[{"$ref":"#/components/schemas/WebhookEnvelope"},{"type":"object","required":["eventType","invoiceId","invoiceNumber","settlementPackageId","publisherCompanyId","currencyCode","currencyExponent","totalCents","totalMinor","saleCount","settledAt","reconciliationPath","readyAt"],"properties":{"eventType":{"type":"string","const":"payout.file_ready"},"invoiceId":{"type":"string"},"invoiceNumber":{"type":["string","null"]},"settlementPackageId":{"type":"string"},"publisherCompanyId":{"type":"string"},"currencyCode":{"type":"string","description":"Payment currency (ISO 4217)."},"currencyExponent":{"type":"integer","minimum":0,"maximum":3,"description":"Number of minor-unit digits for `currencyCode`: 2 for USD, 0 for JPY, 3 for KWD. amount = minor units / 10^currencyExponent. Additive."},"totalCents":{"type":"integer","description":"Deprecated name of `totalMinor` (same value). Kept on the wire; see Naming conventions in the Versioning and compatibility guide. Payout total in minor units of `currencyCode`.","deprecated":true},"totalMinor":{"type":"integer","description":"Payout total in minor units of `currencyCode`. Same amount as `totalCents`, under the `...Minor` name every Seller API amount uses: integer minor units of the currency beside it (see `currencyExponent`)."},"saleCount":{"type":"integer"},"settledAt":{"type":["string","null"],"format":"date-time"},"reconciliationPath":{"type":"string","description":"Path of `GET /finance/invoices/{invoiceId}/reconciliation` for this payout."},"readyAt":{"type":"string","format":"date-time","description":"When the event was raised (an event field, not an envelope field)."}}}]},"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"]},"lastError":{"type":["string","null"],"description":"Classified reason of the last failed attempt: timeout, dns_private_address, dns_failure, connect_refused, connection_error, redirect_limit, url_not_allowed, secret_decrypt_failed, endpoint_deleted, contract_not_active, no_previous_secret (a `previous_secret_only` test challenge on an endpoint with no previous secret in its rotation overlap), or http_<status> when the endpoint answered non-2xx. Null after a success. responseStatus is only ever the endpoint's own status; a transport failure leaves it 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"}}},"SellerEventLogItem":{"type":"object","description":"One event from your event log (`GET /events`, contract date `2026-12-01` and later).","required":["id","eventLogId","eventType","eventVersion","occurredAt","createdAt","resourceType","resourceId","payload"],"properties":{"id":{"type":"string","description":"The event's id; the same value as `eventLogId`."},"eventLogId":{"type":"string","description":"The id every webhook delivery of this event carries as `eventLogId` and in the `X-Avrix-Event-Log-Id` header."},"eventType":{"type":"string","description":"Event name, as in `GET /webhooks/event-types`."},"eventVersion":{"type":"string","const":"1","description":"Payload schema version, as webhook deliveries carry it."},"occurredAt":{"type":"string","format":"date-time","description":"When the event happened."},"createdAt":{"type":"string","format":"date-time","description":"When the event was recorded; the feed's order."},"resourceType":{"type":["string","null"],"enum":["order","chargeback","catalog_export","allocation","allocation_request","dispute_freeze","product","sku","contract_term","connection","connection_request","access_proposal","return_request","promotion","invoice","report","api_key","webhook_endpoint","platform_notice",null],"description":"What the event is about; null for events about no single resource."},"resourceId":{"type":["string","null"],"description":"The id of that resource; for orders, your `orderReference`."},"payload":{"type":"object","additionalProperties":true,"description":"The event's own fields, exactly as a webhook delivery of the event carries them next to the envelope. Never includes plaintext key codes."}}},"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":{"description":"A release date moved. Update listing dates and notify pre-order buyers.","allOf":[{"$ref":"#/components/schemas/WebhookEnvelope"},{"type":"object","required":["eventType","productId","releaseId","skuIds","publisherCompanyId","oldDate","newDate","emittedAt"],"properties":{"eventType":{"type":"string","const":"release.date_changed"},"productId":{"type":"string"},"releaseId":{"type":"string"},"skuIds":{"type":"array","items":{"type":"string"},"description":"SKUs under the release."},"publisherCompanyId":{"type":"string"},"oldDate":{"type":["string","null"],"format":"date-time"},"newDate":{"type":["string","null"],"format":"date-time"},"emittedAt":{"type":"string","format":"date-time"}}}]},"WebhookSkuSellabilityChanged":{"description":"A SKU became sellable or stopped being sellable, or (`firstSeen: true`) a SKU you can sell appeared for the first time. Confirm with `GET /allocations` before changing a buy button.","allOf":[{"$ref":"#/components/schemas/WebhookEnvelope"},{"type":"object","required":["eventType","skuId","skuCode","productId","sellable","reasons","emittedAt"],"properties":{"eventType":{"type":"string","const":"sku.sellability_changed"},"skuId":{"type":"string"},"skuCode":{"type":"string"},"productId":{"type":"string"},"sellable":{"type":"boolean"},"reasons":{"type":"array","items":{"type":"string"},"description":"Readiness blocker codes when `sellable` is false."},"firstSeen":{"type":"boolean","description":"True when the SKU was not known for your company before and is sellable now; false on a flip between sellable and not sellable. The first observation of a company's catalog sends no events."},"emittedAt":{"type":"string","format":"date-time"}}}]},"WebhookSystemEndpointDisabled":{"description":"An endpoint was disabled after consecutive delivery failures. Re-enable it once your receiver is healthy.","allOf":[{"$ref":"#/components/schemas/WebhookEnvelope"},{"type":"object","required":["eventType","endpointId","endpointHost","reason","consecutiveFailures","disabledAt"],"properties":{"eventType":{"type":"string","const":"system.webhook_endpoint_disabled"},"endpointId":{"type":"string"},"endpointHost":{"type":"string","description":"Host of the disabled endpoint URL."},"reason":{"type":"string"},"consecutiveFailures":{"type":"integer"},"disabledAt":{"type":"string","format":"date-time"}}}]},"WebhookSystemEndpointFailing":{"description":"Deliveries to one of your endpoints have kept failing for a while. The endpoint is still active and retries continue; fix your receiver before the circuit breaker disables it.","allOf":[{"$ref":"#/components/schemas/WebhookEnvelope"},{"type":"object","required":["eventType","endpointId","endpointHost","failingSince","firstFailedAt","consecutiveFailedAttempts","occurredAt"],"properties":{"eventType":{"type":"string","const":"system.webhook_endpoint_failing"},"endpointId":{"type":"string"},"endpointHost":{"type":"string","description":"Host of the failing endpoint URL."},"failingSince":{"type":"string","format":"date-time","description":"When the endpoint turned failing."},"firstFailedAt":{"type":"string","format":"date-time","description":"The first failed attempt of the current run."},"consecutiveFailedAttempts":{"type":"integer"},"lastError":{"type":["string","null"],"description":"Classified reason of the last failed attempt (`timeout`, `http_503`, ...)."},"lastResponseStatus":{"type":["integer","null"]},"occurredAt":{"type":"string","format":"date-time"}}}]},"WebhookSystemEndpointRecovered":{"description":"A failing endpoint answered 2xx again.","allOf":[{"$ref":"#/components/schemas/WebhookEnvelope"},{"type":"object","required":["eventType","endpointId","endpointHost","recoveredAt","occurredAt"],"properties":{"eventType":{"type":"string","const":"system.webhook_endpoint_recovered"},"endpointId":{"type":"string"},"endpointHost":{"type":"string","description":"Host of the endpoint URL."},"failingSince":{"type":["string","null"],"format":"date-time","description":"When the endpoint had turned failing."},"recoveredAt":{"type":"string","format":"date-time"},"occurredAt":{"type":"string","format":"date-time"}}}]},"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":"The order's id (`ord_` plus eight characters). One value for the life of the order: the same in the create response, `GET /orders`, `GET /orders/{orderId}`, the bulk line and the `order.fulfilled` webhook. Store this one. Every endpoint that addresses an order (`GET /orders/{orderId}`, `GET /orders?orderReadableId=`, `POST /orders/{orderId}/fulfill`, key replacement) accepts it. On contract dates before `2026-12-01`, with the reconstruction read model (see `GET /whoami` `capabilities.orderReadModel`), a row of an order placed before this change shipped (changelog, `2026-12-01`) carries the id of its first key pull instead."},"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":"Deprecated name of `totalMinor` (same value). Kept on the wire; see Naming conventions in the Versioning and compatibility guide. Sum of recorded sale transactions for this tuple, when present.","deprecated":true},"totalMinor":{"type":["integer","null"],"description":"Sum of recorded sale transactions for this tuple, when present. Same amount as `totalCents`, under the `...Minor` name every Seller API amount uses: integer minor units of the currency beside it (see `currencyExponent`)."},"currencyCode":{"type":["string","null"]},"currencyExponent":{"type":["integer","null"],"minimum":0,"maximum":3,"description":"Number of minor-unit digits for `currencyCode`: 2 for USD, 0 for JPY, 3 for KWD. amount = minor units / 10^currencyExponent; `null` when `currencyCode` is `null`. Additive."},"qtyRequested":{"type":"integer"},"qtyPending":{"type":"integer"},"qtyAssigned":{"type":"integer"},"qtyRevealed":{"type":"integer"},"parentOrderReference":{"type":["string","null"],"description":"The bulk cart this order is a line of (`integrationOrderContext.parentOrderReference` sent with `POST /orders/bulk`); null for an order placed on its own."},"lineIndex":{"type":["integer","null"],"description":"The line's position in that cart (`integrationOrderContext.lineIndex`); null when not a cart line or not sent."}}},"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":{"description":"A keyless redemption URL entered its expiry notice window.","allOf":[{"$ref":"#/components/schemas/WebhookEnvelope"},{"type":"object","required":["eventType","fulfillmentId","orderReference","skuId","platformCode","provider","expiresAt"],"properties":{"eventType":{"type":"string","const":"redemption.expiring"},"fulfillmentId":{"type":"string"},"orderReference":{"type":["string","null"]},"skuId":{"type":"string"},"platformCode":{"type":"string"},"provider":{"type":"string"},"expiresAt":{"type":"string","format":"date-time"}}}]},"SellerFinanceStatementBucket":{"type":"object","description":"Per-currency totals for the statement period. Never sum across currencies.","properties":{"currencyCode":{"type":"string","example":"EUR"},"currencyExponent":{"type":"integer","minimum":0,"maximum":3,"description":"Number of minor-unit digits for `currencyCode`: 2 for USD, 0 for JPY, 3 for KWD. amount = minor units / 10^currencyExponent. Additive."},"transactionCount":{"type":"integer"},"grossSalesCents":{"type":"integer","deprecated":true,"description":"Deprecated name of `grossSalesMinor` (same value). Kept on the wire; see Naming conventions in the Versioning and compatibility guide."},"grossSalesMinor":{"type":"integer","description":"Same amount as `grossSalesCents`, under the `...Minor` name every Seller API amount uses: integer minor units of the currency beside it (see `currencyExponent`)."},"refundedCents":{"type":"integer","description":"Deprecated name of `refundedMinor` (same value). Kept on the wire; see Naming conventions in the Versioning and compatibility guide. Positive magnitude of sale_reversal ledger entries in the period.","deprecated":true},"refundedMinor":{"type":"integer","description":"Positive magnitude of sale_reversal ledger entries in the period. Same amount as `refundedCents`, under the `...Minor` name every Seller API amount uses: integer minor units of the currency beside it (see `currencyExponent`)."},"reinstatedCents":{"type":"integer","description":"Deprecated name of `reinstatedMinor` (same value). Kept on the wire; see Naming conventions in the Versioning and compatibility guide. Positive amount restored by sale_reinstatement ledger entries after won chargebacks.","deprecated":true},"reinstatedMinor":{"type":"integer","description":"Positive amount restored by sale_reinstatement ledger entries after won chargebacks. Same amount as `reinstatedCents`, under the `...Minor` name every Seller API amount uses: integer minor units of the currency beside it (see `currencyExponent`)."},"netSalesCents":{"type":"integer","deprecated":true,"description":"Deprecated name of `netSalesMinor` (same value). Kept on the wire; see Naming conventions in the Versioning and compatibility guide."},"netSalesMinor":{"type":"integer","description":"Same amount as `netSalesCents`, under the `...Minor` name every Seller API amount uses: integer minor units of the currency beside it (see `currencyExponent`)."},"publisherShareCents":{"type":"integer","deprecated":true,"description":"Deprecated name of `publisherShareMinor` (same value). Kept on the wire; see Naming conventions in the Versioning and compatibility guide."},"publisherShareMinor":{"type":"integer","description":"Same amount as `publisherShareCents`, under the `...Minor` name every Seller API amount uses: integer minor units of the currency beside it (see `currencyExponent`)."},"sellerShareCents":{"type":"integer","deprecated":true,"description":"Deprecated name of `sellerShareMinor` (same value). Kept on the wire; see Naming conventions in the Versioning and compatibility guide."},"sellerShareMinor":{"type":"integer","description":"Same amount as `sellerShareCents`, under the `...Minor` name every Seller API amount uses: integer minor units of the currency beside it (see `currencyExponent`)."},"platformFeeCents":{"type":"integer","deprecated":true,"description":"Deprecated name of `platformFeeMinor` (same value). Kept on the wire; see Naming conventions in the Versioning and compatibility guide."},"platformFeeMinor":{"type":"integer","description":"Same amount as `platformFeeCents`, under the `...Minor` name every Seller API amount uses: integer minor units of the currency beside it (see `currencyExponent`)."}},"required":["currencyCode","currencyExponent","transactionCount","grossSalesCents","grossSalesMinor","refundedCents","refundedMinor","reinstatedCents","reinstatedMinor","netSalesCents","netSalesMinor","publisherShareCents","publisherShareMinor","sellerShareCents","sellerShareMinor","platformFeeCents","platformFeeMinor"]},"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 customer-order backorders are enabled (default true; false only while the platform switch is off, when backorderOnUnavailable answers 403 FEATURE_DISABLED with details.reason BACKORDER_NOT_ENABLED). When true, POST /orders accepts awaiting_stock against headroom unless the Content Owner opted out (403 BACKORDER_NOT_ALLOWED). Unfulfilled backorders expire after 14 days with order.backorder_expired."}},"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":"The CONSUMER_* guard code (`CONSUMER_IP_REQUIRED`, `CONSUMER_IP_INVALID`, `CONSUMER_GEO_MISMATCH`, `CONSUMER_IP_HIGH_RISK`, `CONSUMER_GEO_UNAVAILABLE`) that flagged the sale: a would-be denial while consumer geo is in monitor mode, or on `POST /orders` / `POST /orders/commit` an enforced mismatch or high-risk verdict the agreement geo policy let through."},"enforcementDate":{"type":"string","description":"Optional announced enforcement date (ISO date) when set."}}},"RiskWarning":{"type":"object","description":"Additive, on a 200 only: the checkout confirmation scored at or above the Content Owner’s risk threshold (CONSUMER_RISK_HIGH) or could not be scored (CONSUMER_RISK_UNAVAILABLE), and the Content Owner’s riskAction is `warn`, so the order proceeded. Under `refuse` the same outcomes are 422 / 503 errors instead. The score itself is never returned.","required":["code"],"properties":{"code":{"type":"string","enum":["CONSUMER_RISK_HIGH","CONSUMER_RISK_UNAVAILABLE"]}}},"WebhookOrderReady":{"description":"A deferred pre-order or backorder has inventory and can be fulfilled.","allOf":[{"$ref":"#/components/schemas/WebhookEnvelope"},{"type":"object","required":["eventType","orderReference","orderId"],"properties":{"eventType":{"type":"string","const":"order.ready"},"orderReference":{"type":["string","null"]},"orderId":{"type":"string","description":"Readable order id (`ord_…`)."}}}]},"WebhookOrderBackorderExpired":{"description":"A customer-order backorder was still awaiting stock at its timeout (default 14 days). Avrix cancelled it and released the allocation headroom; no keys will be delivered. Refund the buyer.","allOf":[{"$ref":"#/components/schemas/WebhookEnvelope"},{"type":"object","required":["eventType","orderReference","orderId","status","expiredAt"],"properties":{"eventType":{"type":"string","const":"order.backorder_expired"},"orderReference":{"type":"string"},"orderId":{"type":"string","description":"Readable order id (`ord_…`)."},"allocationId":{"type":["string","null"]},"skuId":{"type":["string","null"]},"quantity":{"type":"integer","minimum":0,"description":"Units that were still pending when the backorder expired."},"status":{"type":"string","const":"cancelled"},"backorderCreatedAt":{"type":"string","format":"date-time"},"expiredAt":{"type":"string","format":"date-time"},"recommendedAction":{"type":"string","const":"refund_customer"}},"additionalProperties":true}]},"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":{"$ref":"#/components/schemas/SellerDeliveredKey"},"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","format":"uuid","description":"The share id (`event`) or the deal response id (`custom`)."},"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","ended"]},"vendorCompanyId":{"type":["string","null"],"description":"The vendor running the promotion. Additive."},"name":{"type":["string","null"],"description":"The platform event's or the deal's name. Additive."},"productId":{"type":["string","null"],"format":"uuid","description":"The catalog product the SKU belongs to. Additive."}}},"WebhookPromotionEventFields":{"type":"object","description":"The fields every `promotion.*` event carries. `status` is the offer's state after the change; the envelope's `occurredAt` says when it happened.","required":["sourceType","sourceId","publisherCompanyId","name","status","startDate","endDate","respondBy"],"properties":{"sourceType":{"type":"string","enum":["event","custom"],"description":"`event`: a platform event share, read it at `GET /promotions/shares/{sourceId}`. `custom`: a custom deal, read it at `GET /promotions/deals/{sourceId}`."},"sourceId":{"type":"string","format":"uuid","description":"The share id or the deal response id."},"publisherCompanyId":{"type":"string","description":"The vendor's company id."},"name":{"type":"string"},"status":{"type":"string","description":"Share statuses: `pending`, `accepted`, `declined`, `expired`, `vendor_withdrawn`. Deal statuses: `pending`, `approved`, `rejected`, `expired`."},"startDate":{"type":["string","null"],"format":"date-time"},"endDate":{"type":["string","null"],"format":"date-time"},"respondBy":{"type":["string","null"],"format":"date-time"}}},"CatalogSkuPromotion":{"type":"object","description":"An accepted promotion on a SKU whose window is live or upcoming. `sourceId` is the share id (`event`) or the deal response id (`custom`).","required":["sourceType","sourceId","discountPercent","priceEffect","startDate","endDate","window"],"properties":{"sourceType":{"type":"string","enum":["event","custom"]},"sourceId":{"type":"string","format":"uuid"},"name":{"type":["string","null"],"description":"The platform event's or the deal's name."},"discountPercent":{"type":"number"},"priceEffect":{"type":"string","enum":["list_price","settlement_price","both"],"description":"Which price the discount lowers: `list_price` the price you advertise to buyers, `settlement_price` what an order under the API business model is billed, `both` both."},"startDate":{"type":"string","format":"date-time","description":"Start of the window (UTC, inclusive)."},"endDate":{"type":"string","format":"date-time","description":"End of the window (UTC, inclusive)."},"window":{"type":"string","enum":["live","upcoming"]}}},"CatalogPricePromotionFields":{"type":"object","description":"What a live promotion does to a SKU's price in one country. Additive on `skus[].prices[]` of `GET /products/{productId}` and `GET /products/{productId}/pricing`.","properties":{"listPromo":{"description":"The live promotion the vendor asks you to show to buyers on this SKU (`priceEffect` `list_price` or `both`), or null. Additive.","oneOf":[{"$ref":"#/components/schemas/ListPromoRef"},{"type":"null"}]},"advertisedPriceCents":{"type":"integer","description":"Deprecated name of `advertisedPriceMinor` (same value). Kept on the wire; see Naming conventions in the Versioning and compatibility guide. `basePriceCents` with `listPromo` applied: the price to show to buyers now. Equal to `basePriceCents` when there is no live list-price promotion. Additive.","deprecated":true},"advertisedPriceMinor":{"type":"integer","description":"`basePriceCents` with `listPromo` applied: the price to show to buyers now. Equal to `basePriceCents` when there is no live list-price promotion. Additive. Same amount as `advertisedPriceCents`, under the `...Minor` name every Seller API amount uses: integer minor units of the currency beside it (see `currencyExponent`)."},"promo":{"description":"The live promotion that lowers what an order under the API business model is billed (`priceEffect` `settlement_price` or `both`), or null. The billed price depends on the allocation and the buyer's country: `POST /orders/preview` quotes it. Additive.","oneOf":[{"$ref":"#/components/schemas/SettlementPromoRef"},{"type":"null"}]},"promoResolution":{"type":"string","enum":["applied","none","unavailable"],"description":"`applied` when `listPromo` or `promo` is set, `none` when no promotion is live, `unavailable` when promotions could not be read (then `listPromo` and `promo` say nothing). Additive."}}},"SellerPromotionsSummary":{"type":"object","properties":{"shares":{"type":"object","description":"Counts of the shares offered to you. Shares the vendor has not sent yet are not counted.","properties":{"pending":{"type":"integer"},"accepted":{"type":"integer"},"declined":{"type":"integer"},"expired":{"type":"integer","description":"Not answered in time. Additive."},"vendor_withdrawn":{"type":"integer","description":"Withdrawn by the vendor. Additive."},"total":{"type":"integer"}}},"deals":{"type":"object","properties":{"pending":{"type":"integer"},"approved":{"type":"integer"},"rejected":{"type":"integer"},"expired":{"type":"integer","description":"Not answered in time. Additive."},"total":{"type":"integer"}}}}},"SellerPromotionShareDiscount":{"type":"object","properties":{"productId":{"type":"string","format":"uuid"},"sku":{"type":"string","description":"The SKU code."},"discountPct":{"type":"number"},"skuId":{"type":"string","format":"uuid","description":"The SKU id the calendar and the catalogue use. Additive."},"priceEffect":{"type":"string","enum":["list_price","settlement_price","both"],"description":"Which price the discount lowers: `list_price` the price you advertise to buyers, `settlement_price` what an order under the API business model is billed, `both` both. Additive."}}},"SellerPromotionDealDetail":{"allOf":[{"$ref":"#/components/schemas/SellerPromotionDeal"},{"type":"object","properties":{"description":{"type":["string","null"]},"promotion_code":{"type":["string","null"]},"message":{"type":["string","null"],"description":"The vendor's message to you."},"products":{"type":"array","items":{"$ref":"#/components/schemas/SellerPromotionDealProduct"}}}}]},"SellerPromotionDealProduct":{"type":"object","properties":{"sku_id":{"type":"string","format":"uuid"},"sku_code":{"type":"string"},"external_sku_code":{"type":["string","null"]},"product_id":{"type":["string","null"],"format":"uuid","description":"The catalog product the SKU belongs to. Additive."},"product_name":{"type":"string"},"edition_name":{"type":["string","null"]},"platform_code":{"type":"string"},"platform_name":{"type":"string"},"key_type_name":{"type":"string"},"region_name":{"type":"string"},"discount_percent":{"type":"integer"},"base_price_cents":{"type":["integer","null"],"description":"Informational display price in `currency_code` — the SKU's own-region price as shown to the vendor when the promotion was authored, not the list price of any sale country. Never derive a consumer price from it: `POST /orders/preview` returns `advertisedUnitPriceCents` for the country you sell in."},"currency_code":{"type":["string","null"],"description":"ISO 4217 currency of `base_price_cents`."},"price_effect":{"type":"string","enum":["list_price","settlement_price","both"],"description":"Which price the discount lowers: `list_price` the price you advertise to buyers, `settlement_price` what an order under the API business model is billed, `both` both. Additive."}}},"SellerPromotionDeal":{"type":"object","description":"A custom deal a vendor offered your company. `id` is your answer slot on the deal (the response id): the `responseId` path parameter and the `sourceId` of `sourceType: custom` in the calendar, catalogue promotion fields and `promotion.*` events.","properties":{"id":{"type":"string","format":"uuid","description":"Response ID"},"promotion_id":{"type":"string","format":"uuid"},"promotion_name":{"type":"string"},"vendor_company_id":{"type":"string","description":"The vendor's company id."},"vendor_company_name":{"type":"string"},"start_date":{"type":"string","format":"date-time","description":"Start of the promotion window (UTC, inclusive)."},"end_date":{"type":"string","format":"date-time","description":"End of the promotion window (UTC, inclusive)."},"response_deadline":{"type":["string","null"],"format":"date-time"},"promotion_status":{"type":"string","description":"The deal's own state on the vendor's side (`submitted`, `withdrawn`)."},"response_status":{"type":"string","enum":["pending","approved","rejected","expired"],"description":"`pending` waits for your answer; `approved` and `rejected` are your answer; `expired` was not answered by `respond_by`."},"response_note":{"type":["string","null"],"description":"The note you sent with your answer."},"responded_at":{"type":["string","null"],"format":"date-time"},"product_count":{"type":"integer"},"created_at":{"type":"string","format":"date-time","description":"When the vendor sent the offer. `sort=offeredAt` reads it."},"updated_at":{"type":["string","null"],"format":"date-time","description":"When this offer last changed (an answer, an expiry, a withdrawal or a change of products by the vendor). The `updatedSince` filter and `sort=updatedAt` read it. Additive."},"respond_by":{"type":["string","null"],"format":"date-time","description":"The last instant this offer can be answered: the answer deadline or the start of the promotion, whichever is earlier. After it an answer is refused and the offer becomes `expired`. Additive."}}},"SellerPromotionShareDetail":{"allOf":[{"$ref":"#/components/schemas/SellerPromotionShare"},{"type":"object","properties":{"products":{"type":"array","items":{"$ref":"#/components/schemas/SellerPromotionShareProduct"}}}}]},"SellerPromotionShareProduct":{"type":"object","properties":{"sku_id":{"type":"string","format":"uuid"},"sku_code":{"type":"string"},"external_sku_code":{"type":["string","null"]},"product_id":{"type":["string","null"],"format":"uuid","description":"The catalog product the SKU belongs to."},"product_name":{"type":"string"},"edition_name":{"type":["string","null"]},"key_type_name":{"type":"string"},"region_name":{"type":"string"},"discount_percent":{"type":"integer"},"base_price_cents":{"type":["integer","null"],"description":"Informational display price in `currency_code` — the SKU's own-region price as shown to the vendor when the promotion was authored, not the list price of any sale country. Never derive a consumer price from it: `POST /orders/preview` returns `advertisedUnitPriceCents` for the country you sell in."},"currency_code":{"type":["string","null"],"description":"ISO 4217 currency of `base_price_cents`."},"price_effect":{"type":"string","enum":["list_price","settlement_price","both"],"description":"Which price the discount lowers: `list_price` the price you advertise to buyers, `settlement_price` what an order under the API business model is billed, `both` both. Additive."}}},"SellerPromotionShare":{"type":"object","description":"A platform event promotion a vendor offered your company (a share). The `share_id` is the `sourceId` of `sourceType: event` in the calendar, in catalogue promotion fields and in `promotion.*` events.","properties":{"share_id":{"type":"string","format":"uuid"},"participation_id":{"type":"string","format":"uuid"},"status":{"type":"string","enum":["pending","accepted","declined","expired","vendor_withdrawn"],"description":"`pending` waits for your answer; `accepted` and `declined` are your answer; `expired` was not answered by `respond_by`; `vendor_withdrawn` was withdrawn by the vendor. Shares the vendor has not sent yet are never listed."},"participation_status":{"type":["string","null"]},"seller_notes":{"type":["string","null"],"description":"The note you sent with your answer."},"shared_at":{"type":"string","format":"date-time","description":"When the vendor sent the offer. `sort=offeredAt` reads it."},"responded_at":{"type":["string","null"],"format":"date-time"},"product_snapshot":{"type":["array","null"],"items":{"type":"object","properties":{"sku_id":{"type":"string","format":"uuid"},"discount_percent":{"type":"number"},"base_price_cents":{"type":"integer"},"currency_code":{"type":"string"},"status":{"type":"string"},"product_name":{"type":"string"},"edition_name":{"type":["string","null"]},"sku_name":{"type":"string"}}}},"vendor_company_id":{"type":"string","description":"The vendor's company id."},"vendor_company_name":{"type":"string"},"event_id":{"type":"string","format":"uuid"},"event_name":{"type":"string"},"event_starts_at":{"type":["string","null"],"format":"date-time","description":"Start of the promotion window (UTC, inclusive)."},"event_ends_at":{"type":["string","null"],"format":"date-time","description":"End of the promotion window (UTC, inclusive)."},"event_submission_deadline":{"type":["string","null"],"format":"date-time"},"platform_id":{"type":"string"},"platform_name":{"type":"string"},"platform_code":{"type":"string"},"product_count":{"type":"integer"},"genre_names":{"type":"array","items":{"type":"string"}},"updated_at":{"type":["string","null"],"format":"date-time","description":"When this offer last changed (an answer, an expiry, a withdrawal or a change of products by the vendor). The `updatedSince` filter and `sort=updatedAt` read it. Additive."},"respond_by":{"type":["string","null"],"format":"date-time","description":"The last instant this offer can be answered: the answer deadline or the start of the promotion, whichever is earlier. After it an answer is refused and the offer becomes `expired`. Additive."}}},"RefundPolicy":{"type":"object","description":"Where and how refunds are accepted for this Content Owner and SKU: the refund window (`windowDays`, from the Content Owner or a per-SKU override, `source` says which) and what a refund does to a key. The same object on whoami, allocations and product detail.","required":["windowDays","keyRevealForfeitsRefund","quarantineOnRefund","avrixMovesMoney","source"],"properties":{"windowDays":{"type":["integer","null"],"description":"Days after the sale in which `POST /refunds` (`type: refund`) and `POST /keys/return` are accepted; `null` = no window. Past it the refund answers 422 `REFUND_WINDOW_EXPIRED`. Chargebacks are never windowed."},"keyRevealForfeitsRefund":{"type":"boolean","deprecated":true,"description":"Deprecated: read `revealedKeysRefundable`. The name suggests a revealed key cannot be refunded, which is not the rule; the value is unchanged (always `true`) for existing clients."},"quarantineOnRefund":{"type":"boolean","description":"Refunded keys are quarantined, never recycled into sellable inventory without operator review."},"avrixMovesMoney":{"type":"boolean","const":false},"source":{"type":"string","enum":["platform","publisher","sku"],"description":"Where `windowDays` comes from: `platform` (no window), the vendor's window (`publisher`) or a per-SKU override (`sku`)."},"revealedKeysRefundable":{"type":"boolean","description":"True: a key can be refunded after it was revealed (delivered), within `windowDays`. Revenue-share keys can also be refunded once redeemed; they stay with you (`held`). Other keys are quarantined."}}},"WebhookRedemptionExpired":{"description":"A keyless redemption URL passed `expiresAt` without activation.","allOf":[{"$ref":"#/components/schemas/WebhookEnvelope"},{"type":"object","required":["eventType","fulfillmentId","orderReference","skuId","platformCode","provider","expiresAt","effectiveAt"],"properties":{"eventType":{"type":"string","const":"redemption.expired"},"fulfillmentId":{"type":"string"},"orderReference":{"type":["string","null"]},"skuId":{"type":"string"},"platformCode":{"type":"string"},"provider":{"type":"string"},"expiresAt":{"type":"string","format":"date-time"},"effectiveAt":{"type":"string","format":"date-time","description":"When the redemption expired."}}}]},"WebhookCatalogExportReady":{"description":"An async catalog export artifact is ready to download.","allOf":[{"$ref":"#/components/schemas/WebhookEnvelope"},{"type":"object","required":["eventType","exportId","checksum","bytes","expiresAt","totalProducts"],"properties":{"eventType":{"type":"string","const":"catalog.export_ready"},"exportId":{"type":"string"},"checksum":{"type":"string","description":"Checksum of the gzip NDJSON artifact."},"bytes":{"type":"integer","description":"Artifact size in bytes."},"expiresAt":{"type":"string","format":"date-time","description":"When the signed download URL expires."},"totalProducts":{"type":"integer"}}}]},"WebhookProductDelistingScheduled":{"description":"A product is scheduled to leave your catalog. Same fields as `product.updated` plus the instant it takes effect.","allOf":[{"$ref":"#/components/schemas/WebhookEnvelope"},{"type":"object","required":["eventType","productId","publisherCompanyId","updatedAt"],"properties":{"eventType":{"type":"string","const":"product.delisting_scheduled"},"productId":{"type":"string"},"publisherCompanyId":{"type":"string"},"productName":{"type":["string","null"]},"productSlug":{"type":["string","null"]},"productStatus":{"type":"string"},"launchPhase":{"type":["string","null"]},"tradingState":{"type":["string","null"]},"isArchived":{"type":"boolean"},"updatedAt":{"type":"string","format":"date-time"},"effectiveAt":{"type":["string","null"],"format":"date-time","description":"When the delisting takes effect."}}}]},"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 and are reported as `listPromo` instead."},"startDate":{"type":["string","null"],"format":"date-time"},"endDate":{"type":["string","null"],"format":"date-time"}}},"ListPromoRef":{"type":"object","description":"Live list-price promotion the vendor asks the store to advertise for a quoted SKU (`priceEffect` `list_price` or `both`). `listPromo` itself never changes `unitPriceCents`; a `both` promotion (the default) also appears as `promo`, which does. Render was/now from `initialUnitPriceCents` vs `advertisedUnitPriceCents`; do not recompute from `discountPercent`. `sourceId` is the same id you read under /promotions: the shareId for `event`, the responseId for `custom`. A `both` promotion appears here and as `promo` with the same source.","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":["list_price","both"],"description":"Only list-price-affecting promos are reported here; a `settlement_price` promo lowers `unitPriceCents` (see `promo`) without asking for a consumer-facing discount."},"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","description":"`sale` (+1), `refund` / `chargeback` (−1: the reversal entry, at the instant money moved), `reinstatement` (+1: a won chargeback restoring the sale), `pull` (+1, wholesale / revenue-share custody), `reveal` (0). Summing `economics` over sale, refund, chargeback and reinstatement entries for a period equals the statement's net for that period.","enum":["sale","refund","chargeback","reinstatement","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`. Also set on refund, chargeback and reinstatement entries, naming the promotion the original sale was sold under, and `promoId` matches them too."},"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","vat_country_not_corroborated","vat_anonymizer_flag","vat_declared_rate_above_expected","vat_declared_rate_below_expected","vat_declared_rate_above_ceiling","vat_price_includes_tax_mismatch","vat_declaration_arithmetic_mismatch"]},"description":"`COUNTRY_MISMATCH` plus the settlement's `vat_*` flags persisted on the sale row — the same `warnings` the order response carried. Empty on pull and reveal entries."},"economics":{"type":"object","required":["currencyCode","currencyExponent","unitPriceCents","unitPriceMinor","initialUnitPriceCents","initialUnitPriceMinor","publisherShareCents","publisherShareMinor","sellerShareCents","sellerShareMinor","platformFeeCents","platformFeeMinor"],"properties":{"currencyCode":{"type":["string","null"]},"currencyExponent":{"type":["integer","null"]},"unitPriceCents":{"type":["integer","null"],"description":"Deprecated name of `unitPriceMinor` (same value). Kept on the wire; see Naming conventions in the Versioning and compatibility guide. Billed unit price; negative on reversals.","deprecated":true},"unitPriceMinor":{"type":["integer","null"],"description":"Billed unit price; negative on reversals. Same amount as `unitPriceCents`, under the `...Minor` name every Seller API amount uses: integer minor units of the currency beside it (see `currencyExponent`)."},"initialUnitPriceCents":{"type":["integer","null"],"description":"Deprecated name of `initialUnitPriceMinor` (same value). Kept on the wire; see Naming conventions in the Versioning and compatibility guide. List price before any settlement promo; negative on reversals.","deprecated":true},"initialUnitPriceMinor":{"type":["integer","null"],"description":"List price before any settlement promo; negative on reversals. Same amount as `initialUnitPriceCents`, under the `...Minor` name every Seller API amount uses: integer minor units of the currency beside it (see `currencyExponent`)."},"publisherShareCents":{"type":["integer","null"],"deprecated":true,"description":"Deprecated name of `publisherShareMinor` (same value). Kept on the wire; see Naming conventions in the Versioning and compatibility guide."},"publisherShareMinor":{"type":["integer","null"],"description":"Same amount as `publisherShareCents`, under the `...Minor` name every Seller API amount uses: integer minor units of the currency beside it (see `currencyExponent`)."},"sellerShareCents":{"type":["integer","null"],"deprecated":true,"description":"Deprecated name of `sellerShareMinor` (same value). Kept on the wire; see Naming conventions in the Versioning and compatibility guide."},"sellerShareMinor":{"type":["integer","null"],"description":"Same amount as `sellerShareCents`, under the `...Minor` name every Seller API amount uses: integer minor units of the currency beside it (see `currencyExponent`)."},"platformFeeCents":{"type":["integer","null"],"deprecated":true,"description":"Deprecated name of `platformFeeMinor` (same value). Kept on the wire; see Naming conventions in the Versioning and compatibility guide."},"platformFeeMinor":{"type":["integer","null"],"description":"Same amount as `platformFeeCents`, under the `...Minor` name every Seller API amount uses: integer minor units of the currency beside it (see `currencyExponent`)."}}},"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","declared_within_store_cap","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 and your registered country rate lowered the declared rate; `declared_within_store_cap` means the same missing evidence with a declared rate at or under that cap, applied as declared."},"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","enum":["draft","awaiting_commission_document","payable","disputed","superseded","expired","sent","paid","overdue","cancelled","credited"],"x-extensible-enum":true,"description":"Invoice state. Monthly settlement invoices move `draft` -> `awaiting_commission_document` -> `payable` -> `paid`; `disputed` while a dispute is open, `superseded` when a corrected invoice replaces it, `expired` when it lapsed unpaid. `sent`, `overdue`, `cancelled` and `credited` belong to the older per-allocation invoices (`overdue`: unpaid past `dueAt`; `credited`: offset by a credit note). New values may be added; treat an unknown one as not yet paid."},"currencyCode":{"type":"string"},"currencyExponent":{"type":"integer","minimum":0,"maximum":3,"description":"Number of minor-unit digits for `currencyCode`: 2 for USD, 0 for JPY, 3 for KWD. amount = minor units / 10^currencyExponent. Additive."},"totalMinor":{"type":"integer"}},"required":["invoiceId","status","currencyCode","currencyExponent","totalMinor"]},"SellerFinanceApprovedSettlement":{"type":"object","properties":{"reportId":{"type":"string","format":"uuid"},"publisherCompanyId":{"type":"string"},"contractTermId":{"type":["string","null"],"format":"uuid"},"currencyCode":{"type":"string"},"currencyExponent":{"type":"integer","minimum":0,"maximum":3,"description":"Number of minor-unit digits for `currencyCode`: 2 for USD, 0 for JPY, 3 for KWD. amount = minor units / 10^currencyExponent. Additive."},"publisherShareMinor":{"type":"integer"},"status":{"type":"string"},"invoices":{"type":"array","items":{"$ref":"#/components/schemas/SellerFinanceSettlementInvoice"}}},"required":["reportId","publisherCompanyId","contractTermId","currencyCode","currencyExponent","publisherShareMinor","status","invoices"]},"SellerFinanceOutstandingBalance":{"type":"object","properties":{"publisherCompanyId":{"type":"string"},"contractTermId":{"type":["string","null"],"format":"uuid"},"currencyCode":{"type":"string"},"currencyExponent":{"type":"integer","minimum":0,"maximum":3,"description":"Number of minor-unit digits for `currencyCode`: 2 for USD, 0 for JPY, 3 for KWD. amount = minor units / 10^currencyExponent. Additive."},"outstandingMinor":{"type":"integer"}},"required":["publisherCompanyId","contractTermId","currencyCode","currencyExponent","outstandingMinor"]},"SellerLedgerAmounts":{"type":"object","description":"Running totals in minor units of the entry's currency.","required":["netSalesCents","netSalesMinor","publisherShareCents","publisherShareMinor","sellerShareCents","sellerShareMinor","platformFeeCents","platformFeeMinor"],"properties":{"netSalesCents":{"type":"integer","description":"Deprecated name of `netSalesMinor` (same value). Kept on the wire; see Naming conventions in the Versioning and compatibility guide. Gross sales minus refunds and chargebacks plus reinstatements.","deprecated":true},"netSalesMinor":{"type":"integer","description":"Gross sales minus refunds and chargebacks plus reinstatements. Same amount as `netSalesCents`, under the `...Minor` name every Seller API amount uses: integer minor units of the currency beside it (see `currencyExponent`)."},"publisherShareCents":{"type":"integer","deprecated":true,"description":"Deprecated name of `publisherShareMinor` (same value). Kept on the wire; see Naming conventions in the Versioning and compatibility guide."},"publisherShareMinor":{"type":"integer","description":"Same amount as `publisherShareCents`, under the `...Minor` name every Seller API amount uses: integer minor units of the currency beside it (see `currencyExponent`)."},"sellerShareCents":{"type":"integer","deprecated":true,"description":"Deprecated name of `sellerShareMinor` (same value). Kept on the wire; see Naming conventions in the Versioning and compatibility guide."},"sellerShareMinor":{"type":"integer","description":"Same amount as `sellerShareCents`, under the `...Minor` name every Seller API amount uses: integer minor units of the currency beside it (see `currencyExponent`)."},"platformFeeCents":{"type":"integer","deprecated":true,"description":"Deprecated name of `platformFeeMinor` (same value). Kept on the wire; see Naming conventions in the Versioning and compatibility guide."},"platformFeeMinor":{"type":"integer","description":"Same amount as `platformFeeCents`, under the `...Minor` name every Seller API amount uses: integer minor units of the currency beside it (see `currencyExponent`)."}}},"SellerLedgerEntry":{"type":"object","description":"One money entry of the ledger. Amounts are signed minor units of `currencyCode`.","required":["entryId","kind","occurredAt","currencyCode","currencyExponent","publisherCompanyId","orderReference","keyId","skuId","transactionId","adjustmentReference","grossCents","grossMinor","publisherShareCents","publisherShareMinor","sellerShareCents","sellerShareMinor","platformFeeCents","platformFeeMinor","balanceAfter"],"properties":{"entryId":{"type":"string","description":"Stable entry id, the same as on `GET /activity`."},"kind":{"type":"string","enum":["sale","refund","chargeback","reinstatement"]},"occurredAt":{"type":"string","format":"date-time"},"currencyCode":{"type":"string"},"currencyExponent":{"type":"integer","minimum":0,"maximum":3,"description":"Number of minor-unit digits for `currencyCode`: 2 for USD, 0 for JPY, 3 for KWD. amount = minor units / 10^currencyExponent. Applies to `balanceAfter` too. Additive."},"publisherCompanyId":{"type":["string","null"]},"orderReference":{"type":["string","null"]},"keyId":{"type":["string","null"],"format":"uuid"},"skuId":{"type":["string","null"],"format":"uuid"},"transactionId":{"type":["string","null"],"format":"uuid","description":"The API sale transaction behind the entry (`GET /finance/api-sales/{transactionId}`)."},"adjustmentReference":{"type":["string","null"],"description":"Your refund or chargeback reference."},"grossCents":{"type":"integer","description":"Deprecated name of `grossMinor` (same value). Kept on the wire; see Naming conventions in the Versioning and compatibility guide. Negative for refunds and chargebacks.","deprecated":true},"grossMinor":{"type":"integer","description":"Negative for refunds and chargebacks. Same amount as `grossCents`, under the `...Minor` name every Seller API amount uses: integer minor units of the currency beside it (see `currencyExponent`)."},"publisherShareCents":{"type":"integer","deprecated":true,"description":"Deprecated name of `publisherShareMinor` (same value). Kept on the wire; see Naming conventions in the Versioning and compatibility guide."},"publisherShareMinor":{"type":"integer","description":"Same amount as `publisherShareCents`, under the `...Minor` name every Seller API amount uses: integer minor units of the currency beside it (see `currencyExponent`)."},"sellerShareCents":{"type":"integer","deprecated":true,"description":"Deprecated name of `sellerShareMinor` (same value). Kept on the wire; see Naming conventions in the Versioning and compatibility guide."},"sellerShareMinor":{"type":"integer","description":"Same amount as `sellerShareCents`, under the `...Minor` name every Seller API amount uses: integer minor units of the currency beside it (see `currencyExponent`)."},"platformFeeCents":{"type":"integer","deprecated":true,"description":"Deprecated name of `platformFeeMinor` (same value). Kept on the wire; see Naming conventions in the Versioning and compatibility guide."},"platformFeeMinor":{"type":"integer","description":"Same amount as `platformFeeCents`, under the `...Minor` name every Seller API amount uses: integer minor units of the currency beside it (see `currencyExponent`)."},"balanceAfter":{"$ref":"#/components/schemas/SellerLedgerAmounts"}}},"SellerLedgerBalance":{"type":"object","description":"Closing balance of a window for one currency. For a calendar month equal to `activityTotals` of the statement.","required":["currencyCode","currencyExponent","entryCount","grossSalesCents","grossSalesMinor","refundedCents","refundedMinor","reinstatedCents","reinstatedMinor","netSalesCents","netSalesMinor","publisherShareCents","publisherShareMinor","sellerShareCents","sellerShareMinor","platformFeeCents","platformFeeMinor"],"properties":{"currencyCode":{"type":"string"},"currencyExponent":{"type":"integer","minimum":0,"maximum":3,"description":"Number of minor-unit digits for `currencyCode`: 2 for USD, 0 for JPY, 3 for KWD. amount = minor units / 10^currencyExponent. Additive."},"entryCount":{"type":"integer"},"grossSalesCents":{"type":"integer","deprecated":true,"description":"Deprecated name of `grossSalesMinor` (same value). Kept on the wire; see Naming conventions in the Versioning and compatibility guide."},"grossSalesMinor":{"type":"integer","description":"Same amount as `grossSalesCents`, under the `...Minor` name every Seller API amount uses: integer minor units of the currency beside it (see `currencyExponent`)."},"refundedCents":{"type":"integer","description":"Deprecated name of `refundedMinor` (same value). Kept on the wire; see Naming conventions in the Versioning and compatibility guide. Refunds and chargebacks, as a positive figure.","deprecated":true},"refundedMinor":{"type":"integer","description":"Refunds and chargebacks, as a positive figure. Same amount as `refundedCents`, under the `...Minor` name every Seller API amount uses: integer minor units of the currency beside it (see `currencyExponent`)."},"reinstatedCents":{"type":"integer","deprecated":true,"description":"Deprecated name of `reinstatedMinor` (same value). Kept on the wire; see Naming conventions in the Versioning and compatibility guide."},"reinstatedMinor":{"type":"integer","description":"Same amount as `reinstatedCents`, under the `...Minor` name every Seller API amount uses: integer minor units of the currency beside it (see `currencyExponent`)."},"netSalesCents":{"type":"integer","description":"Deprecated name of `netSalesMinor` (same value). Kept on the wire; see Naming conventions in the Versioning and compatibility guide. Gross sales minus refunds and chargebacks plus reinstatements.","deprecated":true},"netSalesMinor":{"type":"integer","description":"Gross sales minus refunds and chargebacks plus reinstatements. Same amount as `netSalesCents`, under the `...Minor` name every Seller API amount uses: integer minor units of the currency beside it (see `currencyExponent`)."},"publisherShareCents":{"type":"integer","deprecated":true,"description":"Deprecated name of `publisherShareMinor` (same value). Kept on the wire; see Naming conventions in the Versioning and compatibility guide."},"publisherShareMinor":{"type":"integer","description":"Same amount as `publisherShareCents`, under the `...Minor` name every Seller API amount uses: integer minor units of the currency beside it (see `currencyExponent`)."},"sellerShareCents":{"type":"integer","deprecated":true,"description":"Deprecated name of `sellerShareMinor` (same value). Kept on the wire; see Naming conventions in the Versioning and compatibility guide."},"sellerShareMinor":{"type":"integer","description":"Same amount as `sellerShareCents`, under the `...Minor` name every Seller API amount uses: integer minor units of the currency beside it (see `currencyExponent`)."},"platformFeeCents":{"type":"integer","deprecated":true,"description":"Deprecated name of `platformFeeMinor` (same value). Kept on the wire; see Naming conventions in the Versioning and compatibility guide."},"platformFeeMinor":{"type":"integer","description":"Same amount as `platformFeeCents`, under the `...Minor` name every Seller API amount uses: integer minor units of the currency beside it (see `currencyExponent`)."}}},"SellerPayoutReconciliation":{"type":"object","description":"Reconciliation file for one payout (a vendor invoice and its settlement).","required":["invoiceId","invoiceNumber","settlementPackageId","sellerCompanyId","publisherCompanyId","paymentCurrency","paymentCurrencyExponent","paymentState","paymentMethod","paymentReference","settledAt","totalCents","totalMinor","saleCount","movements"],"properties":{"invoiceId":{"type":"string","format":"uuid"},"invoiceNumber":{"type":["string","null"]},"settlementPackageId":{"type":"string","format":"uuid"},"sellerCompanyId":{"type":"string"},"publisherCompanyId":{"type":"string"},"paymentCurrency":{"type":"string","description":"ISO 4217."},"paymentCurrencyExponent":{"type":"integer","minimum":0,"maximum":3,"description":"Number of minor-unit digits for `paymentCurrency`: 2 for USD, 0 for JPY, 3 for KWD. Applies to `totalCents` and every movement's `amountCents`. Sale amounts carry their own `currencyExponent`. Additive."},"paymentState":{"type":"string","description":"`unpaid`, `in_progress`, `paid` or `reversed`. The file is final once `paid`. New values may be added; treat an unknown one as not final.","enum":["unpaid","in_progress","paid","reversed"],"x-extensible-enum":true},"paymentMethod":{"type":["string","null"]},"paymentReference":{"type":["string","null"]},"settledAt":{"type":["string","null"],"format":"date-time"},"totalCents":{"type":"integer","description":"Deprecated name of `totalMinor` (same value). Kept on the wire; see Naming conventions in the Versioning and compatibility guide. Sum of the movement amounts, in minor units of `paymentCurrency`.","deprecated":true},"totalMinor":{"type":"integer","description":"Sum of the movement amounts, in minor units of `paymentCurrency`. Same amount as `totalCents`, under the `...Minor` name every Seller API amount uses: integer minor units of the currency beside it (see `currencyExponent`)."},"saleCount":{"type":"integer"},"movements":{"type":"array","items":{"$ref":"#/components/schemas/SellerPayoutReconciliationMovement"}}}},"SellerFinanceInvoiceLine":{"type":"object","description":"One balance movement the invoice settles: a report's accrual, a refund or chargeback adjustment, or a carried-over amount.","required":["allocationId","movementId","movementType","sourceType","reportId","reportMonth","contractTermId","amountCents","amountMinor","currencyCode","currencyExponent"],"properties":{"allocationId":{"type":"string","format":"uuid"},"movementId":{"type":"string","format":"uuid","description":"The movement, as the reconciliation file names it."},"movementType":{"type":["string","null"],"description":"What produced the movement, for example `report_accrual`, `refund_adjustment` or `chargeback_adjustment`."},"sourceType":{"type":["string","null"],"description":"The kind of record the movement came from, for example `sales_report`."},"reportId":{"type":["string","null"],"format":"uuid","description":"The monthly report the movement belongs to; read it with `GET /finance/reports/{reportId}`."},"reportMonth":{"type":["string","null"]},"contractTermId":{"type":"string","format":"uuid"},"amountCents":{"type":"integer","description":"Deprecated name of `amountMinor` (same value). Kept on the wire; see Naming conventions in the Versioning and compatibility guide. Amount this invoice bills for the movement, in minor units of `currencyCode`. Negative for an adjustment in your favour.","deprecated":true},"amountMinor":{"type":"integer","description":"Amount this invoice bills for the movement, in minor units of `currencyCode`. Negative for an adjustment in your favour. Same amount as `amountCents`, under the `...Minor` name every Seller API amount uses: integer minor units of the currency beside it (see `currencyExponent`)."},"currencyCode":{"type":"string"},"currencyExponent":{"type":"integer","minimum":0,"maximum":3,"description":"Number of minor-unit digits for `currencyCode`: 2 for USD, 0 for JPY, 3 for KWD. amount = minor units / 10^currencyExponent."}}},"SellerFinanceInvoicePayment":{"type":"object","description":"The settlement that pays the invoice: what you owe and how the payment stands.","required":["paymentState","paymentMethod","paymentReference","amountCents","amountMinor","currencyCode","currencyExponent","dueAt","settledAt"],"properties":{"paymentState":{"type":"string","enum":["unpaid","in_progress","paid","reversed"],"description":"`unpaid`, `in_progress` (a transfer is under way), `paid` (cleared; the invoice is `paid`), `reversed` (a cleared payment was returned)."},"paymentMethod":{"type":["string","null"],"description":"How the payment is made, for example `wire_transfer`, once chosen."},"paymentReference":{"type":["string","null"],"description":"The reference your transfer must carry so the vendor can match it."},"amountCents":{"type":"integer","description":"Deprecated name of `amountMinor` (same value). Kept on the wire; see Naming conventions in the Versioning and compatibility guide. What you pay for this invoice, in minor units of `currencyCode`.","deprecated":true},"amountMinor":{"type":"integer","description":"What you pay for this invoice, in minor units of `currencyCode`. Same amount as `amountCents`, under the `...Minor` name every Seller API amount uses: integer minor units of the currency beside it (see `currencyExponent`)."},"currencyCode":{"type":"string"},"currencyExponent":{"type":"integer","minimum":0,"maximum":3,"description":"Number of minor-unit digits for `currencyCode`: 2 for USD, 0 for JPY, 3 for KWD. amount = minor units / 10^currencyExponent."},"dueAt":{"type":["string","null"],"format":"date-time"},"settledAt":{"type":["string","null"],"format":"date-time"}}},"SellerFinanceInvoicePaymentRecord":{"type":"object","description":"A payment recorded against an invoice of the earlier billing model.","required":["paymentRecordId","paymentType","status","amountCents","amountMinor","currencyCode","currencyExponent","bankReference","paymentDate","confirmedAt","createdAt"],"properties":{"paymentRecordId":{"type":"string","format":"uuid"},"paymentType":{"type":"string","description":"`wire_transfer`, `platform_credit`, `refund` or `airwallex`."},"status":{"type":"string","description":"`pending`, `confirmed`, `rejected` or `reversed`."},"amountCents":{"type":"integer","description":"Deprecated name of `amountMinor` (same value). Kept on the wire; see Naming conventions in the Versioning and compatibility guide.","deprecated":true},"amountMinor":{"type":"integer","description":"Same amount as `amountCents`, under the `...Minor` name every Seller API amount uses: integer minor units of the currency beside it (see `currencyExponent`)."},"currencyCode":{"type":"string"},"currencyExponent":{"type":"integer","minimum":0,"maximum":3,"description":"Number of minor-unit digits for `currencyCode`: 2 for USD, 0 for JPY, 3 for KWD. amount = minor units / 10^currencyExponent."},"bankReference":{"type":["string","null"]},"paymentDate":{"type":["string","null"]},"confirmedAt":{"type":["string","null"],"format":"date-time"},"createdAt":{"type":"string","format":"date-time"}}},"SellerFinanceInvoiceDispute":{"type":"object","description":"A dispute you raised on the invoice and how the vendor answered.","required":["disputeId","status","reasonCode","explanation","vendorResponse","raisedAt","respondedAt","resolvedAt","replacementInvoiceId"],"properties":{"disputeId":{"type":"string","format":"uuid"},"status":{"type":"string","description":"`open`, `accepted` (a corrected invoice follows), `rejected`, `withdrawn` or `escalated`."},"reasonCode":{"type":"string","description":"`amount_mismatch`, `tax_incorrect`, `document_mismatch`, `duplicate`, `legal_details` or `other`."},"explanation":{"type":"string"},"vendorResponse":{"type":["string","null"]},"raisedAt":{"type":"string","format":"date-time"},"respondedAt":{"type":["string","null"],"format":"date-time"},"resolvedAt":{"type":["string","null"],"format":"date-time"},"replacementInvoiceId":{"type":["string","null"],"format":"uuid","description":"The corrected invoice, once the vendor has issued it."}}},"SellerFinanceInvoiceDocument":{"type":"object","description":"The invoice document the vendor issued to you. Download it with `downloadPath`.","required":["documentId","fileName","byteSize","contentHash","origin","frozenAt","createdAt","downloadPath"],"properties":{"documentId":{"type":"string","format":"uuid"},"fileName":{"type":"string"},"byteSize":{"type":"integer"},"contentHash":{"type":"string","description":"SHA-256 of the file, hex. Compare it with the file you download."},"origin":{"type":"string","description":"`uploaded` by the vendor or `generated` by Avrix."},"frozenAt":{"type":["string","null"],"format":"date-time"},"createdAt":{"type":"string","format":"date-time"},"downloadPath":{"type":"string","description":"Path of `GET /finance/invoices/{invoiceId}/document`."}}},"SellerFinanceInvoiceHistoryEntry":{"type":"object","required":["eventType","occurredAt"],"properties":{"eventType":{"type":"string","description":"`issued`, `delivered`, `viewed`, `dispute_opened`, `dispute_responded`, `dispute_resolved`, `replaced`, `superseded`, `cancelled`, `reminder_sent` or `payment_state_changed`. New values may be added."},"occurredAt":{"type":"string","format":"date-time"}}},"SellerFinanceInvoiceDetail":{"type":"object","description":"One invoice you owe, with what it bills, how it is being paid, disputes, its document and its history. The summary fields match the row in `GET /finance/invoices`.","required":["id","invoiceNumber","status","invoiceType","totalCents","totalMinor","currencyCode","currencyExponent","issuedAt","dueAt","salesReportId","paidAt","kind","publisherCompanyId","supplierInvoiceNumber","reportMonth","subtotalCents","subtotalMinor","taxCents","taxMinor","paidCents","paidMinor","outstandingCents","outstandingMinor","paymentTermsDays","paymentState","replacesInvoiceId","supersededByInvoiceId","updatedAt","reconciliationAvailable","reconciliationPath","detailPath","lines","payment","paymentRecords","disputes","documents","history"],"properties":{"id":{"type":"string","format":"uuid"},"invoiceNumber":{"type":"string"},"status":{"type":"string","description":"Where the invoice stands. Monthly invoices: `awaiting_commission_document` (issued, not payable until the commission document is attached), `payable`, `overdue` (past `dueAt` unpaid; still payable), `disputed` (you contested it; payment paused), `paid`, `superseded` (replaced by a corrected invoice, see `supersededByInvoiceId`). Invoices of the earlier billing model also use `sent`, `cancelled` and `credited`. Treat an unknown value as not payable and read the invoice again."},"invoiceType":{"type":"string","description":"`final` for an invoice you pay, `credit_note` for money that comes back to you (its total is positive), `proforma` for an advance document of the earlier billing model."},"totalCents":{"type":"integer","description":"Deprecated name of `totalMinor` (same value). Kept on the wire; see Naming conventions in the Versioning and compatibility guide. Invoice total in minor units of `currencyCode`.","deprecated":true},"totalMinor":{"type":"integer","description":"Invoice total in minor units of `currencyCode`. Same amount as `totalCents`, under the `...Minor` name every Seller API amount uses: integer minor units of the currency beside it (see `currencyExponent`)."},"currencyCode":{"type":"string"},"currencyExponent":{"type":"integer","minimum":0,"maximum":3,"description":"Number of minor-unit digits for `currencyCode`: 2 for USD, 0 for JPY, 3 for KWD. amount = minor units / 10^currencyExponent. Additive."},"issuedAt":{"type":"string","format":"date-time"},"dueAt":{"type":["string","null"],"format":"date-time"},"salesReportId":{"type":["string","null"]},"paidAt":{"type":["string","null"],"format":"date-time"},"kind":{"type":"string","enum":["vendor_payable","avrix_commission","legacy_allocation","legacy_report"],"description":"`vendor_payable` is the vendor's monthly invoice to you. `legacy_report` and `legacy_allocation` are documents of the earlier per-report and per-allocation billing. `avrix_commission` is listed for completeness; it is billed to the vendor and never appears in your list."},"publisherCompanyId":{"type":"string","description":"The vendor's company id."},"supplierInvoiceNumber":{"type":["string","null"],"description":"The vendor's own invoice number, as printed on their document. `invoiceNumber` is the Avrix number."},"reportMonth":{"type":["string","null"],"description":"The sales month the invoice bills (`YYYY-MM`), for monthly invoices."},"subtotalCents":{"type":"integer","description":"Deprecated name of `subtotalMinor` (same value). Kept on the wire; see Naming conventions in the Versioning and compatibility guide. Amount before tax, in minor units of `currencyCode`.","deprecated":true},"subtotalMinor":{"type":"integer","description":"Amount before tax, in minor units of `currencyCode`. Same amount as `subtotalCents`, under the `...Minor` name every Seller API amount uses: integer minor units of the currency beside it (see `currencyExponent`)."},"taxCents":{"type":"integer","description":"Deprecated name of `taxMinor` (same value). Kept on the wire; see Naming conventions in the Versioning and compatibility guide. Tax, in minor units of `currencyCode`. `subtotalCents + taxCents = totalCents`.","deprecated":true},"taxMinor":{"type":"integer","description":"Tax, in minor units of `currencyCode`. `subtotalCents + taxCents = totalCents`. Same amount as `taxCents`, under the `...Minor` name every Seller API amount uses: integer minor units of the currency beside it (see `currencyExponent`)."},"paidCents":{"type":["integer","null"],"description":"Deprecated name of `paidMinor` (same value). Kept on the wire; see Naming conventions in the Versioning and compatibility guide. Amount recorded as paid so far, in minor units. Null for invoices of the earlier billing model.","deprecated":true},"paidMinor":{"type":["integer","null"],"description":"Amount recorded as paid so far, in minor units. Null for invoices of the earlier billing model. Same amount as `paidCents`, under the `...Minor` name every Seller API amount uses: integer minor units of the currency beside it (see `currencyExponent`)."},"outstandingCents":{"type":["integer","null"],"description":"Deprecated name of `outstandingMinor` (same value). Kept on the wire; see Naming conventions in the Versioning and compatibility guide. Amount still to pay, in minor units. Null for invoices of the earlier billing model.","deprecated":true},"outstandingMinor":{"type":["integer","null"],"description":"Amount still to pay, in minor units. Null for invoices of the earlier billing model. Same amount as `outstandingCents`, under the `...Minor` name every Seller API amount uses: integer minor units of the currency beside it (see `currencyExponent`)."},"paymentTermsDays":{"type":["integer","null"],"description":"Days between issue and due date that the agreement sets."},"paymentState":{"type":["string","null"],"enum":["unpaid","in_progress","paid","reversed",null],"description":"State of the settlement that pays this invoice (see `GET /finance/payments`); null when the invoice has none, which is the case for invoices of the earlier billing model and for one still waiting for the commission document."},"replacesInvoiceId":{"type":["string","null"],"format":"uuid","description":"On a corrected invoice: the invoice it replaces."},"supersededByInvoiceId":{"type":["string","null"],"format":"uuid","description":"On a replaced invoice (`status: superseded`): the corrected invoice to pay instead."},"updatedAt":{"type":"string","format":"date-time","description":"Last change to the invoice. Filter with `updatedSince` to sync changes."},"reconciliationAvailable":{"type":"boolean","description":"True when `reconciliationPath` answers 200: the invoice has a settlement."},"reconciliationPath":{"type":["string","null"],"description":"Path of this invoice's reconciliation file, when it has one."},"detailPath":{"type":"string","description":"Path of `GET /finance/invoices/{invoiceId}` for this invoice."},"lines":{"type":"array","items":{"$ref":"#/components/schemas/SellerFinanceInvoiceLine"},"description":"What the invoice bills, one entry per balance movement. Empty for invoices of the earlier billing model."},"payment":{"oneOf":[{"$ref":"#/components/schemas/SellerFinanceInvoicePayment"},{"type":"null"}],"description":"The settlement that pays the invoice; null when it has none."},"paymentRecords":{"type":"array","items":{"$ref":"#/components/schemas/SellerFinanceInvoicePaymentRecord"}},"disputes":{"type":"array","items":{"$ref":"#/components/schemas/SellerFinanceInvoiceDispute"}},"documents":{"type":"array","items":{"$ref":"#/components/schemas/SellerFinanceInvoiceDocument"},"description":"The live document you may download; empty when there is none (invoices of the earlier billing model)."},"history":{"type":"array","items":{"$ref":"#/components/schemas/SellerFinanceInvoiceHistoryEntry"},"description":"What happened to the invoice, oldest first, as the console shows it to you."}}},"SellerFinanceInvoiceDocumentLink":{"type":"object","required":["invoiceId","documentId","fileName","byteSize","contentHash","contentType","url","expiresAt"],"properties":{"invoiceId":{"type":"string","format":"uuid"},"documentId":{"type":"string","format":"uuid"},"fileName":{"type":"string"},"byteSize":{"type":"integer"},"contentHash":{"type":"string","description":"SHA-256 of the file, hex."},"contentType":{"type":"string","const":"application/pdf"},"url":{"type":"string","format":"uri","description":"Signed download link. Fetch it without your API key; it stops working at `expiresAt`."},"expiresAt":{"type":"string","format":"date-time","description":"When `url` stops working, five minutes after the response. Ask again for a fresh link."}}},"SellerFinancePayment":{"type":"object","description":"Your side of one vendor invoice's settlement.","required":["paymentId","invoiceId","publisherCompanyId","amountCents","amountMinor","currencyCode","currencyExponent","paymentState","paymentMethod","paymentReference","dueAt","settledAt","createdAt","updatedAt","invoicePath"],"properties":{"paymentId":{"type":"string","format":"uuid"},"invoiceId":{"type":"string","format":"uuid","description":"The vendor invoice this settles."},"publisherCompanyId":{"type":"string","description":"The vendor's company id."},"amountCents":{"type":"integer","description":"Deprecated name of `amountMinor` (same value). Kept on the wire; see Naming conventions in the Versioning and compatibility guide. What you pay, in minor units of `currencyCode`. The commission the vendor pays Avrix out of it is not shown.","deprecated":true},"amountMinor":{"type":"integer","description":"What you pay, in minor units of `currencyCode`. The commission the vendor pays Avrix out of it is not shown. Same amount as `amountCents`, under the `...Minor` name every Seller API amount uses: integer minor units of the currency beside it (see `currencyExponent`)."},"currencyCode":{"type":"string"},"currencyExponent":{"type":"integer","minimum":0,"maximum":3,"description":"Number of minor-unit digits for `currencyCode`: 2 for USD, 0 for JPY, 3 for KWD. amount = minor units / 10^currencyExponent."},"paymentState":{"type":"string","enum":["unpaid","in_progress","paid","reversed"],"description":"`unpaid`, `in_progress` (a transfer is under way), `paid` (cleared; the invoice is `paid`), `reversed` (a cleared payment was returned)."},"paymentMethod":{"type":["string","null"]},"paymentReference":{"type":["string","null"],"description":"The reference your transfer must carry."},"dueAt":{"type":["string","null"],"format":"date-time"},"settledAt":{"type":["string","null"],"format":"date-time"},"createdAt":{"type":"string","format":"date-time"},"updatedAt":{"type":"string","format":"date-time"},"invoicePath":{"type":"string"}}},"SellerFinanceReportTotals":{"type":"object","description":"Report totals in minor units of the report's `currencyCode`. Null when the report has not been totalled yet.","required":["grossCents","grossMinor","netCents","netMinor","reversalsCents","reversalsMinor","vatCents","vatMinor","sellerShareCents","sellerShareMinor","publisherShareCents","publisherShareMinor"],"properties":{"grossCents":{"type":["integer","null"],"description":"Deprecated name of `grossMinor` (same value). Kept on the wire; see Naming conventions in the Versioning and compatibility guide.","deprecated":true},"grossMinor":{"type":["integer","null"],"description":"Same amount as `grossCents`, under the `...Minor` name every Seller API amount uses: integer minor units of the currency beside it (see `currencyExponent`)."},"netCents":{"type":["integer","null"],"description":"Deprecated name of `netMinor` (same value). Kept on the wire; see Naming conventions in the Versioning and compatibility guide.","deprecated":true},"netMinor":{"type":["integer","null"],"description":"Same amount as `netCents`, under the `...Minor` name every Seller API amount uses: integer minor units of the currency beside it (see `currencyExponent`)."},"reversalsCents":{"type":["integer","null"],"description":"Deprecated name of `reversalsMinor` (same value). Kept on the wire; see Naming conventions in the Versioning and compatibility guide.","deprecated":true},"reversalsMinor":{"type":["integer","null"],"description":"Same amount as `reversalsCents`, under the `...Minor` name every Seller API amount uses: integer minor units of the currency beside it (see `currencyExponent`)."},"vatCents":{"type":["integer","null"],"description":"Deprecated name of `vatMinor` (same value). Kept on the wire; see Naming conventions in the Versioning and compatibility guide.","deprecated":true},"vatMinor":{"type":["integer","null"],"description":"Same amount as `vatCents`, under the `...Minor` name every Seller API amount uses: integer minor units of the currency beside it (see `currencyExponent`)."},"sellerShareCents":{"type":["integer","null"],"description":"Deprecated name of `sellerShareMinor` (same value). Kept on the wire; see Naming conventions in the Versioning and compatibility guide. Your share.","deprecated":true},"sellerShareMinor":{"type":["integer","null"],"description":"Your share. Same amount as `sellerShareCents`, under the `...Minor` name every Seller API amount uses: integer minor units of the currency beside it (see `currencyExponent`)."},"publisherShareCents":{"type":["integer","null"],"description":"Deprecated name of `publisherShareMinor` (same value). Kept on the wire; see Naming conventions in the Versioning and compatibility guide. The vendor's share: what the monthly invoice bills for this report.","deprecated":true},"publisherShareMinor":{"type":["integer","null"],"description":"The vendor's share: what the monthly invoice bills for this report. Same amount as `publisherShareCents`, under the `...Minor` name every Seller API amount uses: integer minor units of the currency beside it (see `currencyExponent`)."}}},"SellerFinanceReportConfirmation":{"type":"object","description":"Where the report stands in the monthly cycle and who acts next. Today a report is confirmed (API sales) or submitted (revenue share) in the console; the API reads the state.","required":["state","nextActor","deadline","overdue","submittedAt","confirmIn"],"properties":{"state":{"type":"string","enum":["awaiting_seller","awaiting_vendor","approved","disputed","rejected"],"description":"`awaiting_seller`: you confirm or submit it. `awaiting_vendor`: the vendor reviews it. `approved`: final, and invoiced. `disputed`: the vendor disputes it. `rejected`: you correct and resubmit."},"nextActor":{"type":["string","null"],"enum":["seller","vendor",null],"description":"Who acts next. `seller`: your company (confirm or submit the report, or correct a rejected one). `vendor`: the Content Owner (review a submitted or disputed report). Null once the report is approved."},"deadline":{"type":["string","null"],"description":"When you must confirm or submit by."},"overdue":{"type":"boolean","description":"True when the deadline passed before you confirmed."},"submittedAt":{"type":["string","null"],"format":"date-time"},"confirmIn":{"type":"string","enum":["console"],"description":"Where the report is confirmed today."}}},"SellerFinanceReport":{"type":"object","description":"A monthly sales report: your sales of one vendor's products for one month.","required":["id","reportMonth","status","modelType","publisherCompanyId","currencyCode","currencyExponent","periodStart","periodEnd","deadline","submittedAt","createdAt","updatedAt","revokedAt","totals","confirmation","detailPath","linesPath"],"properties":{"id":{"type":"string","format":"uuid"},"reportMonth":{"type":"string","description":"`YYYY-MM`."},"status":{"type":"string","enum":["draft","overdue","submitted","approved","disputed","rejected"],"description":"Monthly sales report state: `draft` -> `submitted` -> `approved`, or `disputed` / `rejected` on review; `overdue` when it was not submitted in time. Only an `approved` report settles. New values may be added; treat an unknown one as not settled."},"modelType":{"type":"string","enum":["api","revenue_share"],"description":"`api`: Avrix aggregated your API sales. `revenue_share`: you report the sales."},"publisherCompanyId":{"type":"string","description":"The vendor's company id."},"currencyCode":{"type":"string","description":"The report's payment currency."},"currencyExponent":{"type":"integer","minimum":0,"maximum":3,"description":"Number of minor-unit digits for `currencyCode`: 2 for USD, 0 for JPY, 3 for KWD. amount = minor units / 10^currencyExponent."},"periodStart":{"type":["string","null"]},"periodEnd":{"type":["string","null"]},"deadline":{"type":["string","null"]},"submittedAt":{"type":["string","null"],"format":"date-time"},"createdAt":{"type":["string","null"],"format":"date-time"},"updatedAt":{"type":["string","null"],"format":"date-time"},"revokedAt":{"type":["string","null"],"format":"date-time","description":"Set when a correction replaced this report; the correction is a separate report for the same month."},"totals":{"$ref":"#/components/schemas/SellerFinanceReportTotals"},"confirmation":{"$ref":"#/components/schemas/SellerFinanceReportConfirmation"},"detailPath":{"type":"string"},"linesPath":{"type":"string"}}},"SellerFinanceReportFx":{"type":"object","description":"The rate that converted one sale currency into the report currency, frozen when the report was built.","required":["saleCurrency","reportCurrency","rate","source","asOf","fixingTime","convention","identity"],"properties":{"saleCurrency":{"type":"string"},"reportCurrency":{"type":"string"},"rate":{"type":["string","null"],"description":"Units of `reportCurrency` per unit of `saleCurrency`, as a decimal string so no precision is lost."},"source":{"type":["string","null"],"description":"Who published the rate; `identity` when nothing was converted."},"asOf":{"type":["string","null"]},"fixingTime":{"type":["string","null"]},"convention":{"type":["string","null"],"description":"`period_end` or `period_average`: which rate the agreement asks for."},"identity":{"type":"boolean","description":"True when the sale currency is the report currency."}}},"SellerFinanceReportDetail":{"type":"object","description":"One monthly report with its exchange rates and disputes. Its lines are on `linesPath`.","required":["id","reportMonth","status","modelType","publisherCompanyId","currencyCode","currencyExponent","periodStart","periodEnd","deadline","submittedAt","createdAt","updatedAt","revokedAt","totals","confirmation","detailPath","linesPath","rejectionReason","fxConvention","fx","fxAttestations","disputes"],"properties":{"id":{"type":"string","format":"uuid"},"reportMonth":{"type":"string","description":"`YYYY-MM`."},"status":{"type":"string","enum":["draft","overdue","submitted","approved","disputed","rejected"],"description":"Monthly sales report state: `draft` -> `submitted` -> `approved`, or `disputed` / `rejected` on review; `overdue` when it was not submitted in time. Only an `approved` report settles. New values may be added; treat an unknown one as not settled."},"modelType":{"type":"string","enum":["api","revenue_share"],"description":"`api`: Avrix aggregated your API sales. `revenue_share`: you report the sales."},"publisherCompanyId":{"type":"string","description":"The vendor's company id."},"currencyCode":{"type":"string","description":"The report's payment currency."},"currencyExponent":{"type":"integer","minimum":0,"maximum":3,"description":"Number of minor-unit digits for `currencyCode`: 2 for USD, 0 for JPY, 3 for KWD. amount = minor units / 10^currencyExponent."},"periodStart":{"type":["string","null"]},"periodEnd":{"type":["string","null"]},"deadline":{"type":["string","null"]},"submittedAt":{"type":["string","null"],"format":"date-time"},"createdAt":{"type":["string","null"],"format":"date-time"},"updatedAt":{"type":["string","null"],"format":"date-time"},"revokedAt":{"type":["string","null"],"format":"date-time","description":"Set when a correction replaced this report; the correction is a separate report for the same month."},"totals":{"$ref":"#/components/schemas/SellerFinanceReportTotals"},"confirmation":{"$ref":"#/components/schemas/SellerFinanceReportConfirmation"},"detailPath":{"type":"string"},"linesPath":{"type":"string"},"rejectionReason":{"type":["string","null"]},"fxConvention":{"type":["string","null"]},"fx":{"type":"array","items":{"$ref":"#/components/schemas/SellerFinanceReportFx"}},"fxAttestations":{"type":"array","items":{"type":"object","required":["sourceCurrency","paymentCurrency","rate","note","attestedAt"],"properties":{"sourceCurrency":{"type":"string"},"paymentCurrency":{"type":"string"},"rate":{"type":"string"},"note":{"type":"string"},"attestedAt":{"type":"string","format":"date-time"}}},"description":"Rates you stated yourself for a revenue-share report, with your note on where they came from."},"disputes":{"type":"array","items":{"type":"object","required":["disputeId","status","reason","filedByCompanyId","filedAt","resolvedAt"],"properties":{"disputeId":{"type":"string","format":"uuid"},"status":{"type":"string"},"reason":{"type":["string","null"]},"filedByCompanyId":{"type":"string"},"filedAt":{"type":["string","null"],"format":"date-time"},"resolvedAt":{"type":["string","null"],"format":"date-time"}}}}}},"SellerFinanceReportLine":{"type":"object","description":"One line of a monthly report. Sale amounts are in `saleCurrency`; the shares are in the report's `currencyCode` after conversion at `exchangeRate`.","required":["lineId","entryType","skuId","productId","publisherCompanyId","quantity","saleCurrency","saleCurrencyExponent","unitPriceCents","unitPriceMinor","grossCents","grossMinor","netCents","netMinor","vatCents","vatMinor","deductionsCents","deductionsMinor","currencyCode","currencyExponent","exchangeRate","netConvertedCents","netConvertedMinor","publisherShareCents","publisherShareMinor","sellerShareCents","sellerShareMinor","appliedRatePercent","region","requestedCountry","platform","promotionLabel","promotionReference"],"properties":{"lineId":{"type":"string","format":"uuid"},"entryType":{"type":"string","description":"`sale`, or `refund` / `chargeback` for a reversal."},"skuId":{"type":"string"},"productId":{"type":"string"},"publisherCompanyId":{"type":["string","null"]},"quantity":{"type":"integer"},"saleCurrency":{"type":"string","description":"Currency of the sale amounts on this line."},"saleCurrencyExponent":{"type":"integer","minimum":0,"maximum":3,"description":"Number of minor-unit digits for `saleCurrency`."},"unitPriceCents":{"type":["integer","null"],"description":"Deprecated name of `unitPriceMinor` (same value). Kept on the wire; see Naming conventions in the Versioning and compatibility guide. In `saleCurrency`.","deprecated":true},"unitPriceMinor":{"type":["integer","null"],"description":"In `saleCurrency`. Same amount as `unitPriceCents`, under the `...Minor` name every Seller API amount uses: integer minor units of the currency beside it (see `currencyExponent`)."},"grossCents":{"type":["integer","null"],"description":"Deprecated name of `grossMinor` (same value). Kept on the wire; see Naming conventions in the Versioning and compatibility guide. In `saleCurrency`.","deprecated":true},"grossMinor":{"type":["integer","null"],"description":"In `saleCurrency`. Same amount as `grossCents`, under the `...Minor` name every Seller API amount uses: integer minor units of the currency beside it (see `currencyExponent`)."},"netCents":{"type":["integer","null"],"description":"Deprecated name of `netMinor` (same value). Kept on the wire; see Naming conventions in the Versioning and compatibility guide. In `saleCurrency`.","deprecated":true},"netMinor":{"type":["integer","null"],"description":"In `saleCurrency`. Same amount as `netCents`, under the `...Minor` name every Seller API amount uses: integer minor units of the currency beside it (see `currencyExponent`)."},"vatCents":{"type":["integer","null"],"description":"Deprecated name of `vatMinor` (same value). Kept on the wire; see Naming conventions in the Versioning and compatibility guide. In `saleCurrency`.","deprecated":true},"vatMinor":{"type":["integer","null"],"description":"In `saleCurrency`. Same amount as `vatCents`, under the `...Minor` name every Seller API amount uses: integer minor units of the currency beside it (see `currencyExponent`)."},"deductionsCents":{"type":["integer","null"],"description":"Deprecated name of `deductionsMinor` (same value). Kept on the wire; see Naming conventions in the Versioning and compatibility guide. In `saleCurrency`.","deprecated":true},"deductionsMinor":{"type":["integer","null"],"description":"In `saleCurrency`. Same amount as `deductionsCents`, under the `...Minor` name every Seller API amount uses: integer minor units of the currency beside it (see `currencyExponent`)."},"currencyCode":{"type":"string","description":"The report's payment currency: the currency of the shares and `netConvertedCents`."},"currencyExponent":{"type":"integer","minimum":0,"maximum":3,"description":"Number of minor-unit digits for `currencyCode`: 2 for USD, 0 for JPY, 3 for KWD. amount = minor units / 10^currencyExponent."},"exchangeRate":{"type":["string","null"],"description":"The rate from `saleCurrency` to `currencyCode`, as a decimal string."},"netConvertedCents":{"type":["integer","null"],"description":"Deprecated name of `netConvertedMinor` (same value). Kept on the wire; see Naming conventions in the Versioning and compatibility guide. Net amount in `currencyCode`.","deprecated":true},"netConvertedMinor":{"type":["integer","null"],"description":"Net amount in `currencyCode`. Same amount as `netConvertedCents`, under the `...Minor` name every Seller API amount uses: integer minor units of the currency beside it (see `currencyExponent`)."},"publisherShareCents":{"type":["integer","null"],"description":"Deprecated name of `publisherShareMinor` (same value). Kept on the wire; see Naming conventions in the Versioning and compatibility guide. The vendor's share, in `currencyCode`.","deprecated":true},"publisherShareMinor":{"type":["integer","null"],"description":"The vendor's share, in `currencyCode`. Same amount as `publisherShareCents`, under the `...Minor` name every Seller API amount uses: integer minor units of the currency beside it (see `currencyExponent`)."},"sellerShareCents":{"type":["integer","null"],"description":"Deprecated name of `sellerShareMinor` (same value). Kept on the wire; see Naming conventions in the Versioning and compatibility guide. Your share, in `currencyCode`.","deprecated":true},"sellerShareMinor":{"type":["integer","null"],"description":"Your share, in `currencyCode`. Same amount as `sellerShareCents`, under the `...Minor` name every Seller API amount uses: integer minor units of the currency beside it (see `currencyExponent`)."},"appliedRatePercent":{"type":["number","null"],"description":"VAT rate applied, percent."},"region":{"type":["string","null"]},"requestedCountry":{"type":["string","null"]},"platform":{"type":["string","null"]},"promotionLabel":{"type":["string","null"]},"promotionReference":{"type":["string","null"]}}},"SellerPayoutReconciliationMovement":{"type":"object","description":"One balance movement a payout settles.","required":["movementId","movementType","sourceType","amountCents","amountMinor","reportId","reportMonth","sales"],"properties":{"movementId":{"type":"string","format":"uuid"},"movementType":{"type":"string"},"sourceType":{"type":"string","description":"`sales_report` for an approved monthly report, `api_sale_*` for a per-sale adjustment; any other value carries no sales."},"amountCents":{"type":"integer","description":"Deprecated name of `amountMinor` (same value). Kept on the wire; see Naming conventions in the Versioning and compatibility guide. Minor units of the payment currency.","deprecated":true},"amountMinor":{"type":"integer","description":"Minor units of the payment currency. Same amount as `amountCents`, under the `...Minor` name every Seller API amount uses: integer minor units of the currency beside it (see `currencyExponent`)."},"reportId":{"type":["string","null"],"format":"uuid"},"reportMonth":{"type":["string","null"],"description":"Report month as `YYYY-MM`."},"sales":{"type":"array","items":{"$ref":"#/components/schemas/SellerPayoutReconciliationSale"}}}},"SellerPayoutReconciliationSale":{"type":"object","description":"One API sale a payout movement covers. Amounts are in minor units of `currencyCode`, the sale currency.","required":["transactionId","entryType","orderReference","keyId","skuId","saleTimestamp","currencyCode","currencyExponent","grossMinor","vatMinor","netMinor","publisherShareMinor","sellerShareMinor","platformFeeMinor","lineExchangeRate","adjustmentStatus"],"properties":{"transactionId":{"type":"string","format":"uuid","description":"API sale transaction id (`GET /finance/api-sales/{transactionId}`)."},"entryType":{"type":["string","null"],"description":"`sale`, `sale_reversal` or `sale_reinstatement`."},"orderReference":{"type":["string","null"],"description":"Your order reference."},"keyId":{"type":["string","null"],"description":"Key the sale delivered.","format":"uuid"},"skuId":{"type":["string","null"],"description":"SKU sold.","format":"uuid"},"saleTimestamp":{"type":["string","null"],"description":"When the sale happened.","format":"date-time"},"currencyCode":{"type":["string","null"],"description":"Sale currency (ISO 4217)."},"currencyExponent":{"type":["integer","null"],"minimum":0,"maximum":3,"description":"Number of minor-unit digits for `currencyCode`: 2 for USD, 0 for JPY, 3 for KWD. amount = minor units / 10^currencyExponent; `null` when `currencyCode` is `null`. Additive."},"grossMinor":{"type":["integer","null"],"description":"Sale price including VAT."},"vatMinor":{"type":["integer","null"],"description":"VAT on the sale; null when the sale predates the settlement basis."},"netMinor":{"type":["integer","null"],"description":"Sale price excluding VAT."},"publisherShareMinor":{"type":["integer","null"],"description":"Content Owner share."},"sellerShareMinor":{"type":["integer","null"],"description":"Your share."},"platformFeeMinor":{"type":["integer","null"],"description":"Avrix commission."},"lineExchangeRate":{"type":["number","null"],"description":"Rate the sale's report line converted at into the payment currency; null for a per-sale adjustment."},"adjustmentStatus":{"type":["string","null"],"description":"Refund or chargeback state of the sale."}}},"WebhookTestChallenge":{"type":"string","enum":["valid","invalid_signature","stale_timestamp","duplicate","previous_secret_only"],"description":"Receiver test for `POST /webhooks/{id}/test` (sandbox keys only). `valid`: signed normally. `invalid_signature`: signed with a random secret; your endpoint must reject it. `stale_timestamp`: correctly signed with a timestamp ten minutes old; your endpoint must reject it. `duplicate`: one delivery sent twice with the same `eventId`; your endpoint must process it once. `previous_secret_only`: signed with the previous secret only, while a rotation overlap is open; your endpoint must accept it. A delivery that is a signature challenge (`invalid_signature`, `stale_timestamp`, `previous_secret_only`) gets one attempt, is not retried and does not count towards the endpoint's auto-disable threshold."},"WebhookTestEvent":{"type":"object","description":"Present only on test deliveries queued by `POST /webhooks/{id}/test`: on every non-`test.ping` test event, and on a `test.ping` sent as a receiver challenge. The payload is a contract-valid sample; nothing in it describes a real order, key or catalog change. Do not apply it to your records.","required":["testRunId"],"properties":{"testRunId":{"type":"string","description":"Id of the test-fire call, also returned as `data.testRunId` by `POST /webhooks/{id}/test`. Sample ids in the payload are derived from it."},"challenge":{"$ref":"#/components/schemas/WebhookTestChallenge"}}},"WebhookEndpoint":{"type":"object","description":"A webhook endpoint as `GET /webhooks` lists it.","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)."},"consecutiveFailures":{"type":"integer","description":"Deliveries in a row that exhausted their retries (terminal failures). Reset by a successful delivery. The endpoint is disabled when it reaches the platform threshold."},"disabledReason":{"type":["string","null"],"description":"Why the endpoint is disabled (for example `consecutive_failures`), or null while it is active."},"updatedAt":{"type":["string","null"],"format":"date-time","description":"When the endpoint was last changed."},"failing":{"type":"boolean","description":"True while deliveries to this active endpoint keep failing: at least 3 failed attempts in a row over at least 10 minutes. The endpoint stays active and retries continue; this is the early warning, well before the circuit breaker disables it (see `consecutiveFailures`). `system.webhook_endpoint_failing` is sent when it turns true, `system.webhook_endpoint_recovered` when a delivery succeeds again. Always false for a disabled endpoint."},"failingSince":{"type":["string","null"],"format":"date-time","description":"When the endpoint turned `failing`; null while it is not."},"lastSuccessAt":{"type":["string","null"],"format":"date-time","description":"The last delivery attempt your endpoint answered with 2xx."},"lastFailureAt":{"type":["string","null"],"format":"date-time","description":"The last delivery attempt that failed (non-2xx, timeout or connection error)."},"consecutiveFailedAttempts":{"type":"integer","description":"Failed attempts in a row, counting every retry. `consecutiveFailures` counts only deliveries that used up all their retries."},"pendingDeliveries":{"type":"integer","description":"Deliveries waiting to be sent or retried (buffered deliveries of a disabled endpoint are in `bufferedDeliveries`)."}}},"SellerSandboxCertificationObservation":{"type":"object","description":"One piece of traffic that supports a case's status.","required":["at","detail"],"properties":{"at":{"type":"string","format":"date-time","description":"When the request was made or the delivery was created."},"requestId":{"type":"string","description":"`X-Request-Id` of the sandbox request, when the evidence is a request."},"deliveryId":{"type":"string","description":"Webhook delivery id, when the evidence is a delivery (`GET /webhooks/{id}/deliveries`)."},"detail":{"type":"string","description":"What was observed, for example `POST /api/seller/v1/orders → 200 (SANDBOX-ALWAYS-001)`."}}},"SellerSandboxCertificationCase":{"type":"object","description":"Result of one of the 28 certification cases.","required":["number","name","group","status","evidenceQuality","reason","observations","partnerEvidence"],"properties":{"number":{"type":"integer","minimum":1,"maximum":28,"description":"Case number in the Certification guide."},"name":{"type":"string"},"group":{"type":"string","enum":["catalog","orders","fulfilment","webhooks","refunds","operations"]},"status":{"type":"string","enum":["pass","fail","not_run","needs_partner_evidence"],"description":"`pass`: the traffic proves the expected behaviour. `fail`: the traffic proves the opposite (for example a mis-signed test event answered 2xx). `not_run`: no traffic exercises the case yet, or its evidence could not be read. `needs_partner_evidence`: the server-side evidence is consistent, but the case is about behaviour inside your systems; it becomes `pass` once Avrix accepts your evidence submission."},"evidenceQuality":{"type":"string","enum":["complete","unknown"],"description":"`unknown` when a source this case needs could not be read. Such a case is never reported as `pass`."},"reason":{"type":"string","description":"Why the case has this status, or what to do to run it."},"observations":{"type":"array","items":{"$ref":"#/components/schemas/SellerSandboxCertificationObservation"},"description":"Up to five requests or deliveries that support the status. Empty when nothing was observed."},"partnerEvidence":{"type":"string","enum":["none","submitted","accepted","rejected"],"description":"State of your latest evidence submission for this case (Console, sandbox key certification panel)."}}},"SellerSandboxCertificationReport":{"type":"object","description":"Automatic certification report for the calling sandbox key, evaluated from its own sandbox traffic in the evidence window. It contains request and delivery references only: no keys, tokens or buyer data. Passing it does not by itself enable production access.","required":["reportVersion","generatedAt","apiKeyId","environment","window","summary","collectionErrors","cases"],"properties":{"reportVersion":{"type":"integer","description":"Report format version, currently `1`."},"generatedAt":{"type":"string","format":"date-time"},"apiKeyId":{"type":"string","format":"uuid","description":"The sandbox key the report is about (the calling key)."},"environment":{"type":"object","required":["mode","environmentId"],"properties":{"mode":{"type":"string","enum":["shared","isolated"],"description":"`isolated` once your store runs in its own sandbox environment; `shared` before that."},"environmentId":{"type":["string","null"],"format":"uuid","description":"Id of your isolated environment, or null on the shared sandbox."}}},"window":{"type":"object","description":"Evidence window: the last 30 days.","required":["from","to"],"properties":{"from":{"type":"string","format":"date-time"},"to":{"type":"string","format":"date-time"}}},"summary":{"type":"object","description":"Number of cases per status.","required":["pass","fail","not_run","needs_partner_evidence"],"properties":{"pass":{"type":"integer","minimum":0},"fail":{"type":"integer","minimum":0},"not_run":{"type":"integer","minimum":0},"needs_partner_evidence":{"type":"integer","minimum":0}}},"collectionErrors":{"type":"array","items":{"type":"string"},"description":"Evidence sources that could not be read (`requests`, `deliveries`, `scenarios`, `submissions`). Cases that depend on them report `evidenceQuality: unknown` and are not passed. Usually empty; retry later."},"cases":{"type":"array","items":{"$ref":"#/components/schemas/SellerSandboxCertificationCase"},"description":"All 28 cases, in case-number order."},"notCovered":{"type":"array","description":"Areas of the Seller API the cases do not certify, so a full pass is not read as covering them. Rehearse these yourself; `reason` says how.","items":{"type":"object","required":["area","reason"],"properties":{"area":{"type":"string","enum":["promotions","finance_statements","key_management","allocation_requests","partner_access"],"description":"`promotions`: answering event shares and deals, and promotion events. `finance_statements`: invoices, statements and payouts. `key_management`: creating, rotating and revoking API keys and IP allowlists. `allocation_requests`: asking a vendor for more stock and handling the decision. `partner_access`: accepting or declining an access proposal."},"reason":{"type":"string"}}}}}},"SellerConsumerGeoAttestStatus":{"type":"object","description":"Where a buyer network confirmation stands. No buyer data.","required":["attestId","status","expiresAt","completedAt","consumedAt","consumedOrderReference"],"properties":{"attestId":{"type":"string","format":"uuid"},"status":{"type":"string","enum":["pending","completed","consumed","expired","store_server"],"description":"`pending`: the pixel has not loaded yet. `completed`: usable for a checkout. `consumed`: spent on an order (a retry of the same order may still use it). `expired`: past `expiresAt` without being spent. `store_server`: the pixel loaded from an address on the key's allowlist, so it was refused; mint a new one from the checkout page."},"expiresAt":{"type":"string","format":"date-time"},"completedAt":{"type":["string","null"],"format":"date-time","description":"When the pixel loaded."},"consumedAt":{"type":["string","null"],"format":"date-time","description":"When an order spent the confirmation."},"consumedOrderReference":{"type":["string","null"],"description":"Your `orderReference` of the order that spent it."}}},"SellerSandboxResetSummary":{"type":"object","description":"What `POST /sandbox/reset` did in your isolated environment.","required":["environment","resetAt","scenariosExpired","keysReleased","allocationRequestsCancelled","keysAdded","footprintRestored","rehearsal","missingFixtures"],"properties":{"environment":{"type":"object","required":["mode","environmentId"],"properties":{"mode":{"type":"string","enum":["isolated"]},"environmentId":{"type":"string","format":"uuid"}}},"resetAt":{"type":"string","format":"date-time"},"scenariosExpired":{"type":"integer","minimum":0,"description":"Open fault scenarios that were expired."},"keysReleased":{"type":"integer","minimum":0,"description":"Keys a `sold_out_after_hold` scenario held that are available again."},"allocationRequestsCancelled":{"type":"array","items":{"type":"string","format":"uuid"},"description":"Pending allocation requests that were cancelled."},"keysAdded":{"type":"integer","minimum":0,"description":"Keys added to fixture pools that were below their minimum."},"footprintRestored":{"type":"boolean","description":"True once the selling footprint is the sandbox default again."},"rehearsal":{"type":"object","required":["refundWindow","promotions","accessProposal"],"properties":{"refundWindow":{"type":"boolean","description":"The zero-day refund window on `SANDBOX-REFUND-EXPIRED-001` is in place."},"promotions":{"type":["object","null"],"description":"The promotion fixtures on `SANDBOX-PROMO-001`; null when they could not be prepared.","required":["shareId","shareRearmed","dealsCreated"],"properties":{"shareId":{"type":["string","null"],"format":"uuid","description":"The rehearsal event share (`shareId` on GET /promotions/shares)."},"shareRearmed":{"type":"boolean","description":"True when an answered share was made pending again."},"dealsCreated":{"type":"array","items":{"type":"string","enum":["live","upcoming","pending"]},"description":"Rehearsal deals that were missing and were created."}}},"accessProposal":{"type":"object","required":["proposalId","status"],"properties":{"proposalId":{"type":["string","null"],"format":"uuid"},"status":{"type":"string","enum":["created","already_pending","skipped","unavailable"],"description":"`created`: a new pending access proposal was offered. `already_pending`: an open proposal from the sandbox vendor already existed; `proposalId` is that one. `skipped`: the shared sandbox gets no proposal. `unavailable`: no proposal could be offered."}}}}},"missingFixtures":{"type":"array","items":{"type":"string"},"description":"Fixture codes your environment was provisioned without (it predates them). Avrix adds them when it next repairs the environment; ask support if you need them sooner."}}},"WebhookApiKeyExpiring":{"description":"An API key reaches its expiry within 14 days. Sent once per expiry, only for keys meant to live longer than 14 days, and never for a revoked key. Create a replacement key and move to it before `expiresAt`; a new expiry on the same key is announced again.","allOf":[{"$ref":"#/components/schemas/WebhookEnvelope"},{"type":"object","required":["eventType","keyId","expiresAt"],"properties":{"eventType":{"type":"string","const":"api_key.expiring"},"keyId":{"type":"string","format":"uuid","description":"The key's id, as `GET /keys` lists it. Never the secret."},"keyName":{"type":["string","null"],"description":"The key's name."},"environment":{"type":["string","null"],"enum":["production","sandbox",null],"description":"The key's environment."},"expiresAt":{"type":"string","format":"date-time","description":"The key's expiry."}}}]},"WebhookApiKeyExpired":{"description":"An API key reached its expiry and can no longer call the Seller API. Sent once, within the hour after `expiresAt`, and never for a key that was revoked first.","allOf":[{"$ref":"#/components/schemas/WebhookEnvelope"},{"type":"object","required":["eventType","keyId","expiresAt"],"properties":{"eventType":{"type":"string","const":"api_key.expired"},"keyId":{"type":"string","format":"uuid","description":"The key's id, as `GET /keys` lists it. Never the secret."},"keyName":{"type":["string","null"],"description":"The key's name."},"environment":{"type":["string","null"],"enum":["production","sandbox",null],"description":"The key's environment."},"expiresAt":{"type":"string","format":"date-time","description":"The key's expiry."}}}]},"OAuthTokenResponse":{"type":"object","description":"RFC 6749 section 5.1 access token response, plus `meta`.","required":["access_token","token_type","expires_in"],"additionalProperties":true,"properties":{"access_token":{"type":"string","description":"The Bearer token (`avrix_oat_*`). Send it as `Authorization: Bearer <token>`."},"token_type":{"type":"string","enum":["Bearer"]},"expires_in":{"type":"integer","description":"Seconds until the token expires (3600)."},"scope":{"type":"string","description":"The scopes the token carries, space-separated: exactly the API key's scopes."},"meta":{"type":"object","properties":{"requestId":{"type":"string"}}}}},"SellerProductionAccess":{"type":"object","description":"The steps between a production key and production calls, and where this company stands. On deployments that enforce approval, a production key is refused with `403 PRODUCTION_ACCESS_NOT_APPROVED` until `status` is `approved`, so read this with a sandbox key, or read `details.productionAccess` on that 403.","required":["status","enforced","requestedAt","approvedAt","steps"],"properties":{"status":{"type":"string","enum":["approved","requested","not_requested"],"description":"`requested`: a production call was refused for want of approval, which records the request; Avrix reviews it. `not_requested`: no production call has been made yet."},"enforced":{"type":"boolean","description":"Whether this deployment refuses production calls before approval. False on development and test deployments."},"requestedAt":{"type":["string","null"],"format":"date-time","description":"When the first refused production call recorded the request."},"approvedAt":{"type":["string","null"],"format":"date-time","description":"When production access was approved; null until then."},"steps":{"type":"array","description":"In order. `api_model_activated`: the API sales model is enabled for the company (required to create a production key). `production_key_created`: the company holds an active production key. `production_access_approved`: Avrix approved production calls.","items":{"type":"object","required":["step","done"],"properties":{"step":{"type":"string","enum":["api_model_activated","production_key_created","production_access_approved"],"description":"`api_model_activated`: the API sales model is enabled for the company. `production_key_created`: the company holds an active production key. `production_access_approved`: Avrix approved production calls."},"done":{"type":"boolean"}}}}}},"SellerAllocationRequest":{"type":"object","description":"An allocation request you filed, newest first in `GET /allocations/requests` (the 100 most recent). `state` is the one field to read for where it stands; `status` and `resolution` are kept for existing readers.","required":["id","publisherCompanyId","sellerCompanyId","allocationId","skuId","businessModel","allocationGrantId","requestedQuantity","declaredForecast","state","status","resolution","resolvedGrantDelta","resolvedBy","resolvedAt","decisionNote","createdAt","updatedAt"],"properties":{"id":{"type":"string","format":"uuid","description":"The request id (`requestId` on create and on the webhooks)."},"state":{"type":"string","enum":["pending","auto_granted","approved","denied","backordered","cancelled"],"description":"`pending`: waiting for the Content Owner. `auto_granted`: granted by the Content Owner's rules. `approved` / `denied`: decided by the Content Owner. `backordered`: accepted, to be granted when stock arrives. `cancelled`: withdrawn by your company before a decision."},"allocationId":{"type":["string","null"],"format":"uuid","description":"The allocation the request is for; the same value as `allocationGrantId`."},"allocationGrantId":{"type":["string","null"],"format":"uuid","description":"Older name of `allocationId`, kept for existing readers."},"skuId":{"type":"string","format":"uuid"},"skuCode":{"type":["string","null"]},"publisherCompanyId":{"type":"string","description":"The Content Owner's company id."},"sellerCompanyId":{"type":"string","format":"uuid","description":"Your company id."},"businessModel":{"type":"string","enum":["wholesale","api","revenue_share","pre_order"],"description":"Business model of the allocation the request is for."},"requestedQuantity":{"type":"integer","minimum":1},"declaredForecast":{"type":["integer","null"],"description":"The forecast sent with the request, if any."},"status":{"type":"string","enum":["pending","resolved","cancelled"],"description":"Older two-part form of `state`: `pending` (waiting for the Content Owner), `resolved` (decided; see `resolution`) or `cancelled` (withdrawn before a decision). New values may be added; treat an unknown one as not yet decided."},"resolution":{"type":["string","null"],"enum":["auto_granted","approved","denied","backordered",null],"description":"Set when `status` is `resolved`; null while `pending`. `auto_granted`: granted at once under the Content Owner's rules. `approved` / `denied`: decided by the Content Owner. `backordered`: accepted, to be filled when stock arrives."},"resolvedGrantDelta":{"type":["integer","null"],"description":"Keys added to the allocation by the decision; null until resolved."},"resolvedBy":{"type":["string","null"],"description":"Who decided: a Content Owner user id; null for automatic decisions and pending requests."},"resolvedAt":{"type":["string","null"],"format":"date-time"},"decisionNote":{"type":["string","null"],"description":"The Content Owner's note on the decision, if any."},"createdAt":{"type":"string","format":"date-time"},"updatedAt":{"type":"string","format":"date-time","description":"Last change: filed, decided, cancelled."}}},"SellerAllocationRequestCreated":{"type":"object","description":"The request as filed, and what happened to it at once.","required":["requestId","resolution","grantDelta","allocationId","state"],"properties":{"requestId":{"type":"string","format":"uuid","description":"Id of the new request. Read it with `GET /allocations/requests/{id}`."},"resolution":{"type":"string","enum":["pending_review","auto_granted","approved","denied","backordered"],"description":"`auto_granted`: the allocation grew at once (see `grantDelta`). `pending_review`: the Content Owner decides; listen for `allocation.request_decided`. The other values mirror `SellerAllocationRequest.resolution`. New values may be added."},"grantDelta":{"type":"integer","minimum":0,"description":"Keys added to the allocation now; 0 unless `resolution` is `auto_granted`."},"allocationId":{"type":"string","format":"uuid"},"state":{"type":"string","enum":["pending","auto_granted","approved","denied","backordered","cancelled"],"description":"The same value the list and the single read show (`pending` for `pending_review`)."}}},"SellerAvailability":{"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"},"heldQuantity":{"type":["integer","null"],"description":"Keys inside live checkout holds on this allocation right now. `null` when the hold ledger could not be read (then `sellableNow` equals `available`)."},"sellableNow":{"type":"integer","description":"`available` minus `heldQuantity`: what `POST /orders` can take right now. Gate checkout on this, not on `available`."},"maxFulfillableQuantity":{"type":"integer","description":"Same as `sellableNow`: min of allocation headroom and inventory, net of live checkout holds Net of live checkout holds (same as `sellableNow`) since 2026-09-22."},"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":"`POST /allocations/requests` accepts a request for more on this grant (any grant of yours that is not revoked; one without an automatic rule goes to the publisher for review)."},"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_NOT_GRANTED","TERRITORY_EXCLUDED_FOR_RELEASE","REGION_LOCKED_FOR_CONTRACT","REGION_LOCKED_FOR_SKU","SKU_REGION_UNRESOLVED","CATALOG_PRICE_NOT_SET","FOOTPRINT_COUNTRY_NOT_DECLARED","FOOTPRINT_CURRENCY_NOT_DECLARED","CURRENCY_NOT_PERMITTED_BY_TERM","CURRENCY_NOT_PRICED_FOR_COUNTRY","SRP_MISMATCH_FOR_CURRENCY",null],"description":"Why `sellableInCountry` is false; null when sellable. Present only when `country` was requested. When several checks refuse, the first in this order, the same order preview, hold, reserve and `POST /orders` name it in: selling footprint (country, then currency), the territory and then the currency your agreement or partner access grants, territory (restricted countries, region, release exclusions, SKU and contract region locks), catalog price, the priced currency. `SRP_MISMATCH_FOR_CURRENCY` is deprecated and no longer returned."},"price":{"type":["object","null"],"description":"Present only when `country` was requested (API-model allocations). The price a sale in that country charges, in its currency, with the platform price zone it belongs to; null when no price is set. Additive.","properties":{"priceCents":{"type":"integer","description":"Deprecated name of `priceMinor` (same value). Kept on the wire; see Naming conventions in the Versioning and compatibility guide. Minor units of `currencyCode`.","deprecated":true},"priceMinor":{"type":"integer","description":"Minor units of `currencyCode`. Same amount as `priceCents`, under the `...Minor` name every Seller API amount uses: integer minor units of the currency beside it (see `currencyExponent`)."},"currencyCode":{"type":"string"},"currencyExponent":{"type":"integer","minimum":0,"maximum":3,"description":"Number of minor-unit digits for `currencyCode`: 2 for USD, 0 for JPY, 3 for KWD. amount = cents / 10^currencyExponent. Additive."},"zone":{"oneOf":[{"$ref":"#/components/schemas/PriceZone"},{"type":"null"}]}},"required":["priceCents","priceMinor","currencyCode","currencyExponent","zone"]},"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."},"recommendedAction":{"type":["string","null"],"description":"`request_allocation_increase` once `allocationRemaining` is 0; null otherwise."}},"description":"Availability of one SKU on one of your allocations. `GET /availability/{skuCode}`, `GET /availability?skuCode=` and each row of the bulk form answer this shape. Gate checkout on `sellableNow`. Three pairs say the same thing and are kept for compatibility: `maxFulfillableQuantity` equals `sellableNow`, `allOrNothingWillFail` equals `cannotFullyFulfill`, and the deprecated `partialFulfillmentExpected` equals both."},"AllocationReplenishEffect":{"type":"object","description":"What your top-up trigger does under the Content Owner's rules when remaining falls to the threshold. It leaves out the time rule: a crossing sooner than `rules.minIntervalHours` after the last automatic top-up files a request instead.","required":["mode","quantity","limitedBy","reason"],"properties":{"mode":{"type":"string","enum":["automatic","request","off"],"description":"`automatic`: the allocation is topped up at once (`allocation.replenished`). `request`: an allocation request is filed for the Content Owner. `off`: nothing happens."},"quantity":{"type":["integer","null"],"description":"Keys a crossing adds (`automatic`) or asks for (`request`); null when `off`."},"limitedBy":{"type":["string","null"],"enum":["max_quantity","ceiling_cap",null],"description":"What made `quantity` smaller than the top-up you asked for."},"reason":{"type":["string","null"],"enum":["no_threshold","inactive","rules_off","ceiling_cap",null],"description":"Why `mode` is `off` (`no_threshold`, `inactive`: paused or revoked) or `request` (`rules_off`: the Content Owner has automatic top-ups off; `ceiling_cap`: the allocation is at their cap)."}}},"SellerCheckoutHold":{"type":"object","required":["type","holdId","checkoutHoldId","state","createdAt","expiresAt","expiresInSeconds","allocationId","skuId","skuCode","quantity","orderReference"],"properties":{"type":{"type":"string","enum":["checkout_hold"]},"holdId":{"type":"string","format":"uuid"},"checkoutHoldId":{"type":"string","format":"uuid","description":"Same value as `holdId`, under the name POST /orders takes it."},"state":{"type":"string","enum":["active"],"description":"A hold that is no longer live answers 404 `HOLD_NOT_FOUND` instead."},"createdAt":{"type":"string","format":"date-time"},"expiresAt":{"type":"string","format":"date-time","description":"When the hold ends unless it is consumed by POST /orders or released first."},"expiresInSeconds":{"type":"integer","minimum":0},"allocationId":{"type":"string","format":"uuid"},"skuId":{"type":"string","format":"uuid"},"skuCode":{"type":"string"},"quantity":{"type":"integer","minimum":1},"orderReference":{"type":"string"},"customerReference":{"type":["string","null"]},"unitPriceCents":{"type":"integer","description":"Deprecated name of `unitPriceMinor` (same value). Kept on the wire; see Naming conventions in the Versioning and compatibility guide. The unit price bound when the hold was created (API model only); POST /orders charges it while the hold is live. Echo it as `expectedUnitPriceCents`.","deprecated":true},"unitPriceMinor":{"type":"integer","description":"The unit price bound when the hold was created (API model only); POST /orders charges it while the hold is live. Echo it as `expectedUnitPriceCents`. Same amount as `unitPriceCents`, under the `...Minor` name every Seller API amount uses: integer minor units of the currency beside it (see `currencyExponent`)."},"currencyCode":{"type":["string","null"],"description":"Currency of `unitPriceCents`."},"currencyExponent":{"type":["integer","null"],"description":"Minor-unit digits of `currencyCode`."},"salesCountryCode":{"type":["string","null"],"description":"The country the price was bound for."},"priceBoundAt":{"type":["string","null"],"format":"date-time","description":"When the price was bound."}}},"WebhookAllocationRunningLow":{"description":"Remaining fell to or below the allocation's low-stock threshold: your `replenishThreshold` (PATCH /allocations/{id}) when you set one, otherwise 10% of `quantityLimit`, rounded down. Sent once per crossing; sent again only after remaining has risen above the threshold and fallen to it again.","allOf":[{"$ref":"#/components/schemas/WebhookEnvelope"},{"type":"object","required":["eventType","allocationId","remaining","threshold","thresholdSource","crossedAt"],"properties":{"eventType":{"type":"string","const":"allocation.running_low"},"allocationId":{"type":"string"},"skuId":{"type":["string","null"]},"publisherCompanyId":{"type":["string","null"]},"quantityLimit":{"type":["integer","null"]},"quantityPulled":{"type":["integer","null"]},"remaining":{"type":"integer","minimum":0},"threshold":{"type":"integer","minimum":0},"thresholdSource":{"type":"string","enum":["replenish_threshold","default_10_percent"],"description":"`replenish_threshold`: your threshold on the allocation. `default_10_percent`: none set, so 10% of `quantityLimit`."},"crossedAt":{"type":"string","format":"date-time"}}}]},"WebhookAllocationRequestCancelled":{"description":"A pending allocation request was withdrawn by your company (`POST /allocations/requests/{id}/cancel` or the console) before the Content Owner decided it.","allOf":[{"$ref":"#/components/schemas/WebhookEnvelope"},{"type":"object","required":["eventType","requestId","skuId","publisherCompanyId","requestedQuantity","cancelledAt"],"properties":{"eventType":{"type":"string","const":"allocation.request_cancelled"},"requestId":{"type":"string","description":"The request, as `POST /allocations/requests` returned it."},"skuId":{"type":"string"},"publisherCompanyId":{"type":"string","description":"The Content Owner's company id."},"allocationId":{"type":["string","null"]},"requestedQuantity":{"type":"integer"},"cancelledAt":{"type":"string","format":"date-time"}}}]},"RefundEligibilityKey":{"type":"object","required":["keyId","eligible","reason","keyStatus","businessModel","keyDisposition","soldAt","windowDays","refundableUntil","frozen","orderReference"],"properties":{"keyId":{"type":"string","format":"uuid"},"orderReference":{"type":["string","null"]},"eligible":{"type":"boolean"},"reason":{"type":["string","null"],"enum":["key_not_found","key_not_returnable","refund_window_expired",null],"description":"Why `eligible` is false; null when it is true. `key_not_found`: not a key you sold. `key_not_returnable`: its state does not allow a refund. `refund_window_expired`: past `refundableUntil` (refunds only)."},"keyStatus":{"type":["string","null"]},"businessModel":{"type":["string","null"]},"keyDisposition":{"type":["string","null"],"enum":["quarantined","held",null],"description":"What a refund would do to the key; null when it cannot be refunded."},"soldAt":{"type":["string","null"],"format":"date-time"},"windowDays":{"type":["integer","null"]},"refundableUntil":{"type":["string","null"],"format":"date-time","description":"End of the refund window; null when the Content Owner set none. Chargebacks ignore it."},"frozen":{"type":["object","null"],"description":"The open dispute freeze on the key, if any.","properties":{"freezeId":{"type":"string","format":"uuid"},"reason":{"type":"string"},"expiresAt":{"type":"string","format":"date-time"}}}}},"RefundPreview":{"type":"object","required":["type","orderReference","eligible","checkedAt","keys"],"properties":{"type":{"type":"string","enum":["refund","chargeback"],"description":"`refund`: you refunded the buyer. `chargeback`: the buyer's payment was charged back."},"orderReference":{"type":["string","null"]},"eligible":{"type":"boolean","description":"True when every key can be refunded (or charged back)."},"checkedAt":{"type":"string","format":"date-time"},"keys":{"type":"array","items":{"$ref":"#/components/schemas/RefundEligibilityKey"}}}},"SellerDispute":{"type":"object","required":["freezeId","status","resolution","reason","disputeReference","createdAt","expiresAt","endedAt","keyIds","orderReferences","keys"],"properties":{"freezeId":{"type":"string","format":"uuid"},"status":{"type":"string","enum":["active","released","converted","expired"],"description":"`active` until you release it (`released`), a refund or chargeback settles its keys (`converted`), or `expiresAt` passes (`expired`)."},"resolution":{"type":["string","null"],"enum":["released","refunded","chargeback","expired",null],"description":"How it ended; null while active."},"reason":{"type":"string","enum":["payment_dispute","fraud_review","chargeback_inquiry"],"description":"The `reason` you sent on `POST /disputes/freeze`. `payment_dispute`: the buyer disputes the payment. `fraud_review`: the order is under fraud review. `chargeback_inquiry`: a chargeback is being looked into."},"disputeReference":{"type":["string","null"]},"createdAt":{"type":"string","format":"date-time"},"expiresAt":{"type":"string","format":"date-time"},"endedAt":{"type":["string","null"],"format":"date-time"},"keyIds":{"type":"array","items":{"type":"string","format":"uuid"}},"orderReferences":{"type":"array","items":{"type":"string"}},"keys":{"type":"array","items":{"type":"object","required":["keyId","orderReference","active"],"properties":{"keyId":{"type":"string","format":"uuid"},"orderReference":{"type":"string"},"active":{"type":"boolean","description":"False once the freeze ended for this key."}}}}}},"SellerReturnRequest":{"type":"object","required":["returnRequestId","status","reasonCode","details","requestedResolution","resolution","publisherCompanyId","currencyCode","keyCount","decisionNote","decidedAt","respondBy","reversalStatus","createdAt","updatedAt"],"properties":{"returnRequestId":{"type":"string","format":"uuid","description":"The id `return.decided` and `return.information_requested` carry."},"status":{"type":"string","enum":["pending","info_requested","approved","rejected","cancelled","resolved"],"description":"`pending`: waiting on the Content Owner. `info_requested`: the Content Owner asked you a question; answer with `POST /returns/{returnRequestId}/reply`. `approved` / `resolved`: accepted (`resolution` says how). `rejected`. `cancelled`: you withdrew it."},"reasonCode":{"type":"string","enum":["key_invalid","key_already_redeemed","wrong_product","region_locked","description_mismatch","customer_refund","unused_keys"],"description":"Why the keys are returned. `key_invalid`: the key does not activate. `key_already_redeemed`: the key was already redeemed when the buyer tried it. `wrong_product`: the key is for a different product. `region_locked`: the key cannot be activated in the buyer's region. `description_mismatch`: the product is not as described. `customer_refund`: you refunded the buyer. `unused_keys`: keys you did not sell; always resolved as a refund."},"details":{"type":["string","null"]},"requestedResolution":{"type":"string","enum":["refund","replacement"],"description":"What you ask the Content Owner for. `refund`: the sale is refunded. `replacement`: a new key for each returned key."},"resolution":{"type":["string","null"],"enum":["refund","replacement",null],"description":"How an approved return is settled. `refund`: the sale is refunded. `replacement`: a new key for each returned key. Null when the request is not approved."},"publisherCompanyId":{"type":"string","description":"The Content Owner's company id."},"currencyCode":{"type":"string"},"keyCount":{"type":"integer"},"decisionNote":{"type":["string","null"]},"decidedAt":{"type":["string","null"],"format":"date-time"},"respondBy":{"type":["string","null"],"format":"date-time","description":"When the Content Owner is due to answer; null while waiting on you or once decided."},"reversalStatus":{"type":"string","description":"Progress of the money reversal of an approved refund: `not_required`, `pending`, `completed` or `failed`."},"createdAt":{"type":"string","format":"date-time"},"updatedAt":{"type":"string","format":"date-time"}}},"SellerReturnRequestDetail":{"allOf":[{"$ref":"#/components/schemas/SellerReturnRequest"},{"type":"object","required":["keys","messages","evidence"],"properties":{"keys":{"type":"array","items":{"type":"object","required":["keyId","open","replacementKeyId","unitPriceCents","unitPriceMinor"],"properties":{"keyId":{"type":"string","format":"uuid"},"open":{"type":"boolean"},"replacementKeyId":{"type":["string","null"],"format":"uuid","description":"The replacement key, once the Content Owner approved a replacement."},"unitPriceCents":{"type":["integer","null"],"description":"Deprecated name of `unitPriceMinor` (same value). Kept on the wire; see Naming conventions in the Versioning and compatibility guide.","deprecated":true},"unitPriceMinor":{"type":["integer","null"],"description":"Same amount as `unitPriceCents`, under the `...Minor` name every Seller API amount uses: integer minor units of the currency beside it (see `currencyExponent`)."}}}},"messages":{"type":"array","description":"The thread with the Content Owner, oldest first.","items":{"type":"object","required":["messageId","from","body","createdAt"],"properties":{"messageId":{"type":"string","format":"uuid"},"from":{"type":"string","enum":["content_owner","seller"],"description":"`content_owner`: written by the Content Owner. `seller`: written by your company."},"body":{"type":"string"},"createdAt":{"type":"string","format":"date-time"}}}},"evidence":{"type":"array","items":{"type":"object","required":["evidenceId","fileName","contentType","sizeBytes","createdAt"],"properties":{"evidenceId":{"type":"string","format":"uuid"},"fileName":{"type":"string"},"contentType":{"type":["string","null"]},"sizeBytes":{"type":["integer","null"]},"createdAt":{"type":"string","format":"date-time"}}}}}}]},"WebhookChargebackOpened":{"description":"A chargeback was declared on `POST /refunds` (`type: chargeback`). Report the outcome with `POST /chargebacks/resolve`.","allOf":[{"$ref":"#/components/schemas/WebhookEnvelope"},{"type":"object","required":["eventType","keyIds","refundIds","openedAt"],"properties":{"eventType":{"type":"string","const":"chargeback.opened"},"orderReference":{"type":["string","null"]},"orderReferences":{"type":"array","items":{"type":"string"}},"chargebackReference":{"type":["string","null"]},"keyIds":{"type":"array","items":{"type":"string","format":"uuid"}},"refundIds":{"type":"array","items":{"type":"string","format":"uuid"}},"keyDisposition":{"type":"string","enum":["quarantined","held","mixed"],"description":"What happened to the keys: `quarantined` (never sold again, headroom restored), `held` (revenue-share keys stay with you, no headroom change) or `mixed` (both)."},"saleTotals":{"type":"array","description":"Sale value of the refunded API-model keys per currency, in minor units. Keys sold under other business models have no sale record and add nothing.","items":{"type":"object","required":["currencyCode","salePriceCents","salePriceMinor"],"properties":{"currencyCode":{"type":"string"},"salePriceCents":{"type":"integer","description":"Deprecated name of `salePriceMinor` (same value). Kept on the wire; see Naming conventions in the Versioning and compatibility guide.","deprecated":true},"salePriceMinor":{"type":"integer","description":"Same amount as `salePriceCents`, under the `...Minor` name every Seller API amount uses: integer minor units of the currency beside it (see `currencyExponent`)."}}}},"chargebackOccurredAt":{"description":"When the chargeback happened, as you sent it in `occurredAt` on `POST /refunds`; null when you did not send it.","type":["string","null"],"format":"date-time"},"openedAt":{"type":"string","format":"date-time"}},"additionalProperties":true}]},"WebhookKeyReplacementRejected":{"description":"The Content Owner rejected a key replacement you requested with `POST /orders/{orderId}/keys/{keyId}/replace`. The original key stays delivered.","allOf":[{"$ref":"#/components/schemas/WebhookEnvelope"},{"type":"object","required":["eventType","replacementId","keyId","rejectedAt"],"properties":{"eventType":{"type":"string","const":"key.replacement_rejected"},"replacementId":{"type":"string","format":"uuid"},"orderId":{"type":["string","null"]},"orderReference":{"type":["string","null"]},"keyId":{"type":"string","format":"uuid","description":"The key you asked to replace."},"skuId":{"type":["string","null"]},"allocationId":{"type":["string","null"]},"reason":{"type":["string","null"],"description":"The reason you gave on the request."},"decisionNote":{"type":["string","null"],"description":"The Content Owner's note."},"rejectedAt":{"type":"string","format":"date-time"}},"additionalProperties":true}]},"SellerProductLookupMatch":{"type":"object","required":["productId","readableId","productName","productSlug","publisherCompanyId","skuId","skuCode","platformCode","reference"],"properties":{"productId":{"type":"string","format":"uuid"},"readableId":{"type":"string","description":"Prefixed product id (`prd_...`)."},"productName":{"type":"string"},"productSlug":{"type":"string"},"publisherCompanyId":{"type":"string"},"skuId":{"type":"string","format":"uuid"},"skuCode":{"type":"string"},"platformCode":{"type":["string","null"]},"reference":{"type":"object","required":["source","name","value"],"description":"The reference that matched, as `skus[].externalReferences` on product detail names it.","properties":{"source":{"type":"string","description":"`steam`, or the platform code in lower case."},"name":{"type":"string","enum":["appId","packageId","platformProductId"]},"value":{"type":"string"}}}}},"SellerProductLookupRow":{"type":"object","required":["externalReference","matches"],"properties":{"externalReference":{"type":"string","description":"The value as sent."},"matches":{"type":"array","description":"Every SKU shared with you that carries the value. Empty when none does.","items":{"$ref":"#/components/schemas/SellerProductLookupMatch"}}}}},"parameters":{"IdempotencyKey":{"name":"Idempotency-Key","in":"header","required":true,"schema":{"type":"string","minLength":1,"maxLength":64,"pattern":"^[a-zA-Z0-9_-]+$"},"description":"Client-generated key that makes this write safe to retry. **Format:** 1 to 64 characters from `A-Z`, `a-z`, `0-9`, `-` and `_` (a UUID fits). Send the same key and the same JSON body when you retry: a completed request is replayed for 24 hours with `Idempotency-Replayed: true`, and failed (4xx/5xx) responses are never stored, so a retry after fixing the cause runs again. The same key with a different body returns 409 `IDEMPOTENCY_KEY_MISMATCH`. A missing or malformed key returns 400 `IDEMPOTENCY_KEY_REQUIRED` on contract date `2026-12-01` and later (`BAD_REQUEST` on earlier dates)."},"IdempotencyKeyOptional":{"name":"Idempotency-Key","in":"header","required":false,"schema":{"type":"string","minLength":1,"maxLength":64,"pattern":"^[a-zA-Z0-9_-]+$"},"description":"Optional on this operation. When sent, it follows the same format and replay rules as the required header: 1 to 64 characters from `A-Z`, `a-z`, `0-9`, `-` and `_`; the same key and body replay the completed response for 24 hours with `Idempotency-Replayed: true`; the same key with a different body returns 409 `IDEMPOTENCY_KEY_MISMATCH`."},"AvrixApiVersion":{"name":"X-Avrix-Api-Version","in":"header","required":false,"schema":{"type":"string","enum":["2026-04-29","2026-09-01","2026-10-01","2026-12-01","next"]},"description":"Pins the contract date this request is served on, so a later default never changes what your integration sees. Omit it to be served on the stamped default (see the contract dates in the introduction). `next` resolves to the newest date, opt-in dates included: use it to try what is coming, not in production code. A value that is not in the list is refused with 400 `UNSUPPORTED_API_VERSION` and `details.supportedVersions`. The response header of the same name tells you which date served the request. See `https://docs.avrix.io/seller-api/versioning`.","example":"2026-12-01"},"RequestId":{"name":"X-Request-Id","in":"header","required":false,"schema":{"type":"string","minLength":1},"description":"Your own correlation id for this attempt: 8 to 128 characters from `A-Z`, `a-z`, `0-9`, `_`, `.`, `:` and `-` (a UUID or ULID fits). It comes back in the `X-Request-Id` response header and as `requestId` in error bodies, and `GET /requests/{requestId}` finds the request by it. Omit it and a UUID is generated. Send a new value for every attempt, retries included. On contract date `2026-12-01` and later a value outside that format is refused with `400 INVALID_REQUEST_ID` before anything runs; earlier dates echo any value as sent.","example":"0198c2f4-7b1e-8c3a-9d2f-5e6a7b8c9d01"},"SandboxSimulateRateLimit":{"name":"X-Avrix-Sandbox-Simulate","in":"header","required":false,"schema":{"type":"string","enum":["rate_limit"]},"description":"Sandbox keys only; a production key's header is ignored on every contract date. `rate_limit` makes this call answer 429 `RATE_LIMIT_EXCEEDED` with `Retry-After: 2` before any work is done, so you can rehearse your back-off. This operation honours no other value. On contract date `2026-12-01` or later (`X-Avrix-Api-Version: 2026-12-01` or `next`), a sandbox call with any other value, a misspelling included, answers 422 `SANDBOX_SIMULATE_UNKNOWN` before any work, and `details.honoured` lists the values this operation accepts. On earlier dates such a value is ignored and the call runs normally."},"SandboxSimulate":{"name":"X-Avrix-Sandbox-Simulate","in":"header","required":false,"schema":{"type":"string","enum":["rate_limit","webhook_delay_30s","hot_path_timeout","key_decrypt_failed","billing_record_failed","internal_error","service_unavailable","idempotency_in_flight","timeout_then_success","error_after_commit","partial_cart","sold_out_after_hold","webhook_delay_duplicate","buyer_verification_required"]},"description":"Sandbox keys only; a production key's header is ignored on every contract date. Makes this call fail or misbehave on purpose so you can rehearse your recovery. Each operation honours the values listed for it below. On contract date `2026-12-01` or later, a value this operation does not honour, a misspelling included, answers 422 `SANDBOX_SIMULATE_UNKNOWN` before any work, with `details.honoured` listing the values it accepts; on earlier dates such a value is ignored and the call runs normally, except that `POST /orders` answers 422 `SANDBOX_SCENARIO_UNAVAILABLE` for a scenario that belongs to another operation.\n\n**Faults returned before any work is done** (`POST /orders`, `POST /orders/bulk`, `POST /orders/commit`, `POST /keys/pull`): `rate_limit` (429, `Retry-After: 2`), `hot_path_timeout` (504 `HOT_PATH_TIMEOUT`), `key_decrypt_failed` (503 `KEY_DECRYPT_FAILED`), `billing_record_failed` (503 `BILLING_RECORD_FAILED`), `internal_error` (500), `service_unavailable` (503 `SERVICE_UNAVAILABLE`, `Retry-After: 5`), `idempotency_in_flight` (409 `IDEMPOTENCY_REQUEST_IN_FLIGHT`). `POST /orders/hold` and `POST /webhooks/{id}/test` honour `rate_limit`, `internal_error` and `service_unavailable` from this group (`rate_limit` only before contract date `2026-12-01`).\n\n**Delayed webhook** (`POST /orders`, `POST /webhooks/{id}/test`): `webhook_delay_30s` delivers the resulting webhook 30 seconds late.\n\n**Buyer verification**, contract date `2026-12-01` and later; ignored on earlier dates (`POST /orders`, `POST /orders/bulk`, `POST /orders/commit`, `POST /keys/pull`, `POST /orders/hold`, `POST /orders/preview`, `POST /orders/reserve`): `buyer_verification_required` makes this one call behave as if the vendor required buyer network confirmation, so it answers 422 `CONSUMER_GEO_ATTEST_REQUIRED` until you send a completed `consumerGeoAttestId` (mint one with `POST /geo/attest`, read it back with `GET /geo/attest/{attestId}`).\n\n**Stateful scenarios**, which run only in your store's isolated sandbox environment and answer 422 `SANDBOX_SCENARIO_UNAVAILABLE` on the shared sandbox: `timeout_then_success`, `error_after_commit` and `webhook_delay_duplicate` on `POST /orders`; `partial_cart` on `POST /orders/bulk`; `sold_out_after_hold` on `POST /orders/hold`. See `https://docs.avrix.io/seller-api/sandbox`."},"SandboxSimulateWrite":{"name":"X-Avrix-Sandbox-Simulate","in":"header","required":false,"schema":{"type":"string","enum":["rate_limit","internal_error","service_unavailable"],"description":"`rate_limit`: 429 `RATE_LIMIT_EXCEEDED`. `internal_error`: 500 `INTERNAL_ERROR`. `service_unavailable`: 503 `SERVICE_UNAVAILABLE`."},"description":"Sandbox keys only; a production key's header is ignored on every contract date. Makes this call fail on purpose, before any work is done, so you can rehearse your retry logic: `rate_limit` (429 `RATE_LIMIT_EXCEEDED`, `Retry-After: 2`), `internal_error` (500 `INTERNAL_ERROR`), `service_unavailable` (503 `SERVICE_UNAVAILABLE`, `Retry-After: 5`). Retry with the same `Idempotency-Key` where the operation takes one. On contract date `2026-12-01` or later (`X-Avrix-Api-Version: 2026-12-01` or `next`), a sandbox call with any other value, a misspelling included, answers 422 `SANDBOX_SIMULATE_UNKNOWN` before any work, and `details.honoured` lists the values this operation accepts. On earlier dates such a value is ignored and the call runs normally; so are `internal_error` and `service_unavailable`, and on `POST /orders/cancel`, `POST /orders/recover-keys`, `POST /keys/export`, `POST /keys/return`, `POST /refunds` and `POST /chargebacks/resolve` every value, as before."},"SandboxSimulateCheckout":{"name":"X-Avrix-Sandbox-Simulate","in":"header","required":false,"schema":{"type":"string","enum":["rate_limit","internal_error","service_unavailable","buyer_verification_required"],"description":"`rate_limit`: 429 `RATE_LIMIT_EXCEEDED`. `internal_error`: 500 `INTERNAL_ERROR`. `service_unavailable`: 503 `SERVICE_UNAVAILABLE`. `buyer_verification_required`: 422 `CONSUMER_GEO_ATTEST_REQUIRED` until you send a completed `consumerGeoAttestId`."},"description":"Sandbox keys only; a production key's header is ignored on every contract date. `rate_limit` (429 `RATE_LIMIT_EXCEEDED`, `Retry-After: 2`), `internal_error` (500 `INTERNAL_ERROR`) and `service_unavailable` (503 `SERVICE_UNAVAILABLE`, `Retry-After: 5`) make this call fail before any work is done. `buyer_verification_required` makes this one call behave as if the vendor required buyer network confirmation, so it answers 422 `CONSUMER_GEO_ATTEST_REQUIRED` until you send a completed `consumerGeoAttestId` (mint one with `POST /geo/attest`, read it back with `GET /geo/attest/{attestId}`). On contract date `2026-12-01` or later (`X-Avrix-Api-Version: 2026-12-01` or `next`), a sandbox call with any other value, a misspelling included, answers 422 `SANDBOX_SIMULATE_UNKNOWN` before any work, and `details.honoured` lists the values this operation accepts. On earlier dates such a value is ignored and the call runs normally, and only `rate_limit` is honoured, as before."},"IfNoneMatch":{"name":"If-None-Match","in":"header","required":false,"schema":{"type":"string"},"description":"Conditional GET: send the `ETag` of your stored copy. While nothing has changed the answer is `304 Not Modified` with no body."},"WebhookSignature":{"name":"X-Avrix-Signature","in":"header","required":true,"schema":{"type":"string","pattern":"^t=\\d+(,v1=[0-9a-f]{64})+$"},"description":"HMAC-SHA256 signature: `t=<unix seconds>,v1=<hex>`, computed over `<t>.<raw body>` with the endpoint secret. During a secret rotation a second `v1=` signed with the previous secret follows. Verify it, and reject a `t` more than five minutes old, before you process the body.","example":"t=1798761600,v1=5257a869e7ecebeda32affa62cdca3fa51cad7e77a0e56ff536d0ce8e108d8bd"},"WebhookSignatureVersion":{"name":"X-Avrix-Signature-Version","in":"header","required":true,"schema":{"type":"string","const":"1"},"description":"Signature scheme version. Always `1` today.","example":"1"},"WebhookEventId":{"name":"X-Avrix-Event-Id","in":"header","required":true,"schema":{"type":"string"},"description":"Id of this delivery; equal to `eventId` in the body. A replay or another endpoint gets another value."},"WebhookEventLogId":{"name":"X-Avrix-Event-Log-Id","in":"header","required":false,"schema":{"type":"string"},"description":"The event's own id; equal to `eventLogId` in the body and the same on every endpoint, retry and replay. Deduplicate on it. Absent on test deliveries and on deliveries older than the event log."},"WebhookEventType":{"name":"X-Avrix-Event-Type","in":"header","required":true,"schema":{"type":"string"},"description":"Event name; equal to `eventType` in the body.","example":"order.fulfilled"},"WebhookEventVersion":{"name":"X-Avrix-Event-Version","in":"header","required":true,"schema":{"type":"string","const":"1"},"description":"Payload schema version; equal to `eventVersion` in the body.","example":"1"},"WebhookDeliveryId":{"name":"X-Avrix-Delivery-Id","in":"header","required":true,"schema":{"type":"string","format":"uuid"},"description":"Id of the delivery row, as `GET /webhooks/{id}/deliveries` lists it and the retry call takes it.","example":"0b6f6d1e-2f5a-4c8e-9a51-7d3c2e1f0a9b"}}},"externalDocs":{"description":"Seller API guides","url":"https://docs.avrix.io/guides/getting-started"},"tags":[{"name":"Seller auth","description":"Credentials: the OAuth token exchange and Seller API key management (create, list, rotate, revoke, IP allowlist)."},{"name":"Seller meta","description":"Your account and integration: identity (`whoami`), health, selling footprint, integration presets, buyer network confirmation, usage, activity, and request lookup."},{"name":"Catalog","description":"Products, pricing, snapshots, changes and exports: what your connected Content Owners share with you."},{"name":"Reference data","description":"Lookup lists that change rarely: regions and platforms, with the codes other operations accept."},{"name":"Partners","description":"Your connected Content Owners, their offers, and the access proposals they send you."},{"name":"Allocations","description":"Stock you can sell: allocations, allocation requests, automatic top-ups, and availability."},{"name":"Orders","description":"Preview, hold, reserve and commit, create, bulk, cancel, fulfil, key recovery and replacement, and key pull history."},{"name":"Keys","description":"Direct game-key pull and export. API credentials are under Seller auth; key returns are under Refunds."},{"name":"Refunds","description":"Refunds, chargebacks, key returns, and dispute freezes."},{"name":"Webhooks","description":"Endpoint registration, deliveries, replay, the event feed, and webhook egress identity."},{"name":"Finance","description":"Summaries, statements, the ledger, API sales, and invoices."},{"name":"Promotions","description":"Promotion shares, discounts, the calendar, and deal responses."},{"name":"Sandbox","description":"Sandbox-only tools: the automatic certification report."}],"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"},"example":{"eventId":"0aec7f49-d9dc-4a01-8e85-9c6db9c9ebbc","eventLogId":"4f8e6588-4cc3-4e18-89dd-54967a49f800","eventType":"test.ping","eventVersion":"1","occurredAt":"2026-11-02T09:30:00Z","replay":{"sourceDeliveryId":"ced314e9-ec50-4bce-8588-4ee6172e0664","originalEventId":"b0d9ba46-f2af-483e-8332-34af1f496865"},"testEvent":{"testRunId":"eb3ec896-61f6-4db1-8e33-3301c5ece13c","challenge":"valid"},"test":true,"sentAt":"2026-11-02T09:30:00Z","endpointId":"bfd4a39d-9b76-4547-8422-649649885837"}}}},"responses":{"200":{"description":"Acknowledge receipt. Return 2xx quickly; process asynchronously."}},"parameters":[{"$ref":"#/components/parameters/WebhookSignature"},{"$ref":"#/components/parameters/WebhookSignatureVersion"},{"$ref":"#/components/parameters/WebhookEventId"},{"$ref":"#/components/parameters/WebhookEventLogId"},{"$ref":"#/components/parameters/WebhookEventType"},{"$ref":"#/components/parameters/WebhookEventVersion"},{"$ref":"#/components/parameters/WebhookDeliveryId"}]}},"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"},"example":{"eventId":"f12418ac-b549-442c-8177-2f8b6d60f3f6","eventLogId":"42a822ea-966e-412d-87a4-5d133a4cd2e6","eventType":"order.fulfilled","eventVersion":"1","occurredAt":"2026-11-02T09:30:00Z","replay":{"sourceDeliveryId":"c99618f2-b687-4159-84b6-e975e25b4952","originalEventId":"1cebe6a9-abbd-414f-86b9-a1b43a5a0925"},"testEvent":{"testRunId":"226b1050-8ec9-48ee-8cb1-2eb458e7f81b","challenge":"valid"},"orderReference":"store-order-10432","skuId":"c2766efd-f871-4ba8-8140-f4071e029502","skuCode":"EXAMPLE-STEAM-WW","quantity":12,"fulfilledAt":"2026-11-02T09:30:00Z","deliveryMode":"key","keyIds":["0eaf0455-ca4a-47e8-8451-55351d2e9de1"],"delivery":{"items":[{"fulfillmentId":"ac2cf597-1327-464f-8495-056012cabf84","keyId":"01618f4c-5c5c-4491-8981-716e51a35cc5","redemptionUrl":"https://api.avrix.io/api/seller/v1/example","expiresAt":"2026-11-02T09:30:00Z"}],"provider":"hosted_redemption","redemptionUrl":"https://api.avrix.io/api/seller/v1/example","providerRef":null,"fulfillmentId":"4537ef92-65a5-4c58-8277-298012b99fbb","expiresAt":"2026-11-02T09:30:00Z"},"pulled":12,"allocationId":"ce104fe3-caa3-4b3b-86a1-9e55b6e239b0","orderId":"ord_sv3eksj6","deferredReveal":true,"integrationOrderContextRedacted":{"schemaVersion":1,"salesCountryCode":"DE","currencyCode":"EUR","currencyExponent":2,"salesPriceGrossMinor":2450,"salesPriceNetMinor":2450,"appliedDiscountPercentage":20,"appliedDiscountAmountMinor":2450,"buyerLocale":"de-DE","priceIncludesTax":true,"salesTaxAmountMinor":2450,"salesTaxRatePercent":20,"purchaseOrderNumber":"PO-10432","customerType":"b2c","paymentMethodFamily":"card","salesChannel":"web","checkoutSessionId":"cs_10432","lineIndex":1,"parentOrderReference":"store-order-10432","externalMarketplaceOrderId":"e01401e3-dd22-4d8a-88cc-31497628cec7"},"contractTermId":"602633fa-2b91-4108-8e2c-04cdbfe97438","contractTermVersion":1,"materialHash":"9f86d081884c7d659a2feaa0c55ad015a3bf4f1b2b0b822cd15d6c15b0f00a08"}}}},"responses":{"200":{"description":"Acknowledge receipt. Return 2xx quickly; process asynchronously."}},"parameters":[{"$ref":"#/components/parameters/WebhookSignature"},{"$ref":"#/components/parameters/WebhookSignatureVersion"},{"$ref":"#/components/parameters/WebhookEventId"},{"$ref":"#/components/parameters/WebhookEventLogId"},{"$ref":"#/components/parameters/WebhookEventType"},{"$ref":"#/components/parameters/WebhookEventVersion"},{"$ref":"#/components/parameters/WebhookDeliveryId"}]}},"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"},"example":{"eventId":"d9cdf9a0-0621-4794-89f5-f628171147e8","eventLogId":"c85be9f0-bd61-412c-81bf-9b199532bd61","eventType":"order.failed","eventVersion":"1","occurredAt":"2026-11-02T09:30:00Z","replay":{"sourceDeliveryId":"69e8ca1f-ba97-4107-8940-851c68d471e3","originalEventId":"a82771e5-a738-42a7-8ef8-af1c1d9650f0"},"testEvent":{"testRunId":"074bec5c-5a7d-48fb-89bc-72e54dddb5b7","challenge":"valid"},"orderReference":"store-order-10432","allocationId":"c040d145-e9e5-4cbb-8024-0d468f7ebaaf","reason":"preorder_fulfillment_decrypt_failed"}}}},"responses":{"200":{"description":"Acknowledge receipt. Return 2xx quickly; process asynchronously."}},"parameters":[{"$ref":"#/components/parameters/WebhookSignature"},{"$ref":"#/components/parameters/WebhookSignatureVersion"},{"$ref":"#/components/parameters/WebhookEventId"},{"$ref":"#/components/parameters/WebhookEventLogId"},{"$ref":"#/components/parameters/WebhookEventType"},{"$ref":"#/components/parameters/WebhookEventVersion"},{"$ref":"#/components/parameters/WebhookDeliveryId"}]}},"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"},"example":{"eventId":"edc83834-d7b8-404b-8ce3-2af6fd4fadcb","eventLogId":"f1d080ac-32d3-4f77-8896-9b7550554414","eventType":"order.activated","eventVersion":"1","occurredAt":"2026-11-02T09:30:00Z","replay":{"sourceDeliveryId":"4fa59697-c881-4cdc-82e2-5b00fa5d48ea","originalEventId":"52035f70-07db-4f90-82a1-f66378e2817a"},"testEvent":{"testRunId":"8180f9fa-1bba-4b8d-87e4-3281420133ab","challenge":"valid"},"orderReference":"store-order-10432","fulfillmentId":"7c0c11e0-67ee-4520-8da4-b68597934c7a","provider":"hosted_redemption","method":"buyer_reveal","platformCode":"steam","integrationOrderContextRedacted":{"schemaVersion":1,"salesCountryCode":"DE","currencyCode":"EUR","currencyExponent":2,"salesPriceGrossMinor":2450,"salesPriceNetMinor":2450,"appliedDiscountPercentage":20,"appliedDiscountAmountMinor":2450,"buyerLocale":"de-DE","priceIncludesTax":true,"salesTaxAmountMinor":2450,"salesTaxRatePercent":20,"purchaseOrderNumber":"PO-10432","customerType":"b2c","paymentMethodFamily":"card","salesChannel":"web","checkoutSessionId":"cs_10432","lineIndex":1,"parentOrderReference":"store-order-10432","externalMarketplaceOrderId":"e4012925-60b5-4a9c-8a30-63cfba626d23"}}}}},"responses":{"200":{"description":"Acknowledge receipt. Return 2xx quickly; process asynchronously."}},"parameters":[{"$ref":"#/components/parameters/WebhookSignature"},{"$ref":"#/components/parameters/WebhookSignatureVersion"},{"$ref":"#/components/parameters/WebhookEventId"},{"$ref":"#/components/parameters/WebhookEventLogId"},{"$ref":"#/components/parameters/WebhookEventType"},{"$ref":"#/components/parameters/WebhookEventVersion"},{"$ref":"#/components/parameters/WebhookDeliveryId"}]}},"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"},"example":{"eventId":"2e67573b-b74f-4a8f-885a-be5f58c84c06","eventLogId":"2cf6c88e-de21-4d9e-8aa4-1c003e481b09","eventType":"order.reserved","eventVersion":"1","occurredAt":"2026-11-02T09:30:00Z","replay":{"sourceDeliveryId":"42445e21-44ed-443d-8c19-ef308469cc31","originalEventId":"c70f46a1-e328-4bc2-8d1a-89f6fac8bf87"},"testEvent":{"testRunId":"b746afdd-7ca7-4b98-8f1d-44ca43ac20b9","challenge":"valid"},"orderReference":"store-order-10432","reserved":1,"allocationId":"a4265dc7-34c5-4ac3-814b-fbcd1a61c0dc","skuId":"9064f07f-3e9d-40b5-805f-7e1490abdf92","releaseDate":"2026-11-02T09:30:00Z","status":"awaiting_stock","backorderExpiresAt":"2026-11-02T09:30:00Z","integrationOrderContextRedacted":{"schemaVersion":1,"salesCountryCode":"DE","currencyCode":"EUR","currencyExponent":2,"salesPriceGrossMinor":2450,"salesPriceNetMinor":2450,"appliedDiscountPercentage":20,"appliedDiscountAmountMinor":2450,"buyerLocale":"de-DE","priceIncludesTax":true,"salesTaxAmountMinor":2450,"salesTaxRatePercent":20,"purchaseOrderNumber":"PO-10432","customerType":"b2c","paymentMethodFamily":"card","salesChannel":"web","checkoutSessionId":"cs_10432","lineIndex":1,"parentOrderReference":"store-order-10432","externalMarketplaceOrderId":"3b41eb69-1a4a-40e9-8c59-05ef4149d3cb"}}}}},"responses":{"200":{"description":"Acknowledge receipt. Return 2xx quickly; process asynchronously."}},"parameters":[{"$ref":"#/components/parameters/WebhookSignature"},{"$ref":"#/components/parameters/WebhookSignatureVersion"},{"$ref":"#/components/parameters/WebhookEventId"},{"$ref":"#/components/parameters/WebhookEventLogId"},{"$ref":"#/components/parameters/WebhookEventType"},{"$ref":"#/components/parameters/WebhookEventVersion"},{"$ref":"#/components/parameters/WebhookDeliveryId"}]}},"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"},"example":{"eventId":"6dc62e06-33af-4b2c-8b92-28034d39adaf","eventLogId":"18a12e07-0af9-437a-89df-ed3638f7299f","eventType":"order.preorder_fulfilled","eventVersion":"1","occurredAt":"2026-11-02T09:30:00Z","replay":{"sourceDeliveryId":"8f49c2ae-6f92-42de-8ee9-6d8d30af0541","originalEventId":"5fd319b4-ccb4-44d0-8c5c-d82a7b03b580"},"testEvent":{"testRunId":"57437027-a7b8-40ec-896f-c9ddfab90b94","challenge":"valid"},"orderReference":"store-order-10432","pulled":12,"allocationId":"e5cb35f1-ae0c-4137-8179-432757bcb4fb","skuId":"1114d63f-842f-4222-88cb-51a26bf66e4e","orderId":"ord_shjk8xq5","orderReadableId":"ord_9tmhcept"}}}},"responses":{"200":{"description":"Acknowledge receipt. Return 2xx quickly; process asynchronously."}},"parameters":[{"$ref":"#/components/parameters/WebhookSignature"},{"$ref":"#/components/parameters/WebhookSignatureVersion"},{"$ref":"#/components/parameters/WebhookEventId"},{"$ref":"#/components/parameters/WebhookEventLogId"},{"$ref":"#/components/parameters/WebhookEventType"},{"$ref":"#/components/parameters/WebhookEventVersion"},{"$ref":"#/components/parameters/WebhookDeliveryId"}]}},"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"},"example":{"eventId":"fed3f791-2b66-482f-8929-41d2174ac4d1","eventLogId":"a01b0ec8-1e55-4f14-8213-980c2afb315a","eventType":"order.returned","eventVersion":"1","occurredAt":"2026-11-02T09:30:00Z","replay":{"sourceDeliveryId":"49680dfa-2beb-4e35-822d-aa1233b4d5b9","originalEventId":"ed539611-13d8-4412-8a1e-9ecb2474b2e0"},"testEvent":{"testRunId":"a8d8ad0a-ddef-4517-8f57-1cdffe489bc0","challenge":"valid"},"orderReference":"store-order-10432","orderId":"ord_7x8g28re","cancelled":1}}}},"responses":{"200":{"description":"Acknowledge receipt. Return 2xx quickly; process asynchronously."}},"parameters":[{"$ref":"#/components/parameters/WebhookSignature"},{"$ref":"#/components/parameters/WebhookSignatureVersion"},{"$ref":"#/components/parameters/WebhookEventId"},{"$ref":"#/components/parameters/WebhookEventLogId"},{"$ref":"#/components/parameters/WebhookEventType"},{"$ref":"#/components/parameters/WebhookEventVersion"},{"$ref":"#/components/parameters/WebhookDeliveryId"}]}},"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"},"example":{"eventId":"b08bfa04-038f-441f-842a-774267cbc7cb","eventLogId":"af2ced49-d7c5-4d30-81d6-e3bf7f6ab992","eventType":"order.keys_returned","eventVersion":"1","occurredAt":"2026-11-02T09:30:00Z","replay":{"sourceDeliveryId":"c1bf07de-c81c-4eac-83fb-c7d462321b88","originalEventId":"9aa32350-210b-4e5b-8438-437aa5862d02"},"testEvent":{"testRunId":"a91ac572-1f92-42a1-8d03-b467546b7ff2","challenge":"valid"},"orderReference":"store-order-10432","orderReferences":["store-order-10432"],"keyIds":["b3b12e93-7a3e-43d3-8ade-fc5845cf10e8"],"returned":1}}}},"responses":{"200":{"description":"Acknowledge receipt. Return 2xx quickly; process asynchronously."}},"parameters":[{"$ref":"#/components/parameters/WebhookSignature"},{"$ref":"#/components/parameters/WebhookSignatureVersion"},{"$ref":"#/components/parameters/WebhookEventId"},{"$ref":"#/components/parameters/WebhookEventLogId"},{"$ref":"#/components/parameters/WebhookEventType"},{"$ref":"#/components/parameters/WebhookEventVersion"},{"$ref":"#/components/parameters/WebhookDeliveryId"}]}},"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"},"example":{"eventId":"eb91dc77-5422-48a4-81d2-c2208f236716","eventLogId":"782db7c3-b04a-43d0-824d-ddf4c358feba","eventType":"refund.completed","eventVersion":"1","occurredAt":"2026-11-02T09:30:00Z","replay":{"sourceDeliveryId":"97502d0e-ad36-49c5-8be5-777d4f7da089","originalEventId":"4017445b-be43-4cfe-8d8a-0c7b4777bc1f"},"testEvent":{"testRunId":"5d5c2da7-1f8a-42f9-8001-9b1870c79be4","challenge":"valid"},"orderReference":"store-order-10432","orderReferences":["store-order-10432"],"returned":1,"keyIds":["6e352043-dbab-48bc-8d93-6f705e315bd3"],"adjustmentType":"refund","returnRequestId":"e4de19b6-97d2-436b-8cdf-501e51ccd47e","transferId":"cf9eee81-3139-4c02-8416-e065fb407f8c"}}}},"responses":{"200":{"description":"Acknowledge receipt. Return 2xx quickly; process asynchronously."}},"parameters":[{"$ref":"#/components/parameters/WebhookSignature"},{"$ref":"#/components/parameters/WebhookSignatureVersion"},{"$ref":"#/components/parameters/WebhookEventId"},{"$ref":"#/components/parameters/WebhookEventLogId"},{"$ref":"#/components/parameters/WebhookEventType"},{"$ref":"#/components/parameters/WebhookEventVersion"},{"$ref":"#/components/parameters/WebhookDeliveryId"}]}},"chargeback_opened":{"post":{"operationId":"webhook_chargeback_opened","summary":"chargeback.opened","description":"Avrix delivers `chargeback.opened` 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/WebhookChargebackOpened"},"example":{"eventId":"23ed1867-a691-4dd9-81e2-57c677596002","eventLogId":"a8e916bd-827a-4d18-876b-7f54112f64a1","eventType":"chargeback.opened","eventVersion":"1","occurredAt":"2026-11-02T09:30:00Z","replay":{"sourceDeliveryId":"73bc9b5c-bf92-4da4-857c-6dc9bed4ce41","originalEventId":"1dd2a6af-04d1-4cf5-8271-e1a248d5fe4f"},"testEvent":{"testRunId":"77dfb0f3-9cc3-438a-81ab-b20f8f5d44bd","challenge":"valid"},"orderReference":"store-order-10432","orderReferences":["store-order-10432"],"chargebackReference":"chbk_10432","keyIds":["3b3860fb-d1e5-4956-89cc-537d2d2c954a"],"refundIds":["bd8904ae-09b8-42b9-8499-861a46068833"],"keyDisposition":"quarantined","saleTotals":[{"currencyCode":"EUR","salePriceCents":2450,"salePriceMinor":2450}],"chargebackOccurredAt":"2026-11-02T09:30:00Z","openedAt":"2026-11-02T09:30:00Z"}}}},"responses":{"200":{"description":"Acknowledge receipt. Return 2xx quickly; process asynchronously."}},"parameters":[{"$ref":"#/components/parameters/WebhookSignature"},{"$ref":"#/components/parameters/WebhookSignatureVersion"},{"$ref":"#/components/parameters/WebhookEventId"},{"$ref":"#/components/parameters/WebhookEventLogId"},{"$ref":"#/components/parameters/WebhookEventType"},{"$ref":"#/components/parameters/WebhookEventVersion"},{"$ref":"#/components/parameters/WebhookDeliveryId"}]}},"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"},"example":{"eventId":"1c6a06a8-1034-4e4e-87d3-483064b5cad5","eventLogId":"85ae765c-8e64-43cf-8fda-53daf0e7d5cc","eventType":"chargeback.resolved","eventVersion":"1","occurredAt":"2026-11-02T09:30:00Z","replay":{"sourceDeliveryId":"36549c0b-a3d4-4849-82ce-e28d20d5386e","originalEventId":"b4621de0-d483-49ff-8c84-060cd917f98e"},"testEvent":{"testRunId":"7855dea4-daf7-4386-8a75-0e878c761ce4","challenge":"valid"},"chargebackReference":"chbk_10432","outcome":"won","resolved":1}}}},"responses":{"200":{"description":"Acknowledge receipt. Return 2xx quickly; process asynchronously."}},"parameters":[{"$ref":"#/components/parameters/WebhookSignature"},{"$ref":"#/components/parameters/WebhookSignatureVersion"},{"$ref":"#/components/parameters/WebhookEventId"},{"$ref":"#/components/parameters/WebhookEventLogId"},{"$ref":"#/components/parameters/WebhookEventType"},{"$ref":"#/components/parameters/WebhookEventVersion"},{"$ref":"#/components/parameters/WebhookDeliveryId"}]}},"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"},"example":{"eventId":"258e4d98-b71f-4b19-8a87-afe28eb18b60","eventLogId":"7cc3c493-1576-4d32-8caf-6dc175a86d80","eventType":"keys.pulled","eventVersion":"1","occurredAt":"2026-11-02T09:30:00Z","replay":{"sourceDeliveryId":"da3d239d-3632-43b7-8ace-725862440b89","originalEventId":"79749820-ace6-4495-88bc-808a92b3b3ab"},"testEvent":{"testRunId":"87cda882-32a9-4db5-8d29-1cc553ecf77d","challenge":"valid"},"pulled":12,"allocationId":"4dc3c540-7e71-4e2d-8b4e-b5b664376ba5","deferredReveal":true,"orderReadableId":"ord_6hgv2trv","contractTermId":"f5a1d471-abdf-453c-8611-43dcbbcb6566","contractTermVersion":1}}}},"responses":{"200":{"description":"Acknowledge receipt. Return 2xx quickly; process asynchronously."}},"parameters":[{"$ref":"#/components/parameters/WebhookSignature"},{"$ref":"#/components/parameters/WebhookSignatureVersion"},{"$ref":"#/components/parameters/WebhookEventId"},{"$ref":"#/components/parameters/WebhookEventLogId"},{"$ref":"#/components/parameters/WebhookEventType"},{"$ref":"#/components/parameters/WebhookEventVersion"},{"$ref":"#/components/parameters/WebhookDeliveryId"}]}},"key_replaced":{"post":{"operationId":"webhook_key_replaced","summary":"key.replaced","description":"Avrix delivers `key.replaced` 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/WebhookKeyReplaced"},"example":{"eventId":"96334862-aa6d-4668-8ff5-6aa41fbdf09d","eventLogId":"854e7752-d8d0-4bf7-8113-f3bf16f9822f","eventType":"key.replaced","eventVersion":"1","occurredAt":"2026-11-02T09:30:00Z","replay":{"sourceDeliveryId":"621cf035-4478-41c7-8b6a-cbafd96f7878","originalEventId":"09f1a102-9e74-4d4a-8b3b-8b98f2993e2b"},"testEvent":{"testRunId":"e177bb65-059a-4298-8d7c-5cf805db8890","challenge":"valid"},"replacementId":"d17badbe-5110-4b56-811b-4b820b276379","orderId":"ord_xmu2r53p","orderReference":"store-order-10432","replacedKeyId":"817ea40d-e2e6-4d2e-898b-68749ab459e8","keyId":"5c44f147-feb4-4da7-86db-e68363617c38","skuId":"21428e12-64ff-4c7f-8206-f24eba74c21e","allocationId":"415011fb-0ec6-49c0-86d0-2f7addaca0b6","reason":"already_redeemed","approval":"auto","replacedAt":"2026-11-02T09:30:00Z"}}}},"responses":{"200":{"description":"Acknowledge receipt. Return 2xx quickly; process asynchronously."}},"parameters":[{"$ref":"#/components/parameters/WebhookSignature"},{"$ref":"#/components/parameters/WebhookSignatureVersion"},{"$ref":"#/components/parameters/WebhookEventId"},{"$ref":"#/components/parameters/WebhookEventLogId"},{"$ref":"#/components/parameters/WebhookEventType"},{"$ref":"#/components/parameters/WebhookEventVersion"},{"$ref":"#/components/parameters/WebhookDeliveryId"}]}},"key_replacement_rejected":{"post":{"operationId":"webhook_key_replacement_rejected","summary":"key.replacement_rejected","description":"Avrix delivers `key.replacement_rejected` 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/WebhookKeyReplacementRejected"},"example":{"eventId":"31544353-316e-4be0-82e8-34b82e4b200e","eventLogId":"9f176e3d-a0d9-400b-8927-75db0d40d186","eventType":"key.replacement_rejected","eventVersion":"1","occurredAt":"2026-11-02T09:30:00Z","replay":{"sourceDeliveryId":"64709c99-7d31-4f21-864f-c27a866d85c5","originalEventId":"f9eed0db-4547-4a23-82e9-e43d8bd0eb4b"},"testEvent":{"testRunId":"3bb2f7ce-5999-42a6-89f3-fd3f12662511","challenge":"valid"},"replacementId":"21128fa8-de59-45bd-8b6d-61464afecea6","orderId":"ord_ett7skdu","orderReference":"store-order-10432","keyId":"230cf11d-142f-4001-8262-ccd796fafd6c","skuId":"8fc28346-7348-435f-8079-119b73b63d4f","allocationId":"d0e22863-859b-4560-8fd2-c5bc2080df73","decisionNote":"Example text.","rejectedAt":"2026-11-02T09:30:00Z"}}}},"responses":{"200":{"description":"Acknowledge receipt. Return 2xx quickly; process asynchronously."}},"parameters":[{"$ref":"#/components/parameters/WebhookSignature"},{"$ref":"#/components/parameters/WebhookSignatureVersion"},{"$ref":"#/components/parameters/WebhookEventId"},{"$ref":"#/components/parameters/WebhookEventLogId"},{"$ref":"#/components/parameters/WebhookEventType"},{"$ref":"#/components/parameters/WebhookEventVersion"},{"$ref":"#/components/parameters/WebhookDeliveryId"}]}},"keys_revoked":{"post":{"operationId":"webhook_keys_revoked","summary":"keys.revoked","description":"Avrix delivers `keys.revoked` 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/WebhookKeysRevoked"},"example":{"eventId":"62aeed50-1c1c-4622-8d6c-0f9d0fc33c00","eventLogId":"06e821ce-679c-403c-8346-8b7d51b257a4","eventType":"keys.revoked","eventVersion":"1","occurredAt":"2026-11-02T09:30:00Z","replay":{"sourceDeliveryId":"1adbc4e7-1d59-4885-885a-69ade42bf80e","originalEventId":"e09a499d-a2d2-4d67-8b70-7d7bba35a852"},"testEvent":{"testRunId":"a92235c2-3c84-40ce-8db2-3a951f379821","challenge":"valid"},"orderId":"ord_5vm6wuma","orderReference":"store-order-10432","keyIds":["1452b0d1-bc57-4064-89d6-8a96e2cd786c"],"skuId":"c0b841cc-7a1f-465a-8f3b-b1662741b050","allocationId":"ec4d1a1b-c47c-4703-87bb-fcc64dd82ad3","reason":"leaked","recommendedAction":"replace","revokedAt":"2026-11-02T09:30:00Z"}}}},"responses":{"200":{"description":"Acknowledge receipt. Return 2xx quickly; process asynchronously."}},"parameters":[{"$ref":"#/components/parameters/WebhookSignature"},{"$ref":"#/components/parameters/WebhookSignatureVersion"},{"$ref":"#/components/parameters/WebhookEventId"},{"$ref":"#/components/parameters/WebhookEventLogId"},{"$ref":"#/components/parameters/WebhookEventType"},{"$ref":"#/components/parameters/WebhookEventVersion"},{"$ref":"#/components/parameters/WebhookDeliveryId"}]}},"key_frozen":{"post":{"operationId":"webhook_key_frozen","summary":"key.frozen","description":"Avrix delivers `key.frozen` 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/WebhookKeyFrozen"},"example":{"eventId":"e6bc1207-7ca4-4b74-863d-5254ceaec6b2","eventLogId":"3ab5f60d-fd6b-4379-8058-e1926006449f","eventType":"key.frozen","eventVersion":"1","occurredAt":"2026-11-02T09:30:00Z","replay":{"sourceDeliveryId":"9d9ffb93-82f6-4052-8c03-56124b1d9ee2","originalEventId":"a0c3baf8-920a-471e-854d-84961e095872"},"testEvent":{"testRunId":"06a6a70b-b441-4403-8ea5-d5db12b0a59e","challenge":"valid"},"freezeId":"50f963b0-19ed-4256-8924-4e79439e24f7","keyIds":["bfb12e0b-de0e-4c74-8685-77cd5d59a9c4"],"orderReferences":["store-order-10432"],"reason":"payment_dispute","disputeReference":"dsp_10432","expiresAt":"2026-11-02T09:30:00Z"}}}},"responses":{"200":{"description":"Acknowledge receipt. Return 2xx quickly; process asynchronously."}},"parameters":[{"$ref":"#/components/parameters/WebhookSignature"},{"$ref":"#/components/parameters/WebhookSignatureVersion"},{"$ref":"#/components/parameters/WebhookEventId"},{"$ref":"#/components/parameters/WebhookEventLogId"},{"$ref":"#/components/parameters/WebhookEventType"},{"$ref":"#/components/parameters/WebhookEventVersion"},{"$ref":"#/components/parameters/WebhookDeliveryId"}]}},"key_unfrozen":{"post":{"operationId":"webhook_key_unfrozen","summary":"key.unfrozen","description":"Avrix delivers `key.unfrozen` 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/WebhookKeyUnfrozen"},"example":{"eventId":"6dc20a0d-d187-4923-8573-cbbac5111372","eventLogId":"069cf027-c992-4ec2-8cc2-f8aa301125b8","eventType":"key.unfrozen","eventVersion":"1","occurredAt":"2026-11-02T09:30:00Z","replay":{"sourceDeliveryId":"270a5f18-dc81-49e9-8f2a-6370b7dd0280","originalEventId":"b35027d4-ea57-4bc8-8ab8-ce61df4a64e3"},"testEvent":{"testRunId":"6fa18e5b-7a27-47e2-8a56-69f40f232608","challenge":"valid"},"freezeId":"6625081d-08c4-4db5-8d20-ddcc12f58783","keyIds":["553fdbf2-eb35-4005-8b77-8450863d5d1f"],"status":"released","resolution":"released","disputeReference":"dsp_10432","endedAt":"2026-11-02T09:30:00Z"}}}},"responses":{"200":{"description":"Acknowledge receipt. Return 2xx quickly; process asynchronously."}},"parameters":[{"$ref":"#/components/parameters/WebhookSignature"},{"$ref":"#/components/parameters/WebhookSignatureVersion"},{"$ref":"#/components/parameters/WebhookEventId"},{"$ref":"#/components/parameters/WebhookEventLogId"},{"$ref":"#/components/parameters/WebhookEventType"},{"$ref":"#/components/parameters/WebhookEventVersion"},{"$ref":"#/components/parameters/WebhookDeliveryId"}]}},"fulfillment_revoked":{"post":{"operationId":"webhook_fulfillment_revoked","summary":"fulfillment.revoked","description":"Avrix delivers `fulfillment.revoked` 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/WebhookFulfillmentRevoked"},"example":{"eventId":"4528ff64-9d43-40a3-8989-6d6cce6422d9","eventLogId":"62e69ba7-40f0-4744-8ca5-d6acef160ec1","eventType":"fulfillment.revoked","eventVersion":"1","occurredAt":"2026-11-02T09:30:00Z","replay":{"sourceDeliveryId":"4ddb4529-5ad6-46e1-8b60-95d4f64e63bb","originalEventId":"68953093-8a18-41d9-8312-e0a6024a3d8c"},"testEvent":{"testRunId":"821f1b7e-a3a8-454f-8b9f-e8913765ace1","challenge":"valid"},"fulfillmentId":"0de10596-2f2e-4022-8365-634ce7b3648f","orderReference":"store-order-10432","keyId":"5bfb3420-332b-48f1-87d2-323bba65863b","linkGroupId":"a0eafd10-cb5f-4a2a-8b8b-04635003e732","provider":"hosted_redemption","reason":"manual","revokedAt":"2026-11-02T09:30:00Z"}}}},"responses":{"200":{"description":"Acknowledge receipt. Return 2xx quickly; process asynchronously."}},"parameters":[{"$ref":"#/components/parameters/WebhookSignature"},{"$ref":"#/components/parameters/WebhookSignatureVersion"},{"$ref":"#/components/parameters/WebhookEventId"},{"$ref":"#/components/parameters/WebhookEventLogId"},{"$ref":"#/components/parameters/WebhookEventType"},{"$ref":"#/components/parameters/WebhookEventVersion"},{"$ref":"#/components/parameters/WebhookDeliveryId"}]}},"allocation_replenished":{"post":{"operationId":"webhook_allocation_replenished","summary":"allocation.replenished","description":"Avrix delivers `allocation.replenished` 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/WebhookAllocationReplenished"},"example":{"eventId":"7390fc9e-d193-4e9a-84f3-dc2c47955164","eventLogId":"c1d8519b-810a-451d-8405-3ef7e4d3194b","eventType":"allocation.replenished","eventVersion":"1","occurredAt":"2026-11-02T09:30:00Z","replay":{"sourceDeliveryId":"6ea84405-6593-40ce-8e5c-609cbdc9d8eb","originalEventId":"1c5c8dc7-6a38-44c4-8841-d2c8eb29cb9d"},"testEvent":{"testRunId":"b7e79067-7d57-4090-8c23-77ce0bcd3720","challenge":"valid"},"allocationId":"a966d830-61ef-4a01-831e-a03128846f50","skuId":"17cee9fd-9b16-481a-8d3f-35723d954a56","publisherCompanyId":"acme-games","quantity":12,"quantityLimit":50,"remaining":12,"threshold":1,"trigger":"threshold","replenishedAt":"2026-11-02T09:30:00Z"}}}},"responses":{"200":{"description":"Acknowledge receipt. Return 2xx quickly; process asynchronously."}},"parameters":[{"$ref":"#/components/parameters/WebhookSignature"},{"$ref":"#/components/parameters/WebhookSignatureVersion"},{"$ref":"#/components/parameters/WebhookEventId"},{"$ref":"#/components/parameters/WebhookEventLogId"},{"$ref":"#/components/parameters/WebhookEventType"},{"$ref":"#/components/parameters/WebhookEventVersion"},{"$ref":"#/components/parameters/WebhookDeliveryId"}]}},"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"},"example":{"eventId":"d8835d8f-fc10-4273-8ca7-7d6afa347bab","eventLogId":"600d79bf-333f-403b-89d0-57e17e0dad7e","eventType":"allocation.updated","eventVersion":"1","occurredAt":"2026-11-02T09:30:00Z","replay":{"sourceDeliveryId":"2eea3a1f-7077-4a74-8463-bb5d7cc21b57","originalEventId":"2692ce8b-1efd-41f5-8e76-5aa92fe6e428"},"testEvent":{"testRunId":"4bfb26af-6944-4b66-80f3-a6e211e6a0fd","challenge":"valid"},"allocationId":"52ad258e-c7de-4104-8f2f-97840aa6c885","skuId":"987a519e-8b28-4d71-8ed6-6bfd0183d4ce","quantityLimit":50,"quantityPulled":12,"remaining":12,"hotDropMode":true,"status":"active"}}}},"responses":{"200":{"description":"Acknowledge receipt. Return 2xx quickly; process asynchronously."}},"parameters":[{"$ref":"#/components/parameters/WebhookSignature"},{"$ref":"#/components/parameters/WebhookSignatureVersion"},{"$ref":"#/components/parameters/WebhookEventId"},{"$ref":"#/components/parameters/WebhookEventLogId"},{"$ref":"#/components/parameters/WebhookEventType"},{"$ref":"#/components/parameters/WebhookEventVersion"},{"$ref":"#/components/parameters/WebhookDeliveryId"}]}},"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"},"example":{"eventId":"c408a8fe-043b-436f-8cc4-8daf1af6dc33","eventLogId":"4693bedc-6a6b-4e7a-83f3-ce73f2e13d60","eventType":"allocation.depleted","eventVersion":"1","occurredAt":"2026-11-02T09:30:00Z","replay":{"sourceDeliveryId":"a2ec1df1-a38b-443d-8bff-37f5474df0c5","originalEventId":"12d9e5de-7b1b-48a8-8bb3-fe5250f34f44"},"testEvent":{"testRunId":"1b22a901-220f-4dd2-8b0a-e86cda31b1d5","challenge":"valid"},"allocationId":"74f63527-9b73-460b-8b4a-28ec8aa99326","publisherCompanyId":"acme-games","skuId":"8d977d4a-354d-467f-8fee-3118eda8f084","quantityLimit":50,"quantityPulled":12,"remaining":12}}}},"responses":{"200":{"description":"Acknowledge receipt. Return 2xx quickly; process asynchronously."}},"parameters":[{"$ref":"#/components/parameters/WebhookSignature"},{"$ref":"#/components/parameters/WebhookSignatureVersion"},{"$ref":"#/components/parameters/WebhookEventId"},{"$ref":"#/components/parameters/WebhookEventLogId"},{"$ref":"#/components/parameters/WebhookEventType"},{"$ref":"#/components/parameters/WebhookEventVersion"},{"$ref":"#/components/parameters/WebhookDeliveryId"}]}},"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"},"example":{"eventId":"9e467dc9-0446-443c-86ac-a9e7884c64f7","eventLogId":"fbbe3fb3-82e7-44da-8909-cba04859e839","eventType":"allocation.low_stock","eventVersion":"1","occurredAt":"2026-11-02T09:30:00Z","replay":{"sourceDeliveryId":"09c708bf-ca8d-4418-803d-f006a2275520","originalEventId":"3eaacf13-97f6-48c8-8dcc-7a85aa4b179c"},"testEvent":{"testRunId":"9704efb4-fac5-4fc8-8738-17119b4a49de","challenge":"valid"},"allocationId":"739429fd-d667-42d8-84e6-0d0ced7473d4","publisherCompanyId":"acme-games","skuId":"97b0a961-7412-48ea-88b9-c31b20a315e8","quantityLimit":50,"quantityPulled":12,"remaining":12}}}},"responses":{"200":{"description":"Acknowledge receipt. Return 2xx quickly; process asynchronously."}},"parameters":[{"$ref":"#/components/parameters/WebhookSignature"},{"$ref":"#/components/parameters/WebhookSignatureVersion"},{"$ref":"#/components/parameters/WebhookEventId"},{"$ref":"#/components/parameters/WebhookEventLogId"},{"$ref":"#/components/parameters/WebhookEventType"},{"$ref":"#/components/parameters/WebhookEventVersion"},{"$ref":"#/components/parameters/WebhookDeliveryId"}]}},"allocation_running_low":{"post":{"operationId":"webhook_allocation_running_low","summary":"allocation.running_low","description":"Avrix delivers `allocation.running_low` to your registered HTTPS endpoint when it subscribes to it. Verify the signature before processing. Events may be delivered more than once; deduplicate on `eventLogId` (the `X-Avrix-Event-Log-Id` header).","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/WebhookAllocationRunningLow"},"example":{"eventId":"61487985-bf6e-4300-8ba8-6ac0c2ae1772","eventLogId":"5c155acf-d418-48e0-8ab8-5548577327c9","eventType":"allocation.running_low","eventVersion":"1","occurredAt":"2026-11-02T09:30:00Z","replay":{"sourceDeliveryId":"c6f62da4-b15d-42b8-88a7-2bba763b3220","originalEventId":"c7b8b84a-a03a-44f1-85bb-f0cbaaeb3a09"},"testEvent":{"testRunId":"a0bbb382-7fc7-4c32-88f1-1432ac9af245","challenge":"valid"},"allocationId":"0efbe9d6-1849-4528-8a88-9da9e708b4ac","skuId":"3abfe980-b322-4c63-8a00-4f0abf8c0332","publisherCompanyId":"acme-games","quantityLimit":50,"quantityPulled":12,"remaining":12,"threshold":1,"thresholdSource":"replenish_threshold","crossedAt":"2026-11-02T09:30:00Z"}}}},"responses":{"200":{"description":"Acknowledge receipt. Return 2xx quickly; process asynchronously."}},"parameters":[{"$ref":"#/components/parameters/WebhookSignature"},{"$ref":"#/components/parameters/WebhookSignatureVersion"},{"$ref":"#/components/parameters/WebhookEventId"},{"$ref":"#/components/parameters/WebhookEventLogId"},{"$ref":"#/components/parameters/WebhookEventType"},{"$ref":"#/components/parameters/WebhookEventVersion"},{"$ref":"#/components/parameters/WebhookDeliveryId"}]}},"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"},"example":{"eventId":"d817faad-3eb6-468a-8959-b870716000ae","eventLogId":"bb5c3118-20e3-4ff1-8303-a334aadbc153","eventType":"product.updated","eventVersion":"1","occurredAt":"2026-11-02T09:30:00Z","replay":{"sourceDeliveryId":"dc302c29-7ff5-4bf5-84c4-953252f2f1de","originalEventId":"dea8f385-05a1-4c6a-8311-6396cd68446e"},"testEvent":{"testRunId":"3c5cdb22-74f5-4287-8ac5-56bb43cce3aa","challenge":"valid"},"productId":"c521a22d-e65f-4d0d-8359-2a15b5d653ad","publisherCompanyId":"acme-games","productName":"Example Game","productSlug":"example-game","launchPhase":"draft","tradingState":"open","isArchived":false,"updatedAt":"2026-11-02T09:30:00Z","changedFields":["pricing"]}}}},"responses":{"200":{"description":"Acknowledge receipt. Return 2xx quickly; process asynchronously."}},"parameters":[{"$ref":"#/components/parameters/WebhookSignature"},{"$ref":"#/components/parameters/WebhookSignatureVersion"},{"$ref":"#/components/parameters/WebhookEventId"},{"$ref":"#/components/parameters/WebhookEventLogId"},{"$ref":"#/components/parameters/WebhookEventType"},{"$ref":"#/components/parameters/WebhookEventVersion"},{"$ref":"#/components/parameters/WebhookDeliveryId"}]}},"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"},"example":{"eventId":"d9596cfe-2841-4865-8c98-675b230b39a8","eventLogId":"f31c8d5a-9451-473b-8c9d-9b4d60c789d4","eventType":"product.announced","eventVersion":"1","occurredAt":"2026-11-02T09:30:00Z","replay":{"sourceDeliveryId":"e3a5584c-6906-4e9b-8599-605b34093f5e","originalEventId":"52aa956c-d2fd-432d-88cf-68fb78129cce"},"testEvent":{"testRunId":"a5a6a8ef-c927-48f4-8c9f-c0b8a28eb0d3","challenge":"valid"},"productId":"2a0946b4-0332-4538-8d53-5a39dc7f15f2","releaseId":"d20ac8e4-789b-4566-82de-e0bfdb10346b","publisherCompanyId":"acme-games","launchPhase":"announced","emittedAt":"2026-11-02T09:30:00Z"}}}},"responses":{"200":{"description":"Acknowledge receipt. Return 2xx quickly; process asynchronously."}},"parameters":[{"$ref":"#/components/parameters/WebhookSignature"},{"$ref":"#/components/parameters/WebhookSignatureVersion"},{"$ref":"#/components/parameters/WebhookEventId"},{"$ref":"#/components/parameters/WebhookEventLogId"},{"$ref":"#/components/parameters/WebhookEventType"},{"$ref":"#/components/parameters/WebhookEventVersion"},{"$ref":"#/components/parameters/WebhookDeliveryId"}]}},"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"},"example":{"eventId":"1b59383a-419a-452e-8bf8-0ea4bc2bb6d1","eventLogId":"0a673965-06ec-49b0-8c1c-6254c22aeadc","eventType":"product.delisted","eventVersion":"1","occurredAt":"2026-11-02T09:30:00Z","replay":{"sourceDeliveryId":"46dc211d-c26c-4d63-862a-a852aaf26000","originalEventId":"44f75914-aed1-4a1a-8441-18c26aa39f5c"},"testEvent":{"testRunId":"4625a865-0e24-47bd-8573-7978136fcb24","challenge":"valid"},"productId":"7b2644ae-3882-43e7-8ca0-2cb2423f6682","publisherCompanyId":"acme-games","productName":"Example Game","productSlug":"example-game","productStatus":"discontinued","launchPhase":"available","tradingState":"discontinued","isArchived":false,"updatedAt":"2026-11-02T09:30:00Z"}}}},"responses":{"200":{"description":"Acknowledge receipt. Return 2xx quickly; process asynchronously."}},"parameters":[{"$ref":"#/components/parameters/WebhookSignature"},{"$ref":"#/components/parameters/WebhookSignatureVersion"},{"$ref":"#/components/parameters/WebhookEventId"},{"$ref":"#/components/parameters/WebhookEventLogId"},{"$ref":"#/components/parameters/WebhookEventType"},{"$ref":"#/components/parameters/WebhookEventVersion"},{"$ref":"#/components/parameters/WebhookDeliveryId"}]}},"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"},"example":{"eventId":"706205bb-5a67-4551-8bb9-cae3ba1a508c","eventLogId":"ec16b63a-f640-4576-8376-ba7d396c1713","eventType":"release.available","eventVersion":"1","occurredAt":"2026-11-02T09:30:00Z","replay":{"sourceDeliveryId":"1b43089f-6e72-432b-8221-8228c380c361","originalEventId":"3423c2b7-31ff-4404-8a2e-97670f3cfee5"},"testEvent":{"testRunId":"e0a48f32-3662-4f98-8280-b54d1e6b3210","challenge":"valid"},"productId":"4bd84ec7-6cda-46da-88ee-203498da8b01","releaseId":"b518d539-b161-4357-847d-eb594b59e9be","publisherCompanyId":"acme-games","launchPhase":"available","emittedAt":"2026-11-02T09:30:00Z"}}}},"responses":{"200":{"description":"Acknowledge receipt. Return 2xx quickly; process asynchronously."}},"parameters":[{"$ref":"#/components/parameters/WebhookSignature"},{"$ref":"#/components/parameters/WebhookSignatureVersion"},{"$ref":"#/components/parameters/WebhookEventId"},{"$ref":"#/components/parameters/WebhookEventLogId"},{"$ref":"#/components/parameters/WebhookEventType"},{"$ref":"#/components/parameters/WebhookEventVersion"},{"$ref":"#/components/parameters/WebhookDeliveryId"}]}},"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"},"example":{"eventId":"22b48e7c-55dd-4d2a-827b-2f8a574dcdef","eventLogId":"40fabf54-f2ee-4875-886d-701a5fe6ba4c","eventType":"sku.pricing_updated","eventVersion":"1","occurredAt":"2026-11-02T09:30:00Z","replay":{"sourceDeliveryId":"1660165c-bf7e-4fff-86ac-55b096c63a1c","originalEventId":"ab4b31a5-a3be-4400-84ff-e17928fd9137"},"testEvent":{"testRunId":"6998f223-17e5-48ad-88cf-2295441cdca9","challenge":"valid"},"skuId":"c5e6dc78-2bc6-4681-8624-910df9ce9c0c","productId":"df47b80f-ab8f-4856-835a-9025f5df5207","publisherCompanyId":"acme-games","countryCode":"DE","priceCents":2450,"priceMinor":2450,"currencyCode":"EUR","currencyExponent":2,"pricingMode":"inherit","updatedAt":"2026-11-02T09:30:00Z","effectiveAt":"2026-11-02T09:30:00Z","previousPricing":{"priceCents":2450,"priceMinor":2450,"currencyCode":"EUR","currencyExponent":2},"newPricing":{"priceCents":2450,"priceMinor":2450,"currencyCode":"EUR","currencyExponent":2}}}}},"responses":{"200":{"description":"Acknowledge receipt. Return 2xx quickly; process asynchronously."}},"parameters":[{"$ref":"#/components/parameters/WebhookSignature"},{"$ref":"#/components/parameters/WebhookSignatureVersion"},{"$ref":"#/components/parameters/WebhookEventId"},{"$ref":"#/components/parameters/WebhookEventLogId"},{"$ref":"#/components/parameters/WebhookEventType"},{"$ref":"#/components/parameters/WebhookEventVersion"},{"$ref":"#/components/parameters/WebhookDeliveryId"}]}},"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"},"example":{"eventId":"1609bf52-339c-487b-88ea-49443b18d789","eventLogId":"755f894c-5426-46ed-84b7-56d426032c27","eventType":"contract.activated","eventVersion":"1","occurredAt":"2026-11-02T09:30:00Z","replay":{"sourceDeliveryId":"294cd7ad-f8f0-4cbc-893d-78842e5b052b","originalEventId":"dbef92c0-5f14-4027-8fec-2f0c0e0ef0bc"},"testEvent":{"testRunId":"e19a8494-4787-4f59-82ba-c7334ef57395","challenge":"valid"},"connectionId":"93c254aa-def2-4404-836e-b523e9e15048","publisherCompanyId":"acme-games","contractType":"mca","termId":"a4484af4-7568-41f9-8f77-3d1145ba4a1b","version":1}}}},"responses":{"200":{"description":"Acknowledge receipt. Return 2xx quickly; process asynchronously."}},"parameters":[{"$ref":"#/components/parameters/WebhookSignature"},{"$ref":"#/components/parameters/WebhookSignatureVersion"},{"$ref":"#/components/parameters/WebhookEventId"},{"$ref":"#/components/parameters/WebhookEventLogId"},{"$ref":"#/components/parameters/WebhookEventType"},{"$ref":"#/components/parameters/WebhookEventVersion"},{"$ref":"#/components/parameters/WebhookDeliveryId"}]}},"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"},"example":{"eventId":"169f4541-e584-414d-8598-7e7dcfc79d60","eventLogId":"c8ade213-0b24-4887-8a22-23661ce27112","eventType":"contract.superseded","eventVersion":"1","occurredAt":"2026-11-02T09:30:00Z","replay":{"sourceDeliveryId":"9cfd8da0-7d4d-4bde-81e5-a162c0950036","originalEventId":"369bce85-d26e-422e-8525-bc6a6945aa48"},"testEvent":{"testRunId":"ad506341-31d8-422b-8788-ecaa1a37d882","challenge":"valid"},"connectionId":"22712a73-521a-4695-81b2-16a05b7ac401","publisherCompanyId":"acme-games","contractType":"mca","termId":"14ae691d-6673-45cf-8282-3cda55d0686e","version":1}}}},"responses":{"200":{"description":"Acknowledge receipt. Return 2xx quickly; process asynchronously."}},"parameters":[{"$ref":"#/components/parameters/WebhookSignature"},{"$ref":"#/components/parameters/WebhookSignatureVersion"},{"$ref":"#/components/parameters/WebhookEventId"},{"$ref":"#/components/parameters/WebhookEventLogId"},{"$ref":"#/components/parameters/WebhookEventType"},{"$ref":"#/components/parameters/WebhookEventVersion"},{"$ref":"#/components/parameters/WebhookDeliveryId"}]}},"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"},"example":{"eventId":"76dd05a2-3f7b-46e9-8ebc-94c43e582e0e","eventLogId":"dfb23a7f-848a-4304-8423-87bc476d68e6","eventType":"contract.amendment_accepted","eventVersion":"1","occurredAt":"2026-11-02T09:30:00Z","replay":{"sourceDeliveryId":"7e332584-528e-4c39-84c6-a07ebc205f47","originalEventId":"7d262fbd-3d5d-4756-82a7-e3ec9812875f"},"testEvent":{"testRunId":"60127257-41f2-45a9-889a-80ffd3f46b54","challenge":"valid"},"connectionId":"2002c496-ff1a-4ecb-87eb-69df96891e76","publisherCompanyId":"acme-games","contractType":"mca","termId":"e3818a7d-b756-4b95-85c4-412a341cb775","version":1}}}},"responses":{"200":{"description":"Acknowledge receipt. Return 2xx quickly; process asynchronously."}},"parameters":[{"$ref":"#/components/parameters/WebhookSignature"},{"$ref":"#/components/parameters/WebhookSignatureVersion"},{"$ref":"#/components/parameters/WebhookEventId"},{"$ref":"#/components/parameters/WebhookEventLogId"},{"$ref":"#/components/parameters/WebhookEventType"},{"$ref":"#/components/parameters/WebhookEventVersion"},{"$ref":"#/components/parameters/WebhookDeliveryId"}]}},"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"},"example":{"eventId":"c86fbe64-806e-4eed-80bd-5245eee748d5","eventLogId":"0995cf2a-c569-42e5-8c8f-588d6039bfd1","eventType":"invoice.created","eventVersion":"1","occurredAt":"2026-11-02T09:30:00Z","replay":{"sourceDeliveryId":"f2202207-0bbd-4c9e-823d-c93f6407ce15","originalEventId":"0c215f33-52af-4a20-8a4d-e7e35b81f4e5"},"testEvent":{"testRunId":"18941111-d25f-4068-84ef-0b451c9da742","challenge":"valid"},"invoiceId":"84f65919-622a-4227-8b89-3bf26c24cf8a","publisherCompanyId":"acme-games","sellerAllocationId":"66b789f6-e2da-4bb8-895c-bf5b1e102ea0","totalCents":2450,"totalMinor":2450,"currencyCode":"EUR","currencyExponent":2,"invoiceType":"proforma","businessModel":"api","createdAt":"2026-11-02T09:30:00Z"}}}},"responses":{"200":{"description":"Acknowledge receipt. Return 2xx quickly; process asynchronously."}},"parameters":[{"$ref":"#/components/parameters/WebhookSignature"},{"$ref":"#/components/parameters/WebhookSignatureVersion"},{"$ref":"#/components/parameters/WebhookEventId"},{"$ref":"#/components/parameters/WebhookEventLogId"},{"$ref":"#/components/parameters/WebhookEventType"},{"$ref":"#/components/parameters/WebhookEventVersion"},{"$ref":"#/components/parameters/WebhookDeliveryId"}]}},"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"},"example":{"eventId":"ab1d6fde-7dc9-49cf-8083-58fa42cfe7d7","eventLogId":"459c0ce8-99d0-4a10-8386-ccf7c1cc3d33","eventType":"report.ready","eventVersion":"1","occurredAt":"2026-11-02T09:30:00Z","replay":{"sourceDeliveryId":"bde95add-7cff-4f96-8b98-87337137243a","originalEventId":"a8078902-3b04-47f3-8cba-681b17aa405d"},"testEvent":{"testRunId":"8e9228bf-85f1-487c-8d89-989d9c98f1da","challenge":"valid"},"reportId":"ce728cb9-9488-459e-81a2-7768eb40f2f1","reportMonth":"2026-10","modelType":"api","currencyCode":"EUR","transactionCount":12,"readyAt":"2026-11-02T09:30:00Z"}}}},"responses":{"200":{"description":"Acknowledge receipt. Return 2xx quickly; process asynchronously."}},"parameters":[{"$ref":"#/components/parameters/WebhookSignature"},{"$ref":"#/components/parameters/WebhookSignatureVersion"},{"$ref":"#/components/parameters/WebhookEventId"},{"$ref":"#/components/parameters/WebhookEventLogId"},{"$ref":"#/components/parameters/WebhookEventType"},{"$ref":"#/components/parameters/WebhookEventVersion"},{"$ref":"#/components/parameters/WebhookDeliveryId"}]}},"payout_file_ready":{"post":{"operationId":"webhook_payout_file_ready","summary":"payout.file_ready","description":"Avrix delivers `payout.file_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/WebhookPayoutFileReady"},"example":{"eventId":"e7506c5c-a837-463a-85f3-0e0f3b075b1a","eventLogId":"ba9f9308-231c-4f1f-81b3-cc63ba752d0c","eventType":"payout.file_ready","eventVersion":"1","occurredAt":"2026-11-02T09:30:00Z","replay":{"sourceDeliveryId":"89302e33-e956-4755-8d28-8a570c130d1d","originalEventId":"4280aae8-8371-425e-811d-c7f0046445cf"},"testEvent":{"testRunId":"e00b66c7-2e11-477d-800a-54cf78273e4a","challenge":"valid"},"invoiceId":"9249c745-b37d-468d-8017-fb3b62e4b2b7","invoiceNumber":"INV-2026-10-0042","settlementPackageId":"bd84ca4c-3331-4c68-893b-e27e7da4e073","publisherCompanyId":"acme-games","currencyCode":"EUR","currencyExponent":2,"totalCents":2450,"totalMinor":2450,"saleCount":12,"settledAt":"2026-11-02T09:30:00Z","reconciliationPath":"/api/seller/v1/finance/invoices/9249c745-b37d-468d-8017-fb3b62e4b2b7/reconciliation","readyAt":"2026-11-02T09:30:00Z"}}}},"responses":{"200":{"description":"Acknowledge receipt. Return 2xx quickly; process asynchronously."}},"parameters":[{"$ref":"#/components/parameters/WebhookSignature"},{"$ref":"#/components/parameters/WebhookSignatureVersion"},{"$ref":"#/components/parameters/WebhookEventId"},{"$ref":"#/components/parameters/WebhookEventLogId"},{"$ref":"#/components/parameters/WebhookEventType"},{"$ref":"#/components/parameters/WebhookEventVersion"},{"$ref":"#/components/parameters/WebhookDeliveryId"}]}},"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"},"example":{"eventId":"509cf313-0a73-41a9-8d30-0f0f0ec47071","eventLogId":"f8b434b5-a655-4aee-8fb2-05e50e9ec3f4","eventType":"release.date_changed","eventVersion":"1","occurredAt":"2026-11-02T09:30:00Z","replay":{"sourceDeliveryId":"08b2ec4c-be12-4bf0-87e3-8e88313ae20d","originalEventId":"8e046607-d367-463a-84d6-34a93d045622"},"testEvent":{"testRunId":"7b140d13-7cca-4d09-8116-6596583b4d59","challenge":"valid"},"productId":"673fe91d-23c7-4f27-89b2-1cd9a9e3563c","releaseId":"863bc0e3-a539-4047-8d5a-b65e96cd4c39","skuIds":["776a18f8-3546-4824-8f4e-801e796f4567"],"publisherCompanyId":"acme-games","oldDate":"2026-11-02T09:30:00Z","newDate":"2026-11-02T09:30:00Z","emittedAt":"2026-11-02T09:30:00Z"}}}},"responses":{"200":{"description":"Acknowledge receipt. Return 2xx quickly; process asynchronously."}},"parameters":[{"$ref":"#/components/parameters/WebhookSignature"},{"$ref":"#/components/parameters/WebhookSignatureVersion"},{"$ref":"#/components/parameters/WebhookEventId"},{"$ref":"#/components/parameters/WebhookEventLogId"},{"$ref":"#/components/parameters/WebhookEventType"},{"$ref":"#/components/parameters/WebhookEventVersion"},{"$ref":"#/components/parameters/WebhookDeliveryId"}]}},"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"},"example":{"eventId":"7582e05f-3f4e-405f-85ab-622f15c1a87c","eventLogId":"686dedcb-1bd2-4349-87a3-0f0426b42cb8","eventType":"sku.sellability_changed","eventVersion":"1","occurredAt":"2026-11-02T09:30:00Z","replay":{"sourceDeliveryId":"9398ce21-973f-42fe-84a8-ce431d007f0b","originalEventId":"72aa5dff-4c77-4189-8ec0-e3c90cdb5c7b"},"testEvent":{"testRunId":"ec69a2d2-b3b6-4567-84d6-0c3a5878bdc2","challenge":"valid"},"skuId":"8f55c026-46bc-4c24-87fc-fcf9c6d0926f","skuCode":"EXAMPLE-STEAM-WW","productId":"a111498b-3b27-4424-88b9-d2d63ef1b77a","sellable":true,"reasons":[],"firstSeen":true,"emittedAt":"2026-11-02T09:30:00Z"}}}},"responses":{"200":{"description":"Acknowledge receipt. Return 2xx quickly; process asynchronously."}},"parameters":[{"$ref":"#/components/parameters/WebhookSignature"},{"$ref":"#/components/parameters/WebhookSignatureVersion"},{"$ref":"#/components/parameters/WebhookEventId"},{"$ref":"#/components/parameters/WebhookEventLogId"},{"$ref":"#/components/parameters/WebhookEventType"},{"$ref":"#/components/parameters/WebhookEventVersion"},{"$ref":"#/components/parameters/WebhookDeliveryId"}]}},"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"},"example":{"eventId":"ae369466-befb-4ff5-8e19-bf376b2b6141","eventLogId":"88b1ff2d-0036-4fe5-8da2-a4174d7d7d83","eventType":"system.webhook_endpoint_disabled","eventVersion":"1","occurredAt":"2026-11-02T09:30:00Z","replay":{"sourceDeliveryId":"a85fa6a9-9be6-4553-89a9-f6dc9bf13e0e","originalEventId":"f39729fc-8719-4545-8062-9beb4489fe46"},"testEvent":{"testRunId":"d9bf0712-c579-458d-8350-9f9069c69115","challenge":"valid"},"endpointId":"acaa7d93-9ef0-40b7-8c23-2c4fd03fcc25","endpointHost":"store.example.com","consecutiveFailures":1,"disabledAt":"2026-11-02T09:30:00Z","reason":"consecutive_delivery_failures"}}}},"responses":{"200":{"description":"Acknowledge receipt. Return 2xx quickly; process asynchronously."}},"parameters":[{"$ref":"#/components/parameters/WebhookSignature"},{"$ref":"#/components/parameters/WebhookSignatureVersion"},{"$ref":"#/components/parameters/WebhookEventId"},{"$ref":"#/components/parameters/WebhookEventLogId"},{"$ref":"#/components/parameters/WebhookEventType"},{"$ref":"#/components/parameters/WebhookEventVersion"},{"$ref":"#/components/parameters/WebhookDeliveryId"}]}},"system_webhook_endpoint_failing":{"post":{"operationId":"webhook_system_webhook_endpoint_failing","summary":"system.webhook_endpoint_failing","description":"Avrix delivers `system.webhook_endpoint_failing` when deliveries to one of your endpoints have failed at least 3 times in a row over at least 10 minutes. The endpoint stays active and retries continue. It is also on your event log (`GET /events`), so you see it even when every endpoint is down. Sent once per failing episode. Verify the signature before processing.","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/WebhookSystemEndpointFailing"},"example":{"eventId":"987c34fc-8e94-45a6-8ff4-65f965460ecf","eventLogId":"fe8d1231-750d-45da-8bd3-bb0804b10793","eventType":"system.webhook_endpoint_failing","eventVersion":"1","occurredAt":"2026-11-02T09:30:00Z","replay":{"sourceDeliveryId":"ac2689cf-5a3b-4e6d-8738-8e081da5d9d0","originalEventId":"ce4eb57e-f265-4d73-83e1-b7be028d994f"},"testEvent":{"testRunId":"b7206de6-a5c9-40d1-8733-9c41cdba41f5","challenge":"valid"},"endpointId":"b3e6b803-c230-4400-84cc-66b35fb9fbd2","endpointHost":"example_endpointhost","failingSince":"2026-11-02T09:30:00Z","firstFailedAt":"2026-11-02T09:30:00Z","consecutiveFailedAttempts":1,"lastResponseStatus":200}}}},"responses":{"200":{"description":"Acknowledge receipt. Return 2xx quickly; process asynchronously."}},"parameters":[{"$ref":"#/components/parameters/WebhookSignature"},{"$ref":"#/components/parameters/WebhookSignatureVersion"},{"$ref":"#/components/parameters/WebhookEventId"},{"$ref":"#/components/parameters/WebhookEventLogId"},{"$ref":"#/components/parameters/WebhookEventType"},{"$ref":"#/components/parameters/WebhookEventVersion"},{"$ref":"#/components/parameters/WebhookDeliveryId"}]}},"system_webhook_endpoint_recovered":{"post":{"operationId":"webhook_system_webhook_endpoint_recovered","summary":"system.webhook_endpoint_recovered","description":"Avrix delivers `system.webhook_endpoint_recovered` when a failing endpoint answers 2xx again. Verify the signature before processing.","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/WebhookSystemEndpointRecovered"},"example":{"eventId":"1880a4d8-03e2-4569-8025-6c4ec323fd84","eventLogId":"ab3b6738-f9b6-49c2-805b-c1d424e62c00","eventType":"system.webhook_endpoint_recovered","eventVersion":"1","occurredAt":"2026-11-02T09:30:00Z","replay":{"sourceDeliveryId":"52b75406-35a6-4b95-8b59-b820ba988477","originalEventId":"30e9fccf-7665-4c4e-8b42-1903c17ce0a6"},"testEvent":{"testRunId":"0bd4f8e7-c367-48af-892f-241973f98852","challenge":"valid"},"endpointId":"2c2d329b-1226-470b-87a7-7b97c7ad2170","endpointHost":"example_endpointhost","failingSince":"2026-11-02T09:30:00Z","recoveredAt":"2026-11-02T09:30:00Z"}}}},"responses":{"200":{"description":"Acknowledge receipt. Return 2xx quickly; process asynchronously."}},"parameters":[{"$ref":"#/components/parameters/WebhookSignature"},{"$ref":"#/components/parameters/WebhookSignatureVersion"},{"$ref":"#/components/parameters/WebhookEventId"},{"$ref":"#/components/parameters/WebhookEventLogId"},{"$ref":"#/components/parameters/WebhookEventType"},{"$ref":"#/components/parameters/WebhookEventVersion"},{"$ref":"#/components/parameters/WebhookDeliveryId"}]}},"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"},"example":{"eventId":"8c118d76-87b2-4ccb-8121-57f3107da846","eventLogId":"d6443fd3-3d4f-462d-87b8-43ced3e0c96f","eventType":"redemption.expiring","eventVersion":"1","occurredAt":"2026-11-02T09:30:00Z","replay":{"sourceDeliveryId":"1d589220-356e-47c0-8426-408b44176920","originalEventId":"54de41c5-189e-4419-84df-e8ab964dc4b0"},"testEvent":{"testRunId":"5483065e-348f-48d6-84a2-88a8a5bab501","challenge":"valid"},"fulfillmentId":"0869c841-5e9c-4d2a-8efa-fc2451d30844","orderReference":"store-order-10432","skuId":"02fca32b-4f9f-408b-8876-6c3f05f1664d","platformCode":"steam","provider":"hosted_redemption","expiresAt":"2026-11-02T09:30:00Z"}}}},"responses":{"200":{"description":"Acknowledge receipt. Return 2xx quickly; process asynchronously."}},"parameters":[{"$ref":"#/components/parameters/WebhookSignature"},{"$ref":"#/components/parameters/WebhookSignatureVersion"},{"$ref":"#/components/parameters/WebhookEventId"},{"$ref":"#/components/parameters/WebhookEventLogId"},{"$ref":"#/components/parameters/WebhookEventType"},{"$ref":"#/components/parameters/WebhookEventVersion"},{"$ref":"#/components/parameters/WebhookDeliveryId"}]}},"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"},"example":{"eventId":"59ace438-d9f9-41e0-83fc-3fccfa982c24","eventLogId":"9825fe11-5932-455c-8204-7567348d8190","eventType":"order.ready","eventVersion":"1","occurredAt":"2026-11-02T09:30:00Z","replay":{"sourceDeliveryId":"6b0b0641-87fd-4a04-81ed-39d997425ea3","originalEventId":"1e5d1f09-40e1-490e-8bc4-e9075fdc9539"},"testEvent":{"testRunId":"d3d6703d-2f6f-46a7-88de-c640aa1a1b01","challenge":"valid"},"orderReference":"store-order-10432","orderId":"ord_aebg7uw5"}}}},"responses":{"200":{"description":"Acknowledge receipt. Return 2xx quickly; process asynchronously."}},"parameters":[{"$ref":"#/components/parameters/WebhookSignature"},{"$ref":"#/components/parameters/WebhookSignatureVersion"},{"$ref":"#/components/parameters/WebhookEventId"},{"$ref":"#/components/parameters/WebhookEventLogId"},{"$ref":"#/components/parameters/WebhookEventType"},{"$ref":"#/components/parameters/WebhookEventVersion"},{"$ref":"#/components/parameters/WebhookDeliveryId"}]}},"order_backorder_expired":{"post":{"operationId":"webhook_order_backorder_expired","summary":"order.backorder_expired","description":"Avrix delivers `order.backorder_expired` when a customer-order backorder is still awaiting stock at its timeout (default 14 days) and is cancelled. Refund 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/WebhookOrderBackorderExpired"},"example":{"eventId":"db29776e-d0c1-445a-855c-aab2ab22750d","eventLogId":"cfe20f4c-2790-4110-8606-28cf67c27e9d","eventType":"order.backorder_expired","eventVersion":"1","occurredAt":"2026-11-02T09:30:00Z","replay":{"sourceDeliveryId":"65d5657a-29d3-4215-83e7-1e69b1075867","originalEventId":"16fc8994-9ced-4cb3-8ff8-b9f1dc7ac34e"},"testEvent":{"testRunId":"4633ddc3-9b40-42fb-86db-35b70362e8a2","challenge":"valid"},"orderReference":"store-order-10432","orderId":"ord_cszx8yck","allocationId":"f859fd05-7390-4382-8bdb-1f6c88bb10b2","skuId":"19c30bef-e091-46df-89ff-3ec881f542bd","quantity":12,"status":"cancelled","backorderCreatedAt":"2026-11-02T09:30:00Z","expiredAt":"2026-11-02T09:30:00Z"}}}},"responses":{"200":{"description":"Acknowledge receipt. Return 2xx quickly; process asynchronously."}},"parameters":[{"$ref":"#/components/parameters/WebhookSignature"},{"$ref":"#/components/parameters/WebhookSignatureVersion"},{"$ref":"#/components/parameters/WebhookEventId"},{"$ref":"#/components/parameters/WebhookEventLogId"},{"$ref":"#/components/parameters/WebhookEventType"},{"$ref":"#/components/parameters/WebhookEventVersion"},{"$ref":"#/components/parameters/WebhookDeliveryId"}]}},"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"},"example":{"eventId":"07cca226-10dc-448e-826c-4259747b99bd","eventLogId":"09d22968-8056-40cd-8b43-8821f66a3874","eventType":"redemption.expired","eventVersion":"1","occurredAt":"2026-11-02T09:30:00Z","replay":{"sourceDeliveryId":"dcadb3e1-e4f3-4767-83e7-09d179faaac4","originalEventId":"70eece8e-406f-46b3-8c6f-58ebec08f443"},"testEvent":{"testRunId":"b6d304d4-3213-442c-8d9a-63f791112690","challenge":"valid"},"fulfillmentId":"4ca64523-d798-4a83-8afa-99640cd5a10d","orderReference":"store-order-10432","skuId":"b57b0d29-d107-4401-87d2-4af9dadcd508","platformCode":"steam","provider":"hosted_redemption","expiresAt":"2026-11-02T09:30:00Z","effectiveAt":"2026-11-02T09:30:00Z"}}}},"responses":{"200":{"description":"Acknowledge receipt. Return 2xx quickly; process asynchronously."}},"parameters":[{"$ref":"#/components/parameters/WebhookSignature"},{"$ref":"#/components/parameters/WebhookSignatureVersion"},{"$ref":"#/components/parameters/WebhookEventId"},{"$ref":"#/components/parameters/WebhookEventLogId"},{"$ref":"#/components/parameters/WebhookEventType"},{"$ref":"#/components/parameters/WebhookEventVersion"},{"$ref":"#/components/parameters/WebhookDeliveryId"}]}},"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"},"example":{"eventId":"dcc08622-ac17-48a7-8487-9931f8586ab2","eventLogId":"32039971-567d-490c-8bd9-20f117cc962d","eventType":"catalog.export_ready","eventVersion":"1","occurredAt":"2026-11-02T09:30:00Z","replay":{"sourceDeliveryId":"b07f3783-9178-4658-8152-4a81c3d24b4f","originalEventId":"ec46fe93-6e91-4f65-8142-ff3fd2a77c35"},"testEvent":{"testRunId":"d61b062d-1d6f-4b85-8ed4-c939a02bdbbf","challenge":"valid"},"exportId":"9eeca8c5-a233-4482-8be2-a8f22c17b639","checksum":"sha256:9f86d081884c7d659a2feaa0c55ad015a3bf4f1b2b0b822cd15d6c15b0f00a08","bytes":1,"expiresAt":"2026-11-02T09:30:00Z","totalProducts":2450}}}},"responses":{"200":{"description":"Acknowledge receipt. Return 2xx quickly; process asynchronously."}},"parameters":[{"$ref":"#/components/parameters/WebhookSignature"},{"$ref":"#/components/parameters/WebhookSignatureVersion"},{"$ref":"#/components/parameters/WebhookEventId"},{"$ref":"#/components/parameters/WebhookEventLogId"},{"$ref":"#/components/parameters/WebhookEventType"},{"$ref":"#/components/parameters/WebhookEventVersion"},{"$ref":"#/components/parameters/WebhookDeliveryId"}]}},"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"},"example":{"eventId":"d234f786-4fea-4ccb-8bde-fcc5a19505f1","eventLogId":"7cf821b0-d959-4667-841f-e28d8b092d68","eventType":"product.delisting_scheduled","eventVersion":"1","occurredAt":"2026-11-02T09:30:00Z","replay":{"sourceDeliveryId":"c25919f4-f639-4910-8193-065a7a5ec2d8","originalEventId":"49c3f109-124a-49c7-8792-cfa4090f9180"},"testEvent":{"testRunId":"1383a2e8-20f9-4a04-8e71-79c60576b6f4","challenge":"valid"},"productId":"afea7fb6-6432-453d-874c-ba92efafebf0","publisherCompanyId":"acme-games","productName":"Example Game","productSlug":"example-game","productStatus":"active","launchPhase":"available","tradingState":"open","isArchived":false,"updatedAt":"2026-11-02T09:30:00Z","effectiveAt":"2026-11-02T09:30:00Z"}}}},"responses":{"200":{"description":"Acknowledge receipt. Return 2xx quickly; process asynchronously."}},"parameters":[{"$ref":"#/components/parameters/WebhookSignature"},{"$ref":"#/components/parameters/WebhookSignatureVersion"},{"$ref":"#/components/parameters/WebhookEventId"},{"$ref":"#/components/parameters/WebhookEventLogId"},{"$ref":"#/components/parameters/WebhookEventType"},{"$ref":"#/components/parameters/WebhookEventVersion"},{"$ref":"#/components/parameters/WebhookDeliveryId"}]}},"platform_notice":{"post":{"operationId":"webhook_platform_notice","summary":"platform.notice","description":"Avrix delivers `platform.notice` to endpoints that subscribe to it when it announces a change to the Seller API: a contract change, a deprecation, a default contract date change, rate-limit enforcement or planned maintenance. Verify the signature before processing.","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/WebhookPlatformNotice"},"example":{"eventId":"de91f7f1-469b-45bd-832e-62176b7641e8","eventLogId":"076be9c2-c7a7-4801-86d4-3c0701f6cabb","eventType":"platform.notice","eventVersion":"1","occurredAt":"2026-11-02T09:30:00Z","replay":{"sourceDeliveryId":"3562fa79-54c3-4e7e-8f8f-28bcb850d607","originalEventId":"f543f0ee-950c-4822-894c-26885dfc41d8"},"testEvent":{"testRunId":"315e7d0c-884b-4501-85d7-3148acd9b0f1","challenge":"valid"},"noticeId":"maintenance-2026-11-20","category":"api_change","actionRequired":true,"title":"Example Game","summary":"Example text.","effectiveAt":"2026-11-02T09:30:00Z","contractDate":"2026-11-02","affects":["example_affect"],"url":"https://api.avrix.io/api/seller/v1/example","publishedAt":"2026-11-02T09:30:00Z"}}}},"responses":{"200":{"description":"Acknowledge receipt. Return 2xx quickly; process asynchronously."}},"parameters":[{"$ref":"#/components/parameters/WebhookSignature"},{"$ref":"#/components/parameters/WebhookSignatureVersion"},{"$ref":"#/components/parameters/WebhookEventId"},{"$ref":"#/components/parameters/WebhookEventLogId"},{"$ref":"#/components/parameters/WebhookEventType"},{"$ref":"#/components/parameters/WebhookEventVersion"},{"$ref":"#/components/parameters/WebhookDeliveryId"}]}},"order_cancelled":{"post":{"operationId":"webhook_order_cancelled","summary":"order.cancelled","description":"Avrix delivers `order.cancelled` to your registered HTTPS endpoint when it subscribes to it. Verify the signature before processing. Events may be delivered more than once; deduplicate on `eventLogId` (the `X-Avrix-Event-Log-Id` header).","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/WebhookOrderCancelled"},"example":{"eventId":"dad142c4-6a6c-457f-8100-dab2f9188286","eventLogId":"1d926a20-e714-458b-82f8-b9cd19203aa2","eventType":"order.cancelled","eventVersion":"1","occurredAt":"2026-11-02T09:30:00Z","replay":{"sourceDeliveryId":"a9158e6d-c5b6-4881-8556-7d24ef0d5ef9","originalEventId":"ed1887ea-f4e6-4b69-8885-ee0c6042d999"},"testEvent":{"testRunId":"2c709930-e242-47c1-810a-abba4180b643","challenge":"valid"},"orderReference":"store-order-10432","orderId":"ord_xd9bqsty","cancelled":1}}}},"responses":{"200":{"description":"Acknowledge receipt. Return 2xx quickly; process asynchronously."}},"parameters":[{"$ref":"#/components/parameters/WebhookSignature"},{"$ref":"#/components/parameters/WebhookSignatureVersion"},{"$ref":"#/components/parameters/WebhookEventId"},{"$ref":"#/components/parameters/WebhookEventLogId"},{"$ref":"#/components/parameters/WebhookEventType"},{"$ref":"#/components/parameters/WebhookEventVersion"},{"$ref":"#/components/parameters/WebhookDeliveryId"}]}},"allocation_request_decided":{"post":{"operationId":"webhook_allocation_request_decided","summary":"allocation.request_decided","description":"Avrix delivers `allocation.request_decided` to your registered HTTPS endpoint when it subscribes to it. Verify the signature before processing. Events may be delivered more than once; deduplicate on `eventLogId` (the `X-Avrix-Event-Log-Id` header).","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/WebhookAllocationRequestDecided"},"example":{"eventId":"33cb82ef-d2dd-4e20-8146-232eb3681ebc","eventLogId":"781bfd3e-881b-4fe2-8b6b-e3f064251feb","eventType":"allocation.request_decided","eventVersion":"1","occurredAt":"2026-11-02T09:30:00Z","replay":{"sourceDeliveryId":"09dd427f-e151-493b-8996-b693c4dbe3b7","originalEventId":"0cdf96e3-5636-49b2-87f2-da8be1563471"},"testEvent":{"testRunId":"50fdd15c-7d0f-44ac-8186-2f130740e274","challenge":"valid"},"requestId":"7cdb2f91-6ab2-46a1-8495-c4cbb459aa59","resolution":"approved","automatic":true,"skuId":"5fbee437-63fe-4e78-8ed5-2fc4314cc9d7","publisherCompanyId":"acme-games","allocationId":"f1958dc7-b600-4710-89e5-9a58b4c6cc51","requestedQuantity":12,"grantedQuantity":12,"decisionNote":"Example text.","decidedAt":"2026-11-02T09:30:00Z"}}}},"responses":{"200":{"description":"Acknowledge receipt. Return 2xx quickly; process asynchronously."}},"parameters":[{"$ref":"#/components/parameters/WebhookSignature"},{"$ref":"#/components/parameters/WebhookSignatureVersion"},{"$ref":"#/components/parameters/WebhookEventId"},{"$ref":"#/components/parameters/WebhookEventLogId"},{"$ref":"#/components/parameters/WebhookEventType"},{"$ref":"#/components/parameters/WebhookEventVersion"},{"$ref":"#/components/parameters/WebhookDeliveryId"}]}},"allocation_request_cancelled":{"post":{"operationId":"webhook_allocation_request_cancelled","summary":"allocation.request_cancelled","description":"Avrix delivers `allocation.request_cancelled` to your registered HTTPS endpoint when it subscribes to it. Verify the signature before processing. Events may be delivered more than once; deduplicate on `eventLogId` (the `X-Avrix-Event-Log-Id` header).","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/WebhookAllocationRequestCancelled"},"example":{"eventId":"685e098d-8a1f-4e54-8e06-b301748521e4","eventLogId":"2d3a090c-f0c3-4a45-81c9-13351dc4e0bd","eventType":"allocation.request_cancelled","eventVersion":"1","occurredAt":"2026-11-02T09:30:00Z","replay":{"sourceDeliveryId":"6bd20306-d491-46f1-8ffc-dbedd0718512","originalEventId":"aef3c861-fc7a-4e86-894e-b958f4c2a367"},"testEvent":{"testRunId":"e7218c0d-3149-47c6-83f1-657f997a26a6","challenge":"valid"},"requestId":"5a9879c0-db17-40be-8254-bc1016ac7ed4","skuId":"6b21b429-0157-48a6-811f-2b45914a3ea8","publisherCompanyId":"acme-games","allocationId":"cfa4d8f6-31cf-49a9-8b97-cb6bbaef6321","requestedQuantity":12,"cancelledAt":"2026-11-02T09:30:00Z"}}}},"responses":{"200":{"description":"Acknowledge receipt. Return 2xx quickly; process asynchronously."}},"parameters":[{"$ref":"#/components/parameters/WebhookSignature"},{"$ref":"#/components/parameters/WebhookSignatureVersion"},{"$ref":"#/components/parameters/WebhookEventId"},{"$ref":"#/components/parameters/WebhookEventLogId"},{"$ref":"#/components/parameters/WebhookEventType"},{"$ref":"#/components/parameters/WebhookEventVersion"},{"$ref":"#/components/parameters/WebhookDeliveryId"}]}},"product_added":{"post":{"operationId":"webhook_product_added","summary":"product.added","description":"Avrix delivers `product.added` to your registered HTTPS endpoint when it subscribes to it. Verify the signature before processing. Events may be delivered more than once; deduplicate on `eventLogId` (the `X-Avrix-Event-Log-Id` header).","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/WebhookProductAdded"},"example":{"eventId":"e1bc1f3a-51b3-4fca-86d2-d45661074709","eventLogId":"b99c8979-c3b0-4d2e-8519-547f7ca33bfc","eventType":"product.added","eventVersion":"1","occurredAt":"2026-11-02T09:30:00Z","replay":{"sourceDeliveryId":"1bab7293-3b51-4d83-8898-346d979dcfea","originalEventId":"cc9e9631-1f98-47be-8e63-27fbe0fcff65"},"testEvent":{"testRunId":"8d4237c9-2a56-4950-8f6b-f59d56ee87f1","challenge":"valid"},"productId":"a3ba7205-b48e-4818-8888-8b009baf57e6","publisherCompanyId":"acme-games"}}}},"responses":{"200":{"description":"Acknowledge receipt. Return 2xx quickly; process asynchronously."}},"parameters":[{"$ref":"#/components/parameters/WebhookSignature"},{"$ref":"#/components/parameters/WebhookSignatureVersion"},{"$ref":"#/components/parameters/WebhookEventId"},{"$ref":"#/components/parameters/WebhookEventLogId"},{"$ref":"#/components/parameters/WebhookEventType"},{"$ref":"#/components/parameters/WebhookEventVersion"},{"$ref":"#/components/parameters/WebhookDeliveryId"}]}},"contract_expiring":{"post":{"operationId":"webhook_contract_expiring","summary":"contract.expiring","description":"Avrix delivers `contract.expiring` to your registered HTTPS endpoint when it subscribes to it. Verify the signature before processing. Events may be delivered more than once; deduplicate on `eventLogId` (the `X-Avrix-Event-Log-Id` header).","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/WebhookContractExpiring"},"example":{"eventId":"f99ca2f8-91b0-47a1-8f0c-7c57904ed84f","eventLogId":"c5a763cc-439b-4165-8b12-d48a33537a9f","eventType":"contract.expiring","eventVersion":"1","occurredAt":"2026-11-02T09:30:00Z","replay":{"sourceDeliveryId":"d3f13067-d3fe-4096-8a1d-461ad3cdf3d2","originalEventId":"4e3b46bc-a590-49a2-825a-a6989edddbb9"},"testEvent":{"testRunId":"0ae4103e-4ed1-4a47-8fb9-52ec4b3caa6e","challenge":"valid"},"connectionId":"8127728e-e1d7-4cf0-897a-764bafa2cb7b","publisherCompanyId":"acme-games","contractType":"api","termId":"6a559df4-09c3-4986-8ecc-aaa610be5050","changedAt":"2026-11-02T09:30:00Z","validUntil":"2026-11-02T09:30:00Z","windowDays":1}}}},"responses":{"200":{"description":"Acknowledge receipt. Return 2xx quickly; process asynchronously."}},"parameters":[{"$ref":"#/components/parameters/WebhookSignature"},{"$ref":"#/components/parameters/WebhookSignatureVersion"},{"$ref":"#/components/parameters/WebhookEventId"},{"$ref":"#/components/parameters/WebhookEventLogId"},{"$ref":"#/components/parameters/WebhookEventType"},{"$ref":"#/components/parameters/WebhookEventVersion"},{"$ref":"#/components/parameters/WebhookDeliveryId"}]}},"contract_expired":{"post":{"operationId":"webhook_contract_expired","summary":"contract.expired","description":"Avrix delivers `contract.expired` to your registered HTTPS endpoint when it subscribes to it. Verify the signature before processing. Events may be delivered more than once; deduplicate on `eventLogId` (the `X-Avrix-Event-Log-Id` header).","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/WebhookContractExpired"},"example":{"eventId":"c0d5d5e6-fe8b-4807-85ad-c794a4ee68ce","eventLogId":"b9b58f25-4fab-45b5-8688-01233a9ee5b5","eventType":"contract.expired","eventVersion":"1","occurredAt":"2026-11-02T09:30:00Z","replay":{"sourceDeliveryId":"cef9d683-3959-4056-886a-eb06d223614d","originalEventId":"2bf6a43f-5e2a-4ad1-8a26-21de757b4576"},"testEvent":{"testRunId":"0b584487-38e6-432c-8a46-90e2068e22e2","challenge":"valid"},"connectionId":"c93a2ae8-385c-4a3b-8b26-d8bc6ee3febf","publisherCompanyId":"acme-games","contractType":"api","termId":"355c6023-dc38-401c-87d2-f62d5e848431","changedAt":"2026-11-02T09:30:00Z","validUntil":"2026-11-02T09:30:00Z"}}}},"responses":{"200":{"description":"Acknowledge receipt. Return 2xx quickly; process asynchronously."}},"parameters":[{"$ref":"#/components/parameters/WebhookSignature"},{"$ref":"#/components/parameters/WebhookSignatureVersion"},{"$ref":"#/components/parameters/WebhookEventId"},{"$ref":"#/components/parameters/WebhookEventLogId"},{"$ref":"#/components/parameters/WebhookEventType"},{"$ref":"#/components/parameters/WebhookEventVersion"},{"$ref":"#/components/parameters/WebhookDeliveryId"}]}},"contract_terminated":{"post":{"operationId":"webhook_contract_terminated","summary":"contract.terminated","description":"Avrix delivers `contract.terminated` to your registered HTTPS endpoint when it subscribes to it. Verify the signature before processing. Events may be delivered more than once; deduplicate on `eventLogId` (the `X-Avrix-Event-Log-Id` header).","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/WebhookContractTerminated"},"example":{"eventId":"dbfcaef1-4f6b-4a66-86f7-7c4cafe19bfe","eventLogId":"87b7b286-cb68-4fce-870c-5f4b3f50b6a9","eventType":"contract.terminated","eventVersion":"1","occurredAt":"2026-11-02T09:30:00Z","replay":{"sourceDeliveryId":"5cb1b9c2-23ab-4cbf-87d3-05e61c7d48ec","originalEventId":"92759a66-8ea7-4c84-87d0-5ac3473b43f0"},"testEvent":{"testRunId":"571a06ef-8b36-440e-8c6e-03417b6e6b24","challenge":"valid"},"connectionId":"bf45e84a-9e59-42b5-8fc2-e182f393bddb","publisherCompanyId":"acme-games","contractType":"api","termId":"25a8b821-9960-4e56-8008-0a39e0e864e6","changedAt":"2026-11-02T09:30:00Z"}}}},"responses":{"200":{"description":"Acknowledge receipt. Return 2xx quickly; process asynchronously."}},"parameters":[{"$ref":"#/components/parameters/WebhookSignature"},{"$ref":"#/components/parameters/WebhookSignatureVersion"},{"$ref":"#/components/parameters/WebhookEventId"},{"$ref":"#/components/parameters/WebhookEventLogId"},{"$ref":"#/components/parameters/WebhookEventType"},{"$ref":"#/components/parameters/WebhookEventVersion"},{"$ref":"#/components/parameters/WebhookDeliveryId"}]}},"connection_suspended":{"post":{"operationId":"webhook_connection_suspended","summary":"connection.suspended","description":"Avrix delivers `connection.suspended` to your registered HTTPS endpoint when it subscribes to it. Verify the signature before processing. Events may be delivered more than once; deduplicate on `eventLogId` (the `X-Avrix-Event-Log-Id` header).","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/WebhookConnectionSuspended"},"example":{"eventId":"1f1cddbb-2546-4b46-8a28-dffb7afb099d","eventLogId":"30fb5e5a-985b-4b66-81bb-2b1f43c39520","eventType":"connection.suspended","eventVersion":"1","occurredAt":"2026-11-02T09:30:00Z","replay":{"sourceDeliveryId":"0c37f95c-e211-410c-88af-4215927218b7","originalEventId":"5f9ab3a6-6b64-4124-85b4-8750133ce23c"},"testEvent":{"testRunId":"9cde1713-cd2d-4e13-89ea-d60d0c6131fc","challenge":"valid"},"connectionId":"3a009307-423e-4e34-883b-4071f63f75f2","publisherCompanyId":"acme-games","initiatedBy":"publisher","changedAt":"2026-11-02T09:30:00Z"}}}},"responses":{"200":{"description":"Acknowledge receipt. Return 2xx quickly; process asynchronously."}},"parameters":[{"$ref":"#/components/parameters/WebhookSignature"},{"$ref":"#/components/parameters/WebhookSignatureVersion"},{"$ref":"#/components/parameters/WebhookEventId"},{"$ref":"#/components/parameters/WebhookEventLogId"},{"$ref":"#/components/parameters/WebhookEventType"},{"$ref":"#/components/parameters/WebhookEventVersion"},{"$ref":"#/components/parameters/WebhookDeliveryId"}]}},"connection_reactivated":{"post":{"operationId":"webhook_connection_reactivated","summary":"connection.reactivated","description":"Avrix delivers `connection.reactivated` to your registered HTTPS endpoint when it subscribes to it. Verify the signature before processing. Events may be delivered more than once; deduplicate on `eventLogId` (the `X-Avrix-Event-Log-Id` header).","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/WebhookConnectionReactivated"},"example":{"eventId":"b73e6050-2aa8-43b3-8abd-a252bc102132","eventLogId":"ac68c646-bf84-4067-8b74-773aaac77f96","eventType":"connection.reactivated","eventVersion":"1","occurredAt":"2026-11-02T09:30:00Z","replay":{"sourceDeliveryId":"968fb185-6931-42f9-8b3f-236031bef67f","originalEventId":"b790ba8c-cd39-42a5-8458-6adfc3f27e1e"},"testEvent":{"testRunId":"ce4bd23d-3670-4b18-8550-a9ea62dea5b8","challenge":"valid"},"connectionId":"38d8fde4-9f7c-40e5-851f-92fe2557ca45","publisherCompanyId":"acme-games","initiatedBy":"publisher","changedAt":"2026-11-02T09:30:00Z"}}}},"responses":{"200":{"description":"Acknowledge receipt. Return 2xx quickly; process asynchronously."}},"parameters":[{"$ref":"#/components/parameters/WebhookSignature"},{"$ref":"#/components/parameters/WebhookSignatureVersion"},{"$ref":"#/components/parameters/WebhookEventId"},{"$ref":"#/components/parameters/WebhookEventLogId"},{"$ref":"#/components/parameters/WebhookEventType"},{"$ref":"#/components/parameters/WebhookEventVersion"},{"$ref":"#/components/parameters/WebhookDeliveryId"}]}},"connection_ended":{"post":{"operationId":"webhook_connection_ended","summary":"connection.ended","description":"Avrix delivers `connection.ended` to your registered HTTPS endpoint when it subscribes to it. Verify the signature before processing. Events may be delivered more than once; deduplicate on `eventLogId` (the `X-Avrix-Event-Log-Id` header).","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/WebhookConnectionEnded"},"example":{"eventId":"ad20cef4-de9e-4606-8cc4-95bf87a95751","eventLogId":"543b35b2-9ed8-4f01-81e8-92010a10fbb3","eventType":"connection.ended","eventVersion":"1","occurredAt":"2026-11-02T09:30:00Z","replay":{"sourceDeliveryId":"ceba1999-8097-4335-86c2-ad85b1d260de","originalEventId":"c2a09c07-3239-4515-8591-fe2e0f4e6d11"},"testEvent":{"testRunId":"0e928d34-f755-4845-8b09-be1014c76be5","challenge":"valid"},"connectionId":"a90b03a7-4748-427e-87e0-aaeebf98ec6f","publisherCompanyId":"acme-games","initiatedBy":"publisher","changedAt":"2026-11-02T09:30:00Z"}}}},"responses":{"200":{"description":"Acknowledge receipt. Return 2xx quickly; process asynchronously."}},"parameters":[{"$ref":"#/components/parameters/WebhookSignature"},{"$ref":"#/components/parameters/WebhookSignatureVersion"},{"$ref":"#/components/parameters/WebhookEventId"},{"$ref":"#/components/parameters/WebhookEventLogId"},{"$ref":"#/components/parameters/WebhookEventType"},{"$ref":"#/components/parameters/WebhookEventVersion"},{"$ref":"#/components/parameters/WebhookDeliveryId"}]}},"connection_request_decided":{"post":{"operationId":"webhook_connection_request_decided","summary":"connection.request_decided","description":"Avrix delivers `connection.request_decided` to your registered HTTPS endpoint when it subscribes to it. Verify the signature before processing. Events may be delivered more than once; deduplicate on `eventLogId` (the `X-Avrix-Event-Log-Id` header).","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/WebhookConnectionRequestDecided"},"example":{"eventId":"6b04df35-39a6-49dc-838f-5293af789ee5","eventLogId":"a2b91209-87dc-47ab-8669-dbb5b3d19c93","eventType":"connection.request_decided","eventVersion":"1","occurredAt":"2026-11-02T09:30:00Z","replay":{"sourceDeliveryId":"e11015b5-6576-453f-8395-733546fa9c45","originalEventId":"2f247e2c-d035-41d8-8395-6bc598ec238a"},"testEvent":{"testRunId":"3dd3436d-4d73-4e0d-8b35-32dac977e873","challenge":"valid"},"requestId":"71d888e3-2116-4398-8f6d-a2ff2bdf43e0","decision":"approved","publisherCompanyId":"acme-games","connectionId":"32c304e5-7609-412b-8513-c134af63ca9f","reviewNote":"Example text.","requestedAt":"2026-11-02T09:30:00Z","decidedAt":"2026-11-02T09:30:00Z"}}}},"responses":{"200":{"description":"Acknowledge receipt. Return 2xx quickly; process asynchronously."}},"parameters":[{"$ref":"#/components/parameters/WebhookSignature"},{"$ref":"#/components/parameters/WebhookSignatureVersion"},{"$ref":"#/components/parameters/WebhookEventId"},{"$ref":"#/components/parameters/WebhookEventLogId"},{"$ref":"#/components/parameters/WebhookEventType"},{"$ref":"#/components/parameters/WebhookEventVersion"},{"$ref":"#/components/parameters/WebhookDeliveryId"}]}},"access_proposal_created":{"post":{"operationId":"webhook_access_proposal_created","summary":"access.proposal_created","description":"Avrix delivers `access.proposal_created` to your registered HTTPS endpoint when it subscribes to it. Verify the signature before processing. Events may be delivered more than once; deduplicate on `eventLogId` (the `X-Avrix-Event-Log-Id` header).","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/WebhookAccessProposalCreated"},"example":{"eventId":"28228452-cba7-418a-896b-7eadc26abf9f","eventLogId":"1e0b94c1-d282-4cb8-84d7-a925a19aeccb","eventType":"access.proposal_created","eventVersion":"1","occurredAt":"2026-11-02T09:30:00Z","replay":{"sourceDeliveryId":"02c51e9f-eb80-4ec1-8003-d4628088abea","originalEventId":"cced27bf-964d-4593-848b-a8fb1ec4e80f"},"testEvent":{"testRunId":"fb920aea-f900-4196-89c5-6c04b1209f46","challenge":"valid"},"proposalId":"8b4c3006-0789-4733-84ce-a66a4ec820e2","proposalType":"territory_added","connectionId":"cbbb5b62-1f05-4950-84aa-af338f204008","contractTermId":"5bcc51fa-a598-4bd8-86f9-47f7dcd50c86","publisherCompanyId":"acme-games","effectiveFrom":"2026-11-02T09:30:00Z","proposedAt":"2026-11-02T09:30:00Z"}}}},"responses":{"200":{"description":"Acknowledge receipt. Return 2xx quickly; process asynchronously."}},"parameters":[{"$ref":"#/components/parameters/WebhookSignature"},{"$ref":"#/components/parameters/WebhookSignatureVersion"},{"$ref":"#/components/parameters/WebhookEventId"},{"$ref":"#/components/parameters/WebhookEventLogId"},{"$ref":"#/components/parameters/WebhookEventType"},{"$ref":"#/components/parameters/WebhookEventVersion"},{"$ref":"#/components/parameters/WebhookDeliveryId"}]}},"return_decided":{"post":{"operationId":"webhook_return_decided","summary":"return.decided","description":"Avrix delivers `return.decided` to your registered HTTPS endpoint when it subscribes to it. Verify the signature before processing. Events may be delivered more than once; deduplicate on `eventLogId` (the `X-Avrix-Event-Log-Id` header).","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/WebhookReturnDecided"},"example":{"eventId":"cc440b37-f113-466d-85a5-c10c0d729fa5","eventLogId":"d66b4cdc-e6e2-45c7-80c4-ca8694934484","eventType":"return.decided","eventVersion":"1","occurredAt":"2026-11-02T09:30:00Z","replay":{"sourceDeliveryId":"f898c206-dd58-40cf-8d30-a2596fa0efec","originalEventId":"880e9c02-d5c8-4535-8661-eb551fca6efd"},"testEvent":{"testRunId":"b769ca05-750a-4426-8c90-76b6007a9224","challenge":"valid"},"returnRequestId":"175e93ed-fea1-429f-8a20-93ad97d01b6c","decision":"approved","resolution":"refund","publisherCompanyId":"acme-games","keyCount":12,"decisionNote":"Example text.","decidedAt":"2026-11-02T09:30:00Z"}}}},"responses":{"200":{"description":"Acknowledge receipt. Return 2xx quickly; process asynchronously."}},"parameters":[{"$ref":"#/components/parameters/WebhookSignature"},{"$ref":"#/components/parameters/WebhookSignatureVersion"},{"$ref":"#/components/parameters/WebhookEventId"},{"$ref":"#/components/parameters/WebhookEventLogId"},{"$ref":"#/components/parameters/WebhookEventType"},{"$ref":"#/components/parameters/WebhookEventVersion"},{"$ref":"#/components/parameters/WebhookDeliveryId"}]}},"return_information_requested":{"post":{"operationId":"webhook_return_information_requested","summary":"return.information_requested","description":"Avrix delivers `return.information_requested` to your registered HTTPS endpoint when it subscribes to it. Verify the signature before processing. Events may be delivered more than once; deduplicate on `eventLogId` (the `X-Avrix-Event-Log-Id` header).","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/WebhookReturnInformationRequested"},"example":{"eventId":"b0b9ba83-d688-4b8b-84b6-343926fd0dd4","eventLogId":"1da6adbf-32d0-4a8c-8960-8311eeec7deb","eventType":"return.information_requested","eventVersion":"1","occurredAt":"2026-11-02T09:30:00Z","replay":{"sourceDeliveryId":"7832750a-54cf-4fe2-829b-5dad17ef83f0","originalEventId":"320b2fc6-573c-4171-85e7-9847f6ccef42"},"testEvent":{"testRunId":"44bd5d66-5786-47ba-83b9-43759f4c55fb","challenge":"valid"},"returnRequestId":"19e0c87e-3b4f-46b9-8702-5e2899c8cadf","publisherCompanyId":"acme-games","requestedAt":"2026-11-02T09:30:00Z"}}}},"responses":{"200":{"description":"Acknowledge receipt. Return 2xx quickly; process asynchronously."}},"parameters":[{"$ref":"#/components/parameters/WebhookSignature"},{"$ref":"#/components/parameters/WebhookSignatureVersion"},{"$ref":"#/components/parameters/WebhookEventId"},{"$ref":"#/components/parameters/WebhookEventLogId"},{"$ref":"#/components/parameters/WebhookEventType"},{"$ref":"#/components/parameters/WebhookEventVersion"},{"$ref":"#/components/parameters/WebhookDeliveryId"}]}},"promotion_offered":{"post":{"operationId":"webhook_promotion_offered","summary":"promotion.offered","description":"Avrix delivers `promotion.offered` to your registered HTTPS endpoint when it subscribes to it. Verify the signature before processing. Events may be delivered more than once; deduplicate on `eventLogId` (the `X-Avrix-Event-Log-Id` header).","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/WebhookPromotionOffered"},"example":{"eventId":"a69ab955-bff7-4c3d-8951-5cadcd231547","eventLogId":"f0408c0e-2e75-459e-89b3-68f5479d12b5","eventType":"promotion.offered","eventVersion":"1","occurredAt":"2026-11-02T09:30:00Z","replay":{"sourceDeliveryId":"ca0f4875-1cb8-4a8b-8fe8-632463e320bb","originalEventId":"da7c686f-0051-428e-89e8-31774541ce65"},"testEvent":{"testRunId":"959316db-26b2-4fdf-8584-9daa0f0ae940","challenge":"valid"},"sourceType":"event","sourceId":"dcc9995a-2c13-44d4-80d8-eed523896518","publisherCompanyId":"acme-games","name":"Example Game","status":"pending","startDate":"2026-11-02T09:30:00Z","endDate":"2026-11-02T09:30:00Z","respondBy":"2026-11-02T09:30:00Z"}}}},"responses":{"200":{"description":"Acknowledge receipt. Return 2xx quickly; process asynchronously."}},"parameters":[{"$ref":"#/components/parameters/WebhookSignature"},{"$ref":"#/components/parameters/WebhookSignatureVersion"},{"$ref":"#/components/parameters/WebhookEventId"},{"$ref":"#/components/parameters/WebhookEventLogId"},{"$ref":"#/components/parameters/WebhookEventType"},{"$ref":"#/components/parameters/WebhookEventVersion"},{"$ref":"#/components/parameters/WebhookDeliveryId"}]}},"promotion_changed":{"post":{"operationId":"webhook_promotion_changed","summary":"promotion.changed","description":"Avrix delivers `promotion.changed` to your registered HTTPS endpoint when it subscribes to it. Verify the signature before processing. Events may be delivered more than once; deduplicate on `eventLogId` (the `X-Avrix-Event-Log-Id` header).","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/WebhookPromotionChanged"},"example":{"eventId":"cc170401-3e7c-4d4f-8b75-318678d03216","eventLogId":"6a368506-ff83-473d-8dcc-c0896a96238d","eventType":"promotion.changed","eventVersion":"1","occurredAt":"2026-11-02T09:30:00Z","replay":{"sourceDeliveryId":"234407c5-f29a-4ef0-8570-c6b189d6855b","originalEventId":"fab4bc49-852d-4278-877d-c11b8dc24846"},"testEvent":{"testRunId":"4581d3b3-025e-4628-8b49-f00d229b5d33","challenge":"valid"},"sourceType":"event","sourceId":"3dc5f090-0d10-49eb-876a-7645b56226e3","publisherCompanyId":"acme-games","name":"Example Game","status":"pending","startDate":"2026-11-02T09:30:00Z","endDate":"2026-11-02T09:30:00Z","respondBy":"2026-11-02T09:30:00Z","changes":{"addedCount":12,"removedCount":12,"updatedCount":12},"answerAgain":true}}}},"responses":{"200":{"description":"Acknowledge receipt. Return 2xx quickly; process asynchronously."}},"parameters":[{"$ref":"#/components/parameters/WebhookSignature"},{"$ref":"#/components/parameters/WebhookSignatureVersion"},{"$ref":"#/components/parameters/WebhookEventId"},{"$ref":"#/components/parameters/WebhookEventLogId"},{"$ref":"#/components/parameters/WebhookEventType"},{"$ref":"#/components/parameters/WebhookEventVersion"},{"$ref":"#/components/parameters/WebhookDeliveryId"}]}},"promotion_accepted":{"post":{"operationId":"webhook_promotion_accepted","summary":"promotion.accepted","description":"Avrix delivers `promotion.accepted` to your registered HTTPS endpoint when it subscribes to it. Verify the signature before processing. Events may be delivered more than once; deduplicate on `eventLogId` (the `X-Avrix-Event-Log-Id` header).","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/WebhookPromotionAccepted"},"example":{"eventId":"ad968aac-9d44-4aab-8887-04d230b73f22","eventLogId":"2cc771ba-d6a1-432d-8c45-3008e080c988","eventType":"promotion.accepted","eventVersion":"1","occurredAt":"2026-11-02T09:30:00Z","replay":{"sourceDeliveryId":"b9d76112-7c44-4140-8b2e-480d779d46be","originalEventId":"9845761a-3653-44e8-8c3e-e4a3d02f814f"},"testEvent":{"testRunId":"b4c77743-02c3-4095-8d3a-8a0379bc8a87","challenge":"valid"},"sourceType":"event","sourceId":"fe2fa6c0-5817-477c-8c96-3f55c5a7a913","publisherCompanyId":"acme-games","name":"Example Game","status":"accepted","startDate":"2026-11-02T09:30:00Z","endDate":"2026-11-02T09:30:00Z","respondBy":"2026-11-02T09:30:00Z"}}}},"responses":{"200":{"description":"Acknowledge receipt. Return 2xx quickly; process asynchronously."}},"parameters":[{"$ref":"#/components/parameters/WebhookSignature"},{"$ref":"#/components/parameters/WebhookSignatureVersion"},{"$ref":"#/components/parameters/WebhookEventId"},{"$ref":"#/components/parameters/WebhookEventLogId"},{"$ref":"#/components/parameters/WebhookEventType"},{"$ref":"#/components/parameters/WebhookEventVersion"},{"$ref":"#/components/parameters/WebhookDeliveryId"}]}},"promotion_declined":{"post":{"operationId":"webhook_promotion_declined","summary":"promotion.declined","description":"Avrix delivers `promotion.declined` to your registered HTTPS endpoint when it subscribes to it. Verify the signature before processing. Events may be delivered more than once; deduplicate on `eventLogId` (the `X-Avrix-Event-Log-Id` header).","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/WebhookPromotionDeclined"},"example":{"eventId":"333f80ca-7dd3-407f-8524-3223100def61","eventLogId":"944be2e4-f059-4762-8657-a88452e9613d","eventType":"promotion.declined","eventVersion":"1","occurredAt":"2026-11-02T09:30:00Z","replay":{"sourceDeliveryId":"53beeb8d-8bb4-4cdf-8bc9-3e44710b290b","originalEventId":"6252c9b7-4e1a-44e0-8c68-fb7d4e9afd04"},"testEvent":{"testRunId":"484825ea-2408-4d8c-810d-4837b6bee8a4","challenge":"valid"},"sourceType":"event","sourceId":"924745fa-d56a-4d0e-8b0d-a212eccd30b0","publisherCompanyId":"acme-games","name":"Example Game","status":"declined","startDate":"2026-11-02T09:30:00Z","endDate":"2026-11-02T09:30:00Z","respondBy":"2026-11-02T09:30:00Z"}}}},"responses":{"200":{"description":"Acknowledge receipt. Return 2xx quickly; process asynchronously."}},"parameters":[{"$ref":"#/components/parameters/WebhookSignature"},{"$ref":"#/components/parameters/WebhookSignatureVersion"},{"$ref":"#/components/parameters/WebhookEventId"},{"$ref":"#/components/parameters/WebhookEventLogId"},{"$ref":"#/components/parameters/WebhookEventType"},{"$ref":"#/components/parameters/WebhookEventVersion"},{"$ref":"#/components/parameters/WebhookDeliveryId"}]}},"promotion_withdrawn":{"post":{"operationId":"webhook_promotion_withdrawn","summary":"promotion.withdrawn","description":"Avrix delivers `promotion.withdrawn` to your registered HTTPS endpoint when it subscribes to it. Verify the signature before processing. Events may be delivered more than once; deduplicate on `eventLogId` (the `X-Avrix-Event-Log-Id` header).","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/WebhookPromotionWithdrawn"},"example":{"eventId":"3bd01abb-b907-461e-835a-d11389ffa82a","eventLogId":"ebbd35ac-219d-44a9-8bc7-84e7b8e8fd18","eventType":"promotion.withdrawn","eventVersion":"1","occurredAt":"2026-11-02T09:30:00Z","replay":{"sourceDeliveryId":"39fe65d1-a074-4f6e-8df2-9a951dbbd57a","originalEventId":"773700b2-1624-46a6-88ef-269b104e0735"},"testEvent":{"testRunId":"f1154fd4-75f8-4cef-8f20-7b0cd7a529d9","challenge":"valid"},"sourceType":"event","sourceId":"46a834d3-9b45-48d2-8c91-ae93e682ae56","publisherCompanyId":"acme-games","name":"Example Game","status":"vendor_withdrawn","startDate":"2026-11-02T09:30:00Z","endDate":"2026-11-02T09:30:00Z","respondBy":"2026-11-02T09:30:00Z"}}}},"responses":{"200":{"description":"Acknowledge receipt. Return 2xx quickly; process asynchronously."}},"parameters":[{"$ref":"#/components/parameters/WebhookSignature"},{"$ref":"#/components/parameters/WebhookSignatureVersion"},{"$ref":"#/components/parameters/WebhookEventId"},{"$ref":"#/components/parameters/WebhookEventLogId"},{"$ref":"#/components/parameters/WebhookEventType"},{"$ref":"#/components/parameters/WebhookEventVersion"},{"$ref":"#/components/parameters/WebhookDeliveryId"}]}},"promotion_expired":{"post":{"operationId":"webhook_promotion_expired","summary":"promotion.expired","description":"Avrix delivers `promotion.expired` to your registered HTTPS endpoint when it subscribes to it. Verify the signature before processing. Events may be delivered more than once; deduplicate on `eventLogId` (the `X-Avrix-Event-Log-Id` header).","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/WebhookPromotionExpired"},"example":{"eventId":"e8b9f500-c2ac-4cc8-8b01-39e341c0ee75","eventLogId":"cc7a1d4d-9367-4655-8b1e-ab6d6a25fa9b","eventType":"promotion.expired","eventVersion":"1","occurredAt":"2026-11-02T09:30:00Z","replay":{"sourceDeliveryId":"40baa5ad-e0b7-4140-82b0-de18ee21a8aa","originalEventId":"f99f0226-6ac9-486c-8545-f6b3a7632269"},"testEvent":{"testRunId":"3755ba02-7657-48e1-8620-a975b9d35bfb","challenge":"valid"},"sourceType":"event","sourceId":"536ef01f-5d63-4247-8572-366e59f49ab3","publisherCompanyId":"acme-games","name":"Example Game","status":"expired","startDate":"2026-11-02T09:30:00Z","endDate":"2026-11-02T09:30:00Z","respondBy":"2026-11-02T09:30:00Z"}}}},"responses":{"200":{"description":"Acknowledge receipt. Return 2xx quickly; process asynchronously."}},"parameters":[{"$ref":"#/components/parameters/WebhookSignature"},{"$ref":"#/components/parameters/WebhookSignatureVersion"},{"$ref":"#/components/parameters/WebhookEventId"},{"$ref":"#/components/parameters/WebhookEventLogId"},{"$ref":"#/components/parameters/WebhookEventType"},{"$ref":"#/components/parameters/WebhookEventVersion"},{"$ref":"#/components/parameters/WebhookDeliveryId"}]}},"promotion_started":{"post":{"operationId":"webhook_promotion_started","summary":"promotion.started","description":"Avrix delivers `promotion.started` to your registered HTTPS endpoint when it subscribes to it. Verify the signature before processing. Events may be delivered more than once; deduplicate on `eventLogId` (the `X-Avrix-Event-Log-Id` header).","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/WebhookPromotionStarted"},"example":{"eventId":"4cc4bd7d-0a54-4879-8cb8-5ccb9fd60153","eventLogId":"559fec7b-9c17-4f92-87a2-9bed90a42c23","eventType":"promotion.started","eventVersion":"1","occurredAt":"2026-11-02T09:30:00Z","replay":{"sourceDeliveryId":"a292922e-457a-4ebe-867a-467f515ad82c","originalEventId":"366aee3d-9fbf-402d-81d0-af5e053c5171"},"testEvent":{"testRunId":"deadead1-a8f1-4b51-82bd-36e295d149d8","challenge":"valid"},"sourceType":"event","sourceId":"c3537b6a-a158-46ba-8269-450db3732c2c","publisherCompanyId":"acme-games","name":"Example Game","status":"accepted","startDate":"2026-11-02T09:30:00Z","endDate":"2026-11-02T09:30:00Z","respondBy":"2026-11-02T09:30:00Z"}}}},"responses":{"200":{"description":"Acknowledge receipt. Return 2xx quickly; process asynchronously."}},"parameters":[{"$ref":"#/components/parameters/WebhookSignature"},{"$ref":"#/components/parameters/WebhookSignatureVersion"},{"$ref":"#/components/parameters/WebhookEventId"},{"$ref":"#/components/parameters/WebhookEventLogId"},{"$ref":"#/components/parameters/WebhookEventType"},{"$ref":"#/components/parameters/WebhookEventVersion"},{"$ref":"#/components/parameters/WebhookDeliveryId"}]}},"promotion_ended":{"post":{"operationId":"webhook_promotion_ended","summary":"promotion.ended","description":"Avrix delivers `promotion.ended` to your registered HTTPS endpoint when it subscribes to it. Verify the signature before processing. Events may be delivered more than once; deduplicate on `eventLogId` (the `X-Avrix-Event-Log-Id` header).","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/WebhookPromotionEnded"},"example":{"eventId":"e29dbb6a-a58a-48cd-854b-edfdf3186560","eventLogId":"76569707-ed6a-45d2-804e-1d2688617b4e","eventType":"promotion.ended","eventVersion":"1","occurredAt":"2026-11-02T09:30:00Z","replay":{"sourceDeliveryId":"3035aea9-003b-4dc9-8592-06fccce7ddd0","originalEventId":"b745bb90-738d-490b-84fb-d49229eac98b"},"testEvent":{"testRunId":"3491abb5-ef1b-48b8-8726-7b6df7d1ea7f","challenge":"valid"},"sourceType":"event","sourceId":"b11a2671-b380-4a93-82c1-6c3b9ea77d6c","publisherCompanyId":"acme-games","name":"Example Game","status":"accepted","startDate":"2026-11-02T09:30:00Z","endDate":"2026-11-02T09:30:00Z","respondBy":"2026-11-02T09:30:00Z"}}}},"responses":{"200":{"description":"Acknowledge receipt. Return 2xx quickly; process asynchronously."}},"parameters":[{"$ref":"#/components/parameters/WebhookSignature"},{"$ref":"#/components/parameters/WebhookSignatureVersion"},{"$ref":"#/components/parameters/WebhookEventId"},{"$ref":"#/components/parameters/WebhookEventLogId"},{"$ref":"#/components/parameters/WebhookEventType"},{"$ref":"#/components/parameters/WebhookEventVersion"},{"$ref":"#/components/parameters/WebhookDeliveryId"}]}},"invoice_issued":{"post":{"operationId":"webhook_invoice_issued","summary":"invoice.issued","description":"Avrix delivers `invoice.issued` to your registered HTTPS endpoint when it subscribes to it. Verify the signature before processing. Events may be delivered more than once; deduplicate on `eventLogId` (the `X-Avrix-Event-Log-Id` header).","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/WebhookInvoiceIssued"},"example":{"eventId":"c4aafd79-281f-4771-8240-449a251e963a","eventLogId":"8e63ad3a-0fbd-4eba-875a-afcf1b5b43e8","eventType":"invoice.issued","eventVersion":"1","occurredAt":"2026-11-02T09:30:00Z","replay":{"sourceDeliveryId":"f37ab58b-8199-4d66-85e7-14b918eb69d4","originalEventId":"aa633e20-daa7-4fc5-8217-b414b25ddbca"},"testEvent":{"testRunId":"a728f005-7a0f-4bf0-8251-4f8aaab910ee","challenge":"valid"},"invoiceId":"24d51500-5ee0-43c0-8151-049cdc6839c7","invoiceNumber":"INV-2026-10-0042","publisherCompanyId":"acme-games","status":"draft","totalCents":2450,"currencyCode":"EUR","currencyExponent":2,"issuedAt":"2026-11-02T09:30:00Z","dueAt":"2026-11-02T09:30:00Z"}}}},"responses":{"200":{"description":"Acknowledge receipt. Return 2xx quickly; process asynchronously."}},"parameters":[{"$ref":"#/components/parameters/WebhookSignature"},{"$ref":"#/components/parameters/WebhookSignatureVersion"},{"$ref":"#/components/parameters/WebhookEventId"},{"$ref":"#/components/parameters/WebhookEventLogId"},{"$ref":"#/components/parameters/WebhookEventType"},{"$ref":"#/components/parameters/WebhookEventVersion"},{"$ref":"#/components/parameters/WebhookDeliveryId"}]}},"invoice_paid":{"post":{"operationId":"webhook_invoice_paid","summary":"invoice.paid","description":"Avrix delivers `invoice.paid` to your registered HTTPS endpoint when it subscribes to it. Verify the signature before processing. Events may be delivered more than once; deduplicate on `eventLogId` (the `X-Avrix-Event-Log-Id` header).","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/WebhookInvoicePaid"},"example":{"eventId":"a5d32323-979a-48d9-8961-33d9d324d41e","eventLogId":"491c3a91-f3fa-4538-8af7-85bd75df388d","eventType":"invoice.paid","eventVersion":"1","occurredAt":"2026-11-02T09:30:00Z","replay":{"sourceDeliveryId":"96e29825-cbc2-455c-8377-f6362722a066","originalEventId":"62cd3740-335c-496e-88b7-9d71f9b08ead"},"testEvent":{"testRunId":"8917ff05-0a19-417a-8b7b-9062bbf301ee","challenge":"valid"},"invoiceId":"a07daa61-50eb-4862-8c77-7a8916b6f309","invoiceNumber":"INV-2026-10-0042","publisherCompanyId":"acme-games","status":"draft","totalCents":2450,"currencyCode":"EUR","currencyExponent":2,"issuedAt":"2026-11-02T09:30:00Z","dueAt":"2026-11-02T09:30:00Z","paidAt":"2026-11-02T09:30:00Z"}}}},"responses":{"200":{"description":"Acknowledge receipt. Return 2xx quickly; process asynchronously."}},"parameters":[{"$ref":"#/components/parameters/WebhookSignature"},{"$ref":"#/components/parameters/WebhookSignatureVersion"},{"$ref":"#/components/parameters/WebhookEventId"},{"$ref":"#/components/parameters/WebhookEventLogId"},{"$ref":"#/components/parameters/WebhookEventType"},{"$ref":"#/components/parameters/WebhookEventVersion"},{"$ref":"#/components/parameters/WebhookDeliveryId"}]}},"invoice_overdue":{"post":{"operationId":"webhook_invoice_overdue","summary":"invoice.overdue","description":"Avrix delivers `invoice.overdue` to your registered HTTPS endpoint when it subscribes to it. Verify the signature before processing. Events may be delivered more than once; deduplicate on `eventLogId` (the `X-Avrix-Event-Log-Id` header).","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/WebhookInvoiceOverdue"},"example":{"eventId":"313ee4c1-363f-4586-821f-c54708a2ec2f","eventLogId":"f32116ce-ff32-4cd5-8287-6c39de788985","eventType":"invoice.overdue","eventVersion":"1","occurredAt":"2026-11-02T09:30:00Z","replay":{"sourceDeliveryId":"04b240dd-d3af-42c5-8abb-14682e6be4ce","originalEventId":"a9331d8a-8969-43b0-84de-1780cfa7aaa8"},"testEvent":{"testRunId":"6f5de1c2-9c65-43c3-8fc0-ecf27d1f3545","challenge":"valid"},"invoiceId":"b3d6a8a1-1fb4-4f8a-8f76-a32039af413c","invoiceNumber":"INV-2026-10-0042","publisherCompanyId":"acme-games","status":"active","totalMinor":2450,"currencyCode":"EUR","currencyExponent":2,"issuedAt":"2026-11-02T09:30:00Z","dueAt":"2026-11-02T09:30:00Z","replacesInvoiceId":"a4a3a532-44e4-4491-8782-e371c652eb91"}}}},"responses":{"200":{"description":"Acknowledge receipt. Return 2xx quickly; process asynchronously."}},"parameters":[{"$ref":"#/components/parameters/WebhookSignature"},{"$ref":"#/components/parameters/WebhookSignatureVersion"},{"$ref":"#/components/parameters/WebhookEventId"},{"$ref":"#/components/parameters/WebhookEventLogId"},{"$ref":"#/components/parameters/WebhookEventType"},{"$ref":"#/components/parameters/WebhookEventVersion"},{"$ref":"#/components/parameters/WebhookDeliveryId"}]}},"invoice_disputed":{"post":{"operationId":"webhook_invoice_disputed","summary":"invoice.disputed","description":"Avrix delivers `invoice.disputed` to your registered HTTPS endpoint when it subscribes to it. Verify the signature before processing. Events may be delivered more than once; deduplicate on `eventLogId` (the `X-Avrix-Event-Log-Id` header).","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/WebhookInvoiceDisputed"},"example":{"eventId":"1131a300-8235-4dac-88a2-a1727ca65908","eventLogId":"236e9c61-31e9-44c0-8d98-d3817ee9cc98","eventType":"invoice.disputed","eventVersion":"1","occurredAt":"2026-11-02T09:30:00Z","replay":{"sourceDeliveryId":"72e73f44-2bbf-4eba-8f94-0ee51a8c4db4","originalEventId":"182a1f0f-7990-49fb-82be-e8b33b4169ef"},"testEvent":{"testRunId":"ecd9fc02-08c2-4197-863c-465441fda560","challenge":"valid"},"invoiceId":"b381688d-d417-464a-86f1-7c262b4d86be","invoiceNumber":"INV-2026-10-0042","publisherCompanyId":"acme-games","status":"active","totalMinor":2450,"currencyCode":"EUR","currencyExponent":2,"issuedAt":"2026-11-02T09:30:00Z","dueAt":"2026-11-02T09:30:00Z","replacesInvoiceId":"b4ec05a4-2cb8-46e0-81cb-db37698151aa","disputeId":"a5095731-18be-45b0-864b-4c647d109b1b"}}}},"responses":{"200":{"description":"Acknowledge receipt. Return 2xx quickly; process asynchronously."}},"parameters":[{"$ref":"#/components/parameters/WebhookSignature"},{"$ref":"#/components/parameters/WebhookSignatureVersion"},{"$ref":"#/components/parameters/WebhookEventId"},{"$ref":"#/components/parameters/WebhookEventLogId"},{"$ref":"#/components/parameters/WebhookEventType"},{"$ref":"#/components/parameters/WebhookEventVersion"},{"$ref":"#/components/parameters/WebhookDeliveryId"}]}},"invoice_dispute_updated":{"post":{"operationId":"webhook_invoice_dispute_updated","summary":"invoice.dispute_updated","description":"Avrix delivers `invoice.dispute_updated` to your registered HTTPS endpoint when it subscribes to it. Verify the signature before processing. Events may be delivered more than once; deduplicate on `eventLogId` (the `X-Avrix-Event-Log-Id` header).","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/WebhookInvoiceDisputeUpdated"},"example":{"eventId":"860eab1a-7446-4990-878f-431e05b51245","eventLogId":"fe4771c8-03f8-4011-81db-87c9626436cc","eventType":"invoice.dispute_updated","eventVersion":"1","occurredAt":"2026-11-02T09:30:00Z","replay":{"sourceDeliveryId":"6446cae6-4fd3-4bd5-80af-eff150bb8685","originalEventId":"02bb93fb-16f9-4acc-8418-60fa210cb56a"},"testEvent":{"testRunId":"61512927-52dc-41e3-87fa-99180b3bcee4","challenge":"valid"},"invoiceId":"b3c73db3-7cce-4691-8ed2-6b35fc5bbf5a","invoiceNumber":"INV-2026-10-0042","publisherCompanyId":"acme-games","status":"active","totalMinor":2450,"currencyCode":"EUR","currencyExponent":2,"issuedAt":"2026-11-02T09:30:00Z","dueAt":"2026-11-02T09:30:00Z","replacesInvoiceId":"f815e184-42f7-4837-8462-505f08eccb46","disputeId":"c7cf0f15-e996-4c1c-8d78-e50c7bf863c7","outcome":"accepted"}}}},"responses":{"200":{"description":"Acknowledge receipt. Return 2xx quickly; process asynchronously."}},"parameters":[{"$ref":"#/components/parameters/WebhookSignature"},{"$ref":"#/components/parameters/WebhookSignatureVersion"},{"$ref":"#/components/parameters/WebhookEventId"},{"$ref":"#/components/parameters/WebhookEventLogId"},{"$ref":"#/components/parameters/WebhookEventType"},{"$ref":"#/components/parameters/WebhookEventVersion"},{"$ref":"#/components/parameters/WebhookDeliveryId"}]}},"api_key_created":{"post":{"operationId":"webhook_api_key_created","summary":"api_key.created","description":"Avrix delivers `api_key.created` to your registered HTTPS endpoint when it subscribes to it. Verify the signature before processing. Events may be delivered more than once; deduplicate on `eventLogId` (the `X-Avrix-Event-Log-Id` header).","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/WebhookApiKeyCreated"},"example":{"eventId":"8ab62095-8b1f-4aaf-8b8c-25c6d4c9dc35","eventLogId":"102293c1-61e1-462d-8bec-1c4ab8bdceb6","eventType":"api_key.created","eventVersion":"1","occurredAt":"2026-11-02T09:30:00Z","replay":{"sourceDeliveryId":"f0802f86-6c95-432c-878f-8b62835ac21a","originalEventId":"3de2ed2b-a01e-433a-8a50-8aef6a645dec"},"testEvent":{"testRunId":"93117fb3-9eec-486b-84be-42e1dea1fc4a","challenge":"valid"},"keyId":"5250d803-fdad-4220-8c86-caf8e0477b9b","apiKeyId":"5250d803-fdad-4220-8c86-caf8e0477b9b","via":"console","changedAt":"2026-11-02T09:30:00Z"}}}},"responses":{"200":{"description":"Acknowledge receipt. Return 2xx quickly; process asynchronously."}},"parameters":[{"$ref":"#/components/parameters/WebhookSignature"},{"$ref":"#/components/parameters/WebhookSignatureVersion"},{"$ref":"#/components/parameters/WebhookEventId"},{"$ref":"#/components/parameters/WebhookEventLogId"},{"$ref":"#/components/parameters/WebhookEventType"},{"$ref":"#/components/parameters/WebhookEventVersion"},{"$ref":"#/components/parameters/WebhookDeliveryId"}]}},"api_key_rotated":{"post":{"operationId":"webhook_api_key_rotated","summary":"api_key.rotated","description":"Avrix delivers `api_key.rotated` to your registered HTTPS endpoint when it subscribes to it. Verify the signature before processing. Events may be delivered more than once; deduplicate on `eventLogId` (the `X-Avrix-Event-Log-Id` header).","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/WebhookApiKeyRotated"},"example":{"eventId":"9eeab5ee-c2ea-467d-82d5-70879809e3b4","eventLogId":"eca8d871-30be-4c42-856f-bcf5203b77cf","eventType":"api_key.rotated","eventVersion":"1","occurredAt":"2026-11-02T09:30:00Z","replay":{"sourceDeliveryId":"3fbe1a14-6641-4b37-8dc5-cbf7a65ee0d2","originalEventId":"cbe2d290-2713-4ada-86a8-869adbb2fa14"},"testEvent":{"testRunId":"2ee9b6e9-871e-4494-8b5f-ca130893d3fc","challenge":"valid"},"keyId":"0dc17e4b-eaf4-45dc-83a1-7fbed9d52b85","apiKeyId":"0dc17e4b-eaf4-45dc-83a1-7fbed9d52b85","via":"console","changedAt":"2026-11-02T09:30:00Z"}}}},"responses":{"200":{"description":"Acknowledge receipt. Return 2xx quickly; process asynchronously."}},"parameters":[{"$ref":"#/components/parameters/WebhookSignature"},{"$ref":"#/components/parameters/WebhookSignatureVersion"},{"$ref":"#/components/parameters/WebhookEventId"},{"$ref":"#/components/parameters/WebhookEventLogId"},{"$ref":"#/components/parameters/WebhookEventType"},{"$ref":"#/components/parameters/WebhookEventVersion"},{"$ref":"#/components/parameters/WebhookDeliveryId"}]}},"api_key_revoked":{"post":{"operationId":"webhook_api_key_revoked","summary":"api_key.revoked","description":"Avrix delivers `api_key.revoked` to your registered HTTPS endpoint when it subscribes to it. Verify the signature before processing. Events may be delivered more than once; deduplicate on `eventLogId` (the `X-Avrix-Event-Log-Id` header).","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/WebhookApiKeyRevoked"},"example":{"eventId":"1172c4db-a285-4232-808b-2046040c5589","eventLogId":"ba49d1df-5712-4faf-8a2a-086b67b4e448","eventType":"api_key.revoked","eventVersion":"1","occurredAt":"2026-11-02T09:30:00Z","replay":{"sourceDeliveryId":"86fd60da-04be-403e-885f-eaed89d13933","originalEventId":"914dffe5-f72c-4f00-859a-2d48ac83e782"},"testEvent":{"testRunId":"e41dee1a-e390-4a55-8e14-3b73e36e5572","challenge":"valid"},"keyId":"2ef12f92-d719-46c6-8e90-60e649cfe008","apiKeyId":"2ef12f92-d719-46c6-8e90-60e649cfe008","via":"console","changedAt":"2026-11-02T09:30:00Z"}}}},"responses":{"200":{"description":"Acknowledge receipt. Return 2xx quickly; process asynchronously."}},"parameters":[{"$ref":"#/components/parameters/WebhookSignature"},{"$ref":"#/components/parameters/WebhookSignatureVersion"},{"$ref":"#/components/parameters/WebhookEventId"},{"$ref":"#/components/parameters/WebhookEventLogId"},{"$ref":"#/components/parameters/WebhookEventType"},{"$ref":"#/components/parameters/WebhookEventVersion"},{"$ref":"#/components/parameters/WebhookDeliveryId"}]}},"sandbox_certification_passed":{"post":{"operationId":"webhook_sandbox_certification_passed","summary":"sandbox.certification_passed","description":"Avrix delivers `sandbox.certification_passed` to your registered HTTPS endpoint when it subscribes to it. Verify the signature before processing. Events may be delivered more than once; deduplicate on `eventLogId` (the `X-Avrix-Event-Log-Id` header).","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/WebhookSandboxCertificationPassed"},"example":{"eventId":"b10f6ee6-e420-48df-8bac-ce093714dcfe","eventLogId":"81445ea1-5217-42e2-8dcb-5ff93d6016c2","eventType":"sandbox.certification_passed","eventVersion":"1","occurredAt":"2026-11-02T09:30:00Z","replay":{"sourceDeliveryId":"39654ef8-a7f6-492a-8e0b-9f5d8eb9f222","originalEventId":"a8e7af2e-984a-42a7-8b02-29d0ad741545"},"testEvent":{"testRunId":"383cd43e-556d-4610-84ad-bb662cb7af43","challenge":"valid"},"keyId":"44fc87ed-6404-4eb7-8547-906b4d9a757a","keyName":"Storefront production key","environment":"sandbox","reportVersion":1,"caseCount":12,"firstPass":true,"passedAt":"2026-11-02T09:30:00Z"}}}},"responses":{"200":{"description":"Acknowledge receipt. Return 2xx quickly; process asynchronously."}},"parameters":[{"$ref":"#/components/parameters/WebhookSignature"},{"$ref":"#/components/parameters/WebhookSignatureVersion"},{"$ref":"#/components/parameters/WebhookEventId"},{"$ref":"#/components/parameters/WebhookEventLogId"},{"$ref":"#/components/parameters/WebhookEventType"},{"$ref":"#/components/parameters/WebhookEventVersion"},{"$ref":"#/components/parameters/WebhookDeliveryId"}]}},"api_key_expiring":{"post":{"operationId":"webhook_api_key_expiring","summary":"api_key.expiring","description":"Avrix delivers `api_key.expiring` to your registered HTTPS endpoint when it subscribes to it. Verify the signature before processing. Events may be delivered more than once; deduplicate on `eventLogId` (the `X-Avrix-Event-Log-Id` header).","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/WebhookApiKeyExpiring"},"example":{"eventId":"cef3b0f3-5a32-4330-8824-9b2fb6018270","eventLogId":"c3410f81-93d1-4f0c-8d70-8484282e4902","eventType":"api_key.expiring","eventVersion":"1","occurredAt":"2026-11-02T09:30:00Z","replay":{"sourceDeliveryId":"6611e023-21fb-4866-8655-3e30e074f807","originalEventId":"54207ab3-c6b8-4a29-8537-37bf01494351"},"testEvent":{"testRunId":"941c6c46-8bc4-4691-8962-72a82455242c","challenge":"valid"},"keyId":"a1fc5610-6198-4bc6-806e-b7c18db9ca28","keyName":"Storefront production key","environment":"production","expiresAt":"2026-11-02T09:30:00Z"}}}},"responses":{"200":{"description":"Acknowledge receipt. Return 2xx quickly; process asynchronously."}},"parameters":[{"$ref":"#/components/parameters/WebhookSignature"},{"$ref":"#/components/parameters/WebhookSignatureVersion"},{"$ref":"#/components/parameters/WebhookEventId"},{"$ref":"#/components/parameters/WebhookEventLogId"},{"$ref":"#/components/parameters/WebhookEventType"},{"$ref":"#/components/parameters/WebhookEventVersion"},{"$ref":"#/components/parameters/WebhookDeliveryId"}]}},"api_key_expired":{"post":{"operationId":"webhook_api_key_expired","summary":"api_key.expired","description":"Avrix delivers `api_key.expired` to your registered HTTPS endpoint when it subscribes to it. Verify the signature before processing. Events may be delivered more than once; deduplicate on `eventLogId` (the `X-Avrix-Event-Log-Id` header).","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/WebhookApiKeyExpired"},"example":{"eventId":"067e84ed-30c7-4de2-809c-bea061b909eb","eventLogId":"ebdc6aa6-9c60-418e-8e64-c57e59395ac6","eventType":"api_key.expired","eventVersion":"1","occurredAt":"2026-11-02T09:30:00Z","replay":{"sourceDeliveryId":"626a4c9c-a503-4008-8c01-434fcb54d7ce","originalEventId":"8565d66d-521c-45ec-848d-516c9eb1f95e"},"testEvent":{"testRunId":"f1eda90f-cca1-46f9-896d-6797ce98c885","challenge":"valid"},"keyId":"2a20574a-b3d4-4792-8fcf-79b2db2fe594","keyName":"Storefront production key","environment":"production","expiresAt":"2026-11-02T09:30:00Z"}}}},"responses":{"200":{"description":"Acknowledge receipt. Return 2xx quickly; process asynchronously."}},"parameters":[{"$ref":"#/components/parameters/WebhookSignature"},{"$ref":"#/components/parameters/WebhookSignatureVersion"},{"$ref":"#/components/parameters/WebhookEventId"},{"$ref":"#/components/parameters/WebhookEventLogId"},{"$ref":"#/components/parameters/WebhookEventType"},{"$ref":"#/components/parameters/WebhookEventVersion"},{"$ref":"#/components/parameters/WebhookDeliveryId"}]}}}}