API Reference

​​ Base URLs

These are the sandbox hosts. Production runs on different hosts from the sandbox. Firmly provides your production base URLs at go-live — plan for a configuration change, not just a new App ID. Going live changes your App ID, your merchants, and your base URLs.

​​ Request Format

• Content-Type: application/json for all POST/PUT requests
• Accept: application/json
• Domain Parameter: Most endpoints require a merchant domain (e.g., staging.luma.gift)

​​ Response Format

All responses return JSON with consistent structure:

​​ Success Response

{
  "cart_id": "1d6af01a-08ec-59f7-8dc6-abd6f6eeed25",
  "line_items": [
    {
      "line_item_id": "4958451e-0ad5-a545-c865-7b12623e917f",
      "sku": "MH07-XS-Gray",
      "quantity": 1,
      "price": {
        "currency": "USD",
        "value": 22.0,
        "number": 2200,
        "symbol": "$"
      },
      "line_price": {
        "currency": "USD",
        "value": 22.0,
        "number": 2200,
        "symbol": "$"
      },
      "msrp": {
        "currency": "USD",
        "value": 26.4,
        "number": 2640,
        "symbol": "$"
      },
      "image": {
        "url": "https://staging.luma.gift/mh07-xs-gray.jpg",
        "alt": "MH07-XS-Gray",
        "type": "default"
      }
    }
  ],
  "total": {
    "currency": "USD",
    "value": 99.99,
    "number": 9999,
    "symbol": "$"
  }
}

Every currency-valued field (price, line_price, sub_total, shipping_total, tax_total, total, msrp, addon prices, etc.) is returned as an object with currency (ISO 4217 code), value (decimal), number (smallest currency unit — cents for USD), and symbol.

​​ Error Response

{
  "code": 400,
  "error": "ErrorCode",
  "description": "Human-readable error message"
}

​​ HTTP Status Codes

See Errors & Conventions for the full error catalog and retry patterns.

​​ Available APIs

• Authentication — Token generation and session management

• Discovery — Search products across connected merchants

• Affiliate — Preserve affiliate attribution through the shopping session

• Catalog — Browse products and retrieve variant information

• Session — Manage device sessions and preferences

• Cart Management — Core cart operations

• Promotions — Apply and manage promotional codes

• Shipment Configuration — Configure fulfillment and shipping methods

• Addon Management — Manage warranties and protection plans

• Checkout — Complete the purchase flow

• Payment — Secure payment processing, express checkout, and wallets

• Agentic Pay — Network Token Router for autonomous agent purchases

• Headless SDK — Client SDK for headless checkout builds

​​ Common Headers

​​ Required Headers

​​ Optional Headers

​​ Rate Limits

See Rate Limits for how limits are communicated, the 429 retry pattern, and how to design for them. Specific thresholds are shared during commercial onboarding.

​​ Support

• Support: firmlydocs@firmly.ai

​​ Need Implementation Help?

• Implementation Guides — Step-by-step guides for building with Firmly APIs