Keyboard shortcuts

Press ← or → to navigate between chapters

Press S or / to search in the book

Press ? to show this help

Press Esc to hide this help

API Reference Overview

The billing platform exposes two API surfaces:

Customer-Facing API (/v1/)

Used by your application to manage subscriptions, send usage events, and retrieve invoices on behalf of your customers.

MethodPathDescription
POST/v1/subscriptionsCreate a subscription
GET/v1/subscriptions/:idGet a subscription
POST/v1/subscriptions/:id/cancelCancel a subscription
GET/v1/subscriptions/:id/invoicesList invoices for subscription
GET/v1/subscriptions/:id/usageGet usage summary
GET/v1/invoices/:idGet an invoice
POST/v1/invoices/:id/finalizeFinalize a draft invoice
POST/v1/eventsIngest a usage event
POST/v1/webhooks/stripeStripe webhook receiver

Admin API (/admin/v1/)

Used by your Finance and Support teams for customer management, invoice operations, and financial reporting.

MethodPathDescription
GET/admin/v1/customersList all customers
POST/admin/v1/customersCreate customer
GET/admin/v1/customers/:idCustomer 360 view
GET/admin/v1/customers/:id/hierarchyEntity hierarchy
GET/admin/v1/customers/:id/creditsList wallet credits
POST/admin/v1/customers/:id/creditsIssue wallet credit
GET/admin/v1/customers/:id/alertsList spend alerts
POST/admin/v1/customers/:id/alertsCreate spend alert
POST/admin/v1/customers/:id/alerts/:aid/resetReset triggered alert
GET/admin/v1/invoicesList invoices
GET/admin/v1/invoices/:idGet invoice
POST/admin/v1/invoices/:id/voidVoid invoice
POST/admin/v1/invoices/:id/finalizeFinalize invoice
POST/admin/v1/invoices/:id/payMark paid
POST/admin/v1/invoices/:id/credit-noteIssue credit note
POST/admin/v1/invoices/:id/calculate-taxApply tax
POST/admin/v1/subscriptions/:id/pausePause subscription
POST/admin/v1/subscriptions/:id/resumeResume subscription
POST/admin/v1/subscriptions/:id/billManual billing run
GET/admin/v1/catalog/productsList products
POST/admin/v1/catalog/productsCreate product
GET/admin/v1/catalog/plansList plans
POST/admin/v1/catalog/plansCreate plan
POST/admin/v1/catalog/skusCreate SKU
GET/admin/v1/reports/ar-agingAR aging report
GET/admin/v1/reports/mrrMRR/ARR report
GET/admin/v1/auditAudit log
GET/admin/v1/audit/:entity_type/:entity_idEntity audit trail

OpenAPI Spec

The full OpenAPI 3.0 specification is available at:

  • JSON: https://api.bill.sh/openapi.json
  • Redoc UI: https://api.bill.sh/docs/api

Base URLs

EnvironmentBase URL
Productionhttps://api.bill.sh
Local devhttp://localhost:3000