Skip to main content
The Firmly Discovery APIs help users find products across multiple merchant catalogs. These APIs power product search and filtering capabilities.

​
Available Endpoints

Search Products

Search for products using keywords with filters for domains, price, availability, and variant attributes

Get Search Options

Retrieve available filter options for building search filter UIs

​
Key Concepts

​
Discovery vs Catalog APIs

Discovery APIsCatalog APIs
Search across multiple merchantsQuery a specific merchant
Keyword search with filtersDirect product retrieval
Filters and facetsExact lookups by handle/URL
Aggregated product dataReal-time merchant data
Use Discovery APIs when:
  • Users are browsing or searching for products
  • You need to show products from multiple merchants
  • You want to filter by price, availability, or variants
Use Catalog APIs when:
  • You know the exact product and merchant
  • You need real-time availability/pricing
  • You’re building a product detail page for a specific merchant

​
Typical Search Flow

1. Fetch variant options (GET /options)
        ↓
2. User enters search query and selects filters
        ↓
3. Search products (POST /search)
        ↓
4. Display results with previews
        ↓
5. User selects a product
        ↓
6. Catalog API fetches full product details
        ↓
7. Cart API adds item to cart

​
Authentication

All Discovery endpoints require authentication via the x-firmly-authorization header. See Browser Session Authentication for details.

​
Domain Authorization

Search results are limited to merchant domains associated with your account. Contact your account manager to request access to additional merchants.

​
Rate Limits

Discovery APIs are subject to standard rate limits. Contact support for higher limits if needed for production workloads.