Documentation

Quickstart: your first event in 5 minutes

The minimum viable integration is a meter, an API key, and one HTTP request. You can set up products, plans, and customers later.

1. Create a meter — the unit you want to track (API requests, tokens, gigabytes). The quick templates take one click.
2. Create an API key — after creating it you get a personalized version of the command below, pre-filled with your real ingest keys.
3. Send a usage event from your terminal or server:

   curl -X POST https://api.usagebox.com/api/v1/usage \
     -H 'x-api-key: YOUR_API_KEY' \
     -H "Idempotency-Key: $(uuidgen)" \
     -H 'Content-Type: application/json' \
     -d '[{
       "value": 42
     }]'

   A 200 with "processed": 1 means the event was recorded. Reuse the sameIdempotency-Key if the request needs a retry.
4. Watch it land — aggregated usage appears per meter and month within about a minute.

Core Concepts

API Overview

UsageBox exposes a RESTful API. All requests are scoped to the active project and use JSON payloads.

Authentication

Create an API key in the dashboard and send it as the x-api-key header on every request:

Two other credentials exist and are easy to confuse with this one. Authorization: Bearer … carries a Firebase ID token and is what the web dashboard uses — an API key sent this way will fail. And an X-RapidAPI-Key works only at the RapidAPI gateway, never against this origin; call through the gateway and it handles authentication for you.

Common Workflows

curl -X POST https://api.usagebox.com/api/v1/products \
  -H 'x-api-key: <your_api_key>' \
  -H 'Content-Type: application/json' \
  -d '{ "name": "Pro API", "description": "Metered REST API" }'

curl -X POST https://api.usagebox.com/api/v1/usage \
  -H 'x-api-key: <your_api_key>' \
  -H "Idempotency-Key: $(uuidgen)" \
  -H 'Content-Type: application/json' \
  -d '[{ "value": 150 }]'

curl -X POST https://api.usagebox.com/api/v1/subscriptions \
  -H 'x-api-key: <your_api_key>' \
  -H 'Content-Type: application/json' \
  -d '{
    "customer_account_id": "<customer id from POST /api/v1/customers>",
    "plan_id": "<plan id from GET /api/v1/plans>"
  }'

Key API Endpoints

Send usage from your language

There is no SDK to install. Ingest is one POST with a JSON array, so these are complete — copy one, set UBX_API_KEY, and you are metering.

const res = await fetch('https://api.usagebox.com/api/v1/usage', {
  method: 'POST',
  headers: {
    'x-api-key': process.env.UBX_API_KEY,
    'Idempotency-Key': crypto.randomUUID(),
    'Content-Type': 'application/json'
  },
  body: JSON.stringify([{ meter: 'meter.api-requests', value: 1 }])
})
console.log(await res.json())

import os, uuid, requests

res = requests.post(
    "https://api.usagebox.com/api/v1/usage",
    headers={
        "x-api-key": os.environ["UBX_API_KEY"],
        "Idempotency-Key": str(uuid.uuid4()),
    },
    json=[{"meter": "meter.api-requests", "value": 1}],
)
print(res.json())

body := `[{"meter":"meter.api-requests","value":1}]`
req, _ := http.NewRequest("POST",
    "https://api.usagebox.com/api/v1/usage", strings.NewReader(body))
req.Header.Set("x-api-key", os.Getenv("UBX_API_KEY"))
req.Header.Set("Idempotency-Key", uuid.NewString())
req.Header.Set("Content-Type", "application/json")

res, err := http.DefaultClient.Do(req)

$ch = curl_init('https://api.usagebox.com/api/v1/usage');
curl_setopt_array($ch, [
  CURLOPT_POST => true,
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_HTTPHEADER => [
    'x-api-key: ' . getenv('UBX_API_KEY'),
    'Idempotency-Key: ' . bin2hex(random_bytes(16)),
    'Content-Type: application/json',
  ],
  CURLOPT_POSTFIELDS => json_encode([['meter' => 'meter.api-requests', 'value' => 1]]),
]);
echo curl_exec($ch);

Need Help?

Documentation evolves as the platform does. Reach out if you have questions or want to share feedback.

• OpenAPI specification (JSON)
• Interactive API explorer
• Articles & guides
• [email protected]