Products belong to one of two catalogs:
marketplace (Snappy’s curated gift catalog) or swag (branded merchandise templates). Use the filter[catalog] parameter to choose which catalog to query.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 or swag |
type | enum | Product type. One of: physical, digital, giftCard, donation |
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. |
In V3,
type is a single value (not an array as in V2). Use the filter[type] query parameter to filter by type on list endpoints.Key Concepts & Business Rules
Catalog selection - marketplace vs swag
Every Product belongs to one of two catalogs:| Catalog | What it contains |
|---|---|
marketplace (default) | Curated gifts from third-party brands - physical items, digital items, gift cards, donations |
swag | Branded merchandise templates |
filter[catalog] parameter is required on list endpoints (defaults to marketplace). Use swag to retrieve swag templates.
Always order by Variant - not Product
Products are the display-level entity. Variants are the orderable units. When placing an order, always use thevariantId, 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.
Filtering
V3 follows JSON:API filtering conventions on the list endpoint:filter[catalog]-marketplaceorswag(defaults tomarketplace)filter[type]- exact match on product typefilter[search]- free-text search across title, category, and brandfilter[brandId]- comma-separated list of brand IDs (OR semantics)filter[brandName]- case-insensitive substring search on brand namefilter[tagId]- comma-separated list of tag IDs (OR semantics)filter[price][gte]/filter[price][lte]- inclusive price range
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 for the full pagination contract.
Sortable fields on the list endpoint: minPrice, createdAt. Prefix with - for descending order.
Location scoping
Passlocation (ISO 3166-1 alpha-2 country code) to scope pricing and availability to a specific recipient country. Defaults to US.
Account scoping
OptionalSnappy-Account-Id and Snappy-Company-Id headers scope queries to a specific Account or Company - used primarily for swag validation and filtering.
Permissions
All V3 Products endpoints require theproducts:read scope.
How to Work with Products
List productsfields to expand pricing and details.
List product tags
title to filter by name (minimum 3 characters).
Looking for branded swag templates instead of marketplace products? See the Swag page.