---
title: "Actualizar un checkout o modificar sus items"
method: PATCH
path: "/checkouts/{id}"
tags: ["checkouts"]
---

# Actualizar un checkout o modificar sus items

`PATCH /checkouts/{id}`

Actualiza campos del checkout y agrega, modifica o elimina filas individuales sin reenviar el carrito completo.

El checkout debe pertenecer a la cuenta del contexto. Una plataforma que envía `X-ACCOUNT-ID` puede actualizar cualquier checkout de esa hija conectada, sin filtrar por creador.

`items` es una lista de **mutaciones sparse**. Las filas que no aparecen permanecen sin cambios:

- Para agregar, envía `price_id`, `quantity` absoluta y metadata opcional. Solo se pueden agregar precios activos del catálogo de la cuenta; no se aceptan detalles inline en este endpoint.
- Para modificar, envía el `id` de item con prefijo `it_` y una nueva `quantity` absoluta o `metadata`. La metadata reemplaza el objeto completo; `{}` la limpia.
- Para eliminar, envía el `id` de item y `deleted: true` sin otros campos.

Varias filas pueden compartir el mismo `price_id`: cada una conserva su propio `id`, cantidad y metadata. Una solicitud puede mezclar las tres operaciones y se aplica atómicamente; si cualquier mutación o validación del checkout falla, no se guarda ningún cambio. La respuesta exitosa siempre contiene el checkout completo y su colección `items` autoritativa.

Solo un checkout `unpaid` y sin un pago en proceso puede modificarse. Eliminar el último item deja el checkout abierto y vacío, pero no se puede pagar hasta agregar un item válido. Usa `Idempotency-Key` al agregar filas para que un retry de red devuelva la respuesta original sin duplicarlas.

## Path parameters

- `id` string, required

## Headers

- `X-SECRET-KEY` string, required
- `Idempotency-Key` string

## Request body

- object
  - `success_url` string, uri — Nueva URL de éxito
  - `cancel_url` string, uri — Nueva URL de cancelación
  - `metadata` object — Metadata personalizada
  - `expires_at` string, date-time — Nueva fecha de expiración
  - `discount_code` string — Código de descuento/cupón a aplicar al checkout
  - `items` CheckoutItemMutation[] — Mutaciones sparse que se aplican atómicamente al carrito existente. Un arreglo vacío no modifica los items.
    - union
      - CheckoutItemAddition
        - `price_id` string, required — Precio activo del catálogo de la cuenta del checkout.
        - `quantity` integer, required — Cantidad absoluta inicial.
        - `metadata` union
          - string
          - number, double
          - boolean
      - union
        - object
        - object
      - CheckoutItemDeletion
        - `id` string, required
        - `deleted` true, required

## Response `200`

Checkout actualizado con la colección completa y autoritativa de items

