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

# Variants API: The Orderable Units of the Catalog

> Retrieve product variants, check per-country availability and pricing, and access the variant-level details required to place an order.

A **Variant** is the orderable unit in the Snappy catalog - the specific version of a Product with concrete pricing, size, color, or other distinguishing attributes. When placing an order, you always specify a `variantId` (never just a `productId`).

The V3 Variants API lets you retrieve individual variants by ID and check their availability across countries.

<Tip>
  Want to understand how **Variants** fit into the bigger picture? Check out the [Core Concepts & Data Models](/pages/snappy-core-concepts-and-data-models) page.
</Tip>

<Note>
  To list all variants for a specific product, use [`GET /v3/products/{productId}/variants`](/modules/api/v3/products/get-product-variants) - this is part of the [Products API](/modules/api/v3/products/overview) since it's scoped to a product.
</Note>

***

## The Variant Object

| Field             | Type    | Description                                                                                                            |
| :---------------- | :------ | :--------------------------------------------------------------------------------------------------------------------- |
| `id`              | string  | Unique identifier of the variant - required when placing an order                                                      |
| `title`           | string  | Display name of the variant                                                                                            |
| `productId`       | string  | Parent product identifier                                                                                              |
| `selectedOptions` | object  | Key-value option values for this variant (e.g. `{"color": "Black", "size": "M"}`)                                      |
| `taxable`         | boolean | Whether the variant is taxable                                                                                         |
| `media`           | array   | Variant-specific media items                                                                                           |
| `personalization` | object  | Personalization metadata (whether personalization is supported, available template fields). Nullable when unavailable. |
| `descriptionHtml` | string  | Full narrative HTML description                                                                                        |
| `price`           | object  | Variant price in `{amount, currency}`. Returned only when `fields` includes `pricing` (or `price`).                    |
| `priceBreakdown`  | object  | Detailed pricing breakdown. Returned only when `fields` includes `pricing` (or `priceBreakdown`).                      |
| `details`         | object  | Structured details wrapper (description, features, specifications). Returned only when `fields` includes `details`.    |
| `brand`           | object  | Returned only when `include=brand`. Nullable.                                                                          |

***

## Key Concepts & Business Rules

#### Default response is lean

By default, variant responses omit `price`, `priceBreakdown`, and `details`. Use `fields` to request the gated fields when you need them:

* `fields=pricing` - adds `price`, `priceBreakdown`
* `fields=details` - adds the structured `details` wrapper

This keeps responses small for browse and search use cases while letting checkout flows pull the full data they need.

#### Pricing is per country

Variant pricing depends on the recipient's shipping country. Two ways to retrieve it:

* **For a specific country** - use `GET /v3/variants/{variantId}` with `location` (default `US`) and `fields=pricing`
* **Across all countries** - use [`GET /v3/variants/{variantId}/availability`](#get-variant-availability) to retrieve the full per-country availability map

#### Personalization data

The `personalization` object indicates whether the variant supports custom personalization (e.g. a printed name or message) and what template fields are configurable. It is `null` when personalization isn't available for the variant.

#### Availability vs pricing

The availability endpoint returns a map of countries the variant ships to, with country-specific pricing inline. Country codes **not present** in the response should be treated as `isAvailable: false` - only supported countries are returned.

For per-recipient validation, the typical pattern is: check availability once via `GET /v3/variants/{variantId}/availability`, then place an order with the appropriate `location` parameter on `POST /v3/orders`.

#### Account scoping

The optional `Snappy-Account-Id` header scopes queries to a specific Account - primarily for swag validation and filtering.

#### Permissions

All V3 Variants endpoints require the `products:read` scope. (The Variants API shares the `products:read` scope with the Products API since they're part of the same catalog domain.)

***

## How to Work with Variants

**Get a single variant**

```text theme={null} theme={null}
GET /v3/variants/{variantId}
```

Returns a single variant by its ID. Use `fields` to expand pricing and details, and `include=brand` to inline the brand object.

**Get variant availability**

```text theme={null} theme={null}
GET /v3/variants/{variantId}/availability
```

Returns an availability map keyed by ISO 3166-1 alpha-2 country code. Each entry indicates whether the variant ships to that country and includes the country-specific pricing.

***

<Note>
  Looking for **swag base variants** (variations of branded merchandise templates) instead of marketplace variants? See the [Swag](/modules/api/v3/base-products/overview) page.
</Note>