> ## 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 by ID

> Use this endpoint to retrieve a single product by its stable product ID. Returns product-level fields only.

###### Optional parameters
- `include=brand,tags` - return related entities in the response
- `fields=options,priceRange,variantsCount` - return additional product fields. On this endpoint, `fields=options` returns the aggregated variant options array.
- `filter[price][gte]` / `filter[price][lte]` - scope the variants used when computing `priceRange` and `variantsCount`
- `location` - ISO 3166-1 alpha-2 country code (default `US`)
- `Snappy-Account-Id` / `Snappy-Company-Id` headers - optional scoping

###### Please note
- This endpoint returns product-level data only. Use `GET /v3/products/{productId}/variants` to retrieve the full paginated variants list.
- `filter[price][gte]` and `filter[price][lte]` scope the *variants* used when computing `priceRange` and `variantsCount` - they do not filter whether the product itself is returned.

#### Permissions
- Requires: `products:read`



## OpenAPI

````yaml get /v3/products/{productId}
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}:
    get:
      tags:
        - Products
      summary: Get product by ID
      description: >-
        Use this endpoint to retrieve a single product by its stable product ID.
        Returns product-level fields only.


        ###### Optional parameters

        - `include=brand,tags` - return related entities in the response

        - `fields=options,priceRange,variantsCount` - return additional product
        fields. On this endpoint, `fields=options` returns the aggregated
        variant options array.

        - `filter[price][gte]` / `filter[price][lte]` - scope the variants used
        when computing `priceRange` and `variantsCount`

        - `location` - ISO 3166-1 alpha-2 country code (default `US`)

        - `Snappy-Account-Id` / `Snappy-Company-Id` headers - optional scoping


        ###### Please note

        - This endpoint returns product-level data only. Use `GET
        /v3/products/{productId}/variants` to retrieve the full paginated
        variants list.

        - `filter[price][gte]` and `filter[price][lte]` scope the *variants*
        used when computing `priceRange` and `variantsCount` - they do not
        filter whether the product itself is returned.


        #### 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/ProductIncludeV3'
            description: Related entities to include.
            example:
              - brand
              - tags
          required: false
          description: Related entities to include.
          name: include
          in: query
          style: form
          explode: false
        - schema:
            type: array
            items:
              $ref: '#/components/schemas/ProductSingleFieldsV3'
            description: Computed or expanded product fields.
            example:
              - options
              - priceRange
              - variantsCount
          required: false
          description: Computed or expanded product fields.
          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: Product.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GetProductByIdV3Response'
        '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 does not exist.
          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:
    ProductIncludeV3:
      type: string
      enum:
        - brand
        - tags
      description: Related entities to include.
      example: brand
    ProductSingleFieldsV3:
      type: string
      enum:
        - options
        - priceRange
        - variantsCount
      description: Computed or expanded fields for product responses.
      example: priceRange
    GetProductByIdV3Response:
      type: object
      properties:
        id:
          type: string
          description: Stable product identifier.
          example: 655277e68e0719000d6c3fd5
        title:
          type: string
          description: Product title.
          example: NFL 25-Layer StadiumView Wall Art
        createdAt:
          type: string
          format: date-time
          description: Product creation date.
          example: '2026-05-11T10:53:01.026Z'
        media:
          type: array
          items:
            $ref: '#/components/schemas/MediaV3'
          description: Product media.
        category:
          type: object
          properties:
            fullName:
              type: string
              description: Full taxonomy path.
              example: Fan Merchandise / NFL / NFL Memorabilia / Autographed Helmets
          required:
            - fullName
          description: Product category.
        catalog:
          type: string
          enum:
            - marketplace
            - swag
            - giftCards
            - donations
          description: Product catalog.
          example: marketplace
        brand:
          $ref: '#/components/schemas/ProductBrandV3'
        tags:
          type: array
          items:
            $ref: '#/components/schemas/ProductTagV3'
          description: Returned only when `include=tags`.
        options:
          type: array
          items:
            $ref: '#/components/schemas/ProductOptionV3'
          description: Aggregated variant options.
        priceRange:
          $ref: '#/components/schemas/PriceRangeV3'
        variantsCount:
          type: integer
          minimum: 0
          description: Returned only when `fields` includes `variantsCount`.
          example: 9
      required:
        - id
        - title
        - createdAt
        - media
        - category
        - catalog
      description: Product.
    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.
    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.
    ProductTagV3:
      type: object
      properties:
        id:
          type: string
          description: Tag ID.
          example: tag12345
        name:
          type: string
          description: Tag name.
          example: Sustainable
      required:
        - id
        - name
      description: Product tag.
    ProductOptionV3:
      type: object
      properties:
        name:
          type: string
          description: Option name.
          example: nfl_team
        displayName:
          type: string
          description: Option display name.
          example: Team
        displayType:
          type: string
          description: Display type hint.
          example: image
        values:
          type: array
          items:
            $ref: '#/components/schemas/ProductOptionValueV3'
          description: Available values.
      required:
        - name
        - displayName
        - displayType
        - values
      description: Aggregated product option.
    PriceRangeV3:
      type: object
      properties:
        min:
          $ref: '#/components/schemas/PriceV3'
        max:
          $ref: '#/components/schemas/PriceV3'
      required:
        - min
        - max
      description: >-
        Min/max pricing across the product's variants. Returned only when
        `fields` includes `priceRange`.
    ProductOptionValueV3:
      type: object
      properties:
        displayName:
          type: string
          description: Option value display name.
          example: Denver Broncos
        value:
          type: string
          description: Option value.
          example: Denver Broncos
        firstSelectableVariant:
          $ref: '#/components/schemas/VariantV3'
      required:
        - displayName
        - value
        - firstSelectableVariant
      description: Product option value.
    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.
    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: <p>The 25-Layer StadiumViews 3D Wall Art</p>
        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.
    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.
    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: <p>Set of 4 glasses (12oz each)</p>
        features:
          type: string
          nullable: true
          description: HTML product highlights.
          example: <ul><li>Feature</li></ul>
        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`.
  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
        ```

````