Get Cart

GET https://api.firmly.work/api/v2/domains/{domain}/cart

​​ Overview

The Get Cart endpoint retrieves the complete current state of a shopping cart, including:

• All line items with product details and quantities
• Multiple shipments with items grouped by fulfillment requirements
• Complete pricing breakdown (subtotal, shipping, tax, addons, total)
• Available addon offers and current selections
• Cart-level metadata and schema version

​​ Authentication

• x-firmly-authorization (string, required) — Device access token from Browser Session

​​ Path Parameters

• domain (string, required) — Domain of the merchant website (e.g., staging.luma.gift)

​​ Response

• cart_id (string) — Unique identifier for the shopping cart session

• platform_id (string) — Identifier of the merchant’s underlying commerce platform. The literal value varies by merchant and reflects the platform Firmly is integrated with.

• shop_id (string) — Shop identifier (merchant domain, e.g., “staging.luma.gift”)

• display_name (string) — Merchant display name

• cart_status (string) — Current cart status (e.g., “active”)

• line_items (array) — Array of products currently in the cart

  Line Item Properties

  • line_item_id (string) — Unique identifier for the line item
  • platform_line_item_id (string) — Platform-specific line item identifier
  • sku (string) — Product SKU identifier
  • variant_description (string) — Variant-specific description
  • description (string) — Product description
  • base_sku (string) — Base product SKU (parent of variants)
  • quantity (number) — Quantity of the item in cart
  • price (object) — Unit price information
  • currency (string) — Currency code (e.g., USD)
  • value (number) — Price as decimal
  • number (number) — Price in smallest currency unit
  • symbol (string) — Currency symbol
  • line_price (object) — Total price for this line (price × quantity)
  • currency (string) — Currency code (e.g., USD)
  • value (number) — Price as decimal
  • number (number) — Price in smallest currency unit
  • symbol (string) — Currency symbol
  • msrp (object) — Manufacturer’s suggested retail price
  • currency (string) — Currency code (e.g., USD)
  • value (number) — Price as decimal
  • number (number) — Price in smallest currency unit
  • symbol (string) — Currency symbol
  • image (object) — Product image information
  • url (string) — Image URL
  • type (string) — Image size variant (e.g., large, default, small, preview)
  • alt (string) — Alternative text
  • requires_shipping (boolean) — Whether this item requires physical shipping
  • discount (object) — Per-unit discount applied to this line, when the merchant returns line-level discounts. Amount object (currency/value/number/symbol). Present only when the merchant exposes per-line discounts.
  • line_discount (object) — Total discount for this line (per-unit discount × quantity), when the merchant returns line-level discounts. Amount object. Present only when the merchant exposes per-line discounts.
  • variant_handles (array) — Variant configuration handles echoed back from the merchant (e.g. ["color:blue", "size:large"]). Present when the underlying platform represents variants as a set of handles rather than a single SKU.
  • properties (object) — Merchant-specific custom line-item properties (e.g. monogramming text, gift-wrap selection, configurator state). Free-form key/value map.
  • parent_line_item_id (string) — For bundles or kits, the line_item_id of the parent item this row is a child of.
  • line_item_tax (object) — Per-line tax amount, when the merchant exposes line-level tax. Amount object (currency/value/number/symbol).

• shipments (array) — Array of shipment groups, each containing line items with similar fulfillment requirements

  Shipment Properties

  • shipment_id (string) — Unique identifier for the shipment
  • line_item_ids (array) — Array of line item IDs included in this shipment
  • fulfillment_type (object) — Selected fulfillment method (automatically set to default)
  • id (string) — Fulfillment type identifier. One of: SHIP_TO_ADDRESS, SCHEDULED_DELIVERY, PICKUP_IN_STORE.
  • name (string) — Display name
  • description (string) — Detailed description
  • fulfillment_type_options (array) — Available fulfillment types for this shipment
  • shipping_method_options (array) — Available shipping methods for the selected fulfillment type
  • shipping_method (object) — Selected shipping method (defaults to cheapest available option)
  • id (string) — Shipping method identifier
  • description (string) — Shipping method description
  • price (object) — Shipping cost. Required unless hide_price is true.
  • hide_price (boolean) — When true, the merchant wants the price suppressed in the UI (e.g. “Calculated at checkout”). price may be omitted in this case.
  • message (string) — Optional merchant-supplied message about this shipping method (e.g. carrier note, eligibility caveat).
  • estimated_delivery (string) — Delivery timeframe
  • notes (string) — Special instructions or notes for this shipment
  • selected_date (string) — Selected delivery date for scheduled delivery (YYYY-MM-DD format)

