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

# Checkout Sessions

> Create, update, complete, and cancel ACP checkout sessions

<Note>
  All paid endpoints on this page accept optional `memo` (≤ 1000 chars) and
  `decisionContext` (object) body fields. Stored on the receipt for debugging
  and audit — see [Audit Trail](/sdk/audit-context).
</Note>

## Session Lifecycle

```
                    ┌──────────────────┐
                    │ ready_for_payment │
                    └──────┬───────┬───┘
                           │       │
                  complete │       │ cancel
                           ▼       ▼
                    ┌──────────┐ ┌──────────┐
                    │ completed│ │ canceled  │
                    └──────────┘ └──────────┘
```

Both `completed` and `canceled` are **terminal states** — no further updates, completions, or cancellations are allowed.

Sessions expire after **30 minutes**. Expired sessions cannot be completed or updated.

***

## Create Session

<ParamField body="POST" path="/acp/checkout_sessions" />

Creates a new checkout session for a product.

### Request

```bash theme={null}
curl -X POST https://win.oneshotagent.com/acp/checkout_sessions \
  -H "Authorization: Bearer $ACP_TOKEN" \
  -H "API-Version: 2026-01-30" \
  -H "Content-Type: application/json" \
  -d '{
    "line_items": [{
      "item": {
        "id": "oneshot-research",
        "metadata": {
          "topic": "AI agent protocols 2026"
        }
      }
    }],
    "buyer": {
      "email": "agent@example.com",
      "name": "My Agent"
    },
    "idempotency_key": "unique-key-123"
  }'
```

### Parameters

| Field                        | Type   | Required | Description                                            |
| ---------------------------- | ------ | -------- | ------------------------------------------------------ |
| `line_items`                 | array  | Yes      | Products to purchase (currently supports one item)     |
| `line_items[].item.id`       | string | Yes      | Product ID from the manifest                           |
| `line_items[].item.metadata` | object | Yes      | Input parameters matching the product's `input_schema` |
| `buyer.email`                | string | No       | Buyer's email address                                  |
| `buyer.name`                 | string | No       | Buyer's display name                                   |
| `idempotency_key`            | string | No       | Prevents duplicate session creation                    |

### Response (201)

```json theme={null}
{
  "id": "f47ac10b-58cc-4372-a567-0e02b2c3d479",
  "status": "ready_for_payment",
  "line_items": [{
    "item": {
      "id": "oneshot-research",
      "metadata": { "topic": "AI agent protocols 2026" }
    },
    "amount": {
      "unit_amount": 10,
      "currency": "usd"
    }
  }],
  "buyer": {
    "email": "agent@example.com",
    "name": "My Agent"
  },
  "fulfillment": { "type": "digital" },
  "payment_handlers": [{
    "id": "stripe_spt",
    "type": "shared_payment_token",
    "provider": "stripe"
  }],
  "created_at": "2026-03-15T10:00:00.000Z",
  "expires_at": "2026-03-15T10:30:00.000Z"
}
```

<Tip>Use `idempotency_key` to safely retry session creation. If a session with the same key already exists, it returns the existing session (200) instead of creating a new one (201).</Tip>

***

## Retrieve Session

<ParamField body="GET" path="/acp/checkout_sessions/:id" />

Returns the current state of a checkout session.

```bash theme={null}
curl https://win.oneshotagent.com/acp/checkout_sessions/{session_id} \
  -H "Authorization: Bearer $ACP_TOKEN" \
  -H "API-Version: 2026-01-30"
```

For completed sessions, the response includes an `order` object:

```json theme={null}
{
  "id": "f47ac10b-...",
  "status": "completed",
  "order": {
    "id": "ord_f47ac10b",
    "status": "processing",
    "permalink_url": "https://win.oneshotagent.com/v1/requests/..."
  }
}
```

***

## Update Session

<ParamField body="POST" path="/acp/checkout_sessions/:id" />

Updates buyer info, input parameters, or switches product. Only allowed when status is `ready_for_payment`.

```bash theme={null}
curl -X POST https://win.oneshotagent.com/acp/checkout_sessions/{session_id} \
  -H "Authorization: Bearer $ACP_TOKEN" \
  -H "API-Version: 2026-01-30" \
  -H "Content-Type: application/json" \
  -d '{
    "buyer": { "email": "updated@agent.com" },
    "line_items": [{
      "item": {
        "id": "oneshot-email",
        "metadata": {
          "from_address": "me@mydomain.com",
          "to_address": "contact@acme.com",
          "subject": "Hello",
          "body": "Hi there"
        }
      }
    }]
  }'
```

You can update any combination of `buyer` and `line_items`. Switching the `item.id` to a different product updates pricing automatically.

***

## Complete Session

<ParamField body="POST" path="/acp/checkout_sessions/:id/complete" />

Submits payment and triggers tool execution. Requires a Stripe SharedPaymentToken.

```bash theme={null}
curl -X POST https://win.oneshotagent.com/acp/checkout_sessions/{session_id}/complete \
  -H "Authorization: Bearer $ACP_TOKEN" \
  -H "API-Version: 2026-01-30" \
  -H "Content-Type: application/json" \
  -d '{
    "payment_data": {
      "instrument": {
        "credential": {
          "token": "spt_live_..."
        }
      }
    }
  }'
```

### Response (200)

```json theme={null}
{
  "id": "f47ac10b-...",
  "status": "completed",
  "order": {
    "id": "ord_f47ac10b",
    "status": "processing",
    "request_id": "job_01HX...",
    "permalink_url": "https://win.oneshotagent.com/v1/requests/job_01HX..."
  }
}
```

Use `request_id` to poll job status via `GET /v1/requests/{request_id}`.

### Error Responses

| Status | Reason                                   |
| ------ | ---------------------------------------- |
| 400    | Session not in `ready_for_payment` state |
| 400    | Missing SharedPaymentToken               |
| 400    | Session expired                          |
| 402    | Stripe payment failed                    |
| 404    | Session not found                        |

***

## Cancel Session

<ParamField body="POST" path="/acp/checkout_sessions/:id/cancel" />

Cancels a session. Only allowed when status is `ready_for_payment` or `not_ready_for_payment`.

```bash theme={null}
curl -X POST https://win.oneshotagent.com/acp/checkout_sessions/{session_id}/cancel \
  -H "Authorization: Bearer $ACP_TOKEN" \
  -H "API-Version: 2026-01-30"
```

### Response (200)

```json theme={null}
{
  "id": "f47ac10b-...",
  "status": "canceled"
}
```