> ## 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 product variants > Use this endpoint to retrieve a paginated list of variants for a specific product. ###### Filtering options: - Selected options (e.g., size, color) - exact match, multiple options are ANDed together - Price range (min and max) ###### Optional parameters - `include=brand` - include the variant's `brand` object (same shape as the product-level brand, nullable) - `fields=pricing,details` - include variant pricing (`price` and `priceBreakdown`) and the structured `details` wrapper - `filter[price][gte]` / `filter[price][lte]` - inclusive min/max variant price filter - `location` - ISO 3166-1 alpha-2 country code (default `US`) to scope pricing - `page[number]` / `page[size]` - page-number pagination (1-indexed; max 300 per page, default 100) - `Snappy-Account-Id` / `Snappy-Company-Id` headers - optional scoping ###### Please note When `fields` is omitted, `price`, `priceBreakdown`, and `details` are not returned in the public response. Unknown filter keys will return a 400 error. #### Permissions - Requires: `products:read` ## OpenAPI ````yaml get /v3/products/{productId}/variants 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/products/{productId}/variants: get: tags: - Products summary: Get product variants description: >- Use this endpoint to retrieve a paginated list of variants for a specific product. ###### Filtering options: - Selected options (e.g., size, color) - exact match, multiple options are ANDed together - Price range (min and max) ###### Optional parameters - `include=brand` - include the variant's `brand` object (same shape as the product-level brand, nullable) - `fields=pricing,details` - include variant pricing (`price` and `priceBreakdown`) and the structured `details` wrapper - `filter[price][gte]` / `filter[price][lte]` - inclusive min/max variant price filter - `location` - ISO 3166-1 alpha-2 country code (default `US`) to scope pricing - `page[number]` / `page[size]` - page-number pagination (1-indexed; max 300 per page, default 100) - `Snappy-Account-Id` / `Snappy-Company-Id` headers - optional scoping ###### Please note When `fields` is omitted, `price`, `priceBreakdown`, and `details` are not returned in the public response. Unknown filter keys will return a 400 error. #### 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: Stable product ID. example: 655277e68e0719000d6c3fd5 required: true description: Stable product ID. name: productId 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: number nullable: true minimum: 0 description: Inclusive minimum variant price filter. example: 10 required: false description: Inclusive minimum variant price filter. name: filter[price][gte] in: query - schema: type: number nullable: true minimum: 0 description: Inclusive maximum variant price filter. example: 200 required: false description: Inclusive maximum variant price filter. name: filter[price][lte] 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 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: integer minimum: 1 default: 1 description: 1-indexed page number. example: 1 required: false description: 1-indexed page number. name: page[number] in: query - schema: type: integer minimum: 1 maximum: 300 default: 100 description: Number of variants per page (max 300, default 100). example: 100 required: false description: Number of variants per page (max 300, default 100). name: page[size] in: query - 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: Paginated list of variants. content: application/json: schema: $ref: '#/components/schemas/GetProductVariantsV3Response' '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 - Product or variants not found. content: application/json: schema: $ref: '#/components/schemas/ErrorResponseV3' example: message: Product not found. errorCode: 404_PROD_001 errors: - errorCode: 404_PROD_001 message: Product with id 'q1w2e3r4t5' was not found path: pathParameters.productId 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 GetProductVariantsV3Response: type: object properties: data: type: array items: allOf: - $ref: '#/components/schemas/VariantV3' - description: >- A single variant. `price`, `priceBreakdown`, `descriptionHtml`, `details`, and `brand` are returned only when requested via `fields` or `include=brand` on variant endpoints. `fields=pricing` returns `price` and `priceBreakdown`. `descriptionHtml` is a Variant **root-level** field (not part of `details`). description: Variants for the requested page. links: $ref: '#/components/schemas/PaginationLinksV3' required: - data - links description: Paginated variant list response (page-number pagination). 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. VariantV3: 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: First selectable variant for this option value. PaginationLinksV3: type: object properties: first: type: string nullable: true description: Link to the first page. example: >- /v3/products/655277e68e0719000d6c3fd5/variants?page[size]=100&page[number]=1 next: type: string nullable: true description: Link to the next page, or `null` on the final page. example: >- /v3/products/655277e68e0719000d6c3fd5/variants?page[size]=100&page[number]=2 prev: type: string nullable: true description: Link to the previous page, or `null` when not applicable. example: null required: - first - next - prev description: >- Top-level JSON:API-style pagination links for paginated list responses. `first`, `next`, and `prev` are all required and all nullable. `prev` is `null` on cursor-paginated endpoints (backward navigation not supported). 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 ``` ````