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

⚠️ November 2026 - Billing method spending limit range on `POST /v3/accounts`

Breaking. billingMethod.spendingLimit.amount must now be between 0 and 1000000. Values outside that range return 400 (400_PBLC_001). billingMethod itself stays optional, but when it is provided, spendingLimit.amount is required and cannot be null.

⚠️ October 2026 - `401` responses return a string `errorCode`

Breaking. A 401 Unauthorized response, returned when X-Api-Key is missing or invalid, used to have a numeric errorCode (10000), unlike every other V3 error. It now returns 401_PBLC_001, matching the Error Handling page:

{ "status": 401, "errorCode": "401_PBLC_001", "message": "Unauthorized" }

If your integration reads errorCode as a number, or checks for 10000, update it to handle the string 401_PBLC_001.

⚠️ October 2026 - Tax number & postal code validation at order creation (effective November 12, 2026)

Breaking. To improve deliverability and prevent orders from failing later in fulfillment - customs holds, carrier rejections, and tax calculation errors - we’re moving two checks to order creation. Starting November 12, 2026:

Tax number - POST /v3/orders will reject orders shipping to the countries listed below if localizedFields.taxNumber is missing. Orders to all other countries are not affected.
Postal code - POST /v3/orders and POST /v3/orders/addresses/validate will reject postal codes that don’t match the destination country’s format.

Both checks fail immediately, so the input can be corrected and resubmitted right away instead of the order failing after it’s placed. Tax number - pass localizedFields.taxNumber for:

Destination	Required for
China (`CN`), Brazil (`BR`), Argentina (`AR`), Colombia (`CO`)	All orders
South Korea (`KR`), Italy (`IT`)	Swag orders

More countries will follow: Chile (CL), Ecuador (EC), Peru (PE), Uruguay (UY), Venezuela (VE). taxNumber is already accepted today and is ignored for countries that don’t require it, so we recommend sending it on every order where you have it. Postal code - postal codes will be validated against country-specific formats at order creation (for example, a US ZIP code containing letters will be rejected). Countries without a specific format keep the existing check.

Check	Endpoints	Status	`errorCode`
Missing tax number (countries listed above only)	`POST /v3/orders`	`400`	`400_ORDS_008`
Invalid postal code	`POST /v3/orders`, `POST /v3/orders/addresses/validate`	`400`	`400_ORDS_009`

What to do before November 12:

Add a tax number field to your checkout UI and collect it from users shipping to the countries above, then send it as localizedFields.taxNumber.
For user-entered addresses, call Validate order address before placing the order - it applies the same postal code check and returns 400_ORDS_009, so you can fix the address before the order is rejected. Autocomplete order address also helps users enter complete addresses in your UI.
Update your error handling to catch 400_ORDS_008 and 400_ORDS_009.

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": { "merchandisingScore": 92 },
  "CA": { "merchandisingScore": 81 }
}

merchandisingScore 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 through the public API. 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

⚠️ November 2026 - Billing method amount required on `POST /v2/accounts`

Breaking. billingMethod.amount is now required and must be between 0 and 1000000. Requests that omit it, send null, or send a value outside that range return 400. Previously an omitted amount created a billing method with no spending limit.

⚠️ October 2026 - `401` responses return a string `errorCode`

Breaking. A 401 Unauthorized response, returned when X-Api-Key is missing or invalid, now has a string errorCode, the same body V3 returns:

{ "status": 401, "errorCode": "401_PBLC_001", "message": "Unauthorized" }

Previously the body was { "status": 401, "errorCode": 10000, "message": "Unauthorized" }. If your integration reads errorCode as a number, or checks for 10000, update it to handle the string 401_PBLC_001. The status code and message are unchanged, and all other V2 error codes stay numeric.

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

​⚠️ November 2026 - Billing method spending limit range on POST /v3/accounts

​⚠️ October 2026 - 401 responses return a string errorCode

​⚠️ October 2026 - Tax number & postal code validation at order creation (effective November 12, 2026)

​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

​⚠️ November 2026 - Billing method amount required on POST /v2/accounts

​⚠️ October 2026 - 401 responses return a string errorCode

​February 2025 - V2 launch

​🆕 New

​🔄 Changed

V3

⚠️ November 2026 - Billing method spending limit range on `POST /v3/accounts`

⚠️ October 2026 - `401` responses return a string `errorCode`

⚠️ October 2026 - Tax number & postal code validation at order creation (effective November 12, 2026)

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

⚠️ November 2026 - Billing method amount required on `POST /v2/accounts`

⚠️ October 2026 - `401` responses return a string `errorCode`

February 2025 - V2 launch

🆕 New

🔄 Changed