• addons (object) — Available addon services and current selections

  Addon Properties

  • offers (array) — Available addon options
  • addon_id (string) — Unique addon identifier
  • display (object) — Display information
  • scope (string) — Addon scope (CART or ITEM)
  • price (object) — Addon price
  • selections (array) — Currently selected addons

• sub_total (object) — Subtotal of all line items

• shipping_total (object) — Total shipping cost across all shipments

• tax_total (object) — Total tax amount

• addon_total (object) — Total cost of selected addons

• fees (array) — Merchant-imposed fees (e.g. recycle, regulatory), if any

  Fee Properties

  • description (string) — Human-readable label for the fee (e.g. “Recycle fee”)
  • value (number) — Decimal fee amount
  • currency (string) — ISO 4217 currency code
  • number (integer) — Value in smallest currency unit (cents)
  • symbol (string) — Currency symbol

• fee_total (object) — Total of all fees

• total (object) — Grand total including all costs

• shipping_info (object) — Shipping address information (when address is set)

  Shipping Info Properties

  • first_name (string) — Recipient’s first name
  • last_name (string) — Recipient’s last name
  • company (string) — Company name (optional)
  • email (string) — Recipient’s email address
  • phone (string) — Recipient’s phone number
  • address1 (string) — Street address line 1
  • address2 (string) — Street address line 2 (optional)
  • city (string) — City name
  • state_or_province (string) — State or province code
  • state_name (string) — Full state / province name, when the merchant returns it (optional)
  • postal_code (string) — Postal / ZIP code
  • country (string) — Country code (e.g., US, CA)

• billing_info (object) — Billing address (when set via Set Billing Info). Same shape as shipping_info.

• coupons (array) — Promotion codes currently applied to the cart. Array of strings. Manage via the Promotions endpoints.

• cart_discount (object) — Total promotion / coupon discount applied to the cart. Amount object.

• cart_discount_breakdown (array) — Per-promotion breakdown of cart_discount. Each entry has label (string) and discount (Amount).

• tax (object) — Tax amount, V1 field name. Either tax or tax_total may be present depending on the merchant’s adapter — both are optional on a V2 cart. Read them the way Firmly’s own price checks do: prefer tax_total, fall back to tax (tax_total ?? tax). Don’t assume only one exists.

• urls (object, required) — Merchant URLs returned with the cart. The object is always present; its members are optional.

  URL Properties

  • thank_you_page (string) — URL to redirect the buyer to after a successful order.
  • order_status_page (string) — Merchant order-status page for the placed order, when the merchant provides one.

• shop_properties (object) — Merchant payment / wallet capabilities, used by the drop-in to decide which buttons to render.

  Shop Properties

  • paypal (object) — PayPal configuration: payment_enabled, express_enabled, clientId, merchantId, sandbox, intent.
  • klarna (object) — Klarna configuration: enabled, express_enabled, clientId.
  • google_pay (object) — Google Pay configuration: enabled, publishable_key, environment.
  • place_order_vault (boolean) — Whether the merchant routes place-order through Firmly’s payment host.
  • optional_fields (object) — Per-merchant relaxations such as shipping_phone (when phone is not required on shipping address).

• payment_handle (string) — Payment handle identifier (when payment is configured)

• payment_method_options (array) — Available payment methods for checkout

  Payment Method Object

  • type (string) — Payment method type (e.g., “CreditCard”, “PayPal”)
  • wallet (string) — Wallet identifier (e.g., “user”, “paypal”)

• session (object) — Account/session state for this device at this merchant. All fields optional — a merchant adapter that doesn’t support a signal simply omits it.

  Session Properties

  • requires_login (boolean) — The merchant requires the shopper to log in before checkout.
  • is_email_registered (boolean) — The email on the cart already has a merchant account.
  • is_logged_in (boolean) — The device session is currently logged into a merchant account.
  • accepts_membership (array) — Membership/loyalty programs the shopper can opt into at this merchant. Array of strings.
  • accepts_otp (array) — OTP delivery channels the merchant supports for this session: email, phone.

