Docs
Firmly Agentic Commerce
Docs
Set theme to dark (⇧+D)
  1. Docs
  2. Resources
  3. Glossary

Glossary

If you’re seeing a term in the docs and want a quick definition, this page collects them in one place. Each entry has a short definition and a link to the page where it’s used in depth.

​​ Core platform terms

​​ Adapter

Firmly’s pre-built connector for a merchant’s store — either a shared platform adapter (config-only, for industry-standard commerce platforms) or a purpose-built one for custom or in-house stacks. It translates Firmly’s unified cart, checkout, payment, and order APIs into the merchant’s native calls, and the responses back. Each adapter implements only the operations its platform supports, so some endpoints may return OperationNotSupported or NotImplemented for a given merchant.

Used in: Errors & Conventions · Supported platforms

​​ App ID (_appId)

A UUID identifying a destination’s application. The App ID determines which merchants the destination can call, which environment (sandbox vs production) the calls run against, and which authentication scope applies. Contact Firmly to provision one.

Used in: Authentication · Sandbox setup

​​ Device ID

The identifier Firmly issues for a buyer’s session, returned in the browser-session response and carried in the session JWT. It may or may not be reused across carts, depending on the destination’s integration — use it to follow a single buyer’s session and interactions.

​​ Ray ID

Cloudflare’s per-request identifier, returned in the CF-RAY response header on every call to Firmly. Include it when reporting an issue — it lets Firmly trace the exact request.

Used in: Errors & Conventions

​​ Buyer

The party shopping and purchasing through a destination’s surface — the default term for the person or party buying via Firmly. The buyer buys from the merchant; the destination hosts the experience; Firmly runs the commerce underneath.

​​ Destination

The surface where a buyer encounters Firmly-powered commerce — an AI chat product, a wallet, a banking app, a publisher, a brand-loyalty app. Destinations integrate with Firmly’s APIs to reach merchants.

Used in: Destinations overview

​​ Merchant

The seller of record. Orders placed via Firmly land in the merchant’s native order management system. The merchant owns everything that happens after the order is placed.

Used in: For Merchants · Supported platforms

​​ Merchant domain (domain)

The string identifying a merchant in API calls — e.g., staging.luma.gift. Most Firmly endpoints take domain as a path parameter or query argument so each call is scoped to a specific merchant.

Used in: API Reference overview

​​ Solution

Firmly’s product packaging — one of six: Agentic Commerce, Ad Commerce, Branded Commerce, Firmly Connect, Marketplace, Publisher Commerce. Solutions share the underlying platform; they differ in destination shape and contractual posture.

Used in: Solutions overview

​​ Use case

A common pattern destinations build on top of Firmly — e.g. shopping copilot, deal & coupon hunting, smart payment, smart gifting, scheduled buying. Use cases compose Firmly’s underlying APIs (discovery, cart, checkout, payment) into a recognizable buyer behavior. The list is not exhaustive; destinations combine these patterns as their product shape requires.

Used in: Use Cases overview

​​ Authentication terms

​​ JWT

JSON Web Token — the signed, self-contained token format Firmly issues for browser sessions. The access_token returned by POST /api/v1/browser-session is a JWT; pass it on subsequent calls in the x-firmly-authorization header.

Used in: Browser session reference

​​ Browser session

A per-buyer session bootstrapped via POST /api/v1/browser-session. Returns a JWT access_token valid for 1 hour active (renewable while session state persists, ~7 days from last activity). Used when the destination acts on behalf of a specific buyer.

Used in: Browser session reference

​​ Server-to-server (S2S)

Backend authentication using a Firmly-issued secret instead of a per-buyer JWT. Used when the destination is a backend service with its own service identity — banks, wallets, scheduled-buying agents.

Used in: Server-to-server reference

​​ device_id

A stable identifier for the buyer’s device or session, used in S2S contexts so Firmly can scope cart and order state to the right buyer. The destination generates and tracks this.

Used in: Server-to-server reference

​​ x-firmly-authorization

The header carrying either the browser-session JWT or the S2S secret. Required on most authenticated endpoints.

​​ Cart and checkout terms

​​ cart_status

