> ## Documentation Index
> Fetch the complete documentation index at: https://developers.firmly.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Get a Product

> Retrieves detailed information about a specific product

Gets comprehensive product information including variants, pricing, availability, and images. Use this endpoint to display product detail pages or product cards in your application.

## Path Parameters

<ParamField path="merchant-domain" type="string" required>
  The domain of the merchant website (e.g., `staging.luma.gift`)
</ParamField>

<ParamField path="product-handle" type="string" required>
  The product handle or identifier. This is typically the URL-friendly version of the product name.
</ParamField>

## Query Parameters

<ParamField query="postal_code" type="string">
  Postal code to customize pricing, inventory, or availability based on location
</ParamField>

## Response

<ResponseField name="base_sku" type="string">
  The base SKU identifier for the product
</ResponseField>

<ResponseField name="title" type="string">
  The product title
</ResponseField>

<ResponseField name="handle" type="string">
  The product handle/identifier
</ResponseField>

<ResponseField name="description" type="string">
  Product description
</ResponseField>

<ResponseField name="product_type" type="string">
  Category or type of product
</ResponseField>

<ResponseField name="images" type="array">
  Array of product images

  <Expandable title="Image Object">
    <ResponseField name="url" type="string" required>
      URL of the product image
    </ResponseField>

    <ResponseField name="alt" type="string">
      Alternative text for the image
    </ResponseField>

    <ResponseField name="type" type="string">
      Image type: `default`, `small`, `large`, `preview`
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="variant_option_values" type="array">
  Available options for product variants (e.g., colors, sizes)

  <Expandable title="Variant Option">
    <ResponseField name="display_name" type="string">
      Display name for the option type (e.g., "Colors", "Sizes")
    </ResponseField>

    <ResponseField name="property_accessor" type="string">
      Property key for accessing this option
    </ResponseField>

    <ResponseField name="position" type="number">
      Display order position
    </ResponseField>

    <ResponseField name="option_values" type="array">
      Available values for this option

      <Expandable title="Option Value">
        <ResponseField name="display_name" type="string">
          Display name (e.g., "Blue", "Medium")
        </ResponseField>

        <ResponseField name="value" type="string">
          Internal value identifier
        </ResponseField>

        <ResponseField name="available" type="boolean">
          Whether this option is currently available
        </ResponseField>

        <ResponseField name="swatch" type="object">
          Color swatch information

          <Expandable title="Swatch">
            <ResponseField name="url" type="string">
              URL of the swatch image
            </ResponseField>
          </Expandable>
        </ResponseField>

        <ResponseField name="images" type="array">
          Images specific to this option value
        </ResponseField>
      </Expandable>
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="variants" type="array">
  Product variants with specific option combinations

  <Expandable title="Variant">
    <ResponseField name="handle" type="string">
      Variant handle/identifier
    </ResponseField>

    <ResponseField name="sku" type="string">
      Variant SKU
    </ResponseField>

    <ResponseField name="title" type="string">
      Variant title (e.g., "Blue Medium")
    </ResponseField>

    <ResponseField name="display_name" type="string">
      Display name for the variant
    </ResponseField>

    <ResponseField name="add_to_cart_ref" type="object" required>
      Reference for adding this variant to cart

      <Expandable title="Cart Reference">
        <ResponseField name="variant_id" type="string" required>
          The ID to use when adding this variant to cart
        </ResponseField>
      </Expandable>
    </ResponseField>

    <ResponseField name="price" type="object">
      Current price

      <Expandable title="Price">
        <ResponseField name="currency" type="string">
          Currency code (e.g., "USD")
        </ResponseField>

        <ResponseField name="value" type="number">
          Decimal price value
        </ResponseField>

        <ResponseField name="number" type="number">
          Price in cents
        </ResponseField>

        <ResponseField name="symbol" type="string">
          Currency symbol
        </ResponseField>
      </Expandable>
    </ResponseField>

    <ResponseField name="msrp" type="object">
      Manufacturer's suggested retail price
    </ResponseField>

    <ResponseField name="available" type="boolean">
      Whether this variant is available for purchase
    </ResponseField>

    <ResponseField name="variant_option_list" type="array">
      List of option values for this variant (e.g., \["BLUE", "M"])
    </ResponseField>

    <ResponseField name="images" type="array">
      Images specific to this variant
    </ResponseField>

    <ResponseField name="messages" type="array">
      Variant-level messages (promotions, stock warnings, badges, etc.)

      <Expandable title="Message">
        <ResponseField name="type" type="string">
          Message type: `promotion`, `stock`, `badge`, `banner`, `shipping`, `urgency`, `info`
        </ResponseField>

        <ResponseField name="text" type="string" required>
          Display text for the message
        </ResponseField>
      </Expandable>
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="reviews" type="object">
  Product review summary

  <Expandable title="Reviews">
    <ResponseField name="total_reviews" type="number">
      Total number of reviews
    </ResponseField>

    <ResponseField name="average_rating" type="number">
      Average rating (typically 0-5)
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="properties" type="object">
  Additional product properties/metadata
