---
title: "Manage Checkout Lifecycle"
method: PATCH
path: "/checkouts/{checkout_code}"
---

# Manage Checkout Lifecycle

`PATCH /checkouts/{checkout_code}`

Renames, publishes, unpublishes, archives, restores, or promotes the checkout. The body carries any combination of `name`, `description`, `status`, and `is_default` — at least one field is required (an empty body is rejected with 400). Status transitions follow the lifecycle state machine: publish (`PUBLISHED`) is only valid from `NOT_PUBLISHED`; an ARCHIVED checkout is restored in two steps (`status: NOT_PUBLISHED` first, then `status: PUBLISHED`); patching to the current status is rejected. Metadata (`name`/`description`) remains editable while ARCHIVED. `is_default` accepts only `true`: it promotes the checkout to account default, force-publishing it from any state, and atomically demotes the previous default; when `is_default: true` is sent together with `status`, the promotion wins and `status` is ignored. The default checkout cannot be archived or unpublished.

## Path parameters

- `checkout_code` string, required

## Headers

- `X-Idempotency-Key` string

## Request body

- object
  - `name` string — New checkout name. Unique per account (a duplicate name is rejected with 409). Editable in any status, including ARCHIVED.
  - `description` string — New checkout description. Editable in any status, including ARCHIVED.
  - `status` 'PUBLISHED' | 'NOT_PUBLISHED' | 'ARCHIVED' — Target lifecycle status. PUBLISHED is only reachable from NOT_PUBLISHED; NOT_PUBLISHED is reachable from PUBLISHED (unpublish) or ARCHIVED (restore); ARCHIVED is reachable from PUBLISHED or NOT_PUBLISHED. Any other transition — including patching to the current status — is rejected with 400. Unknown values are rejected with 400.
  - `is_default` boolean — Only `true` is accepted: promotes this checkout to account default, force-publishing it from any state and atomically demoting the previous default. `false` is rejected with 400 — demote by promoting another checkout instead.

## Response `200`

The updated checkout summary. The identifier is exposed as the top-level `id`. Read the resulting `status` with the Fetch endpoint.

- CheckoutMutationResponse
  - `id` string — Checkout identifier (UUID).
  - `name` string — Checkout name.
  - `description` string — Checkout description.
  - `is_default` boolean — Whether this checkout is the account's default.
  - `is_active` boolean — Whether the checkout is active (serving traffic).
  - `created_at` string, date-time — Creation timestamp (ISO-8601).

## Other responses

- `400` — Empty body, invalid or same-status transition, unknown `status` value, `is_default: false`, a non-UUID `checkout_code`, or a malformed JSON body.
- `401` — Not authenticated, or the account is not in the beta allowlist.
- `404` — The checkout was not found for this account.
- `409` — Duplicate name, or the checkout is the account's default and cannot be archived or unpublished.

---

[API](https://skmtc.net/y/apis/ai-caller.md) · [All operations](https://skmtc.net/y/apis/ai-caller/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/y/ai-caller/versions/05b629819b49/schema)