> ## Documentation Index
> Fetch the complete documentation index at: https://docs.snappy.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Changelog

> Recent updates, new features, and breaking changes. Track API versions and migrate between releases.

All notable changes to the Snappy API are documented here. We follow Semantic Versioning.

<Note>
  **Breaking changes are marked with ⚠️.** We recommend subscribing to release notifications to stay informed of upcoming changes.
</Note>

***

## ⚠️ v3.1 - July 2026

| Endpoint                                | Changes                                                                                                                                                                                                          |
| --------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `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]`.                                                                                                                 |

## v3.0 - June 2026

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](/modules/api/v3/orders/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](/modules/api/v3/products/overview) and [Variants V3 Overview](/modules/api/v3/variants/overview).
* **V3 Swag (Base Products)** - branded swag templates and base variants exposed via the public API, replacing the standalone Covver integration. See [Swag](/pages/swag-overview).
* **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](/modules/api/v3/exports/overview).
* **V3 Billing Methods** - retrieve funding sources, check remaining balance, and view expiration. See [Billing Methods Overview](/pages/billing-methods).
* **V3 Accounts** - list, retrieve, and create sub-accounts under your Company. See [Accounts V3 Overview](/modules/api/v3/accounts/overview).
* **V3 API Keys Management** - programmatically create, rotate, and revoke API keys using an existing `X-Api-Key`. See [API Keys V3](/modules/api/v3/api-keys/overview).
* **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](/pages/request-response-standards).
* **Standardized error envelope** - every error response returns `{ message, errorCode, errors[] }` with structured `{status}_{DOMAIN}_{sequence}` error codes. See [Request & Response Standards](/pages/request-response-standards).
* **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](/pages/authentication-and-security).
* **PII masking via explicit scopes** - `<domain>:read:masked` returns masked PII; `<domain>:read:unmasked` returns full PII. See [Authentication & Security](/pages/authentication-and-security).

### ⚠️ 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](/pages/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.0 - February 2025

### 🆕 New

* **Granular API Permissions** - API keys can now be scoped to specific endpoints and actions. See [Authentication & Security](/pages/authentication-and-security).
* **PII Masking** - Personally Identifiable Information is now masked by default in API responses. Keys must explicitly enable sensitive data access. See [Authentication & Security](/pages/authentication-and-security).

### 🔄 Changed

* Base URL updated to `https://api.snappy.com/public-api/v2`.
* Pagination now uses `skip` and `limit` parameters. See [Request & Response Standards](/pages/request-response-standards).