Referencia del SDK de Facturación

Referencia completa de todos los métodos de facturación del App Bridge. Consulta planes, gestiona suscripciones y maneja errores desde tu plugin.

Configuración

Todos los métodos de facturación están disponibles a través del hook del App Bridge:

import { useAppBridge } from "@whatalo/plugin-sdk/bridge";

function MyComponent() {
  const bridge = useAppBridge();
  // bridge.billing.*
}

Métodos

`bridge.billing.getPlans()`

Devuelve todos los planes de precios activos de tu plugin.

getPlans(): Promise<BillingPlanResponse[]>

Devuelve: Array de objetos BillingPlanResponse. Devuelve un array vacío si no hay planes activos.

const plans = await bridge.billing.getPlans();

for (const plan of plans) {
  console.log(plan.slug);       // "pro"
  console.log(plan.name);       // "Pro"
  console.log(plan.price);      // 29.99
  console.log(plan.currency);   // "USD"
  console.log(plan.interval);   // "monthly" | "annual" | null
  console.log(plan.trialDays);  // 14
  console.log(plan.features);   // ["Analíticas avanzadas", "Reportes ilimitados"]
  console.log(plan.isPopular);  // true
}

`bridge.billing.getSubscription()`

Devuelve la suscripción activa de la tienda actual a tu plugin, o null si no tiene suscripción.

getSubscription(): Promise<BillingSubscriptionResponse | null>

const sub = await bridge.billing.getSubscription();

if (!sub) {
  // Sin suscripción — mostrar prompt de mejora
  return;
}

console.log(sub.planSlug);          // "pro"
console.log(sub.planName);          // "Pro"
console.log(sub.status);            // "active"
console.log(sub.trialEndsAt);       // "2026-04-15T00:00:00.000Z" | null
console.log(sub.currentPeriodEnd);  // "2026-04-30T00:00:00.000Z" | null
console.log(sub.cancelAtPeriodEnd); // false
console.log(sub.canceledAt);        // null

`bridge.billing.requestSubscription(planSlug)`

Inicia el flujo de suscripción para el plan dado. El host del administrador redirige al comerciante a una página de aprobación donde ve los detalles del plan, precio y período de prueba antes de confirmar.

requestSubscription(planSlug: string): Promise<void>

Parámetros:

Parámetro	Tipo	Descripción
`planSlug`	string	Slug del plan al que suscribirse (ej. `"pro"`)

await bridge.billing.requestSubscription("pro");

Este método no devuelve un valor. El host gestiona la redirección de página después de que el comerciante aprueba. Si el comerciante cancela en la página de aprobación, no se crea ninguna suscripción.

`bridge.billing.cancelSubscription()`

Cancela la suscripción actual al final del período de facturación actual. El comerciante mantiene acceso completo hasta que termine el período — no vuelve a ser cobrado después.

cancelSubscription(): Promise<void>

await bridge.billing.cancelSubscription();
// sub.cancelAtPeriodEnd es ahora true
// sub.canceledAt tiene la marca de tiempo de cancelación

`bridge.billing.reactivateSubscription()`

Deshace una cancelación. Solo disponible mientras la suscripción aún está dentro de su período activo (es decir, cancelAtPeriodEnd es true y el período aún no ha terminado).

reactivateSubscription(): Promise<void>

await bridge.billing.reactivateSubscription();
// sub.cancelAtPeriodEnd es ahora false
// sub.canceledAt es ahora null

`bridge.billing.switchPlan(newPlanSlug)`

Cambia la suscripción actual a un plan diferente. Se aplica prorrateo: el comerciante recibe crédito por el tiempo no utilizado en el plan actual, aplicado inmediatamente al costo del nuevo plan.

switchPlan(newPlanSlug: string): Promise<void>

Parámetros:

Parámetro	Tipo	Descripción
`newPlanSlug`	string	Slug del plan al que cambiar

await bridge.billing.switchPlan("enterprise");

Referencia de Tipos

`BillingPlanResponse`

interface BillingPlanResponse {
  slug: string;
  name: string;
  price: number;       // Unidades monetarias mayores (ej. 29.99)
  currency: string;    // "USD"
  interval: string | null;  // "monthly" | "annual" | null
  trialDays: number;
  features: string[];
  isPopular: boolean;
}

`BillingSubscriptionResponse`

interface BillingSubscriptionResponse {
  planSlug: string;
  planName: string;
  /** "pending" | "trialing" | "active" | "past_due" | "canceled" | "expired" */
  status: string;
  trialEndsAt: string | null;        // ISO timestamp o null
  currentPeriodEnd: string | null;   // ISO timestamp o null
  cancelAtPeriodEnd: boolean;
  canceledAt: string | null;         // ISO timestamp o null
}

Manejo de Errores

Todos los métodos de facturación lanzan excepciones en caso de falla — no devuelven { success: false }. Usa try/catch:

try {
  await bridge.billing.requestSubscription("pro");
} catch (error) {
  bridge.toast.show("La suscripción falló. Por favor intenta de nuevo.", {
    variant: "error",
  });
}

Motivos comunes de falla:

Tiempo de espera de red (límite de 5 segundos por acción)
El slug del plan no existe o está inactivo
No hay suscripción activa al llamar cancel/reactivate/switchPlan
La suscripción ya está en un estado terminal

Operaciones Disponibles

Método	Operación	Descripción
`getPlans`	`getPlans`	Obtener todos los planes activos
`getSubscription`	`getSubscription`	Obtener suscripción actual de la tienda
`requestSubscription`	`requestSubscription`	Iniciar flujo de aprobación de suscripción
`cancelSubscription`	`cancelSubscription`	Cancelar al final del período
`reactivateSubscription`	`reactivateSubscription`	Deshacer una cancelación pendiente
`switchPlan`	`switchPlan`	Cambiar plan con prorrateo

On this page