Saltar al contenido principal

Periodos de prueba

Las suscripciones pueden incluir un periodo de prueba durante el cual no hace falta pagar. Cuando termina la prueba, empieza el primer ciclo de facturación y se cobra al pagador (o se le envía un enlace de pago) según collection_method.

Cómo funcionan los periodos de prueba​

  • trial_period_days: se define al crear la suscripción; esta empieza en estado trialing. Durante ese número de días desde la creación no se cobra nada.
  • trial_end: marca de tiempo ISO opcional para fijar un fin de prueba explícito. También puedes poner trial_end: "now" para empezar en la práctica sin prueba.
  • Cuando termina la prueba:
    • Si collection_method es send_payment_link: se crea un enlace de pago para el primer periodo y (si está configurado) se envía un email al pagador.
    • Si collection_method es auto_charge: el pagador debe haber aprobado el allowance antes de que termine la prueba o en ese momento; si no, la suscripción puede pasar a paused hasta que lo apruebe.
  • subscription.trial_will_end: OrcaRail envía este webhook unos 3 días antes de trial_end para que puedas recordar al pagador que añada un método de pago o apruebe el cobro automático.

Crear una suscripción con periodo de prueba​

Usa trial_period_days (o trial_end) al crear la suscripción:

POST /api/v1/subscriptions
{
  "description": "Pro Plan",
  "amount": "10.00",
  "currency": "usd",
  "token_id": "...",
  "network_id": "...",
  "interval": "month",
  "trial_period_days": 14,
  "payer_email": "[email protected]"
}

La respuesta incluirá:

  • status: "trialing"
  • trial_start: la hora de creación
  • trial_end: la creación + 14 días
  • current_period_start / current_period_end: el primer periodo de facturación tras la prueba

Actualizar el fin de la prueba​

Puedes actualizar trial_end en una suscripción existente (por ejemplo, para ampliar o acortar la prueba):

PATCH /api/v1/subscriptions/:id
{
  "trial_end": "2025-04-15T00:00:00Z"
}

Usa "now" para terminar la prueba de inmediato y lanzar el primer ciclo de facturación.

Flujo de estados con periodo de prueba​

  • trialing: todavía no hay cobro; trial_end está en el futuro.
  • Tras trial_end: la suscripción pasa a active cuando se paga el primer periodo (o a paused si no hay método de pago / allowance).

Webhooks​

  • subscription.created: se envía al crear la suscripción (puede estar en trialing).
  • subscription.trial_will_end: se envía unos 3 días antes de trial_end; úsalo para enviar un email al pagador o pedirle que apruebe el cobro automático.
  • subscription.payment_link.created: cuando se crea el primer enlace de pago tras la prueba (en send_payment_link).
  • subscription.payment_link.paid: cuando se paga el primer ciclo tras la prueba.

Buenas prácticas​

  1. Avisa antes de que termine la prueba: gestiona subscription.trial_will_end para enviar un email o un mensaje en la app.
  2. Cobro automático y periodos de prueba: con auto_charge, pide al pagador que apruebe el allowance antes de trial_end para que el primer cobro salga bien; si no, la suscripción puede pasar a paused o past_due.
  3. Mensajes claros: en la página de pago o de suscripción, muestra la duración de la prueba y la fecha e importe del primer cobro para que el pagador sepa qué esperar.

Próximos pasos​