Actualizar un checkout o modificar sus items | Documentación API de Recurrente

curl -X PATCH https://app.recurrente.com/api/checkouts/id \
     -H "X-SECRET-KEY: <apiKey>" \
     -H "Content-Type: application/json" \
     -d '{
  "items": [
    {
      "id": "it_eyJfcmFpbHMiOnsibWVzc2FnZSI6IkJBaHBBQT09IiwiZXhwIjpudWxsLCJwdXIiOiJjaGVja291dF9pdGVtIn19",
      "quantity": 3,
      "metadata": {
        "size": "L"
      }
    }
  ]
}'

{
  "id": "ch_lmgbvesmihkqzma3",
  "status": "paid",
  "items": [
    {
      "id": "it_eyJfcmFpbHMiOnsibWVzc2FnZSI6IkJBaHBBQT09IiwiZXhwIjpudWxsLCJwdXIiOiJjaGVja291dF9pdGVtIn19",
      "price_id": "price_rky4dog7",
      "quantity": 2,
      "metadata": {}
    }
  ],
  "total_in_cents": 3000,
  "subtotal_in_cents": 3500,
  "discount": {
    "amount_in_cents": 500,
    "coupon": {
      "id": "coup_ugwoxcp4",
      "name": "VERANO25",
      "discount_mode": "code",
      "display_name": "string",
      "amount_off_in_cents": 1500,
      "percent_off": 1.1,
      "automatically_applies": false,
      "max_redemptions": 1,
      "times_redeemed": 0,
      "currency": "GTQ",
      "duration": "once",
      "expires_at": "2024-01-15T09:30:00Z",
      "status": "active"
    }
  },
  "currency": "GTQ",
  "payment_method_types": [
    "card",
    "bank_transfer"
  ],
  "available_installments": [
    3,
    6
  ],
  "live_mode": true,
  "success_url": "string",
  "cancel_url": "string",
  "expires_at": "2024-01-15T09:30:00Z",
  "created_at": "2024-01-15T09:30:00Z",
  "metadata": {},
  "custom_fields": [
    {
      "field_id": "ccf_xxxxxxxxxxxx",
      "key": "engraving",
      "type": "text",
      "value": "string"
    }
  ],
  "transfer_setups": [
    {
      "id": "tr_4a7b9c8d",
      "status": "pending",
      "amount_in_cents": 1,
      "amount_percent": 1.1,
      "currency": "string",
      "recipient_id": "ac_123456",
      "purpose": "fund_split"
    }
  ],
  "latest_intent": {
    "id": "string",
    "type": "string",
    "created_at": "2024-01-15T09:30:00Z",
    "data": {
      "auth_code": "string"
    }
  },
  "payment": {
    "id": "string",
    "paymentable": {
      "type": "Subscription",
      "id": "string",
      "tax_name": "string",
      "tax_id": "string",
      "address": {
        "address_line_1": "string",
        "address_line_2": "string",
        "city": "string",
        "region": "string",
        "country": "string",
        "zip_code": "string"
      },
      "phone_number": "string"
    }
  },
  "payment_method": {
    "id": "string",
    "type": "card",
    "card": {
      "last4": "4242",
      "expiration_month": 12,
      "expiration_year": 2028,
      "network": "visa",
      "issuer_name": "string"
    },
    "address": {
      "address_line_1": "string",
      "address_line_2": "string",
      "city": "string",
      "region": "string",
      "country": "string",
      "zip_code": "string"
    },
    "phone_number": "string"
  }
}

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

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.

Actualiza campos del checkout y agrega, modifica o elimina filas individuales sin reenviar el carrito completo. `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.

Authentication

X-SECRET-KEYstring

Tu clave secreta de API

Path parameters

idstringRequired

ID del checkout

Request

This endpoint expects an object.

success_urlstringOptionalformat: "uri"

Nueva URL de éxito

cancel_urlstringOptionalformat: "uri"

Nueva URL de cancelación

metadatamap from strings to stringsOptional

Metadata personalizada

expires_atdatetimeOptional

Nueva fecha de expiración

discount_codestringOptional

Código de descuento/cupón a aplicar al checkout

itemslist of objects or maps from strings to anyOptional

Mutaciones sparse que se aplican atómicamente al carrito existente. Un arreglo vacío no modifica los items.

Response

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

idstring

ID único del checkout

statusenum

Estado del checkout

itemslist of objects

Colección completa de filas mutables del checkout. No incluye descuentos, envío, fees ni prorrateos derivados.

total_in_centsinteger

Monto total en centavos (después de descuentos)

subtotal_in_centsinteger

Monto subtotal en centavos (antes de descuentos)

discountobject or null

Descuento aplicado al checkout (null si no hay descuento)

currencyenum

Moneda del checkout

payment_method_typeslist of enums

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_installmentslist of integers

Opciones de cuotas (en meses) disponibles en este checkout, independientes de payment_method_types. Vacío si no se ofrecen cuotas.

live_modeboolean

Si el checkout está en modo producción (true) o prueba (false)

success_urlstring

URL de redirección en caso de pago exitoso

cancel_urlstring

URL de redirección en caso de cancelación

expires_atdatetime

Fecha de expiración del checkout

created_atdatetime

Fecha de creación

metadatastring or double or boolean

Metadata personalizada del checkout

custom_fieldslist of objects

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.

transfer_setupslist of objects

Configuraciones de transferencia asociadas

latest_intentobject or null

Último payment intent asociado

paymentobject or null

Información del pago (si está pagado)

payment_methodobject or null

Método de pago utilizado

Errors

400

Bad Request Error

409

Conflict Error

422

Unprocessable Entity Error