Products & Variants API (V2): Catalog Access for Gifting

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.

Want to understand how Products and Variants fit into the bigger picture? Check out the Core Concepts & Data Models page.

V3 has shipped a refreshed Catalog API split into two sections: Products (V3) and Variants (V3). V3 introduces JSON:API conventions, per-country availability, and a cleaner separation between the two entities. V2 and V3 are supported in parallel.

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

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:

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:

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:

GET /v2/products/{productId}

Filtering options:

Budget range
Country

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.

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

GET /v2/variants/{variantId}

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.

Authentication

Marketplace

Gifting

Administration

Products & Variants API (V2): Catalog Access for Gifting

The Product Object

The Variant Object

Key Concepts & Business Rules

Always order by Variant ID

Options vs. Variant Attributes

Pricing is per country

Product types

Tags

Field projection with `fields`

How to Work with Products & Variants

​The Product Object

​The Variant Object

​Key Concepts & Business Rules

​Always order by Variant ID

​Options vs. Variant Attributes

​Pricing is per country

​Product types

​Tags

​Field projection with fields

​How to Work with Products & Variants

The Product Object

The Variant Object

Key Concepts & Business Rules

Always order by Variant ID

Options vs. Variant Attributes

Pricing is per country

Product types

Tags

Field projection with `fields`

How to Work with Products & Variants