Pruebas gratis

Para un producto que deja probar un plan pago antes de cobrarlo. El ejemplo da 14 días de Plus y, si el usuario no paga, lo deja en Hobby gratis, como en planes personales.

El modeloCopiar enlace

• La prueba es el primer periodo de la suscripción, no un plan aparte. Al terminar se renueva como cualquier periodo: Billete emite el Cobro 3 días antes de trialEndsAt y el cliente lo paga desde su página. Pago Móvil no domicilia, así que nadie paga sin enterarse ni hace falta pedir datos de pago para empezar.
• La prueba existe solo al crear la suscripción. Un cambio de Hobby a Plus cobra en el acto, sin prueba. Por eso el usuario empieza en la prueba de Plus en vez de en Hobby.
• El respaldo hace el resto. Si la prueba termina sin pago, la suscripción pasa a Hobby con el mismo ID y tu aplicación solo ajusta el acceso.

1. Pon los días de prueba en el planCopiar enlace

const plus = await billete.plans.create({
  name: "Plus",
  lookupKey: "plus",
  currency: "USD",
  prices: [{ months: 1, amount: 1000 }, { months: 12, amount: 10000 }],
  trialDays: 14,
  fallbackPlanId: PLANS.hobby,
  features: { mensajes: 2000 },
});

trialDays (hasta 365) es la prueba que dan los checkouts del plan. La gracia (gracePeriodDays) también aplica al final de la prueba: con 3 días, quien no paga sigue en Plus 3 días más antes de volver a Hobby.

2. Empieza la pruebaCopiar enlace

Al registrar al usuario, desde tu servidor:

const subscription = await billete.subscriptions.create({
  customer: { externalId: user.id, email: user.email },
  plan: PLANS.plus,
  months: 1,
}, { idempotencyKey: `trial-${user.id}` });

await db.users.update(user.id, {
  subscriptionId: subscription.id,
  trialStartedAt: new Date(),
});

La suscripción queda trialing con las cuotas de Plus. Sin trialDays usa los del plan; envíalos para dar otra duración a este cliente. Un plan pago sin prueba responde trial_required: los periodos pagados se venden con un checkout. months es el ciclo que se cobrará al terminar.

Si prefieres que el usuario elija el plan y el ciclo en una página de Billete, crea un checkout del plan: con trialDays en el plan, el total es 0, el cliente solo confirma sus datos y la suscripción empieza en prueba.

3. Una prueba por clienteCopiar enlace

Un checkout no repite la prueba a un cliente que tiene o tuvo una suscripción en ese plan: al confirmar responde trial_unavailable y cobra el primer periodo. Pero subscriptions.create no lo comprueba, y una suscripción que volvió a Hobby ya no está en Plus, así que la regla vive en tu aplicación:

if (user.trialStartedAt) {
  // Ya la usó: ofrécele pagar Plus con un cambio desde Hobby.
  return showUpgrade();
}

Guarda la marca en tu usuario en vez de deducirla de Billete: un checkout reconoce al cliente por su externalId o por su correo, y con otro correo sería otro cliente.

4. Cambios durante la pruebaCopiar enlace

Un cambio inmediato durante la prueba se aplica gratis y la prueba sigue: el primer cobro ya usa el plan, el ciclo o los puestos nuevos.

// Sigue en prueba, ahora con el ciclo anual.
await billete.subscriptions.changes.create(subscription.id, { months: 12, when: "now" });

// Quiere pagar ya: termina la prueba y cobra desde hoy, en un checkout.
const result = await billete.subscriptions.changes.create(subscription.id, {
  when: "now",
  endTrial: true,
  successUrl: "https://tuapp.com/ajustes/plan",
});
if (result.type === "checkout") return redirect(result.checkout.url);

Pasar a un plan gratuito siempre termina la prueba. Cancelar con cancel(id) la deja correr hasta trialEndsAt y luego pasa a Hobby.

5. Escucha los eventosCopiar enlace

No hay un evento propio del fin de la prueba: es una renovación. Consulta la suscripción en cada evento y muestra lo que diga (status, trialEndsAt, renewal).

Referencia de suscripciones · Referencia de planes · Renovaciones con Pago Móvil