Versioning and deprecations
Understand URL versions, compatible changes, and how retired operations are announced.
The version in the URL tells you which API contract a request uses. Start with /v2 for new
integrations. Active /v1 operations remain documented where no v2 replacement
exists or compatibility is still supported.
The OpenAPI document has its own info.version: the release date of that
document, not a URL version. One document can describe both /v1 and /v2
endpoints. Do not copy its release date into your request path.
Compatibility policy
Within an active URL version, SellApp may add optional request fields, response fields, enum values, endpoints, events, or error detail. Human-readable messages and protective rate limits can also change. Clients must ignore unknown response fields and handle unknown enum values safely.
Breaking changes are changes that can require you to update working code. Removing or renaming a field, changing its type or meaning, making optional input required, or changing an operation's core side effect requires a new URL version or a documented migration window.
Deprecation lifecycle
Deprecated operations have deprecated: true in OpenAPI and an
x-sellapp-replacement value naming the replacement method and path. Retired
operations return 410 Gone; they remain in the contract so tooling can explain
the failure.
The legacy v1 listing and invoice operations are retired in favor of v2 product
and invoice operations. Other v1 resources are not automatically deprecated
merely because their path contains /v1.
Review the API changelog. A JSON feed is available at
/docs/api-changelog.json for automated filtering.