> ## 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.
# Get variant by ID
> Use this endpoint to retrieve a specific Variant by its ID. Returns the parent Product object with the requested Variant in its `variants` array.
###### Required fields:
- `variantId` - the Variant identifier, passed as a path parameter
###### Optional parameters:
- `companyId` query parameter - Company ID (when not inferable from the calling key)
- `country` query parameter - ISO 3166-1 alpha-2 country code
- `fields` query parameter - comma-separated field projection. Valid values: `mediaItems`, `tags`, `brand`, `optionAttributes`, `notices`, `pricing`, `supportedCountries`, `full`
- `Request-Source` header - source of the request
###### Please note:
- This endpoint returns the **parent Product** with the requested Variant inside its `variants` array - not the Variant in isolation. Locate the specific variant inside the returned `variants` list using the supplied `variantId`.
- Returns `422` when the Variant doesn't exist or isn't accessible to the calling key.
#### Permissions
- Requires: `products:read`
## OpenAPI
````yaml get /v2/variants/{variantId}
openapi: 3.0.0
info:
title: Snappy Public API
version: 2.0.0
contact:
name: Snappy Support
email: info@snappy.com
description: >-
Welcome to the Snappy API reference documentation!
You can use this API to integrate with Snappy and spread smiles to your
employees/clients/customers and much more.
In just 3 simple steps you can start sending gifts today: pull the relevant
campaign, send gifts to your recipients and track gift statuses.
So let's get started!
servers:
- url: https://api.snappy.com/public-api
description: Base API URL
- url: https://mtls-api.snappy.com/public-api
description: >-
## mTLS URL
You can also use mTLS to enhance your API security. To get your specific
certificates please contact our support.
Once you configure the certificated correctly, you need to also update
endpoints to use the following secure api base URL:
security: []
tags:
- name: Authentication
description: >-
API keys authenticate requests to the Snappy API. Use these endpoints to
list active keys for your Company, create new keys, or delete keys you no
longer need.
- name: Accounts
description: >-
An **Account** is a sub-entity that lives within a **Company**. Accounts
are used to separate and organize your company's campaigns and gift sends
for different teams, departments or budget owners.
- name: Campaigns
description: >-
A **Campaign** is the primary organizational object used to configure and
send a batch of gifts. It acts as a template for all the settings of a
single gifting initiative, including the target **Recipient** list, the
selected **Collection** or **product**, the budget, branding, and
notification messages.
- name: Collections
description: >-
A **Collection** is a curated catalog of gift items tailored to a specific
theme, budget range, and audience (e.g., "Birthday Gifts Under $50"). The
gift recipient then chooses their preferred item directly from this
collection.
Use these endpoints to:
- Get available collections based on budget and country requirements
- Retrieve budget ranges for specific collections
- Access collection details and products
Please note: Swag collections can only be retrieved by specifying the
accountId in the request.
- name: Products & Variants
description: >-
Use these endpoints to search for and retrieve products and variants
(including by collection and budget), and to list product tags for
building catalog and filtering experiences in your UI.
- name: Gifts
description: >-
A **Gift** is the core transactional object in the Snappy system. It
represents the entire gifting experience for a **Recipient** within a
**Campaign**, from initial creation to final delivery.
The **Gift** object tracks the status and details through each stage of
its lifecycle:
1. **Creation:** The gift is initiated and associated with a recipient and
campaign.
2. **Notification:** The recipient is notified about their gift via email
or other channels.
3. **Selection:** The recipient selects a specific product from the gift
collection (if applicable).
4. **Order Generation:** An order is created based on the selected product
and the recipient's shipping address.
5. **Delivery:** The physical product is shipped and its delivery status
is tracked to completion.
- name: Orders
description: >-
Endpoints for programmatically claiming gifts (ordering on behalf of
recipients), cancelling orders before they ship, and validating or
autocompleting shipping addresses as part of your checkout or fulfillment
flow.
- name: Recipients
description: A **Recipient** is the end-user who receives a **Gift**.
paths:
/v2/variants/{variantId}:
get:
tags:
- Products & Variants
summary: Get variant by ID
description: >-
Use this endpoint to retrieve a specific Variant by its ID. Returns the
parent Product object with the requested Variant in its `variants`
array.
###### Required fields:
- `variantId` - the Variant identifier, passed as a path parameter
###### Optional parameters:
- `companyId` query parameter - Company ID (when not inferable from the
calling key)
- `country` query parameter - ISO 3166-1 alpha-2 country code
- `fields` query parameter - comma-separated field projection. Valid
values: `mediaItems`, `tags`, `brand`, `optionAttributes`, `notices`,
`pricing`, `supportedCountries`, `full`
- `Request-Source` header - source of the request
###### Please note:
- This endpoint returns the **parent Product** with the requested
Variant inside its `variants` array - not the Variant in isolation.
Locate the specific variant inside the returned `variants` list using
the supplied `variantId`.
- Returns `422` when the Variant doesn't exist or isn't accessible to
the calling key.
#### Permissions
- Requires: `products:read`
operationId: getVariantById
parameters:
- schema:
type: string
pattern: ^[A-Za-z0-9]{8,}$
description: Variant ID
example: ab6789cd
required: true
description: Variant ID
name: variantId
in: path
- schema:
type: string
pattern: ^[A-Za-z0-9]{8,}$
description: Company ID
example: '12345678'
required: false
description: Company ID
name: companyId
in: query
- schema:
type: string
required: false
name: country
in: query
- schema:
type: array
items:
$ref: '#/components/schemas/ProductFields'
minItems: 1
uniqueItems: true
description: List of additional fields to include in response objects
example:
- full
required: false
description: List of additional fields to include in response objects
style: form
explode: false
name: fields
in: query
- schema:
$ref: '#/components/schemas/RequestSourceHeader'
required: false
description: Source of the request
name: Request-Source
in: header
responses:
'200':
description: Successful response
content:
application/json:
schema:
$ref: '#/components/schemas/GetVariantByIdResponse'
'400':
description: Bad Request
content:
application/json:
schema:
$ref: '#/components/schemas/ApiStringError'
'401':
description: Unauthorized
content:
application/json:
schema:
allOf:
- $ref: '#/components/schemas/ApiStringError'
- example:
status: 401
errorCode: 401_PBLC_001
message: Unauthorized
'403':
description: Forbidden
content:
application/json:
schema:
allOf:
- $ref: '#/components/schemas/ApiStringError'
- example:
status: 403
errorCode: 403_PBLC_001
message: Forbidden
'422':
description: Product Not Found
content:
application/json:
schema:
allOf:
- $ref: '#/components/schemas/ApiStringError'
- example:
status: 422
errorCode: 422_PBLC_001
message: Product not found
security:
- CompanyLevelAuthentication: []
- BearerAuthentication: []
components:
schemas:
ProductFields:
type: string
enum:
- mediaItems
- tags
- brand
- optionAttributes
- notices
- pricing
- supportedCountries
- full
description: >-
The fields to return additionally in response.
Valid values are: mediaItems, tags, brand, optionAttributes, notices,
pricing, supportedCountries, full.
example: full
RequestSourceHeader:
type: string
enum:
- api_native
- api_zapier
- api_salesforce
- api_ftp
- api_make
description: Source of the request
example: api_native
GetVariantByIdResponse:
type: object
properties:
id:
type: string
description: Product ID
example: abc12345
title:
type: string
description: Product title
example: Product Title
category:
type: string
description: Product category
example: Electronics
brand:
$ref: '#/components/schemas/Brand'
coverImage:
$ref: '#/components/schemas/Media'
options:
$ref: '#/components/schemas/Options'
tags:
type: array
items:
$ref: '#/components/schemas/Tag'
description: Product tags
variants:
type: array
items:
$ref: '#/components/schemas/Variant'
description: Product variants
types:
type: array
items:
$ref: '#/components/schemas/ProductType'
description: Product types
mediaItems:
type: array
items:
$ref: '#/components/schemas/Media'
description: Product media items
notices:
type: object
additionalProperties:
type: string
description: Product notices
example:
shipping: Ships within 3-5 business days
warranty: 1 year warranty
description: Response containing variant details.
example:
id: prodSample01
title: Insulated Stainless Tumbler 30oz
category: Swag
types:
- physical
- on-demand-plus-swag
coverImage:
type: image
publicCloudinaryId: sample-product-image-1
src: https://example.com/images/sample-product-image-1.png
position: 1
mediaItems:
- type: image
publicCloudinaryId: sample-product-image-1
src: https://example.com/images/sample-product-image-1.png
position: 1
- type: image
publicCloudinaryId: sample-product-image-2
src: https://example.com/images/sample-product-image-2.png
position: 2
brand:
id: brandSample01
name: Sample Brand
description: null
tags: []
notices: {}
variants:
- id: varSample01
title: Insulated Stainless Tumbler 30oz - Black
types:
- physical
- on-demand-plus-swag
category: Swag
information:
including: null
description: >-
A double-wall stainless tumbler with a push-on lid and slide
closure.
features: null
specifications:
dimensions: 8in H x 4in W
materials: Stainless steel
weight: 28oz
mediaItems:
- type: image
publicCloudinaryId: sample-variant-image-1
src: https://example.com/images/sample-variant-image-1.png
position: 1
brand:
id: brandSample01
name: Sample Brand
description: null
tags: []
notices: {}
optionAttributes:
color: black
size: 30oz
pricing:
US:
cost: 45
ddp: 0
shipping: 9
totalTax: 4.5
totalFee: 6.75
totalFinalCost: 56.25
supportedCountries:
- countryCode: US
- countryCode: CA
- countryCode: GB
ApiStringError:
type: object
properties:
status:
type: integer
description: The HTTP status code.
example: 400
errorCode:
type: string
description: >-
Internal error code, helps Snappy's technical team to troubleshoot
if needed.
example: 400_PBLC_001
message:
type: string
description: The error message.
example: Unauthorized
errors:
type: array
items:
type: object
properties:
path:
type: string
description: The path of the field that caused the error.
example: body.recipients.0.email
message:
type: string
description: The error message.
example: Invalid email.
errorCode:
type: string
description: >-
Internal error code, helps Snappy's technical team to
troubleshoot if needed.
example: 400_PBLC_002
required:
- path
- message
- errorCode
description: >-
An array of client errors. This field is being returned only for
errors the client should fix, usually with status code 400.
required:
- status
- errorCode
- message
description: >-
API error response with string error codes and optional client error
details
example:
status: 400
errorCode: 400_PBLC_001
message: Bad Request
Brand:
type: object
nullable: true
properties:
id:
type: string
nullable: true
description: Brand ID
example: abCd57eFG0
name:
type: string
description: Brand name
example: Brand Name
description:
type: string
nullable: true
description: Brand description
example: Brand Description
description: Brand information for a product.
example:
id: abCd57eFG0
name: Brand Name
description: Brand Description
Media:
type: object
properties:
position:
type: number
description: Position of the media item
example: 1
type:
$ref: '#/components/schemas/MediaType'
publicCloudinaryId:
type: string
nullable: true
description: Public Cloudinary ID
example: bnxjv94tmzq1w8eplk73ua_picture-1.png
src:
type: string
description: Source URL of the media
example: https://example.com/bnxjv94tmzq1w8eplk73ua_picture-1.png
description: Media item for a product.
example:
position: 1
type: image
publicCloudinaryId: bnxjv94tmzq1w8eplk73ua_picture-1.png
src: https://example.com/bnxjv94tmzq1w8eplk73ua_picture-1.png
Options:
type: object
properties:
takeYourPick:
type: string
description: Take your pick option
example: Rainbow Bagel Making Kit
color:
type: string
description: Color option
example: Black
size:
type: string
description: Size option
example: S
scent:
type: string
description: Scent option
example: Lavender
flavor:
type: string
description: Flavor option
example: Chocolate
beverageType:
type: string
description: Beverage type option
example: Coffee
description: Product options and attributes.
example:
takeYourPick: Rainbow Bagel Making Kit
color: Black
size: S
scent: Lavender
flavor: Chocolate
beverageType: Coffee
Tag:
type: object
properties:
id:
type: string
description: Tag ID
example: tag12345A
name:
type: string
description: Tag name
example: Tag Name
color:
type: string
description: Tag color
example: '#000000'
position:
type: number
description: Tag position
example: 1
description: Tag information for a product.
example:
id: tag12345A
name: Tag Name
color: '#000000'
position: 1
Variant:
type: object
properties:
id:
type: string
description: Variant ID
example: ab6789cd
optionAttributes:
$ref: '#/components/schemas/Options'
brand:
$ref: '#/components/schemas/Brand'
components:
type: string
nullable: true
description: Variant components
example: Component details
description:
type: string
description: Variant description
example: Variant description
features:
type: string
nullable: true
description: Variant features
example: Variant features
category:
type: string
description: >-
Stringified 4-level hierarchical product category path concatenated
by forward slashes. This represents the complete category taxonomy
from the broadest level down to the most specific classification,
providing a clear categorization structure for the variant. Format:
"Level1 / Level2 / Level3 / Level4" where each level becomes
progressively more specific.
example: Electronics / Audio / Headphones / Wireless Earbuds
mediaItems:
type: array
items:
$ref: '#/components/schemas/Media'
description: Variant media items
position:
type: number
description: Variant position
types:
type: array
items:
$ref: '#/components/schemas/ProductType'
description: Variant product types
tags:
type: array
items:
$ref: '#/components/schemas/Tag'
description: Variant tags
title:
type: string
description: Variant title
example: Variant title
information:
$ref: '#/components/schemas/Information'
notices:
type: object
additionalProperties:
type: string
description: Variant notices
pricing:
type: object
additionalProperties:
type: object
properties:
cost:
type: number
description: Base cost of the item
ddp:
type: number
description: Country-specific delivered duty paid amount
shipping:
type: number
description: Country-specific shipping amount
totalFee:
type: number
description: Total fees applied
totalTax:
type: number
description: Total tax amount
totalFinalCost:
type: number
description: Total final cost including all fees and taxes
required:
- cost
- ddp
- shipping
- totalFee
- totalTax
- totalFinalCost
description: >-
Country-specific pricing information with detailed cost breakdown
for each supported market. This object contains pricing data keyed
by ISO country codes (e.g., "US", "CA", "GB"), where each country
entry provides a comprehensive breakdown of costs including base
price, applicable fees, taxes, and the final calculated price. This
field is returned when requested with fields=pricing or fields=full.
example:
US:
cost: 100
ddp: 10
shipping: 5
totalFee: 2
totalTax: 7
totalFinalCost: 109
supportedCountries:
type: array
items:
type: object
properties:
countryCode:
type: string
pattern: ^[A-Z]{2}$
description: ISO 3166-1 alpha-2 country code
required:
- countryCode
description: >-
List of countries where this variant is available for purchase. This
array contains country objects with ISO country codes, typically
used for filtering and availability checks. This field is populated
when requested via the "fields" query parameter to optimize response
payload size and reduce unnecessary data transfer.
example:
- countryCode: US
- countryCode: CA
- countryCode: GB
- countryCode: DE
- countryCode: FR
description: Product variant information.
example:
id: ab6789cd
description: Variant description
features: Variant features
ProductType:
type: string
enum:
- digital
- physical
- base-product-swag
- on-demand-swag
- on-demand-plus-swag
- premium-swag
- experience
- personalized
description: The type of product.
example: digital
MediaType:
type: string
enum:
- image
- video
description: The type of media item.
example: image
Information:
type: object
properties:
including:
type: string
nullable: true
description: What is included
example:
description:
type: string
description: Product description
example: Cutest puppy in the world
features:
type: string
nullable: true
description: Product features
example:
specifications:
$ref: '#/components/schemas/Specifications'
description: Detailed product information.
example:
including:
description: Cutest puppy in the world
features:
specifications:
colorFamily: Brown
dimensions: 37in x17in 6in
materials: Cotton
weight: 1.5 lbs
Specifications:
type: object
nullable: true
properties:
colorFamily:
type: string
description: Color family
example: Brown
dimensions:
type: string
description: Product dimensions
example: 37in x17in 6in
materials:
type: string
description: Product materials
example: Cotton
weight:
type: string
description: Product weight
example: 1.5 lbs
description: Product specifications.
example:
colorFamily: Brown
dimensions: 37in x17in 6in
materials: Cotton
weight: 1.5 lbs
securitySchemes:
CompanyLevelAuthentication:
type: apiKey
in: header
name: X-Api-Key
description: >
## Company Level Authentication
Company level authentication provides access to all resources under your
company, including accounts, campaigns, gifts, and recipients.
### Getting Your API Key
1. **Create an API Key**: Use the `POST /v2/authentication/apiKeys`
endpoint to generate a new API key
2. **Set Expiration**: Choose from 30, 60, 90, or 180 days (default: 90
days)
3. **Optional mTLS**: Enable mutual TLS for enhanced security
4. **Name Your Key**: Provide a descriptive name for easy identification
### Using Your API Key
Include your API key in the `X-Api-Key` header for every request:
```
X-Api-Key: YOUR_24_CHARACTER_API_KEY
```
### API Key Management
- **Maximum Keys**: Up to 3 active API keys per company
- **Rotation**: Delete old keys before creating new ones when at the
limit
- **Security**: Keys are hashed and cannot be retrieved after creation
### Enhanced Security (mTLS)
For production environments, enable mutual TLS authentication:
1. Set `enforceMtls: true` when creating the API key
2. Contact support to obtain your client certificates
3. Use the mTLS endpoint: `https://mtls-api.snappy.com/public-api`
BearerAuthentication:
type: http
scheme: bearer
bearerFormat: JWT
description: >-
Bearer authentication provides access to all resources under your
company, including accounts, campaigns, gifts, and recipients.
````