> ## 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 endpoints for building a swag store.

**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](/modules/api/v2/products/overview), 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.

<Tip>
  Looking for the end-to-end integration walkthrough for building a swag store? See the [Swag Store API](/pages/swag-store-api) guide.
</Tip>

<Note>
  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](/pages/changelog) for updates.
</Note>

***

## 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](/pages/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**

```text theme={null} theme={null}
GET /v3/base-products
```

Returns a paginated list of Base Products. Filter by brand using the `brandIds` query parameter.

**Get a single base product**

```text theme={null} theme={null}
GET /v3/base-products/{baseProductId}
```

**List base variants for a base product**

```text theme={null} theme={null}
GET /v3/base-products/{baseProductId}/variants
```