Descuentos en planes

Para un producto con suscripciones que quiere dar descuentos sin crear planes rebajados. Los ejemplos usan los planes Plus y Pro de planes personales.

El modeloCopiar enlace

• El precio del plan no cambia. El cupón queda en la suscripción y descuenta sus primeros payments cobros; después las renovaciones se cobran completas sin que tu aplicación haga nada. Así no hay planes «Plus promo» que mantener ni clientes atrapados en un precio viejo.
• Cuenta cobros, no meses. payments: 3 son tres meses en el ciclo mensual y tres años en el anual: el cupón no distingue ciclos, así que ofrécelo donde se venda el ciclo que tienes en mente.
• Solo descuenta los planes que cubre. Con plans se limita a esos; si el cliente cambia a otro plan, las renovaciones de ese plan se cobran completas.

1. Los tres primeros meses a mitad de precioCopiar enlace

await billete.coupons.create({
  code: "PLUS50",
  percentOff: 50,
  appliesTo: "plans",
  plans: [PLANS.plus],
  payments: 3,
});

// Un enlace solo con el ciclo mensual y el cupón ya puesto.
const link = await billete.paymentLinks.create({
  type: "plan",
  plan: PLANS.plus,
  months: [1],
});
const promoUrl = `${link.url}?coupon=PLUS50`;

El primer pago, la primera y la segunda renovación salen a mitad de precio; la tercera, completa. Si el plan tiene prueba gratis, el checkout de la prueba guarda el cupón y el primer pago descontado es el que cierra la prueba. renewal.amount de la suscripción ya trae el descuento, así que puedes mostrar cuánto pagará el cliente en su próxima renovación.

2. Promoción de lanzamientoCopiar enlace

Un precio de fundador: 30 % para siempre, solo para los primeros 100 clientes nuevos y hasta fin de mes.

await billete.coupons.create({
  code: "FUNDADOR",
  percentOff: 30,
  appliesTo: "plans",
  payments: null,
  firstPurchaseOnly: true,
  maxRedemptions: 100,
  expiresAt: "2026-11-30T23:59:59-04:00",
});

Sin plans vale para todos los planes del negocio. firstPurchaseOnly deja fuera a quien ya le pagó algo al negocio (un plan gratis o una prueba no cuentan como pago); oncePerCustomer permite un uso por correo. expiresAt y maxRedemptions limitan quién lo aplica, no a quien ya lo tiene: una suscripción con el cupón lo sigue usando por todos sus payments.

Para aplicarlo desde tu servidor, envía coupon al crear el checkout. Tus clientes lo escriben al pagar mientras tu negocio acepte cupones (Configuración › Cobros › Cupones), también en la página de su renovación. Si al pagar el cliente no cumple una condición, el cupón se quita y el pago responde coupon_first_purchase_only o coupon_already_used, para que vea el total nuevo antes de pagar.

3. Descuento para subir de planCopiar enlace

Un cambio que se paga ahora y empieza un periodo nuevo, como pasar de Hobby a Pro, acepta un cupón del plan nuevo:

const input = { plan: PLANS.pro, months: 1, coupon: "PRO50" } as const;
const quote = await billete.subscriptions.changes.preview(user.subscriptionId, input);
// quote.total ya tiene el descuento: muéstralo antes de confirmar.

const result = await billete.subscriptions.changes.create(user.subscriptionId, {
  ...input,
  when: "now",
  successUrl: "https://tuapp.com/ajustes/plan",
});
if (result.type === "checkout") return redirect(result.checkout.url);

El pago del cambio es el primero que descuenta y el cupón reemplaza al que tuviera la suscripción. Sin coupon, el cliente puede escribirlo en el checkout del cambio. Un cambio programado para la renovación, uno sin costo durante una prueba o uno que solo agrega puestos no admiten cupón (coupon_not_applicable).

4. Termina una promociónCopiar enlace

await billete.coupons.update(coupon.id, { active: false });

Desactivarlo detiene las compras nuevas y se puede reactivar; eliminarlo libera el código. En los dos casos, las suscripciones que ya lo tienen conservan su descuento hasta agotar sus payments. La vuelta a un plan gratuito por el respaldo sí quita el cupón.

Referencia de cupones · Cupones en el SDK · Cambios de suscripción