Get All Carts

This will return the list of all carts your account has access to, ordered by most recent first, and broken up via 50 per page. The first page can be accessed via just (/api/v2/carts) or (/api/v2/carts/0).

Request Parameters

🏷️ header · 🔗 path · unmarked parameters are query params

Parameter	Type	Required	Description
`Locally-Api-Token` 🏷️	string	No	Locally issued API key.
`page` 🔗	integer	Yes	Optional page number, starting with 0. Defaults to `0`.
`updated_since_hours`	integer	No	Optional.

Example Request

curl --get 'https://www.locally.com/api/v2/carts/0' \
--header 'Locally-Api-Token: {{API_TOKEN}}' \
--data-urlencode 'updated_since_hours=24'

const response = await fetch('https://www.locally.com/api/v2/carts/0?updated_since_hours=24', {
  headers: {
    'Locally-Api-Token': '{{API_TOKEN}}'
  }
});
const data = await response.json();

import requests

response = requests.get(
    'https://www.locally.com/api/v2/carts/0',
    params={'updated_since_hours': 24},
    headers={'Locally-Api-Token': '{{API_TOKEN}}'}
)
data = response.json()

updated_since_hours is optional — when provided, only carts created or updated within the last N hours are returned.

Example Response

{
  "status": true,
  "properties": {
    "date_time": "2022-02-03 10:52:40",
    "current_page": 0,
    "total_pages": 3
  },
  "carts": [
    {
      "hash": "E3GKY8",
      "type": "HOLD",
      "n_items": 1,
      "source": "From locally.com",
      "ordered_at": "2022-01-28 10:28:22",
      "updated_at": "2022-01-28 15:34:30",
      "delivery_status": "",
      "pickup_window": "2022-01-29 15:00:00",
      "items": [
        {
          "currency": "EUR",
          "total": "100.00",
          "status": "Canceled",
          "sts_status": "N/A",
          "qty": 1,
          "product_id": 967586,
          "order_resolution": "auto-cancelled",
          "upc": "601842495575",
          "alias": [
            "D1447020122-00003"
          ]
        }
      ]
    },
    {
      "hash": "EX2",
      "type": "DELIVERY",
      "n_items": 1,
      "source": "From example.com",
      "ordered_at": "2026-01-29 08:50:36",
      "created_at": "2026-01-29 08:48:14",
      "updated_at": "2026-01-29 10:17:56",
      "delivery_status": "Delivery to destination complete",
      "pickup_window": "",
      "items": [
        {
          "currency": "USD",
          "subtotal": "225.00",
          "tax_total": "23.06",
          "shipping_cost": "0.00",
          "total": "248.06",
          "status": "Confirmed",
          "status_code": 35,
          "sts_status": "N/A",
          "qty": 1,
          "product_id": 548303,
          "order_resolution": "",
          "upc": "686487455948",
          "alias": []
        }
      ],
      "delivery": {
        "delivery_type": "API",
        "carrier_id": 2,
        "status": 5,
        "carrier_name": "Postmates",
        "customer_fee": "6.00",
        "carrier_fee": "6.00",
        "tracking_url": "https://delivery.uber.com/orders/62105936-e413-40d5-aecd-4c335c3cd3c2",
        "estimated_pickup_at": "2026-01-29 16:15:13",
        "estimated_dropoff_at": "2026-01-29 16:17:56",
        "signature_url": "https://www.example.com/signature.jpg",
        "dropoff_photo_url": "https://www.example.com/picture.jpg",
        "address": {
          "first_name": "TEST",
          "last_name": "USER",
          "address_1": "2020 W Willow St",
          "address_2": "",
          "city": "Chicago",
          "state": "IL",
          "zip": "60647",
          "country": "US"
        },
        "driver": {
          "name": "TEST DRIVER",
          "vehicle_description": "Red Toyota Camry",
          "photo_url": "https://via.placeholder.com/150",
          "location": {
            "lat": 41.91136867,
            "lng": -87.67771437
          }
        }
      }
    }
  ]
}

Response Explanation

properties.date_time — Timestamp of when this response was generated (server time), not an order event; use ordered_at and updated_at for order timing.
properties.total_pages — Total pages at 50 carts per page; pages are zero-based (properties.current_page echoes the request). Requesting past the last page returns status: false with a message.
carts[].hash — Unique cart identifier — pass it as the cart_hash path parameter on other Cart API calls such as Update a Cart Item.
carts[].type — Fulfillment type: HOLD (reservation, pay in store), ORDER (paid in-store pickup), or DELIVERY (local delivery).
carts[].updated_at — Most recent change to the cart or any of its items — the timestamp consulted (along with created_at) by the updated_since_hours filter.
carts[].pickup_window — Pickup time slot the shopper selected for an in-store pickup order; empty string when none was chosen.
carts[].items[].status — Item state label, paired with the numeric status_code. All values and their end states are listed in Cart Item Statuses.
carts[].items[].sts_status — Ship-to-Store only: N/A unless the item is a ship-to-store order, otherwise a stage label such as Pending Brand, Processing, or Shipped. Get a Single Cart returns slug forms instead.
carts[].items[].alias — Alternate item codes (UPC aliases, such as your SKUs) registered with Locally for this UPC; an empty array when none exist.
carts[].delivery — Present only on DELIVERY carts: tracking_url is the live tracking link and driver stays null until a courier is assigned.

Request Parameters

Example Request

Example Response

Response Explanation

200200

400400