> ## 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.

# Catalog API Overview

> Browse and retrieve product information from merchant stores

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

<CardGroup cols={2}>
  <Card title="Get a Product" icon="box" href="/api-reference/catalog/get-product">
    Retrieve detailed information about a specific product
  </Card>

  <Card title="Get All Products" icon="list" href="/api-reference/catalog/get-all-products">
    Browse all products from a merchant's catalog
  </Card>

  <Card title="Get Product from URL" icon="link" href="/api-reference/catalog/get-product-from-url">
    Extract product information from a merchant's product page URL
  </Card>
</CardGroup>

<Note>
  Looking for product search? See the [Discovery API](/api-reference/discovery/overview) for searching across multiple merchants.
</Note>

## 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:

```json theme={null}
{
  "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](/api-reference/catalog/get-all-products) to display a product grid
2. When user selects a product, use [Get a Product](/api-reference/catalog/get-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-reference/cart-management/add-line-item) API

### URL-Based Product Discovery

1. User shares or navigates to a merchant product page
2. Use [Get Product from URL](/api-reference/catalog/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](/api-reference/authentication/browser-session) for details.