Get a Product - Firmly API

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

merchant-domain

string

required

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

product-handle

string

required

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

Query Parameters

postal_code

string

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

Response

base_sku

string

The base SKU identifier for the product

title

string

The product title

handle

string

The product handle/identifier

description

string

Product description

product_type

string

Category or type of product

images

array

Array of product images

Show Image Object

url

string

required

URL of the product image

alt

string

Alternative text for the image

type

string

Image type: default, small, large, preview

variant_option_values

array

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

Show Variant Option

display_name

string

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

property_accessor

string

Property key for accessing this option

position

number

Display order position

option_values

array

Available values for this option

Show Option Value

display_name

string

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

value

string

Internal value identifier

available

boolean

Whether this option is currently available

swatch

object

Color swatch information

Show Swatch

url

string

URL of the swatch image

images

array

Images specific to this option value

variants

array

Product variants with specific option combinations

Show Variant

handle

string

Variant handle/identifier

sku

string

Variant SKU

title

string

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

display_name

string

Display name for the variant

add_to_cart_ref

object

required

Reference for adding this variant to cart

Show Cart Reference

variant_id

string

required

The ID to use when adding this variant to cart

price

object

Current price

Show Price

currency

string

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

value

number

Decimal price value

number

Price in cents

symbol

string

Currency symbol

msrp

object

Manufacturer’s suggested retail price

available

boolean

Whether this variant is available for purchase

variant_option_list

array

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

images

array

Images specific to this variant

messages

array

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

Show Message

type

string

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

text

string

required

Display text for the message

reviews

object

Product review summary

Show Reviews

total_reviews

number

Total number of reviews

average_rating

number

Average rating (typically 0-5)

properties

object

Additional product properties/metadata

Expected Errors

ProductNotImplemented

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

Get All ProductsReturns all products from a merchant's catalog

⌘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
  }
}

​Path Parameters

​Query Parameters

​Response

​Expected Errors

Path Parameters

Query Parameters

Response

Expected Errors