• notices (array) — Cart notices providing information about cart state and issues

  Notice Properties

  • code (string) — Notice code identifier

  Available Codes

  • ITEM_NOT_SHIPPABLE — Item cannot be shipped to selected address
  • ITEM_OUT_OF_STOCK — Item is out of stock
  • PROMO_EXPIRED — Promotion code has expired
  • PROMO_NOT_APPLICABLE — Promotion doesn’t apply to cart
  • SHIPPING_NOT_AVAILABLE — Shipping method unavailable
  • PRICE_INCREASED — Item price has increased
  • PRICE_DECREASED — Item price has decreased

  • severity (string) — Notice severity level: info, warning, or error
  • item_id (string) — Line item ID if notice is item-specific
  • details (object) — Additional notice details

  Details Properties

  • description (string) — Detailed description of the notice
  • promo_code (string) — Affected promo code (for promo-related notices)
  • old_value (object) — Previous price (for price change notices)
  • new_value (object) — New price (for price change notices)
  • reason (string) — Reason for the notice

• schema_version (string) — Cart schema version (“2.0”)

​​ Code Examples

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

const response = await fetch('https://api.firmly.work/api/v2/domains/staging.luma.gift/cart', {
  method: 'GET',
  headers: {
    'x-firmly-authorization': 'YOUR_TOKEN'
  }
});

const cart = await response.json();
console.log(cart);

import requests

response = requests.get(
    'https://api.firmly.work/api/v2/domains/staging.luma.gift/cart',
    headers={
        'x-firmly-authorization': 'YOUR_TOKEN'
    }
)

cart = response.json()
print(cart)

<?php
$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api.firmly.work/api/v2/domains/staging.luma.gift/cart",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_HTTPHEADER => [
    "x-firmly-authorization: YOUR_TOKEN"
  ],
]);

$response = curl_exec($curl);
curl_close($curl);

$cart = json_decode($response, true);
print_r($cart);
?>

​​ Response Example

{
  "cart_id": "a5600193-2c13-3356-d063-711da63b7cd7",
  "platform_id": "example_commerce",
  "shop_id": "staging.luma.gift",
  "display_name": "Luma Store",
  "cart_status": "active",
  "line_items": [
    {
      "line_item_id": "bd3710bc-97ef-408d-7382-43b7e5de712f",
      "platform_line_item_id": "0",
      "sku": "MH07-XS-Gray",
      "variant_description": "Gray / XS",
      "description": "Hero Hoodie",
      "base_sku": "MH07",
      "quantity": 1,
      "price": {
        "currency": "USD",
        "value": 54.00,
        "number": 5400,
        "symbol": "$"
      },
      "line_price": {
        "currency": "USD",
        "value": 54.00,
        "number": 5400,
        "symbol": "$"
      },
      "msrp": {
        "currency": "USD",
        "value": 64.00,
        "number": 6400,
        "symbol": "$"
      },
      "image": {
        "url": "https://staging.luma.gift/images/hero-hoodie.jpg",
        "type": "large",
        "alt": "Hero Hoodie in Gray"
      },
      "requires_shipping": true
    }
  ],
  "shipments": [
    {
      "shipment_id": "c2a3f9e8-ba80-8ea1-8762-e498097c8e35",
      "line_item_ids": ["bd3710bc-97ef-408d-7382-43b7e5de712f"],
      "fulfillment_type": {
        "id": "SCHEDULED_DELIVERY",
        "name": "Scheduled Delivery",
        "description": "White glove delivery with scheduled time"
      },
      "fulfillment_type_options": [
        {
          "id": "SHIP_TO_ADDRESS",
          "name": "Ship to Address",
          "description": "Standard shipping to customer address"
        },
        {
          "id": "SCHEDULED_DELIVERY",
          "name": "Scheduled Delivery",
          "description": "White glove delivery with scheduled time"
        },
        {
          "id": "PICKUP_IN_STORE",
          "name": "In-Store Pickup",
          "description": "Pick up at store location"
        }
      ],
      "shipping_method_options": [
        {
          "id": "WHITE_GLOVE",
          "description": "White Glove Delivery Service",
          "price": {
            "currency": "USD",
            "value": 149.99,
            "number": 14999,
            "symbol": "$"
          },
          "estimated_delivery": "Scheduled delivery"
        }
      ],
      "shipping_method": {
        "id": "WHITE_GLOVE",
        "description": "White Glove Delivery Service",
        "price": {
          "currency": "USD",
          "value": 149.99,
          "number": 14999,
          "symbol": "$"
        },
        "estimated_delivery": "Scheduled delivery"
      },
      "notes": "",
      "selected_date": "2025-07-14"
    }
  ],
  "addons": {
    "offers": [
      {
        "addon_id": "shipping_protection",
        "display": {
          "name": "Shipping Protection",
          "description": "Protect your order against shipping damage"
        },
        "scope": "CART",
        "coverage_mode": "PREDEFINED_GROUP",
        "price": {
          "currency": "USD",
          "value": 12.99,
          "number": 1299,
          "symbol": "$"
        }
      }
    ],
    "selections": []
  },
  "sub_total": {
    "currency": "USD",
    "value": 54.00,
    "number": 5400,
    "symbol": "$"
  },
  "shipping_total": {
    "currency": "USD",
    "value": 149.99,
    "number": 14999,
    "symbol": "$"
  },
  "tax_total": {
    "currency": "USD",
    "value": 5.40,
    "number": 540,
    "symbol": "$"
  },
  "fees": [
    {
      "description": "Recycle fee",
      "currency": "USD",
      "value": 2.00,
      "number": 200,
      "symbol": "$"
    }
  ],
  "fee_total": {
    "currency": "USD",
    "value": 2.00,
    "number": 200,
    "symbol": "$"
  },
  "addon_total": {
    "currency": "USD",
    "value": 0.00,
    "number": 0,
    "symbol": "$"
  },
  "total": {
    "currency": "USD",
    "value": 211.39,
    "number": 21139,
    "symbol": "$"
  },
  "shipping_info": {
    "first_name": "John",
    "last_name": "Doe",
    "email": "john.doe@staging.luma.gift",
    "phone": "+1234567890",
    "address1": "123 Main Street",
    "address2": "Apt 4B",
    "city": "New York",
    "state_or_province": "NY",
    "postal_code": "10001",
    "country": "US"
  },
  "payment_handle": "pay_01H2XVBR8C8JS5MQSFPJ8HF9SE",
  "payment_method_options": [
    {
      "type": "CreditCard",
      "wallet": "user"
    },
    {
      "type": "PayPal",
      "wallet": "paypal"
    }
  ],
  "notices": [],
  "schema_version": "2.0"
}

