---
title: "Read a cart"
method: GET
path: "/carts/{cartId}"
tags: ["Carts"]
---

# Read a cart

`GET /carts/{cartId}`

## Request

- Base URL: `https://api.layout.link/v1`
- URL: `https://api.layout.link/v1/carts/{cartId}`
- Auth: HTTP bearer

The cart as Layout holds it. `totalMinor` is the only total, read from the same order Layout's price lock checks; confirm sends it back unchanged.

## Path parameters

- `cartId` string, required

## Headers

- `Layout-Version` '2026-10-01'

## Response `200`

The cart.

- CartEnvelope
  - `cart` Cart, required
    - `id` string, required
    - `status` 'building' | 'ready' | 'needs_answer' | 'failed' | 'canceling' | 'canceled' | 'expired' | 'closed', required: `canceling`: a cancel arrived while the cart was building. Layout releases the cart the moment the build lands, never offers it to the person, and never texts it; read the cart until it is `canceled`.
    - `store` object, nullable, required: The store the cart is at. Filled whenever Layout knows it, on a ready, answered, failed or closed cart alike; null only while building or when nothing names it.
      - `name` string, nullable, required
      - `address` string, nullable, required
    - `items` CartItem[], required
      - `name` string, required
      - `quantity` integer, required
      - `priceMinor` integer, nullable, required
      - `modifiers` string[], required
    - `currency` 'usd', required
    - `totalMinor` integer, nullable, required: The one total, delivery fee and tip included. Confirm sends exactly this as expectedTotalMinor.
    - `fees` CartFees, required
      - `subtotalMinor` integer, nullable, required
      - `taxAndFeesMinor` integer, nullable, required
      - `merchantTotalMinor` integer, required
      - `serviceFeeMinor` integer, required
      - `serviceFeeWaived` boolean, required
      - `creditMinor` integer, required: Layout credit applied when the order is placed. The card is charged totalMinor minus this.
      - `courierFeeMinor` integer, required: The delivery fee, at cost. 0 for pickup.
      - `tipMinor` integer, required: The driver's tip, all of it to the driver. 0 for pickup.
    - `fulfillment` CartFulfillment, required
      - `type` 'pickup' | 'delivery', required
      - `deliveryUnavailable` object, nullable, required: Set when delivery was asked for and cannot happen. The cart stays a pickup; show the message as written.
        - `reason` 'not_enabled' | 'no_address' | 'address_not_found' | 'no_phone' | 'out_of_range' | 'over_limit' | 'unavailable', required: Why delivery is not on this cart. `not_enabled`: not offered to this person yet. `no_address`: they have no saved delivery address; send one. `out_of_range`: the store is too far from the address.
        - `message` string, required
        - `alternative` object, nullable, required: A nearer location of the same restaurant that can deliver to that address. To use it, create a new cart with its placeId and the same items and fulfillment.
          - `placeId` string, required
          - `name` string, required
          - `address` string, required
          - `miles` number, required
      - `savedAddresses` object[]: The person's saved addresses, each Personal or Work, when they can choose delivery. Offer them, then send the label as addressLabel. Never coordinates or notes.
        - `kind` 'personal' | 'work', required: The section the person filed it under.
        - `label` string, required: What to call it: the name they gave it, else "Personal" or "Work".
        - `line` string, required
        - `isDefault` boolean, required
      - `dropoff` object, nullable, required: Where it is going, as one line: the street and the unit, with the person's name for it when they gave one. Never coordinates or notes.
        - `label` string, nullable, required
        - `line` string, required
      - `courierFeeMinor` integer, nullable, required
      - `tip` object, nullable, required: Show the tip and its presets beside the total. The lowest preset is chosen unless you sent one.
        - `minor` integer, required
        - `percent` integer, nullable, required: The preset it came from; null for an amount you sent.
        - `presets` object[], required
          - `percent` integer, required
          - `minor` integer, required
    - `card` object, nullable, required: The card that will be billed. Only on a connected person's token.
      - `brand` string, nullable, required
      - `last4` string, nullable, required
    - `codeRequired` boolean, required: Confirming is expected to need the 6-digit code Layout texts the person, checked each time you read the cart. `codeReason` says why. The confirm decides, and can still answer `code_required`.
    - `codeReason` 'person_setting' | 'over_limit' | 'code_outstanding' | 'first_order_consent' | 'risk_check' | 'unverified', required: `person_setting`: the person keeps codes on in Layout, so every order needs one. `over_limit`: the total is over Layout's limit for orders without a code. `code_outstanding`: a code was already texted for this cart. `first_order_consent`: on a build grant, the person has not yet agreed to your application ordering for them; the first order's code is that agreement. `risk_check`: Layout's checks asked for one on this order (only on `code_required`). `unverified`: Layout could not check just now, so it asks for the code.
    - `confirmationCard` string, nullable, required: Layout's own wording of the cart, to show as written. Only on a connected person's token.
    - `decision` union, required
      - ChoicesDecision
        - `kind` 'choices', required
        - `question` string, required
        - `item` string, required
        - `groups` object[], required
          - `name` string, required
          - `required` boolean, required
          - `options` string[], required
        - `answerWith` object, required
          - `field` 'choices', required
      - PickupTimeDecision
        - `kind` 'pickup_time', required
        - `question` string, required
        - `pickupTime` string, nullable, required
        - `answerWith` object, nullable, required
          - `field` 'acceptPickupTime', required
          - `value` true, required
        - `alternatives` object[], required
          - `placeId` string, required
          - `name` string, required
          - `address` string, required
    - `failure` object, nullable, required
      - `code` string, required
      - `message` string, required
    - `order` object, nullable, required: The order this cart became. On a `closed` cart it was confirmed, here or on another surface, or ended: `status` is the order's state now, and `confirmedVia` names where the person confirmed it when Layout knows.
      - `id` string, required
      - `status` 'building' | 'carted' | 'placing' | 'placed' | 'failed' | 'unconfirmed' | 'refunded', required
      - `confirmedVia` 'sms' | 'tracking_link': Where the person confirmed it, when Layout knows: `sms`, by replying YES to Layout's cart-ready text; `tracking_link`, on Layout's tracking page. Absent when Layout does not know, which includes the Layout app and any API or MCP confirm.
    - `expiresAt` string, nullable, required: When a ready cart stops being confirmable.

## Other responses

- `400`: `unsupported_version`: the Layout-Version header names no version this API answers.
- `401`: The token is missing, expired, revoked, issued for another audience, or the person disconnected. Every 401 reads the same.
- `403`: The credential is real and may not do this: an application or account that is suspended, a live person on an unapproved application, a scope the token was not granted, or a person whose Layout account cannot order yet.
- `404`: No such cart for this application and person. Another application's cart is a 404 too.
- `429`: A per-minute brake.
- `500`: Layout failed to answer. Retry with backoff.
- `503`: Credentials or a dependency could not be checked right now. Retry with backoff.

---

[API](https://skmtc.dev/layout/apis/layout-partner-api.md) · [All operations](https://skmtc.dev/layout/apis/layout-partner-api/llms.txt) · [OpenAPI document](https://skmtc.dev/layout/apis/layout-partner-api/revisions/7ff4ba01bf56?raw)