Programaciones de cargos recurrentes
Una programación define por adelantado cómo cambia un cargo recurrente con el tiempo. Está formada por etapas: cada etapa tiene una fecha de inicio y los precios y cantidades que cobra, y puede tener una fecha de fin, un período de prueba y un método de pago propio. ONVO inicia cada etapa en su fecha y aplica sus ítems al cargo recurrente.
Usala, por ejemplo, para cobrar un precio de lanzamiento durante tres meses y después el precio regular, para dejar listo un cambio de plan que aplica al terminar el período actual, o para vender un plan con una cantidad fija de cobros.
Referencia API relacionada
- Crear una programación
- Listar las programaciones
- Contar las programaciones
- Obtener una programación
- Actualizar una programación
- Cancelar una programación
- Liberar una programación
- Eventos de webhooks
Todas las solicitudes usan tu llave secreta.
Cómo funciona
- Creás la programación con sus etapas, o a partir de un cargo recurrente que ya existe.
- Cuando inicia la primera etapa, ONVO crea el cargo recurrente con los ítems de esa etapa y guarda su identificador en
subscriptionId. Una programación creada a partir de un cargo recurrente existente ya lo tiene desde el inicio. - Cuando inicia cada etapa siguiente, ONVO reemplaza los ítems del cargo recurrente por los de la etapa y crea la renovación del primer período de esa etapa.
- Cuando termina la última etapa, ONVO aplica
endBehavior:releasedeja el cargo recurrente activo y cobrando por su cuenta, ycancello cancela.
ONVO inicia las etapas en una revisión que corre cada tres horas, así que una etapa puede iniciar hasta unas tres horas después de su startDate. Los períodos de cobro se cuentan desde el startDate de la etapa, no desde el momento de la revisión.
Las etapas se numeran desde 0. lastTransitionedPhaseIndex indica la etapa vigente y vale -1 mientras no haya iniciado ninguna.
Estados
| Estado | Qué significa |
|---|---|
not_started | La programación existe, pero todavía no inicia su primera etapa. |
activating | ONVO está creando el cargo recurrente de la primera etapa. Es un estado de paso. |
active | La programación tiene un cargo recurrente y lo lleva por sus etapas. |
completed | Terminó la última etapa y ONVO aplicó endBehavior. |
released | Liberaste la programación. El cargo recurrente sigue por su cuenta. |
canceled | Cancelaste la programación. |
error | ONVO no pudo iniciar una etapa después de cinco intentos. |
Solo podés actualizar, cancelar o liberar una programación en not_started o active.
Crear una programación con etapas
Enviá customerId y phases. Este ejemplo cobra un precio de lanzamiento durante tres períodos y después el precio regular, sin fecha de fin:
curl https://api.onvopay.com/v1/subscription-schedules \
-X POST \
-H "Authorization: Bearer $ONVO_SECRET_KEY" \
-H "Content-Type: application/json" \
-H "Idempotency-Key: $UNIQUE_KEY" \
-d '{
"customerId": "$CUSTOMER_ID",
"defaultPaymentMethodId": "$PAYMENT_METHOD_ID",
"defaultDescription": "Plan Pro",
"endBehavior": "release",
"phases": [
{
"startDate": "2027-01-01T00:00:00.000Z",
"iterations": 3,
"items": [
{ "priceId": "$LAUNCH_PRICE_ID", "quantity": 1 }
]
},
{
"startDate": "2027-04-01T00:00:00.000Z",
"items": [
{ "priceId": "$REGULAR_PRICE_ID", "quantity": 1 }
]
}
]
}'
La programación nace en not_started, con version en 0 y subscriptionId en null. Cuando llega el startDate de la primera etapa, ONVO crea el cargo recurrente, pasa la programación a active y envía subscription_schedule.activated. Si ese startDate ya pasó cuando creás la programación, ONVO la activa sin esperar la siguiente revisión.
Enviá un método de pago del cliente en defaultPaymentMethodId o en el paymentMethodId de la primera etapa. Sin un método de pago la programación no puede activarse y, después de cinco intentos, queda en error.
Con iterations, ONVO calcula el endDate de la etapa a partir del intervalo del precio de su primer ítem. En el ejemplo, tres períodos de un precio mensual que inicia el 1 de enero terminan el 1 de abril, que es justo cuando debe iniciar la etapa siguiente.
Crear una programación desde un cargo recurrente existente
Enviá solo fromSubscription, sin ningún otro parámetro:
curl https://api.onvopay.com/v1/subscription-schedules \
-X POST \
-H "Authorization: Bearer $ONVO_SECRET_KEY" \
-H "Content-Type: application/json" \
-d '{
"fromSubscription": "$SUBSCRIPTION_ID"
}'
El cargo recurrente debe estar en active o trialing, tener al menos un ítem activo, no tener una cancelación pendiente y no tener otra programación en not_started, activating o active.
La programación nace active, con endBehavior en release y una sola etapa que cubre el período actual del cargo recurrente con sus ítems actuales. Toma del cargo recurrente el método de cobro, el método de pago, la descripción y los metadatos. Como nace activa, envía subscription_schedule.created y no subscription_schedule.activated.
Después agregá las etapas que siguen con una actualización. La primera etapa nueva debe iniciar exactamente en el endDate de la etapa vigente:
curl https://api.onvopay.com/v1/subscription-schedules/$SCHEDULE_ID \
-X POST \
-H "Authorization: Bearer $ONVO_SECRET_KEY" \
-H "Content-Type: application/json" \
-d '{
"expectedVersion": 0,
"phases": [
{
"startDate": "$CURRENT_PHASE_END_DATE",
"items": [
{ "priceId": "$NEW_PRICE_ID", "quantity": 1 }
]
}
]
}'
Actualizar una programación
Cada programación tiene un version que empieza en 0 y aumenta en uno con cada actualización y con cada cambio de etapa. Al actualizar, enviá en expectedVersion el version que leíste:
- Si coincide, ONVO aplica el cambio y aumenta
version. - Si la programación cambió desde que la leíste, la respuesta es
409consubscription_schedules.version_conflicty no se aplica nada. Volvé a obtener la programación, revisá su estado actual y reintentá con elversionnuevo.
Así, dos solicitudes simultáneas o un cambio de etapa que ocurre mientras editás no se pisan entre sí. Como un cambio de etapa también aumenta version, obtené la programación justo antes de actualizarla.
Qué podés cambiar:
phasesreemplaza a las etapas que todavía no inician. Las etapas ya iniciadas, incluida la vigente, se conservan. En una programaciónnot_startedreemplaza todas las etapas.endBehavior,defaultCollectionMethod,defaultPaymentMethodIdydefaultDescriptioncambian solo si los enviás.metadatareemplaza todos los metadatos anteriores.
Si la programación ya tiene un cargo recurrente, los cambios en defaultDescription, defaultCollectionMethod, defaultPaymentMethodId y metadata también se aplican a ese cargo recurrente.
Liberar o cancelar
| Qué pasa | La programación | El cargo recurrente |
|---|---|---|
La liberás con POST /v1/subscription-schedules/{id}/release | Queda en released y con subscriptionId en null. | Sigue activo y cobra sus ítems actuales por su cuenta. |
La cancelás con POST /v1/subscription-schedules/{id}/cancel | Queda en canceled. | Si la programación estaba active, se cancela y sus renovaciones en estado open se anulan. |
Termina la última etapa con endBehavior: "release" | Queda en completed y con subscriptionId en null. | Sigue activo y cobra los ítems de la última etapa por su cuenta. |
Termina la última etapa con endBehavior: "cancel" | Queda en completed y conserva subscriptionId. | Se cancela y sus renovaciones en estado open se anulan. |
Liberar o cancelar una programación not_started la termina sin crear un cargo recurrente.
Si la última etapa no tiene endDate ni iterations, la programación sigue active hasta que la liberés o la cancelés. Por eso endBehavior: "cancel" requiere, al crear la programación, que la última etapa tenga endDate o iterations.
Reglas de las etapas
- Enviá entre 1 y 10 etapas por solicitud, y entre 1 y 10 ítems por etapa.
- Cada etapa excepto la última debe tener
endDateoiterations. No enviés los dos en la misma etapa. - Cada etapa debe iniciar exactamente cuando termina la anterior.
iterationsacepta valores entre 1 y 120.- Cada ítem lleva
priceIdopriceData, no ambos.priceDatacrea un precio recurrente nuevo para un producto existente. - Los precios deben ser recurrentes. Los ítems de una etapa deben compartir moneda e intervalo, y todas las etapas deben usar la misma moneda.
quantityacepta valores entre 1 y 999. Si no la enviás, vale 1.trialEnddebe caer dentro de su etapa y a no más de 365 días delstartDate.- Los métodos de pago deben pertenecer al cliente de la programación.
prorationBehaviordecide cómo se cobra un período que la etapa corta antes de completar el intervalo del precio:none, el valor por defecto, cobra el intervalo completo, ycreate_prorationscobra la parte proporcional.
Reintentar la creación sin duplicar
Enviá el encabezado Idempotency-Key con un valor único al crear una programación. Si repetís la solicitud con la misma llave, ONVO retorna la respuesta de la primera en lugar de crear otra programación. ONVO conserva cada llave al menos 24 horas.
Mientras la primera solicitud sigue en curso, una repetición con la misma llave responde 409. Si la primera solicitud falló, podés reintentar con la misma llave.
Errores
Los errores de la API de programaciones usan códigos subscription_schedules.*. Responden 400, excepto donde se indica.
Un cuerpo que no tiene el formato esperado también responde 400, pero sin código: message trae la lista de mensajes de validación. Pasa, por ejemplo, con un parámetro que la API no reconoce, con más de 10 etapas, con endDate e iterations en la misma etapa, o con un ítem que lleva priceId y priceData a la vez o ninguno de los dos.
| Código | Qué significa |
|---|---|
subscription_schedules.not_found | 404. No existe una programación con ese ID en la cuenta y el modo de la llave. |
subscription_schedules.customer_not_found | 404. No existe un cliente con ese ID. |
subscription_schedules.subscription_not_found | 404. No existe un cargo recurrente con el ID de fromSubscription. |
subscription_schedules.version_conflict | 409. La programación cambió desde que la leíste. Obtenela de nuevo y reintentá. |
subscription_schedules.from_subscription_exclusive | Enviaste fromSubscription junto con otro parámetro. |
subscription_schedules.subscription_not_active | El cargo recurrente de fromSubscription no está en active ni en trialing. |
subscription_schedules.subscription_pending_cancellation | El cargo recurrente de fromSubscription tiene una cancelación pendiente. |
subscription_schedules.active_schedule_exists | El cargo recurrente ya tiene una programación en not_started, activating o active. |
subscription_schedules.subscription_has_no_items | El cargo recurrente no tiene ítems activos. |
subscription_schedules.phases_required | Falta phases. |
subscription_schedules.start_date_mismatch | El startDate de la programación no coincide con el de la primera etapa. |
subscription_schedules.cancel_requires_phase_end | endBehavior: "cancel" requiere que la última etapa tenga endDate o iterations. |
subscription_schedules.phase_requires_end | Una etapa que no es la última no tiene endDate ni iterations. |
subscription_schedules.invalid_phase_dates | El endDate de una etapa no es posterior a su startDate. |
subscription_schedules.phases_not_sequential | Una etapa inicia antes de que termine la anterior. |
subscription_schedules.phases_not_contiguous | Una etapa no inicia exactamente cuando termina la anterior. |
subscription_schedules.trial_end_outside_phase | trialEnd cae fuera de su etapa. |
subscription_schedules.trial_too_long | El período de prueba supera los 365 días. |
subscription_schedules.price_not_found | No existe un precio con ese priceId. |
subscription_schedules.product_not_found | No existe un producto con el productId de priceData. |
subscription_schedules.non_recurring_price | Un ítem usa un precio que no es recurrente. |
subscription_schedules.mixed_currencies | Los ítems de una etapa usan monedas distintas. |
subscription_schedules.mixed_intervals | Los ítems de una etapa usan intervalos distintos. |
subscription_schedules.mixed_phase_currencies | Las etapas usan monedas distintas. |
subscription_schedules.invalid_interval | El precio de una etapa con iterations tiene un intervalo que no es válido. |
subscription_schedules.payment_method_not_found | El método de pago no existe o no pertenece al cliente de la programación. |
subscription_schedules.invalid_pagination | Enviaste startingAfter y endingBefore en la misma solicitud. |
subscription_schedules.invalid_status_for_update | La programación no está en not_started ni en active. |
subscription_schedules.invalid_status_for_cancel | La programación no está en not_started ni en active. |
subscription_schedules.not_active_for_release | La programación no está en not_started ni en active. |
Cuando una programación queda en error
Si ONVO no puede activar la programación o iniciar una etapa, lo reintenta. Después de cinco intentos fallidos la programación pasa a error y ONVO envía subscription_schedule.transition_failed. transitionAttempts cuenta los intentos fallidos.
Una programación en error no se puede actualizar, cancelar ni liberar por API.
Webhooks
ONVO envía un evento subscription_schedule.* cuando una programación se crea, se actualiza, se activa, cambia de etapa, termina, se libera, se cancela o falla. Consultá la lista y los campos en Eventos de webhooks.
Buenas prácticas
- Guardá el
idde la programación junto al cargo recurrente en tu sistema. - Obtené la programación antes de actualizarla y enviá su
versionenexpectedVersion. - Enviá
Idempotency-Keyal crear programaciones desde procesos que reintentan. - Escuchá
subscription_schedule.transition_failedpara detectar programaciones enerror.