Versioning & compatibility

The Seller API is versioned at three layers:

1. URL version: /api/seller/v1/* is the canonical public route family for the current major contract (including finance under /api/seller/v1/finance/*). Every unversioned /api/seller/<segment>/* path redirects to its /v1/ form — the URL a doc shows is the URL that responds.
2. Date contract header: every response includes X-Avrix-Api-Version carrying the effective contract date for that request. The stamped default is 2026-04-29; 2026-09-01 is also supported as an opt-in pin (see Supported contract dates). This is the authoritative version marker — the OpenAPI info.version carries the default. Partners may send the same header on requests; unsupported values return 400 UNSUPPORTED_API_VERSION.
3. Legacy major marker (deprecated): every response also includes X-Api-Version: 1. It is deprecated — still emitted for compatibility and never bumped; do not build logic on it.
4. Webhook event version: every webhook delivery includes eventVersion in the JSON body and X-Avrix-Event-Version in headers.

Precedence: URL family (/v1) scopes the route surface; X-Avrix-Api-Version (date contract) governs field-level compatibility within that surface; X-Api-Version carries no compatibility meaning. When markers appear to disagree, the date contract wins.

OAuth routes use /api/seller/oauth/* (no /v1/ segment) but still emit both version headers.

Partner-facing guide notes and contract announcements also appear in the Changelog (documentation waves and notable partner notes). Treat that file as complementary to this page — breaking field/route changes are still governed here.

Do not treat X-Api-Version: 1 as a substitute for the date contract.

Partners may send:

X-Avrix-Api-Version: 2026-04-29

Unsupported future versions must not silently change behavior in production. Sandbox may support X-Avrix-Api-Version: next for dry-run warnings before a breaking migration.

Responses echo the effective date in the X-Avrix-Api-Version header — and POST /orders/bulk additionally echoes meta.contractDate + meta.strict in the body — so a client can assert which behavior profile served each call. From 2026-09-01 (UTC) unpinned requests are served the 2026-09-01 contract automatically; pin 2026-04-29 if you depend on partial-success bulk carts.

Clients MUST:

• Ignore unknown JSON fields in responses and webhook payloads.
• Ignore unknown enum values they do not understand (do not fail closed solely because a new enum member appeared).

Avrix may add optional fields and new enum members without bumping the major URL family. Strict parsers that reject unknowns will break on additive releases.

Avrix does not release any of the following without a versioned rollout, compatibility mode, or migration notice:

• New mandatory request fields.
• Removed or renamed response fields.
• Removed enum values or webhook event names.
• Changed webhook payload meaning.
• Stricter commercial metadata enforcement for existing production keys.

Avrix publishes changelog / guide entries before removing fields. The Active deprecations table lists a Sunset date when a removal is scheduled. There is no universal fixed-day SLA in product policy beyond that commitment.

Seller API responses do not emit Deprecation / Sunset headers by default. The mechanism is in place for contract dates: when a pinned X-Avrix-Api-Version value is scheduled for removal, the platform marks that contract date as deprecated and publishes a sunset date, and responses pinned to that date carry Deprecation: true, Sunset: <HTTP-date> and Link: <…/versioning>; rel="deprecation" (all three are CORS-exposed). Requests on a current date never see them. When a concrete sunset is scheduled for a field or route, we will:

1. Document the change and sunset date on this page and in the Changelog / release notes.
2. Start emitting Deprecation: true and Sunset: <HTTP-date> on affected responses (and re-add those names to Access-Control-Expose-Headers).
3. Keep X-Avrix-Api-Version as the stable version signal until then.

A public RSS/JSON deprecation feed remains a productized delivery surface for the developer hub.

Per-key compatibility mode is the preferred migration control. Old keys can remain on a previous behavior profile while new keys default to strict commercial metadata and contract authority gates. Compatibility mode must never bypass:

• Authentication, scopes, environment matching, or IP allowlists.
• Contract authority final checks.
• Idempotency for commercial mutations.
• PII redaction.
• Returned-key quarantine.

Webhook handlers should store and dedupe by eventId. eventVersion tells handlers which payload schema they received. Webhook delivery is at-least-once and not globally ordered; process events idempotently and reconcile using API reads when a handler was down.

Use since (ISO-8601) as the initial cursor: the server returns events with occurredAt strictly after since (exclusive). Each row is added, updated, or removed (tombstone) and carries changedFields[] so you refetch only changed facets. Page with limit (default 500, max 5000) and follow meta.nextCursor until it is absent. Pair with /catalog/snapshot and periodic /catalog/checksum; if checksum drifts or your cursor is older than the published retention window, cold-start. See Catalog and allocations.