API REFERENCE
Platform billing
The billing Sobtra runs for its own customers. It is separate from the merchant billing surface and uses its own plans, prices, invoices and jobs.
Merchant surface
Members of a merchant can read their own platform subscription and invoices. Reads need billing:read, writes need billing:write.
| Method | Path | Purpose | Permission |
|---|---|---|---|
| GET | /merchants/:merchantId/platform/plans | Active platform plans with current prices. | billing:read |
| GET | /merchants/:merchantId/platform/subscription | Current subscription, outstanding balance and available plans. | billing:read |
| POST | /merchants/:merchantId/platform/subscription | Start a subscription from a platformPlanPriceId. | billing:write |
| POST | /merchants/:merchantId/platform/subscription/cancel | Cancel immediately or at period end. | billing:write |
| POST | /merchants/:merchantId/platform/subscription/change-plan | Change plan immediately or at period end. | billing:write |
| GET | /merchants/:merchantId/platform/invoices | Platform invoices filtered by status and date. | billing:read |
| GET | /merchants/:merchantId/platform/invoices/:invoiceId | Invoice with payments, adjustments, usage and attempts. | billing:read |
| POST | /merchants/:merchantId/platform/invoices/:invoiceId/finalize | Pull pending usage into a draft and issue it. | billing:write |
| POST | /merchants/:merchantId/platform/invoices/:invoiceId/void | Void an unpaid invoice. | billing:write |
| GET | /merchants/:merchantId/platform/payment-methods | Registered platform payment methods. | billing:read |
| POST | /merchants/:merchantId/platform/payment-methods | Register a provider payment method token. | billing:write |
Operator surface
Routes under /platform are restricted to emails listed in PLATFORM_ADMIN_EMAILS.
| Method | Path | Purpose | Permission |
|---|---|---|---|
| POST | /platform/plans | Create a platform plan. | — |
| PATCH | /platform/plans/:planId | Update name, description, entitlements or status. | — |
| POST | /platform/plans/:planId/prices | Publish a price and close the previous open price for that currency. | — |
| GET | /platform/plans/:planId/prices | Price history. | — |
| POST | /platform/prices/:priceId/retire | Close a price now or at a supplied date. | — |
| POST | /platform/invoices/:invoiceId/payments | Record a provider payment result idempotently. | — |
| POST | /platform/invoices/:invoiceId/checkout | Create a hosted checkout for the outstanding balance. | — |
| POST | /platform/usage-records | Record usage against a platform subscription. | — |
| POST | /platform/usage-records/from-payment | Derive usage from a merchant payment using the fee rate. | — |
| GET | /platform/billing-jobs | List billing jobs. | — |
| POST | /platform/billing-jobs/run | Drain due billing jobs. | — |
Proration and credits
An immediate plan change creates a proration invoice. The base fee is the prorated new plan fee for the remaining period, the adjustment is the negated unused value of the old plan, and the total is the net. A net credit writes a credit adjustment and a credit balance rather than a negative charge.
Payment recording
A payment body accepts amount, currency, status (pending, processing, succeeded, failed), providerPaymentId, providerReference, failureReason, platformPaymentMethodId and idempotencyKey. Succeeded payments reconcile the amount paid and clear restriction state; failed payments schedule a retry job 24 hours out, once per invoice.
Billing jobs
The worker and the run endpoint process invoice_finalization, usage_aggregation, subscription_renewal, subscription_cancellation and subscription_restriction. Provider-side job types are left to the provider integration.