Flujo de Suscripción

Cómo los comerciantes se suscriben a los planes de precios de tu plugin usando la API de facturación del App Bridge.

Descripción General

Las suscripciones se inician desde dentro de tu plugin usando la API de facturación del App Bridge. La plataforma gestiona la página de aprobación, la configuración de pago y los eventos del ciclo de vida. Tu plugin lee el estado de la suscripción y reacciona a él.

Paso 1 — Mostrar Planes Disponibles

Obtén tus planes y muéstralos al comerciante:

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

function PricingPage() {
  const bridge = useAppBridge();

  async function loadPlans() {
    const plans = await bridge.billing.getPlans();
    // plans: BillingPlanResponse[]
    // [{ slug, name, price, currency, interval, trialDays, features, isPopular }]
  }
}

Paso 2 — Solicitar una Suscripción

Llama a requestSubscription con un slug de plan. Esto envía una acción de facturación al host del administrador, que redirige al comerciante a una página de aprobación.

async function handleSubscribe(planSlug: string) {
  try {
    await bridge.billing.requestSubscription(planSlug);
    // El host gestiona la redirección — esta función puede no retornar
    // si la página navega durante la aprobación
  } catch (error) {
    bridge.toast.show("No se pudo iniciar la suscripción", { variant: "error" });
  }
}

El comerciante ve los detalles del plan, el precio y la información de la prueba, luego confirma o cancela. Tu plugin no necesita gestionar la redirección de aprobación — la plataforma lo administra.

Paso 3 — Verificar el Estado de la Suscripción

Después de que el comerciante aprueba, lee la suscripción activa:

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

if (!sub) {
  // No hay suscripción activa para esta instalación
  return;
}

console.log(sub.status);            // "trialing", "active", etc.
console.log(sub.planSlug);          // "pro"
console.log(sub.planName);          // "Pro"
console.log(sub.trialEndsAt);       // ISO date string o null
console.log(sub.cancelAtPeriodEnd); // boolean

Estados de Suscripción

Estado	Descripción
`pending`	Esperando aprobación del comerciante en la página de confirmación
`trialing`	En el período de prueba gratuita — el comerciante no es cobrado
`active`	Facturación activa, el comerciante es cobrado en cada ciclo
`past_due`	Un pago falló — el sistema de facturación está reintentando
`canceled`	La suscripción ha terminado
`expired`	El período de prueba o facturación terminó sin renovación

Cancelación

Cancela una suscripción al final del período de facturación actual. El comerciante mantiene acceso completo hasta que termine el período:

await bridge.billing.cancelSubscription();

Después de la cancelación, sub.cancelAtPeriodEnd es true y sub.canceledAt contiene la marca de tiempo. El comerciante no vuelve a ser cobrado después del período actual.

Reactivación

Mientras la suscripción aún está en su período activo, el comerciante puede deshacer una cancelación:

await bridge.billing.reactivateSubscription();

Tras la reactivación, cancelAtPeriodEnd vuelve a false.

Cambio de Plan

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

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

Forma de la Respuesta de Suscripción

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. Usa try/catch:

try {
  await bridge.billing.cancelSubscription();
  bridge.toast.show("Suscripción cancelada", { variant: "success" });
} catch (error) {
  bridge.toast.show("No se pudo cancelar la suscripción", { variant: "error" });
}

Los métodos de facturación no devuelven { success: false } — lanzan excepciones, por lo que aplica el manejo de errores estándar.

Restringir Características por Suscripción

Usa getSubscription para mostrar funcionalidades premium condicionalmente:

function Dashboard() {
  const bridge = useAppBridge();
  const [sub, setSub] = useState<BillingSubscriptionResponse | null>(null);

  useEffect(() => {
    bridge.billing.getSubscription().then(setSub);
  }, []);

  const isActive = sub?.status === "active" || sub?.status === "trialing";

  return isActive ? <PremiumContent /> : <UpgradePrompt />;
}

On this page