> ## 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 single product variant by its ID. Returns the same `Variant` object shape as items in the Get product variants list response.
#### Optional parameters
- `fields=pricing` - include `price` and `priceBreakdown`
- `fields=details` - include the `details` wrapper
- `include=brand` - include the variant's `brand` object
#### Please note
When `fields` is omitted, `price`, `priceBreakdown`, and `details` are not returned in the public response.
#### Permissions
- Requires: `products:read`
## OpenAPI
````yaml get /v3/variants/{variantId}
openapi: 3.0.3
info:
title: Snappy Public API v3
version: 3.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.
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: Products
description: >-
Use these endpoints to retrieve products and tags for building catalog and
browse experiences in your UI.
- name: Collections
description: >-
Use these endpoints to retrieve products within curated collections for
marketplace and browse experiences.
- name: Variants
description: >-
Use these endpoints to retrieve variants, variant pricing, and country
availability for orderable product SKUs.
- name: Billing Methods
description: >-
A **Billing Method** is the funding source attached to an **Account** -
for example, a Purchase Order (PO), Invoice, Prepay deposit, or Credit
Card. Use these endpoints to retrieve billing method details such as
remaining balance, status, and expiration.
- name: Accounts
description: >-
An **Account** is a sub-entity within a **Company**, used to organize
campaigns and gift sends. Use these endpoints to list, retrieve, and
create accounts.
- name: API Keys
description: >-
Use these endpoints to manage API keys for programmatic access. Key
management requires company owner privileges.
- name: Orders
description: >-
Use these endpoints to place, retrieve, cancel, and validate orders and
shipping addresses.
paths:
/v3/variants/{variantId}:
get:
tags:
- Variants
summary: Get variant by ID
description: >-
Use this endpoint to retrieve a single product variant by its ID.
Returns the same `Variant` object shape as items in the Get product
variants list response.
#### Optional parameters
- `fields=pricing` - include `price` and `priceBreakdown`
- `fields=details` - include the `details` wrapper
- `include=brand` - include the variant's `brand` object
#### Please note
When `fields` is omitted, `price`, `priceBreakdown`, and `details` are
not returned in the public response.
#### Permissions
- Requires: `products:read`
parameters:
- schema:
type: string
pattern: >-
^(?:^[A-Za-z0-9]{8,}$|^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$)$
description: Variant ID.
example: FB6bgFV4lf
required: true
description: Variant ID.
name: variantId
in: path
- schema:
type: string
pattern: ^[A-Z]{2}$
default: US
description: ISO 3166-1 alpha-2 country code.
example: US
required: false
description: ISO 3166-1 alpha-2 country code.
name: location
in: query
- schema:
type: array
items:
$ref: '#/components/schemas/VariantIncludeV3'
description: Related entities to include.
example:
- brand
required: false
description: Related entities to include.
name: include
in: query
style: form
explode: false
- schema:
type: array
items:
$ref: '#/components/schemas/VariantFieldsV3'
description: >-
Comma-separated list of variant-level field expansions.
- `pricing` - includes `price` and `priceBreakdown`.
- `details` - includes the variant `details` wrapper.
Use `include=brand` to include the variant's `brand` object
(nullable).
When omitted, `price`, `priceBreakdown`, and `details` are not
returned in the public response.
example:
- pricing
- details
required: false
description: >-
Comma-separated list of variant-level field expansions.
- `pricing` - includes `price` and `priceBreakdown`.
- `details` - includes the variant `details` wrapper.
Use `include=brand` to include the variant's `brand` object
(nullable).
When omitted, `price`, `priceBreakdown`, and `details` are not
returned in the public response.
name: fields
in: query
style: form
explode: false
- schema:
type: string
description: Optional account identifier for swag validation/filtering.
example: acc123456
required: false
description: Optional account identifier for swag validation/filtering.
name: snappy-account-id
in: header
- schema:
type: string
description: Optional company identifier for swag validation/filtering.
example: cmp123456
required: false
description: Optional company identifier for swag validation/filtering.
name: snappy-company-id
in: header
responses:
'200':
description: Single variant.
content:
application/json:
schema:
$ref: '#/components/schemas/GetVariantByIdV3Response'
'400':
description: Bad Request - Invalid query parameters.
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponseV3'
example:
message: Request validation failed.
errorCode: 400_PBLC_001
errors:
- errorCode: 400_PBLC_001
message: >-
filter[price][gte] must be less than or equal to
filter[price][lte]
path: queryStringParameters.filter[price][gte]
'404':
description: Not Found - Variant does not exist or location is not supported.
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponseV3'
example:
message: Variant not found.
errorCode: 404_PDCT_001
errors:
- errorCode: 404_PDCT_001
message: Variant with id 'q1w2e3r4t5' was not found
path: pathParameters.variantId
security:
- ApiKeyAuthentication: []
components:
schemas:
VariantIncludeV3:
type: string
enum:
- brand
description: Related entities to include.
example: brand
VariantFieldsV3:
type: string
enum:
- pricing
- details
description: Variant-level field expansions.
example: pricing
GetVariantByIdV3Response:
type: object
properties:
id:
type: string
description: Variant identifier.
example: FB6bgFV4lf
productId:
type: string
description: Parent product identifier.
example: 655277e68e0719000d6c3fd5
title:
type: string
description: Variant title.
example: NFL 25-Layer StadiumView Wall Art
selectedOptions:
type: object
additionalProperties:
type: string
description: Selected option values for this variant.
example:
nfl_team: Denver Broncos
taxable:
type: boolean
description: Whether the variant is taxable.
example: true
media:
type: array
items:
$ref: '#/components/schemas/MediaV3'
description: Variant media.
personalization:
$ref: '#/components/schemas/PersonalizationV3'
price:
$ref: '#/components/schemas/PriceV3'
priceBreakdown:
$ref: '#/components/schemas/PriceBreakdownV3'
descriptionHtml:
type: string
description: HTML full narrative description.
example: The 25-Layer StadiumViews 3D Wall Art
details:
$ref: '#/components/schemas/VariantDetailsV3'
brand:
$ref: '#/components/schemas/ProductBrandV3'
shippingRequired:
type: boolean
required:
- id
- title
- selectedOptions
- taxable
- media
- personalization
description: Single variant.
ErrorResponseV3:
type: object
properties:
message:
type: string
description: Human-readable error message.
example: Product not found.
errorCode:
type: string
description: Structured error code.
example: 404_PROD_001
errors:
type: array
items:
type: object
properties:
message:
type: string
example: Product with id 'q1w2e3r4t5' was not found
path:
type: string
description: Dot-separated path to the field that caused the error.
example: pathParameters.productId
errorCode:
type: string
example: 404_PROD_001
required:
- message
- path
description: Optional field-level error details.
required:
- message
- errorCode
description: Standard v3 error envelope.
MediaV3:
type: object
properties:
type:
type: string
enum:
- image
- video
description: Media type.
example: image
src:
type: string
format: uri
description: Media source URL.
example: >-
https://media.snappy.com/image/o1xc17wfbda6cl91hm0r6_picture-1.jpg?w=1000&h=1000&q=80&f=auto
required:
- type
- src
description: A media item for v3 endpoints.
PersonalizationV3:
type: object
nullable: true
properties:
isPersonalized:
type: boolean
description: Whether the variant is personalizable.
example: true
personalizationTemplateFields:
type: array
items:
type: string
description: Personalization template field names.
example:
- firstName
- lastName
- department
required:
- isPersonalized
- personalizationTemplateFields
description: Personalization metadata, or null when unavailable.
PriceV3:
type: object
properties:
amount:
type: number
example: 244.99
currency:
type: string
description: ISO 4217 currency code.
example: USD
required:
- amount
- currency
description: Variant price in a given currency.
PriceBreakdownV3:
type: object
properties:
ddp:
type: number
description: Delivered Duty Paid charges (duties + import taxes).
example: 0
shippingFee:
type: number
example: 0
itemPrice:
type: number
description: Base item price before shipping/duties.
example: 244.99
required:
- ddp
- shippingFee
- itemPrice
description: Detailed breakdown of the variant price.
VariantDetailsV3:
type: object
properties:
includes:
type: string
nullable: true
description: HTML content describing what is included.
example: Set of 4 glasses (12oz each)
features:
type: string
nullable: true
description: HTML product highlights.
example:
specifications:
type: object
nullable: true
additionalProperties:
type: string
description: Structured key-value non-regulatory specifications.
example:
material: lead-free glass
capacity: 12oz
dimensions: 4.5' tall
notices:
type: object
nullable: true
additionalProperties:
type: string
description: Structured key-value regulatory notices.
example:
prop65Warning: Warning text
description: >-
Variant-level structured details wrapper. Returned only when `fields`
includes `details`.
ProductBrandV3:
type: object
nullable: true
properties:
id:
type: string
description: Brand ID.
example: 6511b55142c420000d083a55
name:
type: string
description: Brand name.
example: YouTheFan
description:
type: string
nullable: true
description: Brand description.
example: Officially licensed NFL fan merchandise.
required:
- id
- name
- description
description: >-
Product or variant brand. Returned only when `include=brand`. Nullable
when the product or variant has no brand.
securitySchemes:
ApiKeyAuthentication:
type: apiKey
in: header
name: X-Api-Key
description: |-
## Company Level Authentication
Include your API key in the `X-Api-Key` header for every request:
```
X-Api-Key: YOUR_API_KEY
```
````