Skip to main content
A Collection is a curated catalog of gift items tailored to a specific theme, budget range, or audience (e.g. “Birthday Gifts Under $50”). Use Collections to give recipients a focused, branded gifting experience - or to power a marketplace browse flow inside your own platform. The V3 Collections API lets you list Collections, retrieve a single Collection’s metadata, and retrieve the Products within a specific Collection - all using the JSON:API filtering, pagination, and field-expansion conventions used elsewhere in V3.
Want to understand how Collections fit into the bigger picture? Check out the Core Concepts & Data Models page.
V3 exposes three Collections endpoints: list Collections (GET /v3/collections), retrieve a single Collection (GET /v3/collections/{collectionId}), and retrieve the Products within a Collection (GET /v3/collections/{collectionId}/products). The list and by-ID endpoints require the Snappy-Account-Id header. A few endpoints - 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 list (GET /v3/collections) and by-ID (GET /v3/collections/{collectionId}) endpoints return Collection objects - identity, description, media, cover image, and rank. The products endpoint (GET /v3/collections/{collectionId}/products) 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 a filter[catalog] parameter to choose between them: If you don’t specify filter[catalog], the endpoint defaults to marketplace.

​
Cursor pagination

The products endpoint (GET /v3/collections/{collectionId}/products) 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. The list endpoint (GET /v3/collections) uses page-number pagination (page[number] / page[size]) instead, with a meta.total count of matching Collections. → 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=minPrice or sort=createdAt (prefix with - for descending; single field only)
  • Include related entities - include=brand,tags returns full Brand and Tag objects inline
  • Field expansion - fields=priceRange,variantsCount,total requests additional computed fields. total returns a root-level count of products matching the filters across all pages.

​
Location scoping

Pass location (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

On the products endpoint, the Snappy-Account-Id header is optional and scopes queries to a specific Account - used primarily for swag validation and filtering. The list and by-ID endpoints require Snappy-Account-Id (a 404 is returned if it does not match a known Account).

​
Permissions

The products endpoint shares the products:read scope with the V3 Products and Variants endpoints, since its response is a Product list.

​
How to Work with Collections

List Collections
Returns a paginated list of Collections (page-number pagination), ordered by curated rank by default. Requires the Snappy-Account-Id header. Retrieve a single Collection
Returns a single Collection’s metadata - name, description, cover image, thumbnails, rank, and provenance. Requires the Snappy-Account-Id header. Returns 404 (404_PBLC_004) if the Collection ID does not exist. Retrieve products within a Collection
Returns a paginated list of Products in the specified Collection. Filter by catalog, type, price, free-text search, or country. Sort by minPrice 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 Collections
  • GET /collections/budgets - retrieve Collection budget ranges
  • GET /collections/{id}/products/{productId} - get a specific Product within a Collection
  • GET /collections/{id}/products/count - count Products in a Collection
New integrations should use V3 endpoints where available. Existing V2 endpoints will continue to work; they will not be deprecated without advance notice in the Changelog.
Last modified on June 30, 2026