The high-level state of a cart: active (in progress), submitted (order placed), item_not_shippable (blocking issue), or checkout_blocked (validation error). See the lifecycle for state transitions.

Used in: Cart Lifecycle

​​ line_item_id

A stable identifier for an item in a cart. Returned by add-line-item; used to update or remove that specific item later. Distinct from the product’s variant ID.

Used in: Cart Management

​​ shipment_id

When a cart contains items that ship separately (different warehouses, different fulfillment timelines), Firmly groups them into shipments. Each shipment has its own shipment_id for availability and method selection.

Used in: Shipping & Fulfillment

​​ add_to_cart_ref

A structured reference object that identifies what to add to the cart. Its fields come from discovery + catalog responses: variant_id (required — a single clean variant identifier), plus optional product_id and variant_handles. Pass the object to add-line-item or place-order’s items array. It’s distinct from a raw variant ID because it carries the additional attributes some merchants need to resolve an add-to-cart. See Request schemas for the full field list.

Used in: Add line item

​​ custom_properties

Free-form merchant- and platform-specific properties attached to a cart or order. Contents vary by adapter — treat it as an opaque bag and don’t rely on any particular key. The merchant’s order number is not here; it’s the top-level platform_order_number.

Used in: Cart Lifecycle · Place order

​​ Fulfillment

How an order’s items reach the buyer — shipped to an address, picked up in store, or delivered on a schedule. The fulfillment type is set per cart or shipment before a shipping method is chosen.

Used in: Shipping & Fulfillment

​​ Shipping method

A specific delivery option for a shipment (e.g. standard or expedited) with its own price. Available methods appear in cart.shipments[].shipping_method_options after shipping info is set, and the destination records the chosen one. Methods are address-specific — changing the address clears the selection.

Used in: Shipping & Fulfillment

​​ Promo code

A merchant discount code applied to a cart through the Promotions API. A 200 response does not guarantee the code was accepted — re-read the cart afterward and compare the field the promo actually moves.

Used in: Promotions

​​ Express checkout

Payment paths that skip manual card entry using a wallet or buy-now-pay-later provider — Google Pay, PayPal Express, Click to Pay, and Klarna. Each has its own endpoint under the payment surface.

Used in: Express checkout

A merchant-required agreement (terms of sale, warranty, delivery acknowledgment) the buyer must accept before an order is placed. Fetch required consents with Get Consents and record acceptance with Set Consents; unsigned required-explicit consents are rejected at order completion.

Used in: Get Consents · Set Consents

​​ Payment terms

​​ Encrypted card

Card data after JWE encryption with Firmly’s public key. The encrypted blob travels through the destination’s servers but the cleartext PAN never does. Passed as encrypted_card in place-order.

Used in: Get Payment Public Key

​​ JWE

JSON Web Encryption — the format used for encrypting card data. Firmly uses RSA-OAEP-256 for key wrapping and A256GCM for content encryption. Implementations exist in every major language.

Used in: Get Payment Public Key

​​ JWK

JSON Web Key — the RSA public-key format returned by GET /payment/key. It carries kty, n, e, use, and a kid; use it to JWE-encrypt the card before placing an order.

Used in: Get Payment Public Key

​​ kid (key ID)

An identifier for which Firmly public key was used to encrypt a card. Returned in the public-key response. Firmly rotates keys; always re-fetch before placing an order rather than caching long-term.

Used in: Get Payment Public Key

​​ Idempotency key

A UUID generated by the destination, passed in the Idempotency-Key header on mutation calls. On the UCP protocol bridge, retrying with the same key returns the same result instead of duplicating the effect; the core REST endpoints accept the header but do not deduplicate on it today, so guard REST retries by re-reading state first. Use the same key on retries of the same logical attempt; new key only for a genuinely new attempt.

Used in: Errors & Conventions → Idempotency

​​ Vault token

A long-lived reference to a saved card stored in Firmly’s vault service. Used for repeat purchases without re-asking the buyer for card data.

Used in: Smart payment selection

​​ Agentic Pay

Firmly’s payment path for agent-driven checkout, where Firmly acts as a network-token router: it enrolls the cardholder’s card once, then routes tokenization and authorization to the right card network. Supports both a human-in-the-loop model (the cardholder approves each payment) and an autonomous, cardholder-not-present model (the agent transacts within a cardholder-authorized mandate).

