Gestionar la suscripción

Los endpoints de facturación cubren todo el ciclo de vida de la suscripción, con una regla: la API prepara, la persona confirma, el proveedor de pago ejecuta. A través de la API no se mueve dinero. Toda acción que implique un pago devuelve un enlace a la propia página del proveedor (Stripe Checkout, el portal de cliente de Stripe o PayPal), donde la persona ve el importe exacto y confirma.

Tu clave necesita billing:read para leer y billing:manage para crear enlaces. Estos endpoints siguen funcionando cuando la tienda ya no tiene un plan con API. Así es como vuelve una tienda que bajó de plan o cuya suscripción caducó.

1. Consultar lo que es posible

curl https://api.nembol.com/rest/v1/billing \
  -H "Authorization: Bearer $NEMBOL_API_KEY"

{
  "object": "billing",
  "billing_source": "stripe",
  "managed_elsewhere": null,
  "plan": { "key": "enterprise", "name": "Enterprise", "interval": "month" },
  "status": "active",
  "current_period_end": "2026-11-08T07:41:43.000Z",
  "cancel_at_period_end": false,
  "payment_method": { "brand": "visa", "last4": "4242" },
  "usage": { "products": 350, "max_accounts_on_one_channel": 3, "team_members": 0 },
  "plans": [
    {
      "key": "pro",
      "name": "Pro",
      "limits": { "products": 2000, "accounts_per_channel": 2, "team_members": 0 },
      "prices": {
        "month": { "amount": 49, "currency": "usd", "selectable": false,
                   "reason": "The store has 3 accounts on one channel; Pro allows 2 per channel." },
        "year":  { "amount": 441, "currency": "usd", "selectable": false, "reason": "…" }
      }
    }
    // … basic, enterprise, enterprise_plus
  ],
  "invoices": [ { "amount": "79.00", "status": "paid", "url": "https://invoice.stripe.com/…", "created_at": "…" } ],
  "actions": { "change_plan": true, "update_payment_method": true, "cancel": true, "manage": true }
}

plans[].prices.*.selectable te indica qué cambios de plan se aceptan ahora mismo, y reason te dice por qué no. Muéstraselo a la persona: está escrito para ella.

2. Cambiar el plan

Suscribirse, reactivar, subir de plan, bajar de plan y cambiar entre mensual y anual son todos la misma llamada:

curl -X POST https://api.nembol.com/rest/v1/billing/plan_change_link \
  -H "Authorization: Bearer $NEMBOL_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"plan": "enterprise_plus", "interval": "year",
       "return_url": "https://app.example.com/billing/done"}'

{
  "object": "billing_link",
  "action": "change_plan",
  "provider": "stripe",
  "plan": "enterprise_plus",
  "interval": "year",
  "url": "https://billing.stripe.com/p/session/…"
}

La página que se abre depende de la tienda:

No cambia nada hasta que la persona confirma. Después, GET /billing muestra el nuevo plan.

Los límites son los mismos que en el panel

Un cambio de plan se rechaza, antes de crear ningún enlace, cuando el uso de la tienda no cabe en el plan de destino:

{
  "error": {
    "type": "invalid_request_error",
    "code": "plan_limits_exceeded",
    "message": "The store has 3 accounts on one channel; Pro allows 2 per channel. Reduce usage first, or pick a larger plan.",
    "param": "plan"
  }
}

Se comprueban los productos, las cuentas conectadas por canal y los miembros del equipo. Para bajar de plan, reduce primero el uso (por ejemplo, desconecta una cuenta de canal con POST /channel_accounts/{id}/disconnect) y vuelve a pedirlo.

3. Tarjeta, cancelación, renovación

Una prueba no tiene nada que cancelar: cancel_link responde nothing_to_cancel. Una nueva prueba solo está disponible para tiendas canceladas que nunca reiniciaron una y nunca pagaron, o cuyo último periodo de pago terminó hace más de 3 meses (si no, trial_not_available).

URL de retorno

return_url es opcional (por defecto es el panel de Nembol). Si pasas una, debe empezar por una URL registrada para la tienda. Es la misma lista de permitidas que usan las conexiones de canales (POST /redirect_urls, o Configuración → Desarrolladores → URL de redirección).

Buenas prácticas para agentes

• Crea un enlace justo antes de dárselo a la persona, y no lo guardes: los enlaces duran poco.
• Di siempre qué va a pasar antes de enviar el enlace ("esto te cambia a Enterprise+ anual, 1.161 $/año; Stripe mostrará el importe prorrateado").
• Consulta GET /billing cuando la persona vuelva en lugar de dar por hecho que el cambio se produjo. Puede que haya cerrado la página.

Última actualización el 20 de octubre de 2026