> ## 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 & Variants API (V2): Catalog Access for Gifting

> Access Snappy's global catalog, product variants, and tags to render a native gifting marketplace in your own UI.

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

A **Variant** represents the orderable version of a Product, holding the specific details required to place an order such as size, color, pricing, and supported countries.

Because the Variant is always the orderable unit, **every Product contains at least one Variant** - even Products with no variations will have a single Variant object representing the item.

When placing an order, always use the `variantId` from the Product's `variants` array.

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

<Note>
  V3 has shipped a refreshed Catalog API split into two sections: [Products (V3)](/modules/api/v3/products/overview) and [Variants (V3)](/modules/api/v3/variants/overview). V3 introduces JSON:API conventions, per-country availability, and a cleaner separation between the two entities. V2 and V3 are supported in parallel.
</Note>

***

## The Product Object

| Field        | Type   | Description                                                                                                                                                                    |
| :----------- | :----- | :----------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `id`         | string | Unique identifier for the Product                                                                                                                                              |
| `title`      | string | Display name of the Product                                                                                                                                                    |
| `category`   | string | Product category path (e.g. `Electronics / Audio / Headphones`)                                                                                                                |
| `types`      | array  | The type(s) of the product. Possible values: `digital`, `physical`, `base-product-swag`, `on-demand-swag`, `on-demand-plus-swag`, `premium-swag`, `experience`, `personalized` |
| `brand`      | object | The brand associated with this Product. Contains `id`, `name`, and `description`. May be `null` when no brand applies.                                                         |
| `coverImage` | object | The primary display image for the Product. Contains `src`, `type`, and `position`                                                                                              |
| `mediaItems` | array  | Additional images for the Product. Each item contains `src`, `type`, `position`, and `publicCloudinaryId`                                                                      |
| `options`    | object | The available option dimensions for this Product (e.g. `color`, `size`, `scent`, `flavor`). Used to understand what variations exist before retrieving Variants                |
| `tags`       | array  | Tags associated with this Product for categorization and filtering. Each tag contains `id`, `name`, `color`, and `position`                                                    |
| `variants`   | array  | The orderable variations of this Product. Always contains at least one entry. See [The Variant Object](#the-variant-object) below                                              |
| `notices`    | object | Any additional notices or disclaimers associated with this Product                                                                                                             |

***

## The Variant Object

A Variant represents a specific, orderable version of a Product. When placing an order you must always specify the `variantId` - the Product ID alone is not sufficient.

| Field                | Type   | Description                                                                                                                                                                                      |
| :------------------- | :----- | :----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `id`                 | string | Unique identifier for the Variant. This is the ID required when placing an order                                                                                                                 |
| `title`              | string | Display name of the Variant                                                                                                                                                                      |
| `optionAttributes`   | object | The specific option values for this Variant (e.g. `color: Black`, `size: S`)                                                                                                                     |
| `category`           | string | Full category path for this Variant                                                                                                                                                              |
| `types`              | array  | The type(s) of the variant. Same enum as Product `types`                                                                                                                                         |
| `brand`              | object | The brand associated with this Variant. Contains `id`, `name`, and `description`                                                                                                                 |
| `description`        | string | Short description of the Variant                                                                                                                                                                 |
| `features`           | string | Key features of the Variant                                                                                                                                                                      |
| `components`         | string | Components included with the Variant                                                                                                                                                             |
| `mediaItems`         | array  | Images specific to this Variant. Each item contains `src`, `type`, `position`, and `publicCloudinaryId`                                                                                          |
| `information`        | object | Detailed product information including `description`, `features`, `specifications` (dimensions, materials, weight, color family), and `including` (what's in the box)                            |
| `pricing`            | object | Pricing details by country code. Each entry contains `cost`, `ddp`, `shipping`, `totalFee`, `totalTax`, and `totalFinalCost`. Returned only when `fields=pricing` or `fields=full` is requested. |
| `supportedCountries` | array  | List of countries this Variant can be shipped to, identified by `countryCode`. Returned only when `fields=supportedCountries` or `fields=full` is requested.                                     |
| `tags`               | array  | Tags associated with this Variant                                                                                                                                                                |
| `notices`            | object | Any additional notices or disclaimers specific to this Variant                                                                                                                                   |
| `position`           | number | Display order of this Variant relative to others in the same Product                                                                                                                             |

***

## Key Concepts & Business Rules

#### Always order by Variant ID

Products are the display-level object - they represent what a recipient sees when browsing. Variants are the orderable units. When placing an order, always use the `variantId`, not the `productId`.

Every Product contains a `variants` array with at least one entry, even if the product has no variations. For products without variations, the array will contain a single Variant representing the product itself. Always retrieve the `variantId` from this array before placing an order.

#### Options vs. Variant Attributes

The `options` field on the Product object shows the available option dimensions (e.g. `color`, `size`). The `optionAttributes` field on each Variant shows the specific combination of those options that Variant represents. Use `options` to understand what choices exist, and `optionAttributes` to identify the exact Variant.

#### Pricing is per country

Variant `pricing` is keyed by country code and only returned when requested via the `fields` parameter (`fields=pricing` or `fields=full`). Always check that a Variant's `supportedCountries` includes the recipient's country before placing an order.

#### Product types

Products and Variants carry a `types` array. The enum includes:

* **`physical`** - physical items shipped to the recipient's address
* **`digital`** - digital items delivered electronically
* **`experience`** - local experiences and bookings
* **`personalized`** - items with recipient-specific personalization
* **`base-product-swag`** / **`on-demand-swag`** / **`on-demand-plus-swag`** / **`premium-swag`** - swag fulfillment categories

#### Tags

Tags exist at both the Product and Variant level and can be used to filter and categorize items when building a catalog UI. Retrieve all available tags using `GET /v2/products/tags`.

#### Field projection with `fields`

By default, response objects return a slim set of fields. Use the `fields` query parameter to include additional data:

* `mediaItems`, `tags`, `brand`, `optionAttributes`, `notices`, `pricing`, `supportedCountries`
* `full` - return everything

***

## How to Work with Products & Variants

**List Products**

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

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

Filtering options:

* **Budget range (required)** - `minBudget` and `maxBudget`
* Specific Collection (`collectionId`)
* Brand (`brandName` or `brands`)
* Tags (`tags`)
* Title or description text match

**List Product Tags**

Retrieve a list of all available product tags. Tags can be used to categorize and filter products when building your catalog UI:

```text theme={null} theme={null}
GET /v2/products/tags
```

Supports searching by tag name using the `title` parameter (minimum 3 characters). Results are paginated.

**Get a Product (with Variants) by ID**

Retrieve a Product by its ID, including the full list of Variants:

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

Filtering options:

* Budget range
* Country

<Note>
  Despite the endpoint summary "Get variants by product ID," this endpoint returns the full Product object with its `variants` array - not just the variants in isolation.
</Note>

**Get a Variant by ID**

Retrieve the full details of a specific Variant by its ID:

```text theme={null} theme={null}
GET /v2/variants/{variantId}
```

<Note>
  This endpoint returns the parent Product object with the requested Variant in its `variants` array, not the Variant alone. Use the variant ID to locate the specific variant within the returned `variants` list.
</Note>