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

# Checkout

> Five steps from cart to order. Nothing moves money until the final commit.

![Checkout flow: propose, review gate, approve, commit](https://mintcdn.com/agentmall/ZuoglRqW4CDsIaRs/images/checkout.svg?fit=max\&auto=format\&n=ZuoglRqW4CDsIaRs\&q=85\&s=5c33eb15e968654c7ede9abe13cd8a04)

Checkout is five steps: open, address, fulfillment, payment, commit. Nothing moves money until commit.

## 1. Open checkout

```json theme={null}
{ "cart_id": "ses_..." }
```

`create_checkout` opens the merchant checkout page and reads it. Returns `status`, `line_items`, `totals`, `fulfillment.methods`, and `review_hash`. Nothing is placed.

If the cart is empty, the call fails with `cart_empty`. If sign-in is needed, it fails with `sign_in_required`. If items went out of stock, it fails with `out_of_stock` and lists the `unavailable_items`.

## 2. Set the address

```json theme={null}
{
  "id": "ses_...",
  "fulfillment": {
    "address": {
      "first_name": "Jane",
      "last_name": "Doe",
      "street_address": "123 Main St",
      "address_locality": "Austin",
      "address_region": "TX",
      "postal_code": "78701",
      "address_country": "US"
    }
  }
}
```

`update_checkout` with `fulfillment.address` writes the shipping address. US addresses only. At least one name (`first_name` or `last_name`) is required. Optional fields: `extended_address`, `phone_number`.

The response includes updated `totals` with estimated tax. These are estimates until `complete_checkout`.

## 3. Choose fulfillment

```json theme={null}
{
  "id": "ses_...",
  "fulfillment": {
    "method": { "id": "express_delivery", "kind": "delivery", "label": "Express Delivery" }
  }
}
```

`update_checkout` with `fulfillment.method` selects shipping, delivery, or pickup. Use an `id` from `fulfillment.methods` in the checkout response. `kind` is `"shipping"`, `"delivery"`, or `"pickup"`.

The checkout response also includes `fulfillment.delivery_date` when the page shows one: `{ earliest, latest, text }`. `latest` is null for a single date. This field is informational and not part of `review_hash`.

## 4. Add payment

```json theme={null}
{
  "id": "ses_...",
  "payment": {
    "instruments": [
      {
        "id": "card_1",
        "handler_id": "dev.agentmall.card",
        "type": "card",
        "selected": true,
        "credential": { "type": "ciphertext", "value": "ev:..." }
      }
    ]
  }
}
```

`update_checkout` with `payment.instruments` adds a vaulted card. The `credential.value` is Evervault `ev:` ciphertext, collected through the console's `/collect` page. No raw card numbers.

After payment is set, `status` moves from `"incomplete"` to `"ready"`.

## 5. Commit the order

```json theme={null}
{ "id": "ses_...", "review_hash": "abc123...", "total_minor": 4291 }
```

`complete_checkout` places the order. It requires both `review_hash` and `total_minor` from the checkout. If either has changed since your last read, the call fails and nothing is placed. See [Review and safety](https://agentmall.mintlify.site/concepts/review-safety.md) for details.

On success, returns `status: "completed"` with `order.id` and `test`. The session ends.

## Reading the checkout

`get_checkout` re-reads the open checkout without changing anything. Use it to get a fresh `review_hash` and `totals` after a `review_changed` error.

## Cancelling

`cancel_checkout` leaves checkout without placing. Returns `status: "canceled"`. The cart stays open — you can modify it and start checkout again.

## Test keys

With a test key (`am_test_`), `complete_checkout` runs the full flow — reads the review, verifies the hash — but does not submit to the merchant. The order is stored with `test: true` and `permalink_url` is empty. No fee is charged.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.