Swag in Snappy refers to branded merchandise - items like t-shirts, mugs, hats, and notebooks that customers apply their own logo or design to. Swag is the second of Snappy’s two product catalogs (the first being Products & Variants, the curated marketplace catalog).
A Base Product is a swag template - the unbranded item from which customized swag is derived (e.g. “standard cotton t-shirt”). Base Products are the swag-catalog counterpart to standard Products.
A Base Variant is a specific orderable version of a Base Product (e.g. “Standard cotton t-shirt, Medium, Navy”). Base Variants are the swag counterpart to standard Variants - and as with the marketplace catalog, the variant is the orderable unit.
Looking for the end-to-end integration walkthrough for building a swag store? See the Swag Store API guide. The Base Product and Base Variant schemas are intentionally minimal in V3 and will be extended as the swag track matures - customization layers, design assets, and approval flows are planned. Subscribe to the Changelog for updates.
The Base Product Object
| Field | Type | Description |
|---|
id | string | Base product identifier (e.g. bp_a1b2c3) |
title | string | Display name of the Base Product |
media | array | Media items (images, video). Each item contains type and src. |
category | object | Category taxonomy. Contains fullName - the full path separated by / (e.g. apparel / tops) |
type | enum | Product type. One of: physical, digital, giftCard, donation |
brand | object | The brand associated with this Base Product (id, name, description). May be null when no brand applies. |
The Base Variant Object
A Base Variant represents a specific, orderable version of a Base Product. When placing a swag order you must always specify the variant ID - the Base Product id alone is not sufficient.
| Field | Type | Description |
|---|
id | string | Unique identifier for the Base Variant (e.g. bv_x9y8z7) |
baseProductId | string | The parent Base Product identifier |
title | string | Display name of the Base Variant |
selectedOptions | object | The specific option values for this variant (e.g. { "size": "M", "color": "Navy" }) |
media | array | Images and video specific to this variant |
Key Concepts & Business Rules
Swag vs Marketplace
Snappy maintains two separate product catalogs:
| Catalog | What it contains | Use case |
|---|
marketplace | Curated catalog of finished gifts from third-party brands | Send a recipient a specific branded gift |
swag | Templates for branded merchandise | Build a swag store with your company’s branding |
/v3/products/* vs /v3/base-products/*) and distinct schemas.
Base Product → Base Variant → Order
The flow mirrors the marketplace flow: browse Base Products, drill into the Base Variants for the one you want, and place an order specifying the variant. Customization (logo application, design preview, approval) layers in between variant selection and order placement and will be exposed in future API releases.
Base Product and Base Variant list endpoints use page-number pagination (page[number], page[size]):
| Endpoint | Max page size | Default page size |
|---|
| List base products | 100 | 40 |
| Get base variants by base product ID | 500 | 100 |
Brand filtering uses brandIds, not filter[brandId]
Base Product endpoints use a flat brandIds query parameter rather than the JSON:API filter[brandId] family used elsewhere in V3. This is a known divergence - for all other V3 endpoints, use the filter[<field>] style.
Permissions
All Base Products endpoints require the products:read scope on your API key.
How to Work with Swag
List base products
Returns a paginated list of Base Products. Filter by brand using the brandIds query parameter.
Get a single base product
GET /v3/base-products/{baseProductId}
GET /v3/base-products/{baseProductId}/variants
Last modified on June 18, 2026
