Sign in

v1

latestOpenAPI 3.1.02026-07-265817860.8 KB

Records usage for a customer feature and returns updated balances.

Use this after an action happens to decrement usage, or send a negative value to credit balance back.

post/v1/balances.track

Headers

x-api-versionstring required

Request body

customer_idstring required

The ID of the customer.

feature_idstring

The ID of the feature to track usage for. Required if event_name is not provided.

entity_idstring

The ID of the entity for entity-scoped balances (e.g., per-seat limits).

event_namestring

Event name to track usage for. Use instead of feature_id when multiple features should be tracked from a single event.

valuenumber

The amount of usage to record. Defaults to 1. Use negative values to credit balance (e.g., when removing a seat).

propertiesobject

Additional properties to attach to this usage event.

timestampinteger

Unix timestamp in milliseconds to use for the usage event. Defaults to the current time.

overage_behavior'cap' | 'overflow'

How to handle usage that exceeds the available balance. "cap" (default) deducts only what fits, stopping at zero. "overflow" deducts the full value: the balance can go negative and usage limits do not clamp the deduction, though spend limits still apply.

asyncboolean

If true, enqueue the event for asynchronous processing and return 204 immediately. The response will not include balance information.

Example request

{
  "customer_id": "cus_123",
  "feature_id": "messages",
  "value": 1
}

Response

OK

customer_idstring required

The ID of the customer whose usage was tracked.

entity_idstring

The ID of the entity, if entity-scoped tracking was performed.

event_namestring

The event name that was tracked, if event_name was used instead of feature_id.

valuenumber required

The amount of usage that was recorded.

balancesobject

Map of feature_id to updated balance for the tracked feature and any related features (e.g. linked credit systems). Value is null when the customer has no balance for that feature.

Example response

{
  "customer_id": "cus_123",
  "value": 1,
  "balance": {
    "feature_id": "messages",
    "granted": 100,
    "remaining": 72,
    "usage": 28,
    "unlimited": false,
    "overage_allowed": false,
    "max_purchase": null,
    "next_reset_at": 1773851121437,
    "breakdown": [
      {
        "id": "cus_ent_39qmLooixXLAqMywgXywjAz96rV",
        "plan_id": "pro_plan",
        "included_grant": 100,
        "prepaid_grant": 0,
        "remaining": 72,
        "usage": 28,
        "unlimited": false,
        "reset": {
          "interval": "month",
          "resets_at": 1773851121437
        },
        "price": null,
        "expires_at": null
      }
    ]
  },
  "deductions": [
    {
      "balance_id": "cus_ent_3DdSDoyFmoA9Neecl2a2Gc507X2",
      "feature_id": "messages",
      "plan_id": "pro",
      "reset": {
        "interval": "month",
        "resets_at": 1781288736881
      },
      "value": 1
    }
  ]
}