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

> Bundle products into curated collections by budget, theme, or audience, and serve them through the Snappy 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>

## 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`  |
| `coverImage` | string | URL of the Collection's cover image, used for display in campaign setup and recipient experience |
| `thumbnails` | array  | List of URLs of thumbnail images representing items within the Collection                        |
| `createdBy`  | string | The team or user who created the Collection                                                      |
| `createdAt`  | string | ISO 8601 timestamp of when the Collection was created                                            |
| `updatedAt`  | string | ISO 8601 timestamp of the last update                                                            |

***

## Paginated Response

The Collections 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.

#### **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 can be 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

**Retrieving Collections**

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

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

Filtering options:

* Budget range
* Supported countries
* Collection types (e.g. `gifts`, `swag`)

<Note>
  Swag collections can only be retrieved by specifying the `accountId` in the request.
</Note>

**Retrieving Collection Budgets**

Retrieve the available minimum and maximum budget ranges for Collections. Budget ranges determine the price points that recipients can choose from when selecting gifts:

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

Filtering options:

* Budget range
* Supported countries

**Retrieving Products within a Collection**

Retrieve **a list of products** available within a specific Collection:

```text theme={null}
GET /collections/{id}/products
```

Filtering options:

* Budget range
* Supported countries

Retrieve **a specific product** from a specific Collection:

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

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

**Retrieving the Collection Products Count**

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}
GET /collections/{id}/products/count
```