Actualizar un checkout o modificar sus items

PATCH

https://app.recurrente.com/api/checkouts/:id

PATCH

/api/checkouts/:id

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": {},
      "variant": {
        "id": "var_9lstwgbr",
        "product_id": "prod_9lstwgbr",
        "status": "active",
        "title": "M / Rojo",
        "option_values": [
          "M",
          "Rojo"
        ],
        "sku": "string",
        "price_id": "price_3kd9sla2",
        "amount_in_cents": 12500,
        "currency": "GTQ",
        "inventory_quantity": 1,
        "low_stock_threshold": 3
      }
    }
  ],
  "bank_transfer_memo": "SCHOOLAIDORDEN1001",
  "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",
      "duration_in_payments": null,
      "minimum_amount_in_cents": null,
      "once_per_customer": false,
      "product_ids": [],
      "starts_at": "2024-01-15T09:30:00Z",
      "expires_at": "2024-01-15T09:30:00Z",
      "status": "active"
    }
  },
  "currency": "GTQ",
  "payment_method_types": [
    "card",
    "bank_transfer"
  ],
  "available_installments": [
    3,
    6
  ],
  "live_mode": true,
  "amount_set_in_browser": false,
  "clave_enabled": 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"
    }
  ],
  "application_fee_amount": 3250,
  "application_fee_percent": 10,
  "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",
      "wallet": "apple_pay"
    },
    "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.

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.

Authentication

X-SECRET-KEYstring

Tu clave secreta de API.

Una llave de cuenta (sk_live_..., sk_test_...) opera sobre su propia cuenta y, con X-ACCOUNT-ID, sobre sus cuentas conectadas.

La llave también fija el ambiente: una sk_test_ solo lista y resuelve objetos de prueba (live_mode: false) y una sk_live_ solo objetos reales. Un ID del otro ambiente responde 404 (401 en /customers).

Una llave de organización (sk_org_live_..., sk_org_test_...) alcanza todas las cuentas de una organización y solo sirve para leer: saldos, movimientos y reportes. Para operar sobre una cuenta debe nombrarla con X-ACCOUNT-ID; omitirlo en una lectura devuelve todas las cuentas de la organización. Cualquier otro endpoint responde 403 con code: organization_key_unsupported.

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

Allowed values:

itemslist of objects

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

bank_transfer_memostring or nullOptional

Referencia normalizada propuesta por la integración. Es null cuando Recurrente generará la referencia al iniciar el pago por transferencia.

total_in_centsintegerOptional

Monto total en centavos (después de descuentos)

subtotal_in_centsintegerOptional

Monto subtotal en centavos (antes de descuentos)

discountobject or nullOptional

Descuento aplicado al checkout (null si no hay descuento)

currencyenumOptional

Moneda del checkout

Allowed values:

payment_method_typeslist of enumsOptional

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), akisi (efectivo en Akisí; solo cuentas habilitadas, cobros únicos en GTQ con precio fijo y cuentas fuera de Sandbox). 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.

Allowed values:

available_installmentslist of integersOptional

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

live_modebooleanOptional

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

amount_set_in_browserbooleanOptional

El monto lo fijó el navegador del comprador. Solo en checkouts creados por el botón de Clave en el sitio del comercio, con ítems con monto inline y sin firma del servidor. Compáralo con tu pedido antes de entregar.

clave_enabledbooleanOptional

Si el checkout ofrece Clave (tarjetas guardadas del comprador). false cuando se creó con clave_enabled en false.

success_urlstringOptional

URL de redirección en caso de pago exitoso

cancel_urlstringOptional

URL de redirección en caso de cancelación

expires_atdatetimeOptional

Fecha de expiración del checkout

created_atdatetimeOptional

Fecha de creación

metadatastring or double or booleanOptional

Metadata personalizada del checkout

custom_fieldslist of objectsOptional

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 objectsOptional

Configuraciones de transferencia asociadas

application_fee_amountinteger or nullOptional

Comisión de plataforma en centavos (pagos únicos): la suma de las transferencias de comisión del checkout. null cuando no hay comisión.

application_fee_percentdouble or nullOptional

Comisión de plataforma como porcentaje del total de cada factura (suscripciones). null cuando no hay comisión.

latest_intentobject or nullOptional

Último intent unificado asociado. Su id usa el prefijo in_….

paymentobject or nullOptional

Información del pago (si está pagado)

payment_methodobject or nullOptional

Método de pago utilizado

Errors

400

Bad Request Error

409

Conflict Error

422

Unprocessable Entity Error

Authentication

Path parameters

Headers

Request

Response

Errors