> ## Documentation Index
> Fetch the complete documentation index at: https://developers.firmly.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Get Cart

> Retrieves the current state of a shopping cart with all line items, shipments, pricing, and addon information

## 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

<Card>
  <ParamField header="x-firmly-authorization" type="string" required>
    Device authentication token to identify and map the session
  </ParamField>
</Card>

## Path Parameters

<ParamField path="domain" type="string" required>
  Domain of the merchant website (e.g., `staging.luma.gift`)
</ParamField>

## Response

<ResponseField name="cart_id" type="string">
  Unique identifier for the shopping cart session
</ResponseField>

<ResponseField name="platform_id" type="string">
  Platform identifier (e.g., "shopify", "bigcommerce", "magento")
</ResponseField>

<ResponseField name="shop_id" type="string">
  Shop identifier (merchant domain, e.g., "staging.luma.gift")
</ResponseField>

<ResponseField name="display_name" type="string">
  Merchant display name
</ResponseField>

<ResponseField name="cart_status" type="string">
  Current cart status (e.g., "active")
</ResponseField>

<ResponseField name="line_items" type="array">
  Array of products currently in the cart

  <Expandable title="Line Item Properties">
    <ResponseField name="line_item_id" type="string">
      Unique identifier for the line item
    </ResponseField>

    <ResponseField name="platform_line_item_id" type="string">
      Platform-specific line item identifier
    </ResponseField>

    <ResponseField name="sku" type="string">
      Product SKU identifier
    </ResponseField>

    <ResponseField name="variant_description" type="string">
      Variant-specific description
    </ResponseField>

    <ResponseField name="description" type="string">
      Product description
    </ResponseField>

    <ResponseField name="base_sku" type="string">
      Base product SKU (parent of variants)
    </ResponseField>

    <ResponseField name="quantity" type="number">
      Quantity of the item in cart
    </ResponseField>

    <ResponseField name="price" type="object">
      Unit price information

      <ResponseField name="currency" type="string">
        Currency code (e.g., USD)
      </ResponseField>

      <ResponseField name="value" type="number">
        Price as decimal
      </ResponseField>

      <ResponseField name="number" type="number">
        Price in smallest currency unit
      </ResponseField>

      <ResponseField name="symbol" type="string">
        Currency symbol
      </ResponseField>
    </ResponseField>

    <ResponseField name="line_price" type="object">
      Total price for this line (price × quantity)

      <ResponseField name="currency" type="string">
        Currency code (e.g., USD)
      </ResponseField>

      <ResponseField name="value" type="number">
        Price as decimal
      </ResponseField>

      <ResponseField name="number" type="number">
        Price in smallest currency unit
      </ResponseField>

      <ResponseField name="symbol" type="string">
        Currency symbol
      </ResponseField>
    </ResponseField>

    <ResponseField name="msrp" type="object">
      Manufacturer's suggested retail price

      <ResponseField name="currency" type="string">
        Currency code (e.g., USD)
      </ResponseField>

      <ResponseField name="value" type="number">
        Price as decimal
      </ResponseField>

      <ResponseField name="number" type="number">
        Price in smallest currency unit
      </ResponseField>

      <ResponseField name="symbol" type="string">
        Currency symbol
      </ResponseField>
    </ResponseField>

    <ResponseField name="image" type="object">
      Product image information

      <ResponseField name="src" type="string">
        Image URL
      </ResponseField>

      <ResponseField name="alt" type="string">
        Alternative text
      </ResponseField>
    </ResponseField>

    <ResponseField name="requires_shipping" type="boolean">
      Whether this item requires physical shipping
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="shipments" type="array">
  Array of shipment groups, each containing line items with similar fulfillment requirements

  <Expandable title="Shipment Properties">
    <ResponseField name="shipment_id" type="string">
      Unique identifier for the shipment
    </ResponseField>

    <ResponseField name="line_item_ids" type="array">
      Array of line item IDs included in this shipment
    </ResponseField>

    <ResponseField name="fulfillment_type" type="object">
      Selected fulfillment method (automatically set to default)

      <ResponseField name="id" type="string">
        Fulfillment type identifier (e.g., SHIP\_TO\_ADDRESS, SCHEDULED\_DELIVERY, IN\_STORE\_PICKUP)
      </ResponseField>

      <ResponseField name="name" type="string">
        Display name
      </ResponseField>

      <ResponseField name="description" type="string">
        Detailed description
      </ResponseField>
    </ResponseField>

    <ResponseField name="fulfillment_type_options" type="array">
      Available fulfillment types for this shipment
    </ResponseField>

    <ResponseField name="shipping_method_options" type="array">
      Available shipping methods for the selected fulfillment type
    </ResponseField>

    <ResponseField name="shipping_method" type="object">
      Selected shipping method (defaults to cheapest available option)

      <ResponseField name="id" type="string">
        Shipping method identifier
      </ResponseField>

      <ResponseField name="description" type="string">
        Shipping method description
      </ResponseField>

      <ResponseField name="price" type="object">
        Shipping cost
      </ResponseField>

      <ResponseField name="estimated_delivery" type="string">
        Delivery timeframe
      </ResponseField>
    </ResponseField>

    <ResponseField name="notes" type="string">
      Special instructions or notes for this shipment
    </ResponseField>

    <ResponseField name="selected_date" type="string">
      Selected delivery date for scheduled delivery (YYYY-MM-DD format)
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="addons" type="object">
  Available addon services and current selections

  <Expandable title="Addon Properties">
    <ResponseField name="offers" type="array">
      Available addon options

      <ResponseField name="addon_id" type="string">
        Unique addon identifier
      </ResponseField>

      <ResponseField name="display" type="object">
        Display information
      </ResponseField>

      <ResponseField name="scope" type="string">
        Addon scope (CART or ITEM)
      </ResponseField>

      <ResponseField name="price" type="object">
        Addon price
      </ResponseField>
    </ResponseField>

    <ResponseField name="selections" type="array">
      Currently selected addons
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="sub_total" type="object">
  Subtotal of all line items
