Docs
Firmly Agentic Commerce
Docs
Set theme to dark (⇧+D)
  1. Docs
  2. For Merchants
  3. Catalog & Pricing

Catalog & Pricing

This page covers how your product catalog and pricing surface across Firmly-connected destinations. The headline: destinations see your products, your prices, and your rules — accurately.

​​ Two-layer model: catalog index + real-time validation

Firmly maintains a catalog index updated periodically from your platform, plus real-time validation at the merchant at key transactional moments. The two layers serve different purposes:

Layer What it does Refresh cadence
Catalog index Powers fast discovery and search across destinations Per-merchant; typically every few hours
Real-time validation Confirms price and stock at the merchant at order-placement time Every transaction, against your platform’s live API

This means destinations can search quickly (against the index) but orders never land on stale price or out-of-stock SKUs (because of real-time validation).

​​ What lives in the catalog index

Firmly’s catalog index stores the structured product data needed for discovery. The exact fields per platform vary, but typically include:

Field Source
Product ID Your platform’s stable identifier
Variant ID Per-variant SKU identifier
Title Your product title
Description Your product description (HTML or plain text per platform convention)
Images URLs to your product images (typically your CDN)
Price Current price including any active discounts
Currency Your store’s currency
Inventory level Stock indicator (in-stock / out-of-stock or quantity, per your platform)
Variant attributes Size, color, etc. per your platform’s convention
Category Your taxonomy classification
Custom attributes Platform-specific fields you flag in the scoping conversation with Firmly’s team during onboarding (not a self-serve wizard field)

​​ What Firmly does NOT ingest

Firmly indexes only what’s needed to discover and transact. It never ingests:

  • Your existing customer database
  • Your historical order data
  • Internal admin notes on products (private fields, vendor notes, admin-only metadata)
  • Pricing intelligence data (cost basis, margin, MSRP comparisons)

​​ Real-time price and stock validation

At critical transaction moments, Firmly re-validates against your platform’s live API:

Moment What’s re-validated
Product detail view Current price (in case the index is stale)
Add to cart Variant availability
Cart re-read Cart-wide price re-check
Place order Hard validation — price, stock, eligibility — against your live merchant API

If validation fails at place-order, the order doesn’t go through — the destination receives an error (e.g., NotEnoughStockError) and surfaces it to the user. Your platform never sees an order it can’t fulfill.

​​ Pricing nuances

​​ Sale price vs regular price

Firmly’s index stores the price you display — typically the sale price if a sale is active. The pre-sale “regular price” is exposed per your platform’s convention (the exact field name varies by platform) so destinations can show strikethrough pricing if they want.

​​ Regional / multi-currency pricing

If your store offers different prices per region or currency, Firmly’s index respects that. Destinations request a price for a specific market context, and Firmly returns the matching price.

​​ Member / loyalty pricing

If your platform supports member pricing (logged-in customer sees a lower price), Firmly-originated orders default to the public price. Exposing member pricing to a destination is a per-destination contractual decision, and it depends on a mechanism for carrying a member identity through to your platform at price-fetch time. (Note: Firmly Connect SSO is merchant-team portal login, not shopper identity — it does not carry a shopper’s membership through to your store. Discuss the member-identity mechanism with Firmly during onboarding.)

​​ Currency conversion

Firmly doesn’t convert currencies. If your store sells in USD, destinations transact in USD against your store. Multi-currency support comes from your platform’s native multi-currency features.

​​ Promo codes and promotions

Firmly’s Promotions API lets destinations apply promo codes during cart-building. The codes themselves come from your platform’s discount engine — Firmly is the relay, not the issuer.

The flow is simple: a destination calls add-promo-codes with a code (e.g. SAVE10); Firmly forwards it to your platform; your platform validates it against its own rules (stacking, expiry, minimum-cart, category exclusions, customer eligibility) and decides whether the discount applies; and the cart sub-total updates in the response.

If a code doesn’t apply, the destination’s agent reads cart.notices for codes like PROMO_EXPIRED, PROMO_NOT_APPLICABLE — surfaced from your platform’s discount engine.

​​ Promo-code stacking

Whether promo codes stack is your platform’s decision and your business rules. Firmly does not enforce or override stacking rules — it forwards each code application to your platform and lets the platform respond.

​​ Anti-abuse rate limits

Firmly’s edge applies aggressive rate limits to the /promo-codes endpoint to prevent code-stuffing — see Rate limits. Because destinations are rate-limited when trying codes, your discount engine won’t be hammered by code-guessing traffic.

​​ Excluded products

You can exclude specific products from Firmly’s catalog index — they won’t appear in discovery, can’t be added to carts, won’t be reachable from any destination. Common exclusions:

  • Gift cards (some merchants exclude; others include explicitly)
  • Restricted items (alcohol, tobacco, regulated goods in regions where rules vary)
  • Region-exclusive products
  • Bundle SKUs that don’t make sense outside your storefront
  • Test or internal-only products

Exclusions aren’t a self-serve wizard field — you set them up in the catalog-scoping conversation with Firmly’s team during onboarding (the same conversation that scopes the Selected Products subset), and they can be updated later per request.

​​ Inventory and stock signals

Firmly’s index reflects stock state per your platform’s convention:

  • Boolean (in stock / out of stock) — the simplest signal: no quantity is exposed, only whether the item is available
  • Quantity level — if your platform exposes count, Firmly stores it
  • Threshold-based — some merchants treat anything below N as out of stock for protection

If a destination requests an out-of-stock product, discovery still returns the product (so the user can see it exists) but the variant is flagged as unavailable. The destination’s agent surfaces this to the user.

​​ Image hosting

Product images are served from your CDN in nearly all cases. Firmly’s catalog stores the image URLs, and destinations link directly to your images. This means:

  • Your CDN handles the bandwidth and caching
  • Image latency depends on your CDN’s performance, not Firmly’s
  • You can swap images in your platform; destinations pick up the new URLs on the next catalog sync

Firmly never caches or mirrors your images — it stores only the image URL. If you have specific image-hosting needs (e.g., signed URLs, geo-restricted CDN), discuss during onboarding.

​​ Multi-variant products

Products with variants (sizes, colors, options) flow through the catalog as you’ve structured them on your platform. Each variant has its own ID, price, and inventory. Destinations browse the product, see variants, and add a specific variant to the cart.

For variant-heavy verticals (apparel, beauty, supplements) see Use Cases → Vertical Specialist.