All notable changes to the Snappy API are documented here. Entries are grouped by major API version (V3, V2) and appear in reverse chronological order. Breaking-change entries are marked with ⚠️.

We recommend subscribing to release notifications to stay informed of upcoming changes.

V3

September 2026 - Product ranking scores in export

Additive. POST /v3/products/exports and POST /v3/collections/exports now support a ranking value on the fields parameter. Opt in with fields: ["ranking"] to include Snappy’s per-country catalog-ranking score on each product in the exported NDJSON:

"ranking": {
  "US": { "rankingScore": 92 },
  "CA": { "rankingScore": 81 }
}

rankingScore is 0-100, higher is stronger. The score represents the product’s general standing within each country’s catalog and is independent of your filters, collection context, or response position. It does not represent search relevance.

September 2026 - Async order creation

Additive. POST /v3/orders is now asynchronous. The endpoint runs basic validation, creates the order, and returns 200 OK with status: "active". Snappy finalizes the order in the background — vendor confirmation for physical gifts, retrieving card details for digital gifts. When processing completes, the order transitions to status: "completed". Subscribe to the order-status-changed webhook to be notified. For digital variants (gift cards, e-vouchers, prepaid cards), do not call the Digital Cards API until the order reaches completed. The digital card entity is created as part of the async processing. The response envelope and id behavior are unchanged. See Orders overview for details.

September 2026 - API Keys scopes

Additive. Three new scopes for programmatic API key management: apiKeys:create, apiKeys:get, apiKeys:delete. Existing API keys were automatically granted the appropriate scope(s), so integrations that manage keys programmatically continue to work without changes. Assign the new scopes explicitly on any future keys used for key management.

Endpoint	Change
`POST /v3/authentication/api-keys`	Introduces `apiKeys:create`. A notification is sent to all Company admins when a key is created via the API.
`GET /v3/authentication/api-keys`	Introduces `apiKeys:get`.
`DELETE /v3/authentication/api-keys/{keyId}`	Introduces `apiKeys:delete`. A notification is sent to all Company admins when a key is deleted via the API.

See Authentication & Security → Available Scopes.

September 2026 - Order `status` enum cleanup

Doc cleanup. Removed refunded from the Order status enum documentation. This value was never emitted by the API. Valid values: active, completed, cancelled.

August 2026 - `shippingAddress` relaxed for digital variants

Additive. POST /v3/orders shippingAddress object is still required, but for variants where shippingRequired: false (e.g. gift cards, e-vouchers), only countryCode is required inside it. Physical variants (shippingRequired: true) continue to require the full address. Existing callers sending the full address are unaffected.

July 2026 - Digital Cards API launch

New API. Retrieve digital cards issued through Snappy (gift cards, prepaid cards, e-vouchers) and their access codes. Introduces the digitalCards:read scope.

Endpoint	Description
`GET /v3/digital-cards`	Retrieve a paginated list of digital cards. Supports `filter[orderId]`, `include=brand`, and page-number pagination. Introduces the `digitalCards:read` scope. See Digital Cards API.
`GET /v3/digital-cards/{digitalCardId}`	Retrieve a single digital card by its stable ID. Supports `include=brand`. Requires `digitalCards:read`.
`GET /v3/digital-cards/{digitalCardId}/access-code`	Retrieve the static access code for a digital card that uses `accessCode` authentication. Returns `422` for `OTP` cards. Requires `digitalCards:read`.

⚠️ July 2026 - Breaking changes to Accounts, address endpoints, and product-tags

Breaking. A batch of shape and parameter changes across Accounts, address validation/autocomplete, and product-tags. Update integrations that call any of these endpoints.

Endpoint	Change
`GET /v3/accounts`	Removed `companyId`, `createdAt`, `updatedAt`, and `full` from `fields`. Response now only returns `id` and `name`.
`GET /v3/accounts/{accountId}`	Response now only returns `id` and `name`, removing `companyId`, `createdAt`, and `updatedAt`.
`POST /v3/accounts`	`billingMethod` is now optional. When present, all billing method fields are required. Renamed `billingMethod.amount` to `billingMethod.spendingLimit.amount`. Response now only returns `id` and `name`.
`GET /v3/authentication/api-keys`	Removed `filter[accountId]` query parameter and related filtering/link logic.
`POST /v3/orders/addresses/validate`	Request body now matches create-order address shape: `address.address1`, `address.address2`, `address.city`, `address.provinceCode`, `address.postalCode`, `address.countryCode`. Removed top-level `country`.
`GET /v3/orders/addresses/autocomplete`	`filter[country]` is required and normalized to uppercase two-letter country code. Response now matches create-order address shape: `address1`, `address2`, `city`, `provinceCode`, `postalCode`, `countryCode`.
`GET /v3/product-tags`	Renamed query parameter `title` to `filter[name]`. Pagination links now preserve `filter[name]`.

