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

# Products API: Browse Snappy's Catalog

> Retrieve products, search and filter the catalog, browse product tags, and access the variants belonging to each product.

A **Product** is a single specific item available in the Snappy catalog - a physical gift, branded swag, a digital item, a gift card, or a donation.

The V3 Products API lets you browse and retrieve products, search the catalog, and discover the tags used to categorize them. Each Product is the display-level entity; the actual orderable units are **Variants**, retrievable via the product's variants endpoint or through the [Variants API](/modules/api/v3/variants/overview).

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

<Note>
  Products belong to one of four catalogs: `marketplace` (Snappy's curated gift catalog), `swag` (branded merchandise templates), `giftCards`, or `donations`. Use the `filter[catalog]` parameter to choose which catalog to query.
</Note>

***

## The Product Object

| Field           | Type              | Description                                                                                        |
| :-------------- | :---------------- | :------------------------------------------------------------------------------------------------- |
| `id`            | string            | Stable product identifier                                                                          |
| `title`         | string            | Display name of the product                                                                        |
| `createdAt`     | string (ISO 8601) | When the product was added to the catalog                                                          |
| `media`         | array             | Product media items (images, video). Each item contains `type` and `src`.                          |
| `category`      | object            | Category taxonomy. Contains `fullName` - full path separated by `/`.                               |
| `catalog`       | enum              | `marketplace`, `swag`, `giftCards`, or `donations`                                                 |
| `brand`         | object            | Returned only when `include=brand`. Contains `id`, `name`, `description`. Nullable.                |
| `tags`          | array             | Returned only when `include=tags`. Each tag has `id` and `name`.                                   |
| `options`       | array             | Aggregated variant options (e.g. `color`, `size`). Returned only when `fields` includes `options`. |
| `priceRange`    | object            | Min/max pricing across the product's variants. Returned only when `fields` includes `priceRange`.  |
| `variantsCount` | integer           | Number of variants. Returned only when `fields` includes `variantsCount`.                          |

***

## Key Concepts & Business Rules

#### Catalog selection

Every Product belongs to one of four catalogs:

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

The `filter[catalog]` parameter is required on list endpoints (defaults to `marketplace`). Use `swag`, `giftCards`, or `donations` to retrieve those catalogs instead.

#### Always order by Variant - not Product

Products are the display-level entity. Variants are the orderable units. When placing an order, always use the `variantId`, not the `productId`. Retrieve a product's variants using `GET /v3/products/{productId}/variants`.

#### Expanding products with `include` and `fields`

V3 uses JSON:API conventions to keep responses lean by default and expand only what you need:

* **`include`** - return related entities as full objects. Supported values: `brand`, `tags`.
* **`fields`** - return additional computed/expanded fields. On the list endpoint: `priceRange`, `variantsCount`, `total`. On the single-product endpoint: `options`, `priceRange`, `variantsCount`.

Combine them in a single request:

```text theme={null} theme={null}
GET /v3/products?include=brand,tags&fields=priceRange,variantsCount
```

#### Filtering

V3 follows JSON:API filtering conventions on the list endpoint:

* `filter[catalog]` - `marketplace`, `swag`, `giftCards`, or `donations` (defaults to `marketplace`)
* `filter[search]` - free-text search across title, category, and brand
* `filter[brandId]` - comma-separated list of brand IDs (OR semantics)
* `filter[brandName]` - case-insensitive substring search on brand name
* `filter[tagId]` - comma-separated list of tag IDs (OR semantics)
* `filter[price][gte]` / `filter[price][lte]` - inclusive price range

Multiple `filter[...]` expressions are ANDed. Unknown filter keys return `400`.

#### Pagination and sorting

The list endpoint uses **cursor pagination** (`page[cursor]`, `page[size]`, max 300, default 100). The variants-by-product endpoint uses **page-number pagination** (`page[number]`, `page[size]`). See [Request & Response Standards](/pages/request-response-standards) for the full pagination contract.

Sortable fields on the list endpoint: `minPrice`, `createdAt`. Prefix with `-` for descending order.

#### Location scoping

Pass `location` (ISO 3166-1 alpha-2 country code) to scope pricing and availability to a specific recipient country. Defaults to `US`.

#### Account scoping

The optional `Snappy-Account-Id` header scopes queries to a specific Account - used primarily for swag validation and filtering.

#### Permissions

All V3 Products endpoints require the `products:read` scope.

***

## How to Work with Products

**List products**

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

Returns a paginated list of products across all collections. Filter by catalog, type, brand, tag, price, or free-text search.

**Get a single product**

```text theme={null} theme={null}
GET /v3/products/{productId}
```

Returns product-level fields only. Use the variants endpoint below to retrieve the product's variants.

**List variants for a product**

```text theme={null} theme={null}
GET /v3/products/{productId}/variants
```

Returns the product's variants as a paginated list. Use `fields=pricing` to include variant `price` and `priceBreakdown`, and `fields=details` to expand structured details.

**List product tags**

```text theme={null} theme={null}
GET /v3/product-tags
```

Returns a paginated list of available product tags. Use `title` to filter by name (minimum 3 characters).

***

<Note>
  Looking for **branded swag templates** instead of marketplace products? See the [Swag](/modules/api/v3/base-products/overview) page.
</Note>