Sign in

v1

latestOpenAPI 3.1.02026-07-265817860.8 KB

Checks whether a customer currently has enough balance to use a feature.

Use this to gate access before a feature action. Enable sendEvent when you want to check and consume balance atomically in one request.

post/v1/balances.check

Headers

x-api-versionstring required

Request body

customer_idstring required

The ID of the customer.

feature_idstring required

The ID of the feature.

entity_idstring

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

required_balancenumber

Minimum balance required for access. Returns allowed: false if the customer's balance is below this value. Defaults to 1.

propertiesobject

Additional properties to attach to the usage event if send_event is true.

send_eventboolean

If true, atomically records a usage event while checking access. The required_balance value is used as the usage amount. Combines check + track in one call.

with_previewboolean

If true, includes upgrade/upsell information in the response when access is denied. Useful for displaying paywalls.

Example request

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

Response

OK

allowedboolean required

Whether the customer is allowed to use the feature. True if they have sufficient balance or the feature is unlimited/boolean.

customer_idstring required

The ID of the customer that was checked.

entity_idstring nullable

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

required_balancenumber

The required balance that was checked against.

balancesobject

Map of feature_id to balance for the checked feature and any related features (e.g. linked credit systems).

Example response

{
  "allowed": true,
  "customer_id": "cus_123",
  "entity_id": null,
  "required_balance": 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
      }
    ]
  }
}