Migrating from V2 to V3

This guide explains why you’d move an existing integration from V2 to V3, and how to do it endpoint by endpoint. V3 is the recommended standard for all new work.

Why migrate

V3 is a ground-up refresh that standardizes conventions across every endpoint and unlocks surfaces that V2 never exposed.

Area	What V3 gives you
Catalog performance	~85% lower catalog latency and static product/variant IDs that no longer change with real-time availability - so you can cache and store IDs safely.
Orders	Orders are first-class resources. Place an order in a single idempotent call instead of the V2 Campaign → Gift → claim chain, then retrieve, list, and cancel by `orderId`.
Consistency	One JSON:API convention set across all endpoints: `filter[...]`, `include`, `sort`, `page[...]`, and `camelCase` fields everywhere.
Discovery	Default sorting by popularity, enhanced semantic search, and a `marketplace` vs `swag` catalog split.
New surfaces	Billing Methods, asynchronous bulk Export, Swag base products, and Accounts - all introduced in V3.

You don’t have to migrate everything at once. A common path is: keep V2 gifting running, adopt V3 Marketplace for catalog reads first (biggest performance win, lowest risk), then move order placement to V3 Orders.

Before you begin

Your existing API key already works

The same X-Api-Key authenticates both V2 and V3. The version lives in the URL path - there is nothing new to provision to start calling V3.

# V2 - existing call
curl --request GET \
  --url https://api.snappy.com/public-api/v2/accounts \
  --header 'X-Api-Key: YOUR_API_KEY'

# V3 - same key, just the version in the path changes
curl --request GET \
  --url https://api.snappy.com/public-api/v3/accounts \
  --header 'X-Api-Key: YOUR_API_KEY'

Scopes are shared too: a key with products:read already reaches both /v2/products and /v3/products. See Authentication & Security for the full scope table.

Generating an API key (recap)

If you’re starting fresh or want a dedicated key for your V3 rollout:

Open Company Settings

Generate a key

Under API Access, click Generate Key, name it, and set an expiration (up to one year).

Assign scopes

Grant the minimum scopes your integration needs (e.g. products:read, orders:create, orders:read:masked). The same scopes apply to V2 and V3.

Configure PII access

Toggle Expose Sensitive Information to decide whether reads resolve to :read:masked or :read:unmasked.

Copy the secret immediately

The secret is shown once. Store it securely - if you lose it, rotate the key.

Two ways to manage API keys. Create and manage keys in the Snappy dashboard on the Sharing & Access page, or manage them programmatically with an existing X-Api-Key via the key-management endpoints (/v2/authentication/apiKeys or /v3/authentication/api-keys). See API Keys (V3).

New optional scoping header (V3)

V3 endpoints accept an optional header that narrows a request to a sub-entity. Omit it to run against the full org reachable by the key.

Header	Purpose
`Snappy-Account-Id`	Scope the request to a specific Account.

A few endpoints - currently the V3 Collections list and by-ID endpoints - require Snappy-Account-Id. Each reference page notes when it applies.

What changes at a glance

Most of the migration work is mechanical: swap the version in the path and adopt V3’s JSON:API query conventions. This table is your cheat sheet.

Convention	V2	V3
Base path	`/public-api/v2/...`	`/public-api/v3/...`
Field casing	Mixed (`firstname`, `orderRecipient`)	Consistent `camelCase`
Pagination	`skip` / `limit` (offset)	`page[number]` / `page[size]` - or `page[cursor]` / `page[size]` on product list endpoints
Related entities	`expand[]=product` (array)	`include=brand,tags` (comma-separated)
Filtering	Bespoke per endpoint (`minBudget`, `brandName`…)	`filter[field]=...`, ranges via `filter[field][gte]` / `[lte]`
Sorting	Bespoke per endpoint	`sort=field` / `sort=-field` (single field)
Field selection	`fields=id,name`	`fields=id,name` (unchanged)
Dates	ISO 8601 UTC	ISO 8601 UTC (unchanged)
Metadata	Up to 50 pairs	Up to 50 pairs (unchanged)

Pagination: offset → page/cursor

# V2 - offset pagination
GET /v2/orders?skip=200&limit=100

# V3 - page-number pagination (most list endpoints)
GET /v3/orders?page[number]=3&page[size]=100

V3 responses include a top-level links object - use links.next verbatim to fetch the next page rather than building URLs yourself:

{
  "data": [ /* items */ ],
  "links": {
    "first": "/v3/orders?page[number]=1&page[size]=100",
    "next":  "/v3/orders?page[number]=4&page[size]=100",
    "prev":  "/v3/orders?page[number]=2&page[size]=100"
  },
  "meta": { "total": 247 }
}

High-volume product list endpoints (GET /v3/products, GET /v3/collections/{id}/products, GET /v3/products/{id}/variants) use cursor pagination instead: page[cursor] + page[size]. links.prev is always null (no backward navigation). Never parse or construct cursors manually - follow links.next.

Filtering & sorting: bespoke → JSON:API

# V2 - bespoke params
GET /v2/products?minBudget=25&maxBudget=200&brandName=acme

# V3 - JSON:API filter[] with range brackets, plus sort
GET /v3/products?filter[price][gte]=25&filter[price][lte]=200&filter[brandName]=acme&sort=minPrice

Multiple filter[...] expressions are ANDed. Unknown filter keys return 400.

Hydration: `expand[]` → `include`

# V2
GET /v2/gifts/gft_abcd123?expand[]=product&expand[]=recipient

# V3
GET /v3/products/prd_98765?include=brand,tags

Deep dive - Orders

This is the biggest behavioral change in V3. In V2, an Order is a sub-entity of a Gift: even Direct Fulfillment goes through a two-step gift-and-claim flow, and you retrieve order state by reading the parent Gift. In V3, Orders are first-class - created, retrieved, listed, and cancelled directly.

Placing an order

V2 - two steps (create gift, then claim):

# 1. Create a gift under a campaign
curl --request POST \
  --url https://api.snappy.com/public-api/v2/gifts \
  --header 'X-Api-Key: YOUR_API_KEY' \
  --header 'Content-Type: application/json' \
  --data '{
    "campaignId": "cmp_12345",
    "recipients": [
      { "firstname": "Jordan", "lastname": "Lee", "email": "jordan@example.com", "key": "order-9982" }
    ]
  }'

# 2. Claim the gift to place the order
curl --request POST \
  --url https://api.snappy.com/public-api/v2/gifts/gft_abcd123/claim \
  --header 'X-Api-Key: YOUR_API_KEY' \
  --header 'Content-Type: application/json' \
  --data '{
    "variantId": "var_55555",
    "recipient": {
      "firstName": "Jordan",
      "lastName": "Lee",
      "address1": "123 Main St",
      "city": "Austin",
      "provinceCode": "TX",
      "postalCode": "78701",
      "countryCode": "US"
    }
  }'

V3 - one idempotent call:

curl --request POST \
  --url https://api.snappy.com/public-api/v3/orders \
  --header 'X-Api-Key: YOUR_API_KEY' \
  --header 'Content-Type: application/json' \
  --data '{
    "idempotencyKey": "order-9982",
    "billingMethodId": "bm_abc123",
    "variantId": "var_55555",
    "recipient": {
      "firstName": "Jordan",
      "lastName": "Lee",
      "email": "jordan@example.com",
      "phone": "+15125550123"
    },
    "shippingAddress": {
      "address1": "123 Main St",
      "city": "Austin",
      "provinceCode": "TX",
      "postalCode": "78701",
      "countryCode": "US"
    },
    "tags": ["q4-campaign"],
    "metadata": { "externalRecipientId": "crm-user-987" }
  }'

In V3 the recipient’s contact details and the shipping address are separate objects (recipient + shippingAddress), whereas V2’s claim payload merged them. The idempotencyKey (1–120 chars) is required in V3 and replaces the V2 recipient key for double-billing protection.

Retrieving, listing, and cancelling

Operation	V2	V3
Get order	`GET /v2/gifts/{giftId}` (read order off the Gift)	`GET /v3/orders/{orderId}`
List orders	- (no direct list; iterate Gifts)	`GET /v3/orders` (filter by `status`, `idempotencyKey`, `createdAt`)
Cancel order	`POST /v2/gifts/{giftId}/cancel`	`POST /v3/orders/{orderId}/cancel`
Validate address	`POST /v2/orders/addresses/validate`	`POST /v3/orders/addresses/validate`
Autocomplete address	`GET /v2/orders/addresses/autocomplete`	`GET /v3/orders/addresses/autocomplete`

Order field mapping