June 2026 - V3 launch

V3 introduces a parallel API line for Marketplace, Orders, and Export, alongside refreshed Billing Methods and Accounts surfaces. V2 is not deprecated — V3 lives alongside V2 at https://api.snappy.com/public-api/v3 and uses the same X-Api-Key authentication. Pick the version that matches your endpoint path; the API key works for both.

🆕 New APIs

V3 Orders — single-call order placement replaces the old Campaign → Gift → Order chain. Orders are first-class resources, retrievable, listable, and cancellable independent of Gifts. See Orders V3 Overview.
V3 Marketplace — Products, Variants, and Collections with 85% lower catalog latency, static product and variant IDs that no longer change with real-time availability, default sorting by popularity, and enhanced semantic search. See Products V3 Overview and Variants V3 Overview.
V3 Swag (Base Products) — branded swag templates and base variants exposed via the public API, replacing the standalone Covver integration. See Swag.
V3 Export — asynchronous, NDJSON-based bulk catalog export for partners maintaining a local product mirror. Pair with stock-availability-updates webhooks for incremental refresh. See Export API.
V3 Billing Methods — retrieve funding sources, check remaining balance, and view expiration. See Billing Methods Overview.
V3 Accounts — list, retrieve, and create sub-accounts under your Company. See Accounts V3 Overview.
V3 API Keys Management — programmatically create, rotate, and revoke API keys using an existing X-Api-Key. See API Keys V3.
Product Recommendations — new endpoint surfaces related products to drive engagement.

🔄 New conventions in V3

JSON:API-style query syntax — filter[field], include, fields, sort, and page[number] / page[size] pagination (cursor pagination on product list endpoints). See Request & Response Standards.
Standardized error envelope — every error response returns { message, errorCode, errors[] } with structured {status}_{DOMAIN}_{sequence} error codes.
camelCase field names across all V3 endpoints, replacing the mixed casing in V2.
New scoping header — Snappy-Account-Id narrows a request to a specific sub-entity (RFC 6648 compliant; no X- prefix). See Authentication & Security.
PII masking via explicit scopes — <domain>:read:masked returns masked PII; <domain>:read:unmasked returns full PII.

V2 → V3 migration notes

V2 remains fully supported. No deprecation timeline. V3 is purely additive — the version is in the URL path (/v2/... vs /v3/...), and the same X-Api-Key authenticates both.
The Order entity is now independent of the Gift entity. In V2, orders are retrieved via their parent Gift. In V3:
- Orders are accessible directly via /v3/orders.
- Order-level webhooks fire alongside gift-level webhooks for V3 orders. See Webhook Event Types.
Pagination conventions differ between V2 and V3. V2 uses skip / limit; V3 uses page[number] / page[size] on most endpoints, with cursor pagination on product list endpoints.

V2

February 2025 - V2 launch

🆕 New

Granular API Permissions — API keys can now be scoped to specific endpoints and actions. See Authentication & Security.
PII Masking — Personally Identifiable Information is now masked by default in API responses. Keys must explicitly enable sensitive data access. See Authentication & Security.

🔄 Changed

Base URL updated to https://api.snappy.com/public-api/v2.
Pagination now uses skip and limit parameters. See Request & Response Standards.

​V3

​September 2026 - Product ranking scores in export

​September 2026 - Async order creation

​September 2026 - API Keys scopes

​September 2026 - Order status enum cleanup

​August 2026 - shippingAddress relaxed for digital variants

​July 2026 - Digital Cards API launch

​⚠️ July 2026 - Breaking changes to Accounts, address endpoints, and product-tags

​June 2026 - V3 launch

​🆕 New APIs

​🔄 New conventions in V3

​V2 → V3 migration notes

​V2

​February 2025 - V2 launch

​🆕 New

​🔄 Changed

V3

September 2026 - Product ranking scores in export

September 2026 - Async order creation

September 2026 - API Keys scopes

September 2026 - Order `status` enum cleanup

August 2026 - `shippingAddress` relaxed for digital variants

July 2026 - Digital Cards API launch

⚠️ July 2026 - Breaking changes to Accounts, address endpoints, and product-tags

June 2026 - V3 launch

🆕 New APIs

🔄 New conventions in V3

V2 → V3 migration notes

V2

February 2025 - V2 launch

🆕 New

🔄 Changed