Suscripciones

Métodos

Subscription

Así se ve el objeto que devuelven los métodos de este módulo.

Suscribir a un cliente

landapay.subscriptions.create(params, options?)

Devuelve la URL del checkout donde el cliente registra su método de pago. Si plan es un objeto, primero se crea el plan; si customer es un objeto, se crea el cliente o se reutiliza el que ya tiene ese email o externalId. La suscripción se crea cuando el cliente completa el checkout y te llega con el webhook subscription.created.

Parámetros

Devuelve

Promise<{ checkoutUrl: string; checkout: SubscriptionCheckout; plan: Plan | null; customer: string | null; subscription: null }>

1const { checkoutUrl } = await landapay.subscriptions.create({2  plan: {3    name: "Licencia Pro",4    interval: "monthly",5    amount: 4_990_000,6    trialDays: 14,7  },8  customer: { name: "María Gómez", email: "[email protected]" },9  externalId: "user_42",10  redirectUrl: "https://tuapp.com/suscripcion",11});12 13// Envía al usuario a checkoutUrl

Obtener una suscripción

landapay.subscriptions.retrieve(id, options?)

Parámetros

Devuelve

Promise<Subscription>

1const subscription = await landapay.subscriptions.retrieve("sub_SUBSCRIPTION2345");2 3if (subscription.status === "active" || subscription.status === "trialing") {4  // Dar acceso5}

Obtener el checkout de una suscripción

landapay.subscriptions.retrieveCheckout(id, options?)

Útil al volver del checkout: el campo subscription trae el id de la suscripción cuando el cliente lo completó.

Parámetros

Devuelve

Promise<SubscriptionCheckout>

1const checkout = await landapay.subscriptions.retrieveCheckout("scs_SESSIONCODE23456");2 3console.log(checkout.status, checkout.subscription);

Actualizar una suscripción

landapay.subscriptions.update(id, params, options?)

Cambia la referencia externa o la metadata. El precio y la frecuencia vienen del plan.

Parámetros

Devuelve

Promise<Subscription>

1await landapay.subscriptions.update("sub_SUBSCRIPTION2345", {2  metadata: { seats: 10 },3});

Cancelar una suscripción

landapay.subscriptions.cancel(id, params?, options?)

Por defecto sigue activa hasta el final del periodo pagado (subscription.cancel_scheduled). Con atPeriodEnd: false termina de inmediato (subscription.canceled). En ambos casos el cliente recibe un correo.

Parámetros

Devuelve

Promise<Subscription>

1await landapay.subscriptions.cancel("sub_SUBSCRIPTION2345", {2  atPeriodEnd: false,3  reason: "Pedido del usuario",4});

Reanudar una suscripción

landapay.subscriptions.resume(id, options?)

Quita una cancelación programada para el final del periodo.

Parámetros

Devuelve

Promise<Subscription>

await landapay.subscriptions.resume("sub_SUBSCRIPTION2345");

Calcular un cambio de plan sin aplicarlo

landapay.subscriptions.previewPlanChange(id, params, options?)

Devuelve lo que se cobraría hoy, lo que quedaría a favor del cliente y cuándo entraría en vigor, para mostrarlo antes de confirmar. Recibe lo mismo que changePlan; usa un id de plan para no crear planes que no se van a usar.

Parámetros

Devuelve

Promise<PlanChangePreview>

PlanChangePreview

1const preview = await landapay.subscriptions.previewPlanChange("sub_SUBSCRIPTION2345", {2  plan: "plan_PRO2345ABCDEFGH",3});4 5if (preview.charge > 0) {6  console.log(`Pagarás hoy ${preview.charge / 100} ${preview.currency}`);7} else if (preview.balanceDelta > 0) {8  console.log(`Quedarán a tu favor ${preview.balanceDelta / 100} ${preview.currency}`);9}

Cambiar el plan de una suscripción

landapay.subscriptions.changePlan(id, params, options?)

Aplica el cambio de inmediato, lo programa para el final del periodo o cobra la diferencia al método de pago guardado; el cambio solo se aplica si ese cobro se aprueba. Si se rechaza lanza InvalidRequestError con código payment_declined. Si el cobro queda pendiente (Nequi o Bancolombia), pendingPlanChange.status es pending_payment hasta el webhook subscription.plan_changed o subscription.plan_change_failed. Si plan es un objeto, primero se crea el plan.

Parámetros

Devuelve

Promise<Subscription>

1const subscription = await landapay.subscriptions.changePlan("sub_SUBSCRIPTION2345", {2  plan: "plan_PRO2345ABCDEFGH",3  behavior: "prorate",4});5 6console.log(subscription.plan, subscription.pendingPlanChange);

Deshacer un cambio de plan programado

landapay.subscriptions.cancelPlanChange(id, options?)

Quita el cambio programado con period_end; la suscripción sigue en su plan. Si no hay uno programado responde 409 no_plan_change_scheduled.

Parámetros

Devuelve

Promise<Subscription>

await landapay.subscriptions.cancelPlanChange("sub_SUBSCRIPTION2345");

Listar las facturas de una suscripción

landapay.subscriptions.listInvoices(id, params?, options?)

Una factura por ciclo y una por cada cobro de cambio de plan, la más reciente primero, igual que el tab Cobros del panel. Con await obtienes una página con data, page, totalPages, total, hasMore y los métodos nextPage() y previousPage() (devuelven null si no hay más). Con for await recorres todas las facturas y la librería pide las páginas siguientes por ti.

Parámetros

Devuelve

PagePromise<Invoice> (con await: Page<Invoice>)

Invoice

1// Una página (15 por defecto, máximo 50)2const page = await landapay.subscriptions.listInvoices("sub_SUBSCRIPTION2345", {3  page: 1,4  limit: 15,5});6 7console.log(page.total, page.totalPages);8const next = await page.nextPage(); // null si no hay más9 10// Todas, sin pensar en páginas11for await (const invoice of landapay.subscriptions.listInvoices("sub_SUBSCRIPTION2345")) {12  console.log(invoice.number, invoice.url);13}

Abrir la página para actualizar el método de pago

landapay.subscriptions.createPaymentMethodSession(id, params?, options?)

Devuelve un enlace de un solo uso, válido 15 minutos, para que el cliente vea, agregue o elimine métodos. Si la suscripción está en past_due o unpaid, guardar o elegir un método cobra el ciclo que falló. Si aprueba, el cliente vuelve a returnUrl (o al redirectUrl del checkout) con subscription_id y payment_id, y recibes payment.approved y subscription.activated. Si la suscripción está al día, solo se guarda el método.

Parámetros

Devuelve

Promise<PaymentMethodSession>

PaymentMethodSession

1const session = await landapay.subscriptions.createPaymentMethodSession(2  "sub_SUBSCRIPTION2345",3  { returnUrl: "https://tuapp.com/facturacion" },4);5 6console.log(session.url, session.expiresAt);