V2 (on the Gift / Order)	V3 (on the Order)	Notes
`orders[].id`	`id`	Order is now top-level, not nested under a Gift.
`orders[].status` (`active`, `cancelled`)	`status` (`active`, `completed`, `cancelled`, `refunded`)	V3 adds commercial lifecycle states.
-	`fulfillmentStatus` (`unfulfilled`, `fulfilled`, `cancelled`)	New: physical status, separate from commercial `status`.
`orderRecipient`	`recipient`	`{ firstName, lastName, email, phone }`.
-	`shippingAddress`	Address is now its own object.
`orderedProducts[].selectedProduct.variantId`	`lineItems[].variantId`
`orderedProducts[].selectedProduct.title`	`lineItems[].title`
`orderedProducts[].deliveryDetails`	`fulfillments[]`	Many-to-many between line items and shipments; carrier name is in `fulfillments[].trackingCompany`; tracking number/URL in `fulfillments[].trackingInfo`.
`deliveryDetails.status`	`fulfillments[].status`	Delivery statuses renamed and switched to snake_case (e.g. `orderReceived` → `confirmed`, `inTransit` → `in_transit`, `outForDelivery` → `out_for_delivery`).

Order-level webhooks fire alongside gift-level webhooks for V3 orders, so you can track delivery state without polling. See Webhook Event Types.

Deep dive - Marketplace (Products, Variants & Collections)

V2 modeled the catalog as a single Product object with an embedded variants array. V3 splits Products (display-level) and Variants (orderable units) into separate resources with their own endpoints, and adds the marketplace vs swag catalog split.

Listing products

V2 - budget is required, types is an array, offset pagination:

curl --request GET \
  --url 'https://api.snappy.com/public-api/v2/products?minBudget=25&maxBudget=200&brandName=acme&limit=100&skip=0' \
  --header 'X-Api-Key: YOUR_API_KEY'

V3 - JSON:API filters, cursor pagination:

curl --request GET \
  --url 'https://api.snappy.com/public-api/v3/products?filter[catalog]=marketplace&filter[price][gte]=25&filter[price][lte]=200&filter[brandName]=acme&include=brand,tags&sort=minPrice&page[size]=100' \
  --header 'X-Api-Key: YOUR_API_KEY'

Getting variants

In V2, both GET /v2/products/{id} and GET /v2/variants/{id} returned the full Product object with a variants array. In V3 the entities are cleanly separated:

# V2 - product carries its variants inline
GET /v2/products/prd_98765            # returns product + variants[]

# V3 - product and variants are separate resources
GET /v3/products/prd_98765            # product-level fields only
GET /v3/products/prd_98765/variants   # paginated list of variants
GET /v3/variants/var_55555            # a single variant on its own

Key catalog differences

V2	V3	What to change
`minBudget` / `maxBudget` (required)	`filter[price][gte]` / `filter[price][lte]` (optional)	Budget is no longer mandatory; use price range filters when needed.
`types: ["physical", ...]` (array)	No direct equivalent	Product type filtering is no longer supported. Use `filter[catalog]` to scope by catalog.
Variants embedded in product	`GET /v3/products/{id}/variants`	Fetch variants from the dedicated endpoint.
`expand[]`	`include=brand,tags`	Switch hydration syntax.
`GET /v2/products/tags`	`GET /v3/product-tags`	Path renamed.
IDs could change with availability	Static IDs	Safe to cache/store product and variant IDs.
No catalog split	`filter[catalog]=marketplace` \| `swag` \| `giftCards` \| `donations`	Required on list endpoints (defaults to `marketplace`).

Maintaining a local mirror of the catalog? V3 adds an asynchronous, NDJSON-based Export API - pair it with stock-availability-updates webhooks for incremental refresh instead of repeatedly paging the list endpoints.

Everything else: endpoint mapping

The remaining domains keep identical functionality in V3 - the same operations and data, relocated to /v3/... and re-skinned in V3 conventions (camelCase, filter[...], page[...], include). Migrating these is the mechanical swap described in What changes at a glance: change the path, update pagination/filter params, and adjust field casing.