Used in: Agentic Pay

​​ PAN

Primary Account Number — the full card number. With Firmly’s JWE flow the cleartext PAN is encrypted client-side and never travels through the destination’s servers in the clear.

Used in: Security Model

​​ Network token

A card-network-issued token that stands in for the underlying card during a transaction. Agentic Pay retrieves network token credentials (token, expiry, cryptogram) at order completion; the token’s last four can differ from the funding card’s last four.

Used in: Agentic Pay

​​ Cardholder-not-present

A payment made when the cardholder is not actively present to approve it — for example, an autonomous agent transacting within a pre-authorized mandate. Agentic Pay supports this alongside cardholder-present (human-in-the-loop) checkout.

Used in: Agentic Pay

​​ Protocol terms

​​ UCP

Universal Commerce Protocol — Google’s open standard for AI search surfaces to talk to commerce providers. Firmly’s UCP bridge translates UCP calls into Firmly’s underlying cart and checkout APIs.

Used in: Protocols

​​ MCP

Model Context Protocol — Anthropic’s open standard for AI agents to invoke tools. Firmly’s MCP server exposes commerce tools (search, cart, shipping, payment) the LLM can call iteratively.

Used in: Protocols

​​ ACP

Agentic Commerce Protocol — OpenAI’s spec for agentic commerce in ChatGPT and Operator surfaces.

Used in: Protocols

​​ MCP-Apps

An extension of MCP that allows hosts (like ChatGPT or Claude) to render a widget UI alongside the conversation. Firmly’s MCP server can act as an MCP-Apps host’s commerce backend.

Used in: Protocols

​​ Surface and UI terms

​​ Dropin

Firmly’s pre-built checkout widget — a Svelte-based UI hosted at a Firmly URL. Can be loaded as a top-level page (hosted checkout), embedded in an iframe (embedded checkout), or wrapped via the SDK. Renders cart, shipping, payment, and order confirmation.

Used in: Hosted checkout · Embedded checkout

​​ Hosted checkout

The pattern where Firmly hosts the entire checkout UI on a Firmly-owned page. The destination redirects the buyer to the dropin URL; after order placement the buyer lands on the merchant’s confirmation page.

Used in: Hosted checkout

​​ Embedded checkout

The pattern where the dropin is rendered inside the destination’s surface as an iframe. The two communicate via window.postMessage.

Used in: Embedded checkout

​​ Headless / Deep link

The pattern where the destination calls Firmly’s REST API directly without any Firmly-rendered UI. The destination is the checkout UI, or the checkout has no UI at all.

Used in: Deep link / Headless

​​ Other

​​ place-order

The atomic operation that submits a cart to the merchant as a real order. After success, cart_status becomes submitted and the merchant’s order number appears in platform_order_number.

Used in: Place order (v2)

​​ thank_you_page

The merchant-side confirmation URL returned in the place-order response. This is where the buyer lands after a hosted-checkout flow. Distinct from any destination-side confirmation page.

Used in: Hosted checkout

​​ Affiliate attribution

The mechanism by which Firmly relays the originating destination to the merchant, so affiliate commissions and origination credit flow back to the destination — without manual reconciliation.

Used in: How Firmly Works

​​ Attribution

The general practice of tagging each order with the originating destination’s identifier so origination credit flows back to the right destination. See Affiliate attribution for the commission-relay case.

Used in: How Firmly Works

​​ TTL

Time to live — how long a piece of state persists before it expires. Firmly’s edge cart state has a 7-day TTL; browser-session tokens carry their own, shorter lifetime.

Used in: Cart Lifecycle

​​ VCC (Virtual Card)

A network-tokenized, purpose-scoped card credential provisioned for an autonomous purchase (used by Agentic Pay) so a merchant or PSP never receives a real cardholder PAN.

​​ V1 adapters

Older (version 1) merchant-platform adapters. Some operations available on v2 adapters are not exposed by v1 adapters; pages note where behavior differs by adapter version.

​​ PCI scope

The set of systems subject to PCI DSS controls because they handle cardholder data. Firmly’s client-side JWE encryption keeps the destination’s servers out of scope for the card number — no cleartext PAN passes through them.