Skip to main content
Usage endpoints let you track and bill metered consumption. Each customer has a credit balance per product — you deduct credits as they use your service, grant credits when they top up, and refund credits when needed. Only works with metered products.

​
The credit balance object

​
id
string
Unique identifier for this balance record.
​
customer_id
string
The customer this balance belongs to.
​
product_id
string
The product this balance is tied to.
​
balance
number
Current available credits.
​
consumed
number
Total credits consumed to date.
​
granted
number
Total credits granted to date.
​
created_at
string
ISO 8601 timestamp.
​
updated_at
string
ISO 8601 timestamp.

​
Get balance

GET /customers/{customer_id}/credits/{product_id} Returns the current credit balance for a customer on a given product. 
curl https://api.stellartools.dev/customers/cus_01jx.../credits/prod_01jx... \
  -H "x-api-key: YOUR_API_KEY"

​
Ingest usage

POST /customers/{customer_id}/credits/{product_id}/transaction Deduct, refund, or grant credits. Pass dry_run: true to check if the customer has enough credits without committing anything. 
curl -X POST https://api.stellartools.dev/customers/cus_01jx.../credits/prod_01jx.../transaction \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "amount": 5000,
    "type": "deduct"
  }'

​
Body

​
amount
number
required
Raw usage amount in the product’s native unit (e.g. tokens, requests). Converted to credits automatically based on the product’s units_per_credit setting.
​
type
string
required
One of deduct, refund, or grant.
​
dry_run
boolean
If true, checks credit sufficiency without making any changes. Returns is_sufficient and remaining_balance instead of the normal response.
​
reason
string
Optional description of why this transaction occurred.
​
metadata
object
Arbitrary key-value data to attach to the transaction.

​
Response

{
  "balance": 4950,
  "billed_units": 5000,
  "credits_deducted": 50
}
​
balance
number
New credit balance after the transaction.
​
billed_units
number
The raw usage amount you passed in.
​
credits_deducted
number
Credits actually consumed (converted from raw units).