- Checkout
  - `id` string, required — ID único del checkout
  - `status` 'unpaid' | 'paid' | 'payment_in_progress' | 'expired', required — Estado del checkout
  - `total_in_cents` integer — Monto total en centavos (después de descuentos)
  - `subtotal_in_cents` integer — Monto subtotal en centavos (antes de descuentos)
  - `discount` CheckoutDiscount — Descuento aplicado al checkout (null si no hay descuento)
    - `amount_in_cents` integer — Monto del descuento en centavos
    - `coupon` Coupon
      - `id` string — ID único del cupón
      - `name` string — Nombre o código del cupón
      - `discount_mode` 'code' | 'bank' | 'custom_bins' — Tipo de descuento
      - `display_name` string, nullable — Nombre visible para el cliente (usado en modo custom_bins)
      - `amount_off_in_cents` integer, nullable — Descuento fijo en centavos
      - `percent_off` number, double, nullable — Porcentaje de descuento
      - `automatically_applies` boolean — Si el descuento se aplica automáticamente en checkouts de tienda
      - `max_redemptions` integer, nullable — Número máximo de usos
      - `times_redeemed` integer — Número de veces que se ha redimido el descuento
      - `currency` string, nullable — Moneda del descuento fijo
      - `duration` 'once' | 'forever' — Duración del descuento para suscripciones
      - `expires_at` string, date-time, nullable — Fecha de expiración
      - `status` string — Estado del cupón
  - `currency` 'GTQ' | 'USD' — Moneda del checkout
  - `payment_method_types` CheckoutPaymentMethodTypesItems[] — Métodos de pago que se le ofrecerán al comprador en este checkout, ya resueltos según la configuración del producto/cuenta, la moneda y el tipo de cobro: `card` (tarjeta, pago de contado), `bank_transfer` (transferencia bancaria), `stablecoins` (dólares digitales), `balance` (Balance Recurrente). Las cuotas se exponen por separado en `available_installments`; `card` indica pago de contado, así que un checkout puede ofrecer cuotas (`available_installments` no vacío) sin incluir `card`.
  - `available_installments` integer[] — Opciones de cuotas (en meses) disponibles en este checkout, independientes de `payment_method_types`. Vacío si no se ofrecen cuotas.
  - `live_mode` boolean — Si el checkout está en modo producción (true) o prueba (false)
  - `success_url` string — URL de redirección en caso de pago exitoso
  - `cancel_url` string — URL de redirección en caso de cancelación
  - `expires_at` string, date-time — Fecha de expiración del checkout
  - `created_at` string, date-time — Fecha de creación
  - `metadata` union
    - string
    - number, double
    - boolean
  - `items` CheckoutItem[], required — Colección completa de filas mutables del checkout. No incluye descuentos, envío, fees ni prorrateos derivados.
    - `id` string, required — ID estable de esta fila del checkout. Úsalo para modificarla o eliminarla.
    - `price_id` string, required — ID del precio asociado. Puede repetirse en varias filas.
    - `quantity` integer, required — Cantidad absoluta de esta fila.
    - `metadata` union, required
      - string
      - number, double
      - boolean
  - `custom_fields` CheckoutCustomFieldValue[] — Valores recolectados de los campos personalizados. Si el checkout tiene múltiples productos, cada producto contribuye sus propias entradas — la `key` puede repetirse entre productos. Usa `field_id` como identificador canónico al reconciliar valores.
    - `field_id` string — Identificador canónico del campo (estable y único por producto). Úsalo para reconciliar valores; en checkouts con múltiples productos, dos entradas pueden tener la misma `key` pero distinto `field_id`.
    - `key` string — Identificador legible definido por el comerciante. Puede repetirse entre productos en el mismo checkout.
    - `type` 'text' | 'numeric' | 'dropdown'
    - `value` string
  - `transfer_setups` TransferSetup[] — Configuraciones de transferencia asociadas
    - `id` string — ID de la configuración de transferencia
    - `status` 'pending' | 'completed' | 'cancelled' | 'reversed' — En pagos únicos: `pending` mientras el cobro no se completa y `completed` cuando la transferencia se ejecutó. En suscripciones la configuración queda `pending` mientras la suscripción está activa. `cancelled` si el checkout, la suscripción o un reembolso canceló el setup antes de ejecutarlo; `reversed` si un reembolso devolvió una transferencia ya completada.
    - `amount_in_cents` integer, nullable — Monto fijo en centavos a transferir (pagos únicos). No puede exceder el monto neto disponible después de fees, FEL e IVA.
    - `amount_percent` number, double, nullable — Porcentaje del total de cada factura a transferir (suscripciones).
    - `currency` string — Moneda
    - `recipient_id` string — ID de la cuenta de Recurrente que recibe los fondos (no es una cuenta bancaria).
    - `purpose` 'fund_split' | 'platform_commission' — Semántica comercial de la transferencia. Usa `platform_commission` únicamente cuando el checkout pertenece a una cuenta conectada y los fondos regresan a su plataforma; ese valor habilita la reconciliación y facturación diaria de la comisión.
  - `latest_intent` CheckoutLatestIntent — Último intent unificado asociado. Su `id` usa el prefijo `in_…`.
    - `id` string
    - `type` string
    - `created_at` string, date-time
    - `data` CheckoutLatestIntentData
      - `auth_code` string, nullable
  - `payment` CheckoutPayment — Información del pago (si está pagado)
    - `id` string — ID del pago
    - `paymentable` CheckoutPaymentPaymentable
      - `type` string — Tipo de elemento pagable
      - `id` string — ID del elemento pagable
      - `tax_name` string, nullable — Nombre fiscal del comprador
      - `tax_id` string, nullable — ID fiscal del comprador
      - `address` Address
        - `address_line_1` string, nullable — Línea de dirección 1
        - `address_line_2` string, nullable — Línea de dirección 2
        - `city` string, nullable — Ciudad
        - `region` string, nullable — Región o departamento
        - `country` string, nullable — País
        - `zip_code` string, nullable — Código postal
      - `phone_number` string, nullable — Número de teléfono del comprador
  - `payment_method` CheckoutPaymentMethod — Método de pago utilizado
    - `id` string — ID del método de pago
    - `type` string — Tipo de método de pago
    - `card` CheckoutPaymentMethodCard
      - `last4` string — Últimos 4 dígitos de la tarjeta
      - `expiration_month` integer — Mes de expiración
      - `expiration_year` integer — Año de expiración
      - `network` string — Red de la tarjeta
      - `issuer_name` string, nullable — Nombre del banco emisor
    - `address` Address
      - `address_line_1` string, nullable — Línea de dirección 1
      - `address_line_2` string, nullable — Línea de dirección 2
      - `city` string, nullable — Ciudad
      - `region` string, nullable — Región o departamento
      - `country` string, nullable — País
      - `zip_code` string, nullable — Código postal
    - `phone_number` string, nullable — Número de teléfono asociado al método de pago

## Other responses

- `400` — Una mutación, metadata o el checkout resultante es inválido; no se guardó ningún cambio
- `409` — La clave de idempotencia está en uso o fue reutilizada con otro payload
- `422` — El checkout tiene un pago en proceso, ya fue pagado o no está en un estado editable

---

[API](https://skmtc.dev/recurrente/apis/referencia-api.md) · [All operations](https://skmtc.dev/recurrente/apis/referencia-api/llms.txt) · [OpenAPI document](https://skmtc-service-production.skmtc.workers.dev/v1/apis/recurrente/referencia-api/revisions/f494a078482c/schema)