Skip to main content
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

FieldTypeDescription
idstringUnique identifier for the Product
titlestringDisplay name of the Product
categorystringProduct category path (e.g. Electronics / Audio / Headphones)
typesarrayThe type(s) of the product. Possible values: digital, physical, base-product-swag, on-demand-swag, on-demand-plus-swag, premium-swag, experience, personalized
brandobjectThe brand associated with this Product. Contains id, name, and description. May be null when no brand applies.
coverImageobjectThe primary display image for the Product. Contains src, type, and position
mediaItemsarrayAdditional images for the Product. Each item contains src, type, position, and publicCloudinaryId
optionsobjectThe available option dimensions for this Product (e.g. color, size, scent, flavor). Used to understand what variations exist before retrieving Variants
tagsarrayTags associated with this Product for categorization and filtering. Each tag contains id, name, color, and position
variantsarrayThe orderable variations of this Product. Always contains at least one entry. See The Variant Object below
noticesobjectAny 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.
FieldTypeDescription
idstringUnique identifier for the Variant. This is the ID required when placing an order
titlestringDisplay name of the Variant
optionAttributesobjectThe specific option values for this Variant (e.g. color: Black, size: S)
categorystringFull category path for this Variant
typesarrayThe type(s) of the variant. Same enum as Product types
brandobjectThe brand associated with this Variant. Contains id, name, and description
descriptionstringShort description of the Variant
featuresstringKey features of the Variant
componentsstringComponents included with the Variant
mediaItemsarrayImages specific to this Variant. Each item contains src, type, position, and publicCloudinaryId
informationobjectDetailed product information including description, features, specifications (dimensions, materials, weight, color family), and including (what’s in the box)
pricingobjectPricing details by country code. Each entry contains cost, ddp, shipping, totalFee, totalTax, and totalFinalCost. Returned only when fields=pricing or fields=full is requested.
supportedCountriesarrayList of countries this Variant can be shipped to, identified by countryCode. Returned only when fields=supportedCountries or fields=full is requested.
tagsarrayTags associated with this Variant
noticesobjectAny additional notices or disclaimers specific to this Variant
positionnumberDisplay 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: 
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.
Last modified on June 18, 2026