Get cart

Request Parameters

🏷️ header · unmarked parameters are query params

Parameter	Type	Required	Description
`Locally-Api-Token` 🏷️	string	Yes	Locally API token must be passed in the header to authenticate the API consumer.
`Locally-Api-Session-Id` 🏷️	string	Yes	Session ID must be passed in the header to persist the user session. Can expire.
`Locally-Pl-Jwt` 🏷️	string	No	JSON Web Token passed in the header to identify the user. Does not expire.

Example Request

curl 'https://www.locally.com/headless/api/1.0/cart' \
--header 'Locally-Api-Token: {{API_TOKEN}}' \
--header 'Locally-Api-Session-Id: {{SESSION_ID}}' \
--header 'Locally-Pl-Jwt: {{CART_HASH_JWT}}'

const response = await fetch('https://www.locally.com/headless/api/1.0/cart', {
  headers: {
    'Locally-Api-Token': '{{API_TOKEN}}',
    'Locally-Api-Session-Id': '{{SESSION_ID}}',
    'Locally-Pl-Jwt': '{{CART_HASH_JWT}}'
  }
});
const cart = await response.json();

import requests

response = requests.get(
    'https://www.locally.com/headless/api/1.0/cart',
    headers={
        'Locally-Api-Token': '{{API_TOKEN}}',
        'Locally-Api-Session-Id': '{{SESSION_ID}}',
        'Locally-Pl-Jwt': '{{CART_HASH_JWT}}'
    }
)
cart = response.json()

Locally-Pl-Jwt is optional: pass the cart_hash_jwt value returned by a previous cart response to retrieve the same cart even after the session ID has expired.

Example Response

{
    "success": true,
    "data": {
        "n_in_cart": 1,
        "cart_hash": "QE3QL6",
        "cart_content": {
            "user": {
                "id": 999,
                "email": "[email protected]",
                "first_name": "",
                "last_name": "",
                "phone": "",
                "preferred_zip": "60605",
                "preferred_country": "US"
            },
            "cart": {
                "id": 999,
                "user_id": 999,
                "hash": "QE3QL6",
                "subtotal": 100,
                "tax_total": 10.10,
                "shipping_cost_total": 0,
                "grand_total": 110.10,
                "first_name": "",
                "last_name": "",
                "address": "",
                "address_2": "",
                "city": "",
                "state": "",
                "zip": "",
                "email": "",
                "phone": "",
                "country": "",
                "locale": "en-us",
                "origin": "www.example.com",
                "for_hold": 0,
                "for_delivery": 0,
                "delivery_first_name": "",
                "delivery_last_name": "",
                "delivery_address": "",
                "delivery_address_2": "",
                "delivery_city": "",
                "delivery_state": "",
                "delivery_zip": "",
                "delivery_country": "",
                "delivery_fee_total": 0,
                "is_test": 0,
                "delivery_choice": "",
                "store_delivery_fee": 0,
                "delivery_notes": "",
                "coupon_discount_total": 0,
                "coupon_code": "",
                "coupon_discount_reason": "",
                "for_ship_to_store": 0,
                "cart_currency": "USD",
                "items": [
                    {
                        "id": 999,
                        "qty": 1,
                        "upc": "000000000000",
                        "product_name": "ACME Outfitters Widget",
                        "product_company_name": "ACME Outfitters",
                        "product_image": "image.jpg",
                        "product_color": "Red",
                        "product_size": "M",
                        "product_price": 100,
                        "product_id": 999999,
                        "store_id": 99999,
                        "subtotal": 100,
                        "tax_total": 10.10,
                        "shipping_cost": 0,
                        "grand_total": 110.10,
                        "qty_available": 10,
                        "message": "",
                        "fulfillment_type": 0,
                        "product_currency": "USD",
                        "product_company_id": 999,
                        "coupon_discount_total": 0,
                        "vat": 0,
                        "tax_rate": 10.25,
                        "product": {
                            "id": 999999,
                            "name": "ACME Outfitters Widget",
                            "company_id": 999,
                            "style_number": "99999",
                            "image": "image.jpg",
                            "long_description": "Lorem ipsum.",
                            "average_rating": 5,
                            "n_reviews": 1,
                            "upc_data": null,
                            "company": null
                        }
                    }
                ],
                "custom_cart_text": ""
            },
            "country": {
                "id": 99,
                "name": "United States",
                "code": "US",
                "primary_currency": "USD",
                "secondary_currency": "",
                "primary_locale": "en-us",
                "phone_prefix": "1",
                "display_marketing_consent": "",
                "consent_checkbox_default_state": 0,
                "code_3": "USA",
                "display_brand_marketing_consent": ""
            },
            "cart_error": 0,
            "cart_disclaimer": "By continuing you agree to our <a href=https:\/\/www.locally.com\/terms target=_blank>terms of service<\/a>",
            "cart_store": {
                "id": 99999,
                "name": "ACME Outfitters Chicago",
                "address": "123 ACME St.",
                "zip": "00000",
                "company_id": 999,
                "lat": "41.91136867",
                "lng": "-87.67771437",
                "phone": "(312) 555-0142",
                "mon_time_open": 1100,
                "mon_time_close": 1900,
                "tue_time_open": 1100,
                "tue_time_close": 1900,
                "wed_time_open": 1100,
                "wed_time_close": 1900,
                "thu_time_open": 1100,
                "thu_time_close": 1900,
                "fri_time_open": 1100,
                "fri_time_close": 1900,
                "sat_time_open": 1100,
                "sat_time_close": 1900,
                "sun_time_open": 1100,
                "sun_time_close": 1700,
                "address_2": "",
                "city": "Chicago",
                "state": "IL",
                "country": "US",
                "timezone": "America\/Chicago",
                "average_rating": 5,
                "n_reviews": 3,
                "image": "image.jpg",
                "web_address": "https:\/\/www.example.com",
                "is_temporarily_closed": 0,
                "area": null,
                "store_hours": [
                    {
                        "id": 1,
                        "store_id": 99999,
                        "type": 0,
                        "custom_label": null,
                        "dow": 0,
                        "single_day": null,
                        "closed": 0,
                        "start_time": 700,
                        "end_time": 2000,
                        "group": 1,
                        "is_closed": 0
                    },
                    {
                        "id": 2,
                        "store_id": 99999,
                        "type": 0,
                        "custom_label": null,
                        "dow": 1,
                        "single_day": null,
                        "closed": 0,
                        "start_time": 700,
                        "end_time": 2000,
                        "group": 1,
                        "is_closed": 0
                    }
                ],
                "pickup_time_slots": {
                    "time": null,
                    "days": null
                },
                "store_vat_details": {
                    "id": 99999,
                    "uses_vat": 0,
                    "sales_tax_label": ""
                },
                "acquisition_options": {
                    "bopis": 1,
                    "sdd": 1,
                    "ropis": 1
                }
            }
        },
        "delivery_options": null,
        "cart_hash_jwt": "eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJjYXJ0X2hhc2giOiJRRTNRTDYiLCJjcmVhdGVkX2F0IjoxNzIxNDA4MDAwfQ.sQ5xL0y3fY8pWq2ZbNvA7cRkT1uHdGmE4jXoPiC6VnM",
        "session": {
            "id": "vD2kq9mXw4bT7nR5cJ1sL8fA3gH6pZ0yE2uN4iK9"
        }
    },
    "msg": ""
}

