Skip to main content
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.
Want to understand how Variants fit into the bigger picture? Check out the Core Concepts & Data Models page.
To list all variants for a specific product, use GET /v3/products/{productId}/variants - this is part of the Products API since it’s scoped to a product.

​
The Variant Object

​
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 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
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
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.
Looking for swag base variants (variations of branded merchandise templates) instead of marketplace variants? See the Swag page.
Last modified on June 30, 2026