API reference / Token auth

Billing

Read usage for the current period, attach a payment method via Stripe, open the billing portal, and set a monthly spend cap.

GET /v1/billing/usage

Token + X-MailStack-Org

Current-period usage and billing state.

Response

{
  "periodKey": "2026-06",
  "emailsSent": 4200,
  "freeMonthlyAllowance": 3000,
  "freeRemaining": 0,
  "billableEmails": 1200,
  "pricePer1kCents": 40,
  "hasPaymentMethod": true,
  "monthlySpendCapCents": 5000
}

POST /v1/billing/setup-intent

Token + X-MailStack-Org

Create a Stripe SetupIntent to attach a card.

Response

{ "clientSecret": "seti_..._secret_...", "customerId": "cus_..." }

POST /v1/billing/payment-method/sync

Token + X-MailStack-Org

Reconcile the default payment method with Stripe and return fresh usage.

Response

{ "hasPaymentMethod": true, "emailsSent": 4200 }

GET /v1/billing/portal

Token + X-MailStack-Org

Query param: returnUrl (where Stripe returns after the portal closes).

Response

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

PUT /v1/billing/spend-cap

Token + X-MailStack-Org

Set or clear the monthly spend cap.

Request body

{ "monthlySpendCapCents": 5000 }

Response

{ "monthlySpendCapCents": 5000 }

SDKs

Prefer a typed client? The Billing endpoints are covered by the official Node, .NET, Go, and Flutter/Dart SDKs.