Das Abonnement verwalten

Die Billing-Endpoints decken den gesamten Lebenszyklus des Abonnements ab, mit einer Regel: Die API bereitet vor, die Person bestätigt, der Zahlungsanbieter führt aus. Über die API fließt kein Geld. Jede Aktion, die eine Zahlung beinhaltet, liefert einen Link zur eigenen Seite des Anbieters (Stripe Checkout, das Stripe-Kundenportal oder PayPal), wo die Person den genauen Betrag sieht und bestätigt.

Dein Schlüssel braucht billing:read zum Lesen und billing:manage zum Erstellen von Links. Diese Endpoints funktionieren weiter, wenn der Shop keinen Plan mit API-Zugang mehr hat. So kommt ein herabgestufter oder abgelaufener Shop zurück.

1. Lesen, was möglich ist

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 sagt dir, welche Planwechsel gerade akzeptiert werden, und reason, warum nicht. Zeig das der Person; es ist für sie geschrieben.

2. Den Plan wechseln

Abschließen, Reaktivieren, Upgrade, Downgrade und der Wechsel zwischen monatlich und jährlich sind alle derselbe Aufruf:

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

Welche Seite sich öffnet, hängt vom Shop ab:

Nichts ändert sich, bis die Person bestätigt. Danach zeigt GET /billing den neuen Plan.

Die Limits sind dieselben wie im Dashboard

Ein Planwechsel wird abgelehnt, bevor überhaupt ein Link erstellt wird, wenn die Nutzung des Shops nicht in den Zielplan passt:

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

Geprüft werden Produkte, verbundene Konten pro Kanal und Teammitglieder. Für ein Downgrade reduzierst du zuerst die Nutzung (trenne zum Beispiel ein Kanalkonto mit POST /channel_accounts/{id}/disconnect) und fragst dann erneut.

3. Karte, Kündigung, Verlängerung

Eine Testphase hat nichts zu kündigen: cancel_link antwortet mit nothing_to_cancel. Eine neue Testphase steht nur gekündigten Shops zur Verfügung, die nie eine neu gestartet und nie bezahlt haben oder deren letzter bezahlter Zeitraum vor mehr als 3 Monaten endete (andernfalls trial_not_available).

Rückkehr-URLs

return_url ist optional (Standard ist das Nembol-Dashboard). Wenn du eine übergibst, muss sie mit einer für den Shop registrierten URL beginnen. Es ist dieselbe Allowlist wie bei Kanalverbindungen (POST /redirect_urls oder Einstellungen → Entwickler → Weiterleitungs-URLs).

Gute Praxis für Agenten

• Erstelle einen Link unmittelbar, bevor du ihn der Person gibst, und speichere ihn nicht: Links sind kurzlebig.
• Sag immer, was passieren wird, bevor du den Link sendest („damit wechselst du zu Enterprise+ jährlich, 1.161 $/Jahr; Stripe zeigt dir den anteiligen Betrag“).
• Prüfe GET /billing, nachdem die Person zurückkommt, statt anzunehmen, dass die Änderung erfolgt ist. Vielleicht hat sie die Seite geschlossen.

Zuletzt aktualisiert am 20. Oktober 2026