</ResponseField>

<ResponseField name="shipping_total" type="object">
  Total shipping cost across all shipments
</ResponseField>

<ResponseField name="tax_total" type="object">
  Total tax amount
</ResponseField>

<ResponseField name="addon_total" type="object">
  Total cost of selected addons
</ResponseField>

<ResponseField name="total" type="object">
  Grand total including all costs
</ResponseField>

<ResponseField name="shipping_info" type="object">
  Shipping address information (when address is set)

  <Expandable title="Shipping Info Properties">
    <ResponseField name="first_name" type="string">
      Recipient's first name
    </ResponseField>

    <ResponseField name="last_name" type="string">
      Recipient's last name
    </ResponseField>

    <ResponseField name="email" type="string">
      Recipient's email address
    </ResponseField>

    <ResponseField name="phone" type="string">
      Recipient's phone number
    </ResponseField>

    <ResponseField name="company" type="string">
      Company name (optional)
    </ResponseField>

    <ResponseField name="address_line_1" type="string">
      Street address line 1
    </ResponseField>

    <ResponseField name="address_line_2" type="string">
      Street address line 2 (optional)
    </ResponseField>

    <ResponseField name="city" type="string">
      City name
    </ResponseField>

    <ResponseField name="state_code" type="string">
      State/province code
    </ResponseField>

    <ResponseField name="zip" type="string">
      ZIP/postal code
    </ResponseField>

    <ResponseField name="country_code" type="string">
      Country code (e.g., US, CA)
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="payment_handle" type="string">
  Payment handle identifier (when payment is configured)
</ResponseField>

<ResponseField name="payment_method_options" type="array">
  Available payment methods for checkout

  <Expandable title="Payment Method Object">
    <ResponseField name="type" type="string">
      Payment method type (e.g., "CreditCard", "PayPal")
    </ResponseField>

    <ResponseField name="wallet" type="string">
      Wallet identifier (e.g., "user", "paypal")
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="notices" type="array">
  Cart notices providing information about cart state and issues

  <Expandable title="Notice Properties">
    <ResponseField name="code" type="string">
      Notice code identifier

      <Expandable title="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
      </Expandable>
    </ResponseField>

    <ResponseField name="severity" type="string">
      Notice severity level: `info`, `warning`, or `error`
    </ResponseField>

    <ResponseField name="item_id" type="string">
      Line item ID if notice is item-specific
    </ResponseField>

    <ResponseField name="details" type="object">
      Additional notice details

      <Expandable title="Details Properties">
        <ResponseField name="description" type="string">
          Detailed description of the notice
        </ResponseField>

        <ResponseField name="promo_code" type="string">
          Affected promo code (for promo-related notices)
        </ResponseField>

        <ResponseField name="old_value" type="object">
          Previous price (for price change notices)
        </ResponseField>

        <ResponseField name="new_value" type="object">
          New price (for price change notices)
        </ResponseField>

        <ResponseField name="reason" type="string">
          Reason for the notice
        </ResponseField>
      </Expandable>
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="schema_version" type="string">
  Cart schema version ("2.0")
