Skip to main content

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.

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 & Variants fit into the bigger picture? Check out the Core Concepts & Data Models page.

​
The Product Object

FieldTypeDescription
idstringUnique identifier for the Product
titlestringDisplay name of the Product
categorystringProduct category path (e.g. Electronics / Audio / Headphones)
typesarrayThe type of product. Possible values: digital, physical
brandobjectThe brand associated with this Product. Contains id, name, and description
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 of variant. Possible values: digital, physical
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. Each entry contains cost, totalFee, totalTax, and totalFinalCost
supportedCountriesarrayList of countries this Variant can be shipped to, identified by countryCode
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 via POST /orders, 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 — never assume a Product can be ordered without one.

​
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

The pricing object on each Variant is keyed by country code. Always check that a Variant’s supportedCountries list includes the recipient’s country before placing an order.

​
Product types

Products and Variants carry a types field indicating whether the item is digital or physical. This affects fulfillment behavior — digital items are delivered electronically, physical items are shipped to the recipient’s address.

​
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 the GET /products/tags endpoint.

​
How to Work with Products & Variants

Retrieving 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 /products/tags
Supports searching by tag name using the title parameter. Results are paginated. Retrieving Products Search for and retrieve a list of available products based on your specified criteria: 
GET /products
Filtering options:
  • Budget range
  • Specific collection
  • Brand
Retrieving Variants by Product ID Retrieve a list of all Variants for a specific Product: 
GET /products/{productId}/variants
Filtering options:
  • Budget range
  • Supported countries
Retrieving Variant by ID Retrieve a specific Variant by its ID: 
GET /variants/{variantId}
Last modified on April 30, 2026