Saltar al contenido principal

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​

Todas las solicitudes usan tu llave secreta.

Cómo funciona​

  1. Creás la programación con sus etapas, o a partir de un cargo recurrente que ya existe.
  2. 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.
  3. 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.
  4. Cuando termina la última etapa, ONVO aplica endBehavior: release deja el cargo recurrente activo y cobrando por su cuenta, y cancel lo 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​

EstadoQué significa
not_startedLa programación existe, pero todavía no inicia su primera etapa.
activatingONVO está creando el cargo recurrente de la primera etapa. Es un estado de paso.
activeLa programación tiene un cargo recurrente y lo lleva por sus etapas.
completedTerminó la última etapa y ONVO aplicó endBehavior.
releasedLiberaste la programación. El cargo recurrente sigue por su cuenta.
canceledCancelaste la programación.
errorONVO 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 409 con subscription_schedules.version_conflict y no se aplica nada. Volvé a obtener la programación, revisá su estado actual y reintentá con el version nuevo.

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:

  • phases reemplaza a las etapas que todavía no inician. Las etapas ya iniciadas, incluida la vigente, se conservan. En una programación not_started reemplaza todas las etapas.
  • endBehavior, defaultCollectionMethod, defaultPaymentMethodId y defaultDescription cambian solo si los enviás.
  • metadata reemplaza 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é pasaLa programaciónEl cargo recurrente
La liberás con POST /v1/subscription-schedules/{id}/releaseQueda 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}/cancelQueda 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 endDate o iterations. No enviés los dos en la misma etapa.
  • Cada etapa debe iniciar exactamente cuando termina la anterior.
  • iterations acepta valores entre 1 y 120.
  • Cada ítem lleva priceId o priceData, no ambos. priceData crea 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.
  • quantity acepta valores entre 1 y 999. Si no la enviás, vale 1.
  • trialEnd debe caer dentro de su etapa y a no más de 365 días del startDate.
  • Los métodos de pago deben pertenecer al cliente de la programación.
  • prorationBehavior decide 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, y create_prorations cobra 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ódigoQué significa
subscription_schedules.not_found404. No existe una programación con ese ID en la cuenta y el modo de la llave.
subscription_schedules.customer_not_found404. No existe un cliente con ese ID.
subscription_schedules.subscription_not_found404. No existe un cargo recurrente con el ID de fromSubscription.
subscription_schedules.version_conflict409. La programación cambió desde que la leíste. Obtenela de nuevo y reintentá.
subscription_schedules.from_subscription_exclusiveEnviaste fromSubscription junto con otro parámetro.
subscription_schedules.subscription_not_activeEl cargo recurrente de fromSubscription no está en active ni en trialing.
subscription_schedules.subscription_pending_cancellationEl cargo recurrente de fromSubscription tiene una cancelación pendiente.
subscription_schedules.active_schedule_existsEl cargo recurrente ya tiene una programación en not_started, activating o active.
subscription_schedules.subscription_has_no_itemsEl cargo recurrente no tiene ítems activos.
subscription_schedules.phases_requiredFalta phases.
subscription_schedules.start_date_mismatchEl startDate de la programación no coincide con el de la primera etapa.
subscription_schedules.cancel_requires_phase_endendBehavior: "cancel" requiere que la última etapa tenga endDate o iterations.
subscription_schedules.phase_requires_endUna etapa que no es la última no tiene endDate ni iterations.
subscription_schedules.invalid_phase_datesEl endDate de una etapa no es posterior a su startDate.
subscription_schedules.phases_not_sequentialUna etapa inicia antes de que termine la anterior.
subscription_schedules.phases_not_contiguousUna etapa no inicia exactamente cuando termina la anterior.
subscription_schedules.trial_end_outside_phasetrialEnd cae fuera de su etapa.
subscription_schedules.trial_too_longEl período de prueba supera los 365 días.
subscription_schedules.price_not_foundNo existe un precio con ese priceId.
subscription_schedules.product_not_foundNo existe un producto con el productId de priceData.
subscription_schedules.non_recurring_priceUn ítem usa un precio que no es recurrente.
subscription_schedules.mixed_currenciesLos ítems de una etapa usan monedas distintas.
subscription_schedules.mixed_intervalsLos ítems de una etapa usan intervalos distintos.
subscription_schedules.mixed_phase_currenciesLas etapas usan monedas distintas.
subscription_schedules.invalid_intervalEl precio de una etapa con iterations tiene un intervalo que no es válido.
subscription_schedules.payment_method_not_foundEl método de pago no existe o no pertenece al cliente de la programación.
subscription_schedules.invalid_paginationEnviaste startingAfter y endingBefore en la misma solicitud.
subscription_schedules.invalid_status_for_updateLa programación no está en not_started ni en active.
subscription_schedules.invalid_status_for_cancelLa programación no está en not_started ni en active.
subscription_schedules.not_active_for_releaseLa 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 id de la programación junto al cargo recurrente en tu sistema.
  • Obtené la programación antes de actualizarla y enviá su version en expectedVersion.
  • Enviá Idempotency-Key al crear programaciones desde procesos que reintentan.
  • Escuchá subscription_schedule.transition_failed para detectar programaciones en error.