API Credits & Usage

How API requests consume credits, how credits are allocated, and how to monitor your balance.

Claret meters API usage with credits. Each request deducts a fixed number of credits based on the kind of work it does. Credits are allocated monthly per tenant.

Cost categories

Every endpoint belongs to a cost category. The cost is flat per request; it does not scale with the number of rows returned or submitted.

Category	Credits / request	Endpoints
Reference data	1	GET on master data (items, uoms, calendars, locations, customer groups, etc.)
Transactional data	5	GET on sales, inventory, supply plans, financial plans
Import	10	File-based import endpoints
Compute	50	Supply plan and forecast generation
Free	0	Job status, token management, credit utilities

A few compute and batch endpoints carry an explicit higher cost that reflects the work they trigger: batch supply plan generation is 200, forecast generation is 100, and generate-all forecasts is 500.

Allocation and rollover

• Each tenant receives a monthly credit allocation (the default is generous and sized well above expected usage).

• Unused credits roll over month to month, up to a cap of 3× the monthly allocation. Credits above that cap do not accumulate.

• Allocations refresh automatically each month; there is nothing to renew.

Credits are allocated monthly. If a tenant consistently approaches its allocation, contact [e-mail] to review the allocation.

Monitoring your balance

Every metered response reports credit usage in two places.

Response headers:

Header	Meaning
X-Api-Credits-Used	Credits deducted by this request.
X-Api-Credits-Remaining	Credits left in the tenant's balance after this request.

Response envelope (meta.credits):

{
  "message": "Items retrieved.",
  "data": { "items": [] },
  "meta": {
    "credits": { "cost": 1, "remaining": 9998999 }
  },
  "links": {}
}

The Usage dashboard

In the Claret app, Settings → Workspace Settings → API Access → Usage (Workspace Admins only) gives a fuller picture. Four cards summarize the account:

• Credit Balance — credits available right now.

• Monthly Allocation — credits granted each month.

• Rollover Cap — the ceiling unused credits can accumulate to.

• Next Allocation — days until credits refresh.

The Usage tab with balance cards, chart, and transaction history

Below the cards, a chart plots credits used over time (Daily, Weekly, or Monthly), and a Transaction History grid lists each allocation and deduction. Rows that bundle a day's activity are clickable, opening a drill-down that itemizes the individual API calls — amount, endpoint, request ID, and time — behind that line.

Drilling into the API calls behind a day's credit usage

For a request-by-request audit trail (timestamp, token, endpoint, method, status, credits, response time), use the Query Log tab.

The Query Log tab listing every API request

Running out of credits

When a tenant's balance cannot cover a request, the request is rejected with 402 Payment Required and no work is performed. Wait for the monthly refresh, or contact support to review the allocation.

Free-category endpoints (job status, token management) are never blocked by a low balance, so an integration can always check the status of work it already submitted.

Dry runs

Write, compute, and workflow endpoints accept a dry_run flag (or the X-Dry-Run: true header). A dry-run request validates the payload without performing the work and does not consume credits. Use it to check a payload before committing.

Related documentation

• Scopes Reference — which scope each endpoint type requires.

• Rate Limiting — request-rate limits, separate from credits.

• Error Reference — handling 402 and other statuses.