Swag Products: Branded Merchandise Templates

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

The two catalogs use distinct endpoints (/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.

Pagination

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

See Request & Response Standards for the full V3 pagination contract.

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

GET /v3/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}

List base variants for a base product

GET /v3/base-products/{baseProductId}/variants

Authentication

Marketplace

Gifting

Administration

Swag Products: Branded Merchandise Templates

The Base Product Object

The Base Variant Object

Key Concepts & Business Rules

Swag vs Marketplace

Base Product → Base Variant → Order

Brand filtering uses `brandIds`, not `filter[brandId]`

Permissions

How to Work with Swag

​The Base Product Object

​The Base Variant Object

​Key Concepts & Business Rules

​Swag vs Marketplace

​Base Product → Base Variant → Order

​Pagination

​Brand filtering uses brandIds, not filter[brandId]

​Permissions

​How to Work with Swag

The Base Product Object

The Base Variant Object

Key Concepts & Business Rules

Swag vs Marketplace

Base Product → Base Variant → Order

Pagination

Brand filtering uses `brandIds`, not `filter[brandId]`

Permissions

How to Work with Swag