Skip to main content
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

Get a Product

Retrieve detailed information about a specific product

Get All Products

Browse all products from a merchant’s catalog

Get Product from URL

Extract product information from a merchant’s product page URL

​
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

The catalog APIs work seamlessly with cart operations: 
{
  "variants": [{
    "sku": "SHIRT-M-BLUE",
    "add_to_cart_ref": {
      "variant_id": "SHIRT-M-BLUE"  // Use this ID with add-line-item API
    },
    "price": {
      "value": 29.99,
      "currency": "USD"
    }
  }]
}

​
Regional Customization

All catalog endpoints support a postal_code parameter to provide localized:
  • Product availability
  • Regional pricing
  • Shipping options
  • Store inventory

​
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. Use the add_to_cart_ref.variant_id with 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. Proceed with add to cart using the variant information

​
Authentication

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