Gestisci l'abbonamento

Gli endpoint di fatturazione coprono l'intero ciclo di vita dell'abbonamento, con una regola: l'API prepara, la persona conferma, il fornitore di pagamento esegue. Nessun movimento di denaro passa dall'API. Ogni azione che comporta un pagamento restituisce un link alla pagina del fornitore stesso (Stripe Checkout, il portale clienti di Stripe o PayPal) dove la persona vede l'importo esatto e conferma.

La tua chiave deve avere billing:read per leggere e billing:manage per creare i link. Questi endpoint continuano a funzionare anche quando lo store non ha più un piano con API. È così che uno store passato a un piano inferiore o scaduto può tornare.

1. Leggi cosa è possibile

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 ti dice quali cambi di piano sono accettati in questo momento, e reason ti dice perché no. Mostralo alla persona; è scritto per lei.

2. Cambia il piano

Sottoscrivere, riattivare, passare a un piano superiore o inferiore e passare dal mensile all'annuale (o viceversa) sono tutte la stessa chiamata:

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/…"
}

Quale pagina si apre dipende dallo store:

Non cambia nulla finché la persona non conferma. Dopo, GET /billing mostra il nuovo piano.

I limiti sono gli stessi della dashboard

Un cambio di piano viene rifiutato, prima che venga creato qualsiasi link, quando l'utilizzo dello store non rientra nel piano di destinazione:

{
  "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"
  }
}

I controlli riguardano prodotti, account collegati per canale e membri del team. Per passare a un piano inferiore, prima riduci l'utilizzo (ad esempio, scollega un account del canale con POST /channel_accounts/{id}/disconnect), poi richiedi di nuovo.

3. Carta, annullamento, rinnovo

Una prova non ha nulla da annullare: cancel_link risponde nothing_to_cancel. Una nuova prova è disponibile solo per gli store annullati che non ne hanno mai riavviata una e non hanno mai pagato, oppure il cui ultimo periodo pagato è terminato più di 3 mesi fa (altrimenti trial_not_available).

URL di ritorno

return_url è facoltativo (il valore predefinito è la dashboard di Nembol). Se ne passi uno, deve iniziare con un URL registrato per lo store. È la stessa lista consentita usata per collegare i canali (POST /redirect_urls, oppure Impostazioni → Sviluppatori → URL di reindirizzamento).

Buone pratiche per gli agenti

• Crea un link subito prima di darlo alla persona, e non salvarlo: i link durano poco.
• Di' sempre cosa succederà prima di inviare il link ("questo ti fa passare a Enterprise+ annuale, 1.161 $/anno; Stripe ti mostrerà l'importo proporzionale").
• Controlla GET /billing dopo che la persona è tornata, invece di dare per scontato che il cambio sia avvenuto. Potrebbe aver chiuso la pagina.

Ultimo aggiornamento il 20 ottobre 2026