> ## 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 (V2): Curated Gift Catalogs

> Bundle products into curated collections by budget, theme, or audience, and serve them through the Snappy V2 API.

A **Collection** is a curated catalog of gift items tailored to a specific theme, budget range, and audience (e.g. "Birthday Gifts Under \$50"). The gift recipient then chooses their preferred item directly from this collection.

<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>
  Looking for the V3 endpoint that returns Products within a Collection? See [Collections (V3)](/modules/api/v3/collections/overview) for `GET /v3/collections/{collectionId}/products` with JSON:API filtering, cursor pagination, and the V3 response envelope.
</Note>

***

## The Collection Object

| Field        | Type                        | Description                                                                                               |
| :----------- | :-------------------------- | :-------------------------------------------------------------------------------------------------------- |
| `id`         | string                      | Unique identifier for the Collection                                                                      |
| `name`       | string                      | Display name of the Collection                                                                            |
| `types`      | array                       | The category of items in this Collection. Possible values: `gifts`, `swag`, `local experiences`, `custom` |
| `coverImage` | string (nullable)           | URL of the Collection's cover image, used for display in campaign setup and recipient experience          |
| `thumbnails` | array (nullable)            | List of URLs of thumbnail images representing items within the Collection                                 |
| `createdBy`  | string (nullable)           | The team or user who created the Collection                                                               |
| `createdAt`  | string (ISO 8601)           | When the Collection was created                                                                           |
| `updatedAt`  | string (ISO 8601, nullable) | When the Collection was last updated                                                                      |

***

## Paginated Response

The Collections list endpoint returns a paginated response with the following envelope:

| Field     | Type   | Description                                                               |
| :-------- | :----- | :------------------------------------------------------------------------ |
| `results` | array  | The list of Collection objects returned for the current page              |
| `skip`    | number | The number of items skipped from the start of the list                    |
| `limit`   | number | The maximum number of items returned per page. Default and maximum is 100 |

<Note>
  For details on how to paginate through large result sets, see [Request & Response Standards → Pagination](/pages/request-response-standards).
</Note>

***

## Key Concepts & Business Rules

#### Collections are read-only via the API

Collections available to your Account are curated by Snappy or created via the Snappy Dashboard. You cannot create or modify Collections through the API - only retrieve them.

#### Collection types

The `types` field indicates the category of items within the Collection. This can be useful for filtering Collections when configuring a Campaign for a specific use case - for example, selecting only `swag` Collections for a branded merchandise campaign.

#### Swag Collections require `accountId`

Swag Collections are scoped to specific Accounts. To retrieve them, you must include the `accountId` parameter on the list endpoint - they will not appear without it.

#### Two scopes, depending on what you call

The Collections endpoints split across two permission scopes:

* **`collections:read`** - list Collections and retrieve budget ranges (`GET /v2/collections`, `GET /v2/collections/budgets`)
* **`products:read`** - retrieve products within a Collection or count them (`GET /v2/collections/{id}/products`, `GET /v2/collections/{id}/products/{productId}`, `GET /v2/collections/{id}/products/count`)

Make sure your API key carries both scopes if your integration browses Collections and their products.

#### Assigning a Collection to a Campaign

To use a Collection in a gifting flow, assign its `id` to a Campaign. Recipients will then browse and select from that Collection when they claim their gift.

<Note>
  A Campaign is assigned either a Collection or a specific Product - not both. See [Campaigns](/modules/api/v2/campaigns/overview) for details.
</Note>

***

## How to Work with Collections

**List Collections**

Search for and retrieve a list of available Collections based on your specified criteria:

```text theme={null} theme={null}
GET /v2/collections
```

Filtering options:

* Budget value (required)
* Supported countries
* Collection types (e.g. `gifts`, `swag`, `local experiences`, `custom`)
* Account ID (required for Swag Collections)

**Retrieve Collection Budget Ranges**

Retrieve the available minimum and maximum budget ranges for Collections - useful for determining the price points available to recipients before configuring a Campaign:

```text theme={null} theme={null}
GET /v2/collections/budgets
```

Filtering options:

* Collection type (required)
* Collection ID
* Supported countries

**List Products within a Collection**

Retrieve a list of products available within a specific Collection:

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

Filtering options:

* Budget range (min/max - both required)
* Country

**Get a Specific Product from a Collection**

Retrieve a specific product from a specific Collection by ID:

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

<Tip>
  The Product objects returned in this response follow the standard Product schema. See [Products & Variants](/modules/api/v2/products/overview) for the full object structure.
</Tip>

**Count Products in a Collection**

Retrieve the number of products available within a specific Collection - useful for display purposes or pagination planning before fetching the full product list:

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