> ## 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.

# Swag Products: Branded Merchandise Templates

> Browse Snappy's swag catalog - base products and base variants for branded merchandise. Schema, relationships, and V3 catalog endpoints.

**Swag** in Snappy refers to branded merchandise - items like t-shirts, mugs, hats, and notebooks that customers apply their own logo or design to. The V3 Swag API exposes this catalog through Base Products and Base Variants. For the standard Product and Variant model, see [Products](/modules/api/v3/products/overview) and [Variants](/modules/api/v3/variants/overview).

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.

<Tip>
  Looking to create and manage a fully branded store? See the separate [Swag Store API](/pages/swag-store-api).
</Tip>

***

## The Base Product Object

| Field | Type | Description |
| :- | :- | :- |
| `id` | string | Base product UUID (e.g. `048392af-5f4c-4ddc-b0e2-7a0edf152268`) |
| `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`) |
| `brand` | object or null | The brand (`id`, `name`, `description`). Returned only with `include=brand`; may be `null`. |
| `tags` | array | Product tags (`id`, `name`). Returned only with `include=tags`. |
| `options` | array | Aggregated variant options (`name`, `values`). Returned only with `fields=options`. |

***

## 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 | Base variant UUID (e.g. `d772e853-64d4-4578-b6d2-4c00396ad6a6`) |
| `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" }`) |
| `taxable` | boolean | Whether the variant is taxable |
| `media` | array | Images and video specific to this variant |
| `shippingRequired` | boolean | Whether the variant requires shipping. Returned when available. |

***

## Key Concepts & Business Rules

#### Swag Base Products vs standard Products

V3 exposes two related endpoint families:

| Endpoint family | Object model | Purpose |
| :- | :- | :- |
| `/v3/products/*` | Products and Variants | Browse standard products across the `marketplace`, `swag`, `giftCards`, and `donations` catalogs |
| `/v3/swag/*` | Base Products and Base Variants | Browse branded-merchandise templates and their available variants |

The endpoint families use different response schemas and are not interchangeable.

#### 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.

#### 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 | 300 | 100 |
| Get base variants by base product ID | 300 | 100 |

See [Request & Response Standards](/pages/request-response-standards) for the full V3 pagination contract.

#### Filtering

The Base Product list endpoint supports these JSON:API-style filters:

* `filter[brandId]` - comma-separated brand IDs
* `filter[brandName]` - case-insensitive brand name search
* `filter[tagId]` - comma-separated tag UUIDs
* `filter[title]` - case-insensitive title search
* `filter[id]` - comma-separated Base Product UUIDs
* `filter[color]` - comma-separated color titles
* `filter[size]` - comma-separated size titles
* `filter[printingTechnique]` - comma-separated printing-technique names

Multiple values within a filter use OR semantics. Unknown filter keys return `400`.

#### Location

All Base Product and Base Variant requests require a supported ISO 3166-1 alpha-2 `location` query parameter.

#### Account scoping

All Base Product and Base Variant requests require the `Snappy-Account-Id` header.

#### Permissions

All Base Product and Base Variant endpoints require the `products:read` scope on your API key.

***

## How to Work with Swag

**List base products**

```text theme={null} theme={null}
GET /v3/swag/base-products?location=US
```

Returns a paginated list of Base Products. Use `include=brand,tags` for related entities and `fields=options` for aggregated variant options.

**Get a single base product**

```text theme={null} theme={null}
GET /v3/swag/base-products/{baseProductId}?location=US
```

Returns one Base Product. This endpoint supports the same `include` and `fields` expansions as the list endpoint.

**List base variants for a base product**

```text theme={null} theme={null}
GET /v3/swag/base-products/{baseProductId}/variants?location=US
```

Returns a paginated list of Base Variants. This endpoint does not accept `include` or `fields`.

**Get a single base variant**

```text theme={null} theme={null}
GET /v3/swag/base-variants/{baseVariantId}?location=US
```

Returns one Base Variant. This endpoint does not accept `include` or `fields`.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.