Usage, invoices, and API
Billing usage, invoice, and payment readiness views help Builders understand whether customer billing data is being retained, whether the app has invoice state to review, and what remains before paid customer flows are enabled.
The launch surface is intentionally provider-neutral. Switera shows customer, plan, subscription, usage, invoice, and collection concepts without exposing internal billing engine identifiers.
Usage meters
Usage meters summarize retained billable events for one app. The Billing page shows:
- meter name
- net quantity
- pending quantity
- delivered quantity
- failed quantity
- event count
- number of organizations represented
- last event timestamp
Initial metering exists for Storage, Managed Data, managed app Email sends, production custom Webhook emits, and authenticated app API requests made with secret app keys. Other product meters are tracked in the Billing roadmap.
Invoice visibility
The Collection status panel is read-only. It shows invoices when invoice records exist for synced billing customers.
Invoice rows expose:
- invoice number
- billing customer
- issue date
- due date
- invoice status
- payment status
- total amount
- open amount
- overdue state
Payment collection setup, customer payment portal actions, dunning, and full reconciliation remain launch work. Treat invoice visibility as operational status, not as the full customer billing portal.
Payment collection readiness
The overview response includes a payment_provider object. It gives the Billing page a conservative readiness state, a next action, and a checklist for customer mapping, active plan setup, customer assignments, invoice visibility, and payment collection.
Use this object to decide whether an app is ready for test payment collection. Do not treat it as a customer checkout API.
Billing webhook events
Switera emits Billing lifecycle events through the app-level Webhooks service after successful local writes:
| Event | When it fires |
|---|---|
sf.billing.plan.created | A plan is created. |
sf.billing.plan.updated | A plan is updated. |
sf.billing.plan.archived | A plan is archived. |
sf.billing.subscription.created | A customer assignment is created. |
sf.billing.subscription.updated | A customer assignment is updated. |
sf.billing.subscription.canceled | A customer assignment is canceled. |
Webhook payloads use Switera Billing concepts and omit internal billing engine IDs.
API route map
Billing API routes are app-scoped and require a trusted secret app key with manage_settings scope.
| Action | Route |
|---|---|
| Overview | GET /api/v1/apps/{appId}/billing/overview |
| List customers | GET /api/v1/apps/{appId}/billing/customers |
| Sync organizations into Billing | POST /api/v1/apps/{appId}/billing/customers/sync-tenants |
| List plans | GET /api/v1/apps/{appId}/billing/plans |
| Create plan | POST /api/v1/apps/{appId}/billing/plans |
| Update plan | PUT /api/v1/apps/{appId}/billing/plans/{planId} |
| Archive plan | POST /api/v1/apps/{appId}/billing/plans/{planId}/archive |
| List subscriptions | GET /api/v1/apps/{appId}/billing/subscriptions |
| Create subscription | POST /api/v1/apps/{appId}/billing/subscriptions |
| Update subscription | PUT /api/v1/apps/{appId}/billing/subscriptions/{subscriptionId} |
| Cancel subscription | POST /api/v1/apps/{appId}/billing/subscriptions/{subscriptionId}/cancel |
| List invoices | GET /api/v1/apps/{appId}/billing/invoices |
Overview response
The overview endpoint returns the data used by the Billing page:
curl "https://switera.com/api/v1/apps/$APP_ID/billing/overview" \
-H "Authorization: Bearer $SWITERA_SECRET_KEY"
Important fields:
| Field | Meaning |
|---|---|
customer_summary | Customer mapping totals and sync status. |
plan_summary | Total, active, draft, and archived plan counts. |
subscription_summary | Total assignments by lifecycle state. |
invoice_summary | Invoice and collection totals. |
payment_provider | Provider-neutral payment collection readiness, next action, and setup checks. |
meters | Usage rollups by meter name. |
recent_events | Latest retained usage events. |
recent_customers | Recently mapped billing customers. |
plans | Current plan catalog preview. |
recent_subscriptions | Recent customer assignments. |
recent_invoices | Recent invoice status rows. |
launch_gaps | Remaining launch work visible to Builders. |
Common failures
| Response or symptom | Check |
|---|---|
401 Unauthorized | Missing, malformed, expired, or non-secret app key. |
403 Forbidden | Key lacks manage_settings, belongs to a different app, or is outside its allowed IP range. |
409 Plan code already exists | Use a different stable plan code or update the existing plan. |
409 Customer already has a current billing subscription | Update or cancel the current assignment first. |
| Empty invoices | No invoice records exist yet for synced billing customers. |
Payment collection shows setup_required | Complete customer mapping, active plan setup, customer assignment, invoice visibility, and test payment verification. |
| Empty usage meters | No billable usage has been retained for the app yet. |
Related pages: