Everything you need to integrate UsageBox into your product—from authentication to billing workflows.
UsageBox is a usage-based billing platform that helps you track consumption, rate events, and invoice customers automatically. Use this guide to learn the building blocks and wire the API into your stack in minutes.
The minimum viable integration is a meter, an API key, and one HTTP request. You can set up products, plans, and customers later.
curl -X POST https://api.usagebox.com/api/v1/usage \
-H 'x-api-key: YOUR_API_KEY' \
-H 'Content-Type: application/json' \
-d '[{
"subscription": "sub.your-subscription",
"product_item": "item.your-product-item",
"meter": "meter.api-requests",
"value": 42
}]'A 200 with "Usage batch accepted" means the event is queued for aggregation.subscription and product_item values are ingest keys from your catalog. Events referencing keys that don't exist yet are accepted but skipped during aggregation — set up the catalog (below) to see numbers move.Group your resources by environment or product line. Projects let you isolate data, credentials, and configuration.
Represent the services you sell. Each product can expose multiple plans that define how customers are billed.
Attach pricing to a product. Plans define recurring charges, included usage, and overage rules for subscriptions.
Capture the raw usage signals you want to bill on—API calls, seats, bandwidth, or any measurable unit.
Store account details for the companies or users you bill. Customers can hold multiple active subscriptions.
Connect customers to a plan. Subscriptions keep track of lifecycle state, usage accumulation, and invoicing windows.
Send granular events through the API so UsageBox can rate them against the correct pricing model in real time.
Authenticate requests to the UsageBox API. Rotate keys per environment and restrict them to the projects they serve.
UsageBox exposes a RESTful API. All requests are scoped to the active project and use JSON payloads.
https://api.usagebox.com/v1/Authenticate with API keys from the dashboard. Provide the key in the Authorization header on every request:
Authorization: Bearer your-api-keyDefine what you sell and how you price it. Products and plans—with embedded entitlement limits—describe your catalog.
POST /api/v1/products with a name and reference code. Products act as the parent container for plans.
Use POST /api/v1/plans to configure billing cadence, base price, and usage tiers aligned with your pricing model.
Add entitlement fields on each plan document to toggle capabilities and quota limits exposed in the dashboard.
curl -X POST https://api.usagebox.com/v1/products \
-H 'Authorization: Bearer <api_key>' \
-H 'Content-Type: application/json' \
-d '{ "name": "Pro API", "code": "pro-api" }'Track consumption in real time by wiring your application telemetry to UsageBox meters.
Create meters with POST /api/v1/meters, specifying unit names, aggregation, and the products they belong to.
POST /api/v1/usage with batches of events. Each event references a meter, subscription, and quantity.
Use GET /api/v1/activity or the dashboard to confirm UsageBox is applying pricing and usage limits correctly.
curl -X POST https://api.usagebox.com/v1/usage \
-H 'Authorization: Bearer <api_key>' \
-H 'Content-Type: application/json' \
-d '{
"events": [
{
"subscription_id": "sub_123",
"meter_id": "mtr_compute",
"quantity": 150,
"occurred_at": "2024-05-01T12:00:00Z"
}
]
}'Provision customers, activate subscriptions, and keep billing state synchronized with downstream systems.
POST /api/v1/customers with the identifiers you use in your product (corporate ID, domain, or UUID).
POST /api/v1/subscriptions to connect a customer, plan, and optional trial or contract metadata.
PATCH /api/v1/subscriptions/{id} to pause, resume, or update terms without losing historical usage.
curl -X POST https://api.usagebox.com/v1/subscriptions \
-H 'Authorization: Bearer <api_key>' \
-H 'Content-Type: application/json' \
-d '{
"customer_id": "cust_456",
"plan_id": "plan_usage_plus",
"starts_at": "2024-05-01",
"external_reference": "crm-789"
}'| Endpoint | Methods | Description |
|---|---|---|
/api/v1/projects | GET, PATCH | Fetch your projects and select an active project. |
/api/v1/products | GET, POST | List and create products in the active project. |
/api/v1/plans | GET, POST | Manage plans and pricing tiers linked to products. |
/api/v1/meters | GET, POST | Create meters and inspect meter configuration. |
/api/v1/customers | GET, POST | Create customers and fetch their billing profile. |
/api/v1/subscriptions | GET, POST, PATCH | Start, update, or view subscription lifecycle state. |
/api/v1/usage | POST | Submit usage events for metered billing. |
/api/v1/api-keys | GET, POST, DELETE | Rotate API credentials and manage access. |
/api/v1/activity | GET | Inspect rating outcomes, charges, and events. |
Use our official SDKs for quick integrations.
Documentation evolves as the platform does. Reach out if you have questions or want to share feedback.
Create an account, generate an API key, and start metering usage today.
Create Free Account