</ResponseField>

## Code Examples

<CodeGroup>
  ```bash cURL theme={null}
  curl --request GET \
    --url https://api.firmly.work/api/v2/domains/staging.luma.gift/cart \
    --header 'x-firmly-authorization: YOUR_TOKEN'
  ```

  ```javascript JavaScript theme={null}
  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);
  ```

  ```python Python theme={null}
  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 PHP theme={null}
  <?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);
  ?>
  ```
</CodeGroup>

<ResponseExample>
  ```json theme={null}
  {
    "cart_id": "cart_01H2XVBR8C8JS5MQSFPJ8HF9SA",
    "platform_id": "shopify",
    "shop_id": "staging.luma.gift",
    "display_name": "Luma Store",
    "cart_status": "active",
    "line_items": [
      {
        "line_item_id": "item_01H2XVBR8C8JS5MQSFPJ8HF9SB",
        "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": {
          "src": "https://staging.luma.gift/images/hero-hoodie.jpg",
          "alt": "Hero Hoodie in Gray"
        },
        "requires_shipping": true
      }
    ],
    "shipments": [
      {
        "shipment_id": "ship_01H2XVBR8C8JS5MQSFPJ8HF9SD",
        "line_item_ids": ["item_01H2XVBR8C8JS5MQSFPJ8HF9SB"],
        "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": "IN_STORE_PICKUP",
            "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",
          "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": "$"
    },
    "addon_total": {
      "currency": "USD",
      "value": 0.00,
      "number": 0,
      "symbol": "$"
    },
    "total": {
      "currency": "USD",
      "value": 209.39,
      "number": 20939,
      "symbol": "$"
    },
    "shipping_info": {
      "first_name": "John",
      "last_name": "Doe",
      "email": "john.doe@staging.luma.gift",
      "phone": "+1234567890",
      "company": "",
      "address_line_1": "123 Main Street",
      "address_line_2": "Apt 4B",
      "city": "New York",
      "state_code": "NY",
      "zip": "10001",
      "country_code": "US"
    },
    "payment_handle": "pay_01H2XVBR8C8JS5MQSFPJ8HF9SE",
    "payment_method_options": [
      {
        "type": "CreditCard",
        "wallet": "user"
      },
      {
        "type": "PayPal",
        "wallet": "paypal"
      }
    ],
    "notices": [
      {
        "code": "ITEM_NOT_SHIPPABLE",
        "severity": "error",
        "item_id": "item_01H2XVBR8C8JS5MQSFPJ8HF9SB",
        "details": {
          "description": "This item cannot be shipped to the selected address",
          "reason": "Shipping restrictions apply to this location"
        }
      }
    ],
    "schema_version": "2.0"
  }
  ```
</ResponseExample>

## Error Responses

<Accordion title="400 Bad Request">
  Invalid request format or missing required headers

  ```json theme={null}
  {
    "code": 400,
    "error": "MissingAuthHeader",
    "description": "x-firmly-authorization header is required"
  }
  ```
</Accordion>

<Accordion title="401 Unauthorized">
  Invalid or expired authentication token

  ```json theme={null}
  {
    "code": 401,
    "error": "InvalidJWTToken",
    "description": "The JWT token is invalid"
  }
  ```
</Accordion>

<Accordion title="404 Not Found">
  Cart does not exist for the given domain

  ```json theme={null}
  {
    "code": 404,
    "error": "ErrorCartNotFound",
    "description": "Cart not found"
  }
  ```
</Accordion>

<Accordion title="422 Unprocessable Entity">
  Store service unavailable or other processing error

  ```json theme={null}
  {
    "code": 422,
    "error": "ErrorStoreUnavailable",
    "description": "Store service unavailable"
  }
  ```
</Accordion>

## Related Endpoints

* [Add Line Item](/api-reference/cart-management/add-line-item) - Add items to cart
* [Update Line Item](/api-reference/cart-management/update-line-item) - Modify cart items
* [Clear Cart](/api-reference/cart-management/clear-cart) - Empty the cart