Zum Inhalt springen

Billing API

Drei Endpunkte erlauben es Agenten und Integrationen, mit dem Abrechnungsstatus zu arbeiten, den Ihr Dashboard verwaltet.

Alle Endpunkte erfordern einen Bearer-API-Key (siehe Authentifizierung).

GET /me/billing/state

Gibt eine Momentaufnahme des Abonnements Ihres Tenants zurück.

Terminal-Fenster
curl https://api.saiku.bi/me/billing/state \
-H "Authorization: Bearer $SAIKU_API_KEY"

Antwort:

{
"tenantId": "81e301f2-…",
"tier": "team",
"stripeCustomerId": "cus_…",
"subscriptionStatus": "active",
"currentPeriodEnd": "2026-06-23T00:00:00Z",
"trialEndsAt": null,
"billedFeaturesActive": true
}

Felder:

  • tier — starter, team, business oder enterprise.
  • subscriptionStatus — der Status von Stripe wortwörtlich. Die Werte, die Sie in der Praxis sehen, sind trialing, active, past_due, unpaid, canceled oder leer (free / pre-billing).
  • currentPeriodEnd — wann Ihre aktuelle Abrechnungsperiode endet. Bei aktivem Abo erfolgt zu diesem Zeitpunkt die Verlängerung.
  • trialEndsAt — nur gesetzt, solange subscriptionStatus = trialing.
  • billedFeaturesActive — true, solange Sie Zugriff auf abgerechnete Features haben. Andernfalls false. Verwenden Sie dies, um Ihr eigenes UI zu gaten.

Zwei Formen, nicht eine

Ein Tenant, der nie ein Abonnement gestartet hat, hat keinen Billing-Datensatz dahinter, und die Antwort ist kürzer — sie trägt nur:

{
"tenantId": "81e301f2-…",
"tier": "starter",
"subscriptionStatus": "",
"billedFeaturesActive": false
}

stripeCustomerId, currentPeriodEnd und trialEndsAt sind abwesend, nicht null. Liest Ihr Client state.currentPeriodEnd und erwartet ein null, bekommt er stattdessen undefined — verzweigen Sie also auf billedFeaturesActive (oder auf die Anwesenheit des Schlüssels), statt anzunehmen, dass jedes Feld immer da ist.

Wenn Billing nicht konfiguriert ist

Hat das Gateway keinen Stripe-Key verdrahtet, gibt jeder Endpunkt auf dieser Seite 503 zurück:

{
"error": "billing_disabled",
"message": "Stripe billing is not configured on this gateway."
}

Sie sehen das bei Self-hosted-Builds und lokalen Stacks, wo es erwartet ist. Auf api.saiku.bi ist es das nicht — wenn Sie es dort treffen, sagen Sie uns Bescheid.

POST /me/billing/checkout-session

Erzeugt eine einmalige URL zum von Stripe gehosteten Checkout, um eine Testphase zu starten oder einen Plan zu abonnieren.

Terminal-Fenster
curl -X POST https://api.saiku.bi/me/billing/checkout-session \
-H "Authorization: Bearer $SAIKU_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"tier": "team",
"email": "alice@acme.com",
"name": "Acme Corp",
"successUrl": "https://app.acme.com/billing/success",
"cancelUrl": "https://app.acme.com/billing/cancel"
}'

Antwort:

{
"url": "https://checkout.stripe.com/c/pay/cs_test_a1…",
"sessionId": "cs_test_a1…"
}

Senden Sie den Browser des Benutzers per 303-Redirect an url. Die URL ist einmalig und verfällt nach wenigen Minuten — nicht cachen.

successUrl und cancelUrl sind absolute URLs, an die Stripe den Benutzer nach Abschluss oder Abbruch des Checkouts zurücksendet. Beide müssen HTTPS sein.

POST /me/billing/portal-session

Erzeugt eine einmalige URL zum Stripe Customer Portal. Das Portal ist die von Stripe gehostete Seite zur Verwaltung des Abonnements: Karte aktualisieren, Plan ändern, Rechnungen herunterladen, kündigen.

Terminal-Fenster
curl -X POST https://api.saiku.bi/me/billing/portal-session \
-H "Authorization: Bearer $SAIKU_API_KEY" \
-H "Content-Type: application/json" \
-d '{ "returnUrl": "https://app.acme.com/billing" }'

Antwort:

{ "url": "https://billing.stripe.com/p/session/test_…" }

Liefert 409 no_customer, wenn der Tenant noch nie ein Checkout abgeschlossen hat — es gibt keinen Stripe-Kunden zu verwalten. Führen Sie zuerst POST /me/billing/checkout-session aus.

Ein durchgängiges Beispiel — eingebetteter Abonnementstatus

Wenn Sie ein Admin-UI bauen, das Saiku Cloud umschließt, und Ihren Benutzern den aktuellen Plan inline anzeigen möchten:

// pseudocode
const state = await fetch('https://api.saiku.bi/me/billing/state', {
headers: { Authorization: `Bearer ${saikuApiKey}` }
}).then(r => r.json());
if (!state.billedFeaturesActive) {
// user has no active subscription or trial — show "upgrade" CTA
const session = await fetch(
'https://api.saiku.bi/me/billing/checkout-session',
{
method: 'POST',
headers: {
Authorization: `Bearer ${saikuApiKey}`,
'Content-Type': 'application/json'
},
body: JSON.stringify({
tier: 'team',
email: user.email,
name: org.name,
successUrl: `${window.location.origin}/billing/success`,
cancelUrl: `${window.location.origin}/billing/cancel`
})
}
).then(r => r.json());
window.location.href = session.url;
} else {
// user has access — show current plan + manage button
renderPlan(state.tier, state.currentPeriodEnd);
const portal = await fetch(
'https://api.saiku.bi/me/billing/portal-session',
{
method: 'POST',
headers: {
Authorization: `Bearer ${saikuApiKey}`,
'Content-Type': 'application/json'
},
body: JSON.stringify({ returnUrl: `${window.location.origin}/billing` })
}
).then(r => r.json());
renderManageButton(portal.url);
}