Catalog

The Firmly Catalog APIs allow you to browse merchant product catalogs and retrieve detailed product information. These APIs are essential for building product discovery experiences before adding items to the cart.

​​ Available Endpoints

​​ Key Concepts

​​ Product Structure

Products in Firmly have a rich structure that includes:

• Base product information: SKU, title, description, images
• Variants: Different options like size, color with individual pricing
• Availability: Stock status and regional availability
• Pricing: Current price, MSRP, and currency information
• Cart references: The add_to_cart_ref field connects products to cart operations

​​ Integration with Cart APIs

Each variant carries an add_to_cart_ref object. Pass that entire object as add_to_cart_ref in the Add Line Item request body — do not reconstruct it or send only variant_id, since it may also carry product_id, variant_handles, or properties the merchant needs.

{
  "variants": [{
    "sku": "SHIRT-M-BLUE",
    "add_to_cart_ref": {
      "variant_id": "SHIRT-M-BLUE"
    },
    "price": {
      "value": 29.99,
      "currency": "USD"
    }
  }]
}

The corresponding Add Line Item request passes that add_to_cart_ref through unchanged:

{
  "add_to_cart_ref": {
    "variant_id": "SHIRT-M-BLUE"
  },
  "quantity": 1
}

​​ Regional Customization

The single-product endpoints — Get a Product and Get Product from URL — accept a postal_code query parameter for localized pricing, inventory, and availability. Get All Products instead takes a countryCode parameter (default us).

​​ Common Use Cases

​​ Product Browsing Flow

1. Use Get All Products to display a product grid
2. When user selects a product, use Get a Product for details
3. Display variant options and let user select size/color
4. Pass the selected variant’s full add_to_cart_ref object to the Add Line Item API

​​ URL-Based Product Discovery

1. User shares or navigates to a merchant product page
2. Use Get Product from URL to extract product data
3. Display product information in your interface
4. Add to cart by passing the chosen variant’s full add_to_cart_ref object to Add Line Item

​​ Authentication

All catalog endpoints require authentication using the x-firmly-authorization header. See Authentication for details.