Checkouts

Crear un checkoutCopiar enlace

curl https://api.billete.run/v1/checkouts \
  -H "Authorization: Bearer $BILLETE_API_KEY" \
  -H "Billete-Version: 2026-10-24" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: checkout-order-123" \
  -d '{
    "items": [{"product": "prod_ejemplo", "quantity": 1}],
    "customer": {"email": "cliente@example.com"},
    "successUrl": "https://example.com/gracias?checkout={CHECKOUT_ID}",
    "cancelUrl": "https://example.com/carrito"
  }'

Usa items para productos o plan y months para una suscripción. Redirige a url en la respuesta. {CHECKOUT_ID} se sustituye por el identificador creado.

En planes por puesto, si no envías quantity el cliente elige los puestos en el checkout alojado, entre el mínimo y el máximo del plan (empieza en el mínimo). Con quantity los puestos quedan fijos; añade adjustableQuantity: true para que empiece en esa cantidad y el cliente pueda cambiarla, o adjustableQuantity: false sin quantity para vender el mínimo fijo. adjustableQuantity: true en un plan que no se cobra por puesto es quantity_not_adjustable. El cliente solo cambia los puestos: el ciclo y el precio son los del checkout.

El subtotal es precio unitario por cantidad y los cupones se aplican sobre las líneas que cubren; en una prueba gratis el total es 0 (el cupón se guarda para el primer pago) y la suscripción empieza con los puestos elegidos. En planes de puestos incluidos solo se admite cantidad 1. Cuando se paga, la suscripción guarda los puestos en quantity (el items[0].quantity del checkout completado).

Un checkout de plan crea una suscripción nueva, y un cliente no puede tener dos en curso al mismo plan: si el cliente ya tiene una (trialing, active, past_due o suspended), crear el checkout con customer responde 409 subscription_exists, y pagarlo también, antes de cobrar, cuando el cliente se conoce al pagar por su correo (como en un enlace de pago). En el caso raro de que dos checkouts del mismo plan se paguen a la vez, el que se confirma después queda completed sin subscriptionId: Billete no crea la segunda suscripción, solicita el reembolso completo de ese pago y avisa al negocio. Para cambiar el plan, el ciclo o los puestos de una existente usa POST /v1/subscriptions/:subscription/changes: cuando hay algo que pagar devuelve un checkout con purpose: "subscription_change" y su cotización en subscriptionChange (kind, from, to, creditApplied, unusedCredit, importes y outcome). Ese checkout se paga igual que cualquier otro, pero no admite cambiar la cantidad; un cupón solo si el cambio lo permite (cambios con cupón).

ConfirmaciónCopiar enlace

En un checkout de cambio, completed solo significa que el pago se confirmó. Revisa subscriptionChange.outcome: applied aplicó el cambio; rejected significa que las condiciones de la suscripción cambiaron antes de confirmarse el pago, así que la suscripción no cambió y Billete solicitó el reembolso de ese pago (también emite subscription.change_failed).

Para una URL reutilizable, crea un enlace de pago.