Billing

post/api/v1/billing/cancel

Cancel

Cancel the subscription at the end of the paid period; the plan stays until then.

Requires an API key

curl -s -X POST "$OSR_URL/api/v1/billing/cancel" \
  -H "Authorization: Bearer $OSR_API_KEY"

post/api/v1/billing/checkout

Checkout

Start a subscription (Checkout Session URL) or, with a live one, switch its plan in place. plan names a paid plan; interval is month (default) or year when the deployment sells an annual price for it. The first checkout of a workspace starts the plan's free trial without a payment method (trial_days of the plan, granted at once: trial_end in the answer and url back to /platform/dashboard/billing?redeemed=<plan>), as does any coupon that applies - coupon in the body, or the auto-apply promotion the workspace is still eligible for; this works without Stripe too. "coupon": "" skips the trial and the promotion and pays now. A plan whose trial asks for a card (trial_needs_card) carries it into Stripe Checkout instead.

Requires an API key

curl -s -X POST "$OSR_URL/api/v1/billing/checkout" \
  -H "Authorization: Bearer $OSR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{}'

{}

get/api/v1/billing/coupons

Status

The promotion on offer, the workspace's running coupon trial and the plans it could still unlock.

Requires an API key

curl -s "$OSR_URL/api/v1/billing/coupons" \
  -H "Authorization: Bearer $OSR_API_KEY"

post/api/v1/billing/coupons/redeem

Redeem

Apply a coupon: the workspace moves to plan now, free of charge, until the trial ends. Owners and admins only. 404 unknown code, 400 when the coupon does not cover the plan or ran out, 409 when this workspace redeemed it before or already pays for a subscription.

Requires an API key

curl -s -X POST "$OSR_URL/api/v1/billing/coupons/redeem" \
  -H "Authorization: Bearer $OSR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "code": "string", "plan": "string" }'

{
  "code": "string",
  "plan": "string"
}

post/api/v1/billing/coupons/validate

Validate

Check a code before redeeming it: the coupon's terms plus eligible / reason for this workspace (and for plan when given).

Requires an API key

curl -s -X POST "$OSR_URL/api/v1/billing/coupons/validate" \
  -H "Authorization: Bearer $OSR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "code": "string" }'

{
  "code": "string"
}

post/api/v1/billing/credits/checkout

Credits

Buy credits: a Stripe Checkout Session (payment mode) for amount_cents; the webhook credits the wallet when it completes and the browser returns to /platform/dashboard/billing?credited=<cents>. save_payment_method keeps the card for auto top-up; auto_topup (amount_cents, threshold_cents) switches auto top-up on as soon as the purchase completes.

Requires an API key

curl -s -X POST "$OSR_URL/api/v1/billing/credits/checkout" \
  -H "Authorization: Bearer $OSR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "amount_cents": 1 }'

{
  "amount_cents": 1
}

get/api/v1/billing/invoices

Invoices

The workspace's Stripe invoices, newest first, with hosted page and PDF links.

Requires an API key

curl -s "$OSR_URL/api/v1/billing/invoices" \
  -H "Authorization: Bearer $OSR_API_KEY"

post/api/v1/billing/portal

Portal

A Stripe Billing Portal session (payment method, invoices, cancel / resume) for the workspace.

Requires an API key

curl -s -X POST "$OSR_URL/api/v1/billing/portal" \
  -H "Authorization: Bearer $OSR_API_KEY"

get/api/v1/billing/statement

Statement

The monthly credits statement (month = YYYY-MM, default the current month) as JSON or Markdown.

Requires an API key

curl -s "$OSR_URL/api/v1/billing/statement?format=json" \
  -H "Authorization: Bearer $OSR_API_KEY"

get/api/v1/billing/subscription

Subscription

Plan, billing state, period end and whether the portal / invoices are available.

Requires an API key

curl -s "$OSR_URL/api/v1/billing/subscription" \
  -H "Authorization: Bearer $OSR_API_KEY"

get/api/v1/billing/usage

Usage

The workspace's metered usage with both sides of the price - provider cost and what the workspace is charged - grouped by day (default), model, provider, key or tenant; format=csv downloads it.

Requires an API key

curl -s "$OSR_URL/api/v1/billing/usage?days=30&group=day" \
  -H "Authorization: Bearer $OSR_API_KEY"

get/api/v1/billing/wallet

Wallet

The credits wallet: billing mode, balance, the last top-up, what a purchase may be and today's pending charges.

Requires an API key

curl -s "$OSR_URL/api/v1/billing/wallet" \
  -H "Authorization: Bearer $OSR_API_KEY"

put/api/v1/billing/wallet/auto-topup

Set Auto Topup

Turn auto top-up on or change it: buy amount_cents of credits with the saved payment method whenever the available balance falls to threshold_cents or below. 409 without a saved card - buy credits once with save_payment_method (or auto_topup) first.

Requires an API key

curl -s -X PUT "$OSR_URL/api/v1/billing/wallet/auto-topup" \
  -H "Authorization: Bearer $OSR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "amount_cents": 1, "threshold_cents": 1 }'

{
  "amount_cents": 1,
  "threshold_cents": 1
}

delete/api/v1/billing/wallet/auto-topup

Clear Auto Topup

Turn auto top-up off; forget_card=true also detaches the saved payment method at Stripe.

Requires an API key

curl -s -X DELETE "$OSR_URL/api/v1/billing/wallet/auto-topup?forget_card=false" \
  -H "Authorization: Bearer $OSR_API_KEY"

get/api/v1/billing/wallet/ledger

Ledger

The append-only ledger behind the balance, newest first.

Requires an API key

curl -s "$OSR_URL/api/v1/billing/wallet/ledger?limit=100" \
  -H "Authorization: Bearer $OSR_API_KEY"

post/api/v1/billing/webhook

Webhook

No authentication

curl -s -X POST "$OSR_URL/api/v1/billing/webhook"