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, retrieve the Products within a specific Collection, and retrieve a Collection’s featured Products for a budget - 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 four Collections endpoints: list Collections (GET /v3/collections), retrieve a single Collection (GET /v3/collections/{collectionId}), retrieve the Products within a Collection (GET /v3/collections/{collectionId}/products), and retrieve a Collection’s featured Products (GET /v3/collections/{collectionId}/products/featured). 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 endpoints (GET /v3/collections/{collectionId}/products and GET /v3/collections/{collectionId}/products/featured) return Product objects, not the Collection itself. Each Product carries identity, media, category, catalog, 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

​
Catalog selection

Snappy maintains 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. Featured products are a Snappy-curated selection of the most popular items in a Collection that fit a given budget. We recommend displaying them at the top of your Collection page, above the full product list. Request them with GET /v3/collections/{collectionId}/products/featured, passing the budget as filter[price][gte] and filter[price][lte] (both required). Pass a stable seed (for example, a recipient ID) to return the same selection for the same Collection, budget, and location.

​
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. The featured products endpoint (GET /v3/collections/{collectionId}/products/featured) is not paginated - it returns the full featured selection, typically fewer than 100 products, in a single data array. → See Request & Response Standards for the full V3 pagination contract.

​
Filtering, sorting, and field expansion

V3 follows JSON:API conventions:
  • Filtering - filter[catalog], filter[search] (free-text across product title and description), 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 requests additional computed fields.

​
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 endpoints share the products:read scope with the V3 Products and Variants endpoints, since their responses are Product lists.

​
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) 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.
Retrieve featured products within a Collection
Returns a Snappy-curated selection of the most popular Products in the Collection that fit the budget - display these at the top of the page. filter[price][gte] and filter[price][lte] are required. Optional: location, seed, include (brand, tags), and fields (selectedOrFirstAvailableVariant, priceRange, variantsCount). Request selectedOrFirstAvailableVariant to get an orderable variant on each Product without a separate variants call. Not paginated - the selection is typically fewer than 100 products. Returns 404 (404_PBLC_004) if the Collection ID does not exist.

​
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 October 26, 2026