> ## 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.

# Collections API: Curated Gift Catalogs

> Retrieve products within a curated collection for marketplace and browse experiences. Filter by catalog, price, type, and search - with cursor pagination and JSON:API conventions.

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.

<Tip>
  Want to understand how **Collections** fit into the bigger picture? Check out the [Core Concepts & Data Models](/pages/snappy-core-concepts-and-data-models) page.
</Tip>

<Note>
  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](#v2-endpoints-legacy) below) and will be migrated to V3 in a future release.
</Note>

***

## 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, and optional brand, tags, `priceRange`, and `variantsCount` (when requested via `include` or `fields`).

→ See [Products & Variants Overview](/modules/api/v2/products/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:

| Catalog                 | What it contains                                                   |
| :---------------------- | :----------------------------------------------------------------- |
| `marketplace` (default) | Curated gifts from third-party brands - physical and digital items |
| `swag`                  | Branded merchandise templates                                      |
| `giftCards`             | Gift cards                                                         |
| `donations`             | Charitable donations                                               |

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](/pages/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, 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

| Endpoint                                      | Required scope     |
| :-------------------------------------------- | :----------------- |
| `GET /v3/collections`                         | `collections:read` |
| `GET /v3/collections/{collectionId}`          | `collections:read` |
| `GET /v3/collections/{collectionId}/products` | `products:read`    |

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**

```text theme={null} theme={null}
GET /v3/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**

```text theme={null} theme={null}
GET /v3/collections/{collectionId}
```

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**

```text theme={null} theme={null}
GET /v3/collections/{collectionId}/products
```

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.

<Note>
  Variants are **not** returned by this endpoint. To retrieve the variants for a specific Product, use `GET /v3/products/{productId}/variants`.
</Note>

***

## 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](/pages/changelog).