Subscription, budget & usage
Keep the workspace subscription, advertising funds, and integration activity distinct.
Three separate measurements
| Measurement | What it represents | Where to read it |
|---|---|---|
| Subscription | The workspace's SaaS entitlement | get_subscription |
| Ad wallet | Funding available for advertising | list_campaigns |
| Integration usage | Admitted REST/MCP operations over 30 days | get_usage |
The public API introduces no additional usage price. Current subscription terms are shown in checkout; the API does not define a separate price plan.
Subscribe through the owner flow
curl -X POST https://api.benjiads.com/v1/billing/checkout \
-H "Authorization: Bearer $BENJIADS_API_KEY" \
-H "Idempotency-Key: subscription-handoff-001"The response is a URL with action: "complete_in_browser". Open it for the owner, who signs in, reviews the terms, and authorizes checkout. An existing subscriber can manage billing there.
Poll get_subscription afterward. Returning from the browser or receiving a checkout URL is not proof of payment. Rights come from server-verified Stripe state and signed billing events.
Advertising money
Wallet amounts are USD cents in the BenjiAds customer-facing accounting unit.
balanceCents: cumulative credited advertising funding.spentLifetimeCents: lifetime spend used by the balance calculation.remainingCents: funds currently available for advertising.spentCents: spend for the selected reporting period.
The provider-to-wallet conversion is already applied at the existing boundary. Do not add it again. If the provider is unavailable, reports can fall back to stored spend values.
Advertising funding uses the dashboard. A top-up cannot override a billing pause, a license hold, or incomplete campaign preparation. Included advertising credit is granted once per owner account.
Failed or cancelled subscriptions
Existing billing rules pause delivery on failed payment or cancellation. Launch checks inspect entitlement and the billing pause separately from the wallet balance. Repair billing before retrying an activation with a new action key.
Use list_invoices for invoices associated with the workspace's BenjiAds subscription.