​​ Blocked cart (item_not_shippable)

cart_status can also come back as one of the other values in the ShoppingCartV2 schema — most notably item_not_shippable, which means checkout is blocked because an item in the cart can’t ship to the current address. When that happens, notices[] carries the reason:

{
  "cart_status": "item_not_shippable",
  "notices": [
    {
      "code": "ITEM_NOT_SHIPPABLE",
      "severity": "error",
      "item_id": "bd3710bc-97ef-408d-7382-43b7e5de712f",
      "details": {
        "description": "This item cannot be shipped to the selected address",
        "reason": "Shipping restrictions apply to this location"
      }
    }
  ]
}

Resolve it by removing the item, changing the shipping address, or picking a different fulfillment option, then re-fetch the cart.

​​ Related Endpoints

• Add Line Item — Add items to cart
• Update Line Item — Modify cart items
• Clear Cart — Empty the cart

​​ Error Responses

Errors return a JSON body with code, error, and description. Use the error value to drive client logic — descriptions are human-readable and may change.

{
  "code": 400,
  "error": "MissingAuthHeader",
  "description": "x-firmly-authorization header is missing or invalid."
}

{
  "code": 400,
  "error": "InvalidToken",
  "description": "Jwt token is invalid."
}

{
  "code": 400,
  "error": "InvalidAPIToken",
  "description": "API token is invalid."
}

{
  "code": 400,
  "error": "BadRequest",
  "description": "Bad request."
}

{
  "code": 401,
  "error": "Unauthorized",
  "description": "Unauthorized."
}

{
  "code": 401,
  "error": "InvalidJWTToken",
  "description": "Jwt token is invalid."
}

{
  "code": 404,
  "error": "PartnerNotFound",
  "description": "Partner not found."
}

{
  "code": 404,
  "error": "DomainNotFound",
  "description": "This domain was not found in firmly servers."
}

{
  "code": 404,
  "error": "CartNotFound",
  "description": "Cart was not found."
}

{
  "code": 412,
  "error": "OperationNotSupported",
  "description": "This operation is not supported for this store."
}

{
  "code": 422,
  "error": "UnprocessableEntity",
  "description": "The given payload has unprocessable, invalid or non-existent data. Please check the data and try again."
}