Platform billing

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.

MethodPathPurposePermission
GET/merchants/:merchantId/platform/plansActive platform plans with current prices.billing:read
GET/merchants/:merchantId/platform/subscriptionCurrent subscription, outstanding balance and available plans.billing:read
POST/merchants/:merchantId/platform/subscriptionStart a subscription from a platformPlanPriceId.billing:write
POST/merchants/:merchantId/platform/subscription/cancelCancel immediately or at period end.billing:write
POST/merchants/:merchantId/platform/subscription/change-planChange plan immediately or at period end.billing:write
GET/merchants/:merchantId/platform/invoicesPlatform invoices filtered by status and date.billing:read
GET/merchants/:merchantId/platform/invoices/:invoiceIdInvoice with payments, adjustments, usage and attempts.billing:read
POST/merchants/:merchantId/platform/invoices/:invoiceId/finalizePull pending usage into a draft and issue it.billing:write
POST/merchants/:merchantId/platform/invoices/:invoiceId/voidVoid an unpaid invoice.billing:write
GET/merchants/:merchantId/platform/payment-methodsRegistered platform payment methods.billing:read
POST/merchants/:merchantId/platform/payment-methodsRegister a provider payment method token.billing:write

Operator surface

Routes under /platform are restricted to emails listed in PLATFORM_ADMIN_EMAILS.

MethodPathPurposePermission
POST/platform/plansCreate a platform plan.—
PATCH/platform/plans/:planIdUpdate name, description, entitlements or status.—
POST/platform/plans/:planId/pricesPublish a price and close the previous open price for that currency.—
GET/platform/plans/:planId/pricesPrice history.—
POST/platform/prices/:priceId/retireClose a price now or at a supplied date.—
POST/platform/invoices/:invoiceId/paymentsRecord a provider payment result idempotently.—
POST/platform/invoices/:invoiceId/checkoutCreate a hosted checkout for the outstanding balance.—
POST/platform/usage-recordsRecord usage against a platform subscription.—
POST/platform/usage-records/from-paymentDerive usage from a merchant payment using the fee rate.—
GET/platform/billing-jobsList billing jobs.—
POST/platform/billing-jobs/runDrain 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.