Domain	V2	V3	Migration notes
Campaigns	`/v2/campaigns`	`/v3/campaigns`	Same create/read/update/estimate operations. Swap `skip`/`limit` → `page[...]` and bespoke filters → `filter[...]`.
Gifts	`/v2/gifts`	`/v3/gifts`	Same lifecycle (create, retrieve, update, expire). Recipient fields become `camelCase` (`firstName`/`lastName`).
Recipients	`/v2/recipients`	`/v3/recipients`	Same roster CRUD. JSON:API pagination and filtering.
Collections	`/v2/collections` (+ budgets, products, count)	`/v3/collections` (+ products)	List and by-ID Collection resources; products within a Collection use cursor pagination and `products:read`. List/by-ID require `Snappy-Account-Id`.
Accounts	`/v2/accounts`	`/v3/accounts`	Same list/retrieve/create.
Billing Methods	-	`/v3/billing-methods`	New in V3: check remaining balance/expiration. Use before high-value orders.
Address validate	`POST /v2/orders/addresses/validate`	`POST /v3/orders/addresses/validate`	Identical behavior.
Address autocomplete	`GET /v2/orders/addresses/autocomplete`	`GET /v3/orders/addresses/autocomplete`	Identical behavior.

Scopes are unchanged across versions - e.g. campaigns:create, recipients:read:masked, accounts:read work for both /v2 and /v3. You do not need to regenerate keys to call the V3 equivalents.

Error handling

The error object stays a flat shape in V3, with the same split between validation (400) and everything else:

// Validation error (400)
{ "path": "campaignId", "errorCode": "INVALID_REQUEST", "message": "The campaignId provided does not exist." }

// All other errors (401, 403, 404, 409, 422, 5xx)
{ "status": 404, "errorCode": "NOT_FOUND", "message": "The resource you requested could not be found." }

The main change is errorCode: V3 uses the structured format {STATUS}_{DOMAIN}_{SEQUENCE} (e.g. 404_PROD_001, 403_PBLC_001), while V2 uses symbolic codes (e.g. NOT_FOUND). Switch on errorCode, never on message. See Request & Response Standards and Error Handling.

Migration checklist

Confirm your key reaches V3

Repeat one existing V2 read against the /v3/... path with the same X-Api-Key. If it returns data, you’re ready - no new credentials needed.

Adopt V3 query conventions

Update your client’s pagination (page[...]), filtering (filter[...]), sorting (sort=), and hydration (include=) helpers. Follow links.next verbatim.

Migrate catalog reads first

Move Products/Variants/Collections to V3 - lowest risk, biggest performance win. Split your product-and-variants reads into the separate V3 endpoints and start caching the now-static IDs.

Move order placement to V3 Orders

Replace the gift-create → claim flow with a single POST /v3/orders. Generate a stable idempotencyKey per order and split recipient vs shippingAddress. Read order state from GET /v3/orders/{orderId} instead of the parent Gift.

Update error handling

Switch your error branching to the structured errorCode format.

Migrate remaining domains

Apply the mechanical path/convention swap to Campaigns, Gifts, Recipients, Accounts, and address endpoints. Adopt Billing Methods to pre-check funds before high-value orders.

Run both versions in parallel, then cut over

Because the same key serves both, you can ship V3 per domain behind a flag, verify, and retire the V2 calls when you’re confident.

Need a hand planning your migration? Reach out to your Snappy contact.

Welcome

Start building

Our API Standards

Migrating to V3

Webhooks & Events

Why migrate

Before you begin

Your existing API key already works

Generating an API key (recap)

New optional scoping header (V3)

What changes at a glance

Filtering & sorting: bespoke → JSON:API

Hydration: `expand[]` → `include`

Deep dive - Orders

Placing an order

Retrieving, listing, and cancelling

Order field mapping

Deep dive - Marketplace (Products, Variants & Collections)

Listing products

Getting variants

Key catalog differences

Everything else: endpoint mapping

Error handling

Migration checklist

​Why migrate

​Before you begin

​Your existing API key already works

​Generating an API key (recap)

​New optional scoping header (V3)

​What changes at a glance

​Pagination: offset → page/cursor

​Filtering & sorting: bespoke → JSON:API

​Hydration: expand[] → include

​Deep dive - Orders

​Placing an order

​Retrieving, listing, and cancelling

​Order field mapping

​Deep dive - Marketplace (Products, Variants & Collections)

​Listing products

​Getting variants

​Key catalog differences

​Everything else: endpoint mapping

​Error handling

​Migration checklist

Why migrate

Before you begin

Your existing API key already works

Generating an API key (recap)

New optional scoping header (V3)

What changes at a glance

Pagination: offset → page/cursor

Filtering & sorting: bespoke → JSON:API

Hydration: `expand[]` → `include`

Deep dive - Orders

Placing an order

Retrieving, listing, and cancelling

Order field mapping

Deep dive - Marketplace (Products, Variants & Collections)

Listing products

Getting variants

Key catalog differences

Everything else: endpoint mapping

Error handling

Migration checklist