Response Explanation

success — true for a healthy cart. Cart-level failures still return HTTP 200 with success: false and the reason in data.cart_content.cart_error; other failures use HTTP 4xx/5xx with msg and error_code.
data.n_in_cart — Count of distinct line items in the cart, not the summed quantity — a single item with qty: 2 still returns n_in_cart: 1.
data.cart_hash — The cart's permanent short identifier, identical to data.cart_content.cart.hash. Use it as the hash parameter when placing the order.
data.cart_content.cart.subtotal — All money fields (subtotal, tax_total, grand_total, items[].product_price) are decimal amounts in cart_currency — dollars and cents, never integer cents. items[].tax_rate is a percentage (10.25 means 10.25%).
data.cart_content.cart.is_test — 1 when the cart was created with a test_-prefixed API token. Test carts skip real payment capture and fulfillment processing.
data.cart_content.cart.items[].id — Cart item line ID — the {{ITEM_ID}} key for Update cart's qty array and its remove_item parameter. Removal only works before the item is ordered (Cart Item Statuses).
data.cart_content.cart.items[].qty_available — The store's current on-hand stock for this UPC, capped by any brand per-order quantity limit. Quantity updates above this value are silently ignored.
data.cart_content.cart_error — 0 when the cart is healthy. On a cart-level failure it becomes a human-readable message (for example, a purchase option no longer available) and success flips to false.
data.cart_hash_jwt — Non-expiring signed JWT encoding the cart hash. Save it and send it as the Locally-Pl-Jwt header to retrieve or update this cart after the session ID expires.
data.session.id — The current session ID. It can change between calls, so always send the latest value in the Locally-Api-Session-Id header on your next request. Session IDs eventually expire.