Get a Product

GET

api

domains-products

{merchant-domain}

{product-handle}

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'

{
  "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
  }
}

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

string

required

The domain of the merchant website (e.g., staging.luma.gift)

string

required

The product handle or identifier. This is typically the URL-friendly version of the product name.

Query Parameters

string

Postal code to customize pricing, inventory, or availability based on location

Response

string

The base SKU identifier for the product

string

The product title

string

The product handle/identifier

string

Product description

string

Category or type of product

array

Array of product images

Show Image Object

string

required

URL of the product image

string

Alternative text for the image

string

Image type: default, small, large, preview

array

Available options for product variants (e.g., colors, sizes)

Show Variant Option

string

Display name for the option type (e.g., “Colors”, “Sizes”)

string

Property key for accessing this option

number

Display order position

array

Available values for this option

Show Option Value

string

Display name (e.g., “Blue”, “Medium”)

string

Internal value identifier

boolean

Whether this option is currently available

object

Color swatch information

Show Swatch

string

URL of the swatch image

array

Images specific to this option value

array

Product variants with specific option combinations

Show Variant

string

Variant handle/identifier

string

Variant SKU

string

Variant title (e.g., “Blue Medium”)

string

Display name for the variant

object

required

Reference for adding this variant to cart

Show Cart Reference

string

required

The ID to use when adding this variant to cart

object

Current price

Show Price

string

Currency code (e.g., “USD”)

number

Decimal price value

number

Price in cents

string

Currency symbol

object

Manufacturer’s suggested retail price

boolean

Whether this variant is available for purchase

array

List of option values for this variant (e.g., [“BLUE”, “M”])

array

Images specific to this variant

array

Variant-level messages (promotions, stock warnings, badges, etc.)

Show Message

string

Message type: promotion, stock, badge, banner, shipping, urgency, info

string

required

Display text for the message

object

Product review summary

Show Reviews

number

Total number of reviews

number

Average rating (typically 0-5)

object

Additional product properties/metadata

Expected Errors

404

The merchant’s platform doesn’t support individual product retrieval

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'

{
  "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
  }
}

⌘I

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'

{
  "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
  }
}

Home

Core Concepts

Implementation Guides

Ask Agent SDK

API Reference

firmly Connect

Resources

Path Parameters

Query Parameters

Response

Expected Errors

​Path Parameters

​Query Parameters

​Response

​Expected Errors

Path Parameters

Query Parameters

Response

Expected Errors