</ResponseField>

## Expected Errors

<ResponseField name="ProductNotImplemented" type="404">
  The merchant's platform doesn't support individual product retrieval
</ResponseField>

<RequestExample>
  ```bash theme={null}
  curl --request GET \
    --url 'https://api.firmly.work/api/v1/domains-products/staging.luma.gift/radiant-tee?postal_code=10001' \
    --header 'x-firmly-authorization: YOUR_AUTH_TOKEN'
  ```
</RequestExample>

<ResponseExample>
  ```json theme={null}
  {
    "base_sku": "WS12",
    "title": "Radiant Tee",
    "handle": "radiant-tee",
    "description": "A comfortable and stylish tee perfect for any occasion",
    "product_type": "Tees",
    "images": [
      {
        "url": "https://cdn.staging.luma.gift/products/radiant-tee-main.jpg",
        "type": "default"
      }
    ],
    "variant_option_values": [
      {
        "display_name": "Size",
        "property_accessor": "size",
        "position": 0,
        "option_values": [
          {
            "display_name": "Small",
            "value": "S",
            "available": true
          },
          {
            "display_name": "Medium",
            "value": "M",
            "available": true
          },
          {
            "display_name": "Large",
            "value": "L",
            "available": false
          }
        ]
      },
      {
        "display_name": "Color",
        "property_accessor": "color",
        "position": 1,
        "option_values": [
          {
            "display_name": "White",
            "value": "WHITE",
            "available": true,
            "swatch": {
              "url": "https://cdn.staging.luma.gift/swatches/white.jpg"
            }
          },
          {
            "display_name": "Orange",
            "value": "Orange",
            "available": true,
            "swatch": {
              "url": "https://cdn.staging.luma.gift/swatches/blue.jpg"
            }
          }
        ]
      }
    ],
    "variants": [
      {
        "handle": "radiant-tee-xs-orange",
        "sku": "WS12-XS-Orange",
        "title": "Radiant Tee - XS Orange",
        "display_name": "XS / Orange",
        "add_to_cart_ref": {
          "variant_id": "WS12-XS-Orange"
        },
        "price": {
          "currency": "USD",
          "value": 22.00,
          "number": 2200,
          "symbol": "$"
        },
        "msrp": {
          "currency": "USD",
          "value": 22.00,
          "number": 2200,
          "symbol": "$"
        },
        "available": true,
        "variant_option_list": ["XS", "Orange"],
        "images": [
          {
            "url": "https://cdn.staging.luma.gift/products/radiant-tee-orange.jpg",
            "type": "default"
          }
        ],
        "messages": [
          {
            "type": "promotion",
            "text": "20% off - Limited Time Offer"
          },
          {
            "type": "stock",
            "text": "Only 3 left in stock"
          }
        ]
      },
      {
        "handle": "radiant-tee-xs-blue",
        "sku": "WS12-XS-Blue",
        "title": "Radiant Tee - XS Blue",
        "display_name": "XS / Blue",
        "add_to_cart_ref": {
          "variant_id": "WS12-XS-Blue"
        },
        "price": {
          "currency": "USD",
          "value": 22.00,
          "number": 2200,
          "symbol": "$"
        },
        "msrp": {
          "currency": "USD",
          "value": 22.00,
          "number": 2200,
          "symbol": "$"
        },
        "available": true,
        "variant_option_list": ["XS", "Blue"],
        "images": [
          {
            "url": "https://cdn.staging.luma.gift/products/radiant-tee-blue.jpg",
            "type": "default"
          }
        ]
      }
    ],
    "reviews": {
      "total_reviews": 127,
      "average_rating": 4.5
    }
  }
  ```
</ResponseExample>