Docs
Firmly Agentic Commerce
Docs
Set theme to dark (⇧+D)
  1. Docs
  2. Troubleshooting
  3. Technical FAQ

Technical FAQ

For evaluation-stage questions, see the General FAQ. For solution-specific questions, see the Agentic Commerce or Branded Commerce FAQ.

​​ Environments and credentials

​​ What’s the difference between sandbox and production?

Different hosts, different App IDs, different merchant domains. The sandbox host is api.firmly.work; the production host differs and is published at go-live. Sandbox App IDs reach test merchant stores (typically staging. prefix domains) and production App IDs reach live merchants, because each environment carries its own set of configured merchants. Read the host from configuration rather than hard-coding it, so the move to production is a config change.

​​ How do I get a sandbox App ID?

Contact Firmly. They provision the App ID and the test merchant pairing.

​​ Can I move from sandbox to production without code changes?

Yes — for the API integration. Going live is a configuration change (swap the App ID, swap the merchant domain). What does change: real cards instead of test cards, real merchant catalogs, real fulfillment.

​​ Which base URLs do I use?

Purpose Base URL
Main API (cart, checkout, discovery, etc.) https://api.firmly.work
Commerce / checkout API (place-order family) https://cc.firmly.work
Test merchant for sandbox staging.luma.gift

See Authentication for the auth headers each requires.

​​ Authentication

​​ When should I use browser session vs server-to-server?

Use browser session when… Use server-to-server when…
The destination acts on behalf of a specific user session The destination is a backend service with its own identity
You need cart and order tied to a user’s device You’re orchestrating from a backend (scheduled buying, B2B)
The session is short-lived (per chat or shopping session) You need long-lived service identity

See Authentication.

​​ How long does a session JWT live?

Active for 1 hour; renewable while the session state is still retained (~7 days from last activity — not a fixed server-enforced window). After that, bootstrap a fresh session via Browser Session or Server-to-Server.

​​ Can I share a session JWT across users?

No. Each session JWT is tied to a single device_id. Reusing a JWT for a different user mixes their cart state.

​​ Protocols

​​ Do I have to use UCP, MCP, or ACP?

No. Direct REST is always available and is the universal path. The protocols are translation layers for specific agent platforms. See Protocols.

​​ Which protocol should my AI chat product use?

If your platform supports MCP-Apps, use MCP. Otherwise direct REST. See AI surfaces.

​​ Can I mix protocols in a single flow?

No. A given session uses one protocol. The choice is per-integration, not per-call.

​​ Idempotency and retries

​​ What’s the idempotency window?

24 hours per Idempotency-Key. Same key + same request payload within the window returns the cached response. Same key + different payload returns an idempotency conflict error.

See Idempotency.

​​ Which endpoints accept Idempotency-Key?

The UCP protocol bridge deduplicates on it for create/complete/cancel operations. The core REST endpoints accept the header but do not act on it today — send it for forward compatibility, not for retry-safety.

​​ How do I retry safely after a network blip?

On the UCP bridge, reuse the same Idempotency-Key — Firmly returns the original response if the operation completed. On the core REST endpoints, re-read state before retrying: after a failed place-order, fetch the cart and check cart_status — if it’s submitted, the order went through and you must not retry.

​​ Rate limits

​​ What are the rate limits?

Limits vary by endpoint and authentication mode. The endpoints most likely to hit limits are the OTP / verification endpoints. Specific thresholds are shared during commercial onboarding.

See Rate Limits for the current limits.

​​ How do I detect a rate-limit hit?

HTTP 429 Too Many Requests. The response includes a Retry-After header indicating how long to wait before retrying.

​​ Are rate limits per-device or per-account?

Per-device for browser-session calls. Per-account for server-to-server. The exact scope is endpoint-specific — see Rate Limits.

​​ Versioning

​​ How are API versions handled?

V1 and V2 endpoints coexist. New integrations should use V2 for cart, place-order, and complete-order. V1 is maintained for existing integrations. See API Reference.

​​ Will V1 stay around?

V1 endpoints stay supported as long as merchants and destinations rely on them. There is no scheduled deprecation today. The Changelog tracks any version changes.