Docs
Firmly Agentic Commerce
Docs
Set theme to dark (⇧+D)
  1. Docs
  2. API Reference
  3. Standard flow
  4. Standard cart

Standard cart

Cart operations for the Standard flow (/api/v1). The cart is created implicitly on the first add — a GET before anything is added returns 404 CartNotFound. Every response is the full cart, so you rarely need a separate GET.

All calls are on https://api.firmly.work and require the x-firmly-authorization header (the token from Browser Session). {domain} is the merchant domain, e.g. staging.luma.gift.

​​ Get cart

GET /api/v1/domains/{domain}/cart

Returns the current cart. Returns 404 CartNotFound before the first item is added.


curl --request GET \
  --url https://api.firmly.work/api/v1/domains/staging.luma.gift/cart \
  --header 'x-firmly-authorization: YOUR_TOKEN'

Response — the cart, with line items and totals resolved from the merchant catalog. Every money field is an object with currency, value (decimal), number (smallest unit), and symbol.


{
  "cart_id": "255fc5bd-b2d5-40c1-9040-eba8e1284a92",
  "cart_status": "active",
  "line_items": [
    {
      "line_item_id": "380c6749-dc4f-7c63-f049-847e3862f396",
      "sku": "MH09-S-Blue",
      "description": "Abominable Hoodie",
      "quantity": 1,
      "price": {
        "currency": "USD",
        "value": 69,
        "number": 6900,
        "symbol": "$"
      },
      "line_price": {
        "currency": "USD",
        "value": 69,
        "number": 6900,
        "symbol": "$"
      },
      "msrp": {
        "currency": "USD",
        "value": 82.8,
        "number": 8280,
        "symbol": "$"
      },
      "image": {
        "url": "https://staging.luma.gift/abominable-hoodie.jpg",
        "alt": "Abominable Hoodie",
        "type": "default"
      }
    }
  ],
  "sub_total": {
    "currency": "USD",
    "value": 69,
    "number": 6900,
    "symbol": "$"
  },
  "shipping_total": {
    "currency": "USD",
    "value": 0,
    "number": 0,
    "symbol": "$"
  },
  "fees": [
    {
      "description": "Recycle fee",
      "currency": "USD",
      "value": 2,
      "number": 200,
      "symbol": "$"
    }
  ],
  "fee_total": {
    "currency": "USD",
    "value": 2,
    "number": 200,
    "symbol": "$"
  },
  "total": {
    "currency": "USD",
    "value": 71,
    "number": 7100,
    "symbol": "$"
  },
  "payment_method_options": [
    {
      "type": "CreditCard",
      "wallet": "user"
    },
    {
      "type": "PayPal",
      "wallet": "paypal"
    }
  ]

}

​​ Add a line item

POST /api/v1/domains/{domain}/cart/line-items

Adds a product, creating the cart if one doesn’t exist. Pass the add_to_cart_ref straight from a catalog product variant.

  • add_to_cart_ref (object, required) — { "variant_id": "..." } from the catalog.
  • quantity (integer, required) — minimum 1.

curl --request POST \
  --url https://api.firmly.work/api/v1/domains/staging.luma.gift/cart/line-items \
  --header 'Content-Type: application/json' \
  --header 'x-firmly-authorization: YOUR_TOKEN' \
  --data '{ "add_to_cart_ref": { "variant_id": "24-MB05" }, "quantity": 1 }'

​​ Update quantity

PUT /api/v1/domains/{domain}/cart/line-items/{productId}

Sets a line item’s quantity. Quantity 0 removes the item.

  • quantity (integer, required) — 0 or greater.

curl --request PUT \
  --url https://api.firmly.work/api/v1/domains/staging.luma.gift/cart/line-items/24-MB05 \
  --header 'Content-Type: application/json' \
  --header 'x-firmly-authorization: YOUR_TOKEN' \
  --data '{ "quantity": 2 }'

​​ Clear the cart

DELETE /api/v1/domains/{domain}/cart/line-items

Removes all items.


curl --request DELETE \
  --url https://api.firmly.work/api/v1/domains/staging.luma.gift/cart/line-items \
  --header 'x-firmly-authorization: YOUR_TOKEN'

​​ Apply promo codes

POST /api/v1/domains/{domain}/cart/promo-codes

Applies one or more promo codes (1–10). DELETE on the same path clears them.

  • promo_codes (array of strings, required) — 1 to 10 codes.

curl --request POST \
  --url https://api.firmly.work/api/v1/domains/staging.luma.gift/cart/promo-codes \
  --header 'Content-Type: application/json' \
  --header 'x-firmly-authorization: YOUR_TOKEN' \
  --data '{ "promo_codes": ["WELCOME10"] }'

​​ Set attribution

PUT /api/v1/domains/{domain}/cart/attribution

Attach affiliate / UTM attribution so the order is credited to your destination.

  • attribution (object, required) — with optional utm (string, e.g. utm_source=partner&utm_medium=cpc), referrer_url, referral_code, landing_page.

curl --request PUT \
  --url https://api.firmly.work/api/v1/domains/staging.luma.gift/cart/attribution \
  --header 'Content-Type: application/json' \
  --header 'x-firmly-authorization: YOUR_TOKEN' \
  --data '{ "attribution": { "utm": "utm_source=partner&utm_campaign=spring", "referral_code": "PARTNER123" } }'

​​ Errors

Errors return { code, error, description }; program against error. Common cases: CartNotFound (404, get before first add), ProductNotFound (404, stale variant_id), NotEnoughStockError (409), PostalCodeRequired (412). See Errors & Conventions for the full catalog.

​​ Next

Standard checkout Add the shipping and billing addresses Try it live Run these calls against the sandbox