Only one Collections endpoint is currently exposed via V3 (
GET /v3/collections/{collectionId}/products). Additional endpoints - listing all available Collections, fetching budgets, counting products, and retrieving a single Product within a Collection - remain on V2 (see V2 Endpoints below) and will be migrated to V3 in a future release.What V3 returns
The V3 Collections endpoint returns Product objects, not the Collection itself. Each Product carries identity, media, category, catalog, type, and optional brand, tags,priceRange, and variantsCount (when requested via include or fields).
→ See Products & Variants Overview for the full Product schema and include / fields reference.
Key Concepts & Business Rules
Marketplace vs Swag
Snappy maintains two parallel catalogs. The V3 endpoint accepts afilter[catalog] parameter to choose between them:
| Catalog | What it contains |
|---|---|
marketplace (default) | Curated gifts from third-party brands - physical items, digital items, gift cards, donations |
swag | Branded merchandise templates |
filter[catalog], the endpoint defaults to marketplace.
Cursor pagination
The V3 endpoint uses cursor pagination (page[cursor] and page[size], max 300, default 100). The response includes a top-level links object with first, next, and prev URLs. Use links.next verbatim to fetch the next page - do not parse or construct cursors manually. links.prev is always null on cursor-paginated endpoints; backward navigation is not supported.
→ See Request & Response Standards for the full V3 pagination contract.
Filtering, sorting, and field expansion
V3 follows JSON:API conventions:- Filtering -
filter[catalog],filter[type](physical,digital,giftCard,donation),filter[search](free-text across product title, category, and brand),filter[price][gte]/filter[price][lte] - Sorting -
sort=minPriceorsort=createdAt(prefix with-for descending; single field only) - Include related entities -
include=brand,tagsreturns full Brand and Tag objects inline - Field expansion -
fields=priceRange,variantsCount,totalrequests additional computed fields.totalreturns a root-level count of products matching the filters across all pages.
Location scoping
Passlocation (ISO 3166-1 alpha-2 country code, e.g. US, GB, DE) to scope pricing and availability to a specific recipient country. Defaults to US.
Account scoping
Pass the optionalSnappy-Account-Id header to scope queries to a specific Account - used primarily for swag validation and filtering. The optional Snappy-Company-Id header further scopes to a specific Company.
Permissions
The V3 Collections endpoint requires theproducts:read scope on your API key. (Same scope as the V3 Products and Variants endpoints, since the response is a Product list.)
How to Work with Collections
Retrieve products within a CollectionminPrice or createdAt. Expand related entities (brand, tags) and computed fields (priceRange, variantsCount, total) as needed.
Returns 404 (404_PBLC_004) if the Collection ID does not exist.
Variants are not returned by this endpoint. To retrieve the variants for a specific Product, use
GET /v3/products/{productId}/variants.V2 Endpoints (Legacy)
The following V2 Collections endpoints remain available while the migration to V3 is in progress:GET /collections- list available CollectionsGET /collections/budgets- retrieve Collection budget rangesGET /collections/{id}/products/{productId}- get a specific Product within a CollectionGET /collections/{id}/products/count- count Products in a Collection