181 lines
6.1 KiB
Plaintext
181 lines
6.1 KiB
Plaintext
---
|
|
title: "Balances Track"
|
|
openapi: "openapi POST /v1/balances.track"
|
|
---
|
|
|
|
import { DynamicParamField } from "/components/dynamic-param-field.jsx";
|
|
import { DynamicResponseField } from "/components/dynamic-response-field.jsx";
|
|
import { DynamicResponseExample } from "/components/dynamic-response-example.jsx";
|
|
|
|
### Body Parameters
|
|
|
|
<DynamicParamField body="customer_id" type="string" required>
|
|
ID which you provided when creating the customer
|
|
</DynamicParamField>
|
|
|
|
<DynamicParamField body="feature_id" type="string">
|
|
ID of the feature to track usage for. Required if event_name is not provided. Use this for direct feature tracking.
|
|
</DynamicParamField>
|
|
|
|
<DynamicParamField body="event_name" type="string">
|
|
An [event name](/features/tracking-usage#using-event-names) can be used in place of feature_id. This can be used if multiple features are tracked in the same event.
|
|
</DynamicParamField>
|
|
|
|
<DynamicParamField body="value" type="number">
|
|
The amount of usage to record. Defaults to 1. Can be negative to increase the balance (e.g., when removing a seat).
|
|
</DynamicParamField>
|
|
|
|
<DynamicParamField body="properties" type="object">
|
|
Additional properties to attach to this usage event.
|
|
</DynamicParamField>
|
|
|
|
<DynamicParamField body="idempotency_key" type="string">
|
|
Unique key to prevent duplicate event recording. Use this to safely retry requests without creating duplicate usage records.
|
|
</DynamicParamField>
|
|
|
|
<DynamicParamField body="entity_id" type="string">
|
|
If using [entity balances](/features/feature-entities) (eg, seats), the entity ID to track usage for.
|
|
</DynamicParamField>
|
|
|
|
|
|
### Response
|
|
|
|
<DynamicResponseField name="customer_id" type="string">
|
|
The ID of the customer
|
|
</DynamicResponseField>
|
|
|
|
<DynamicResponseField name="entity_id" type="string">
|
|
The ID of the entity (if provided)
|
|
</DynamicResponseField>
|
|
|
|
<DynamicResponseField name="event_name" type="string">
|
|
The name of the event
|
|
</DynamicResponseField>
|
|
|
|
<DynamicResponseField name="value" type="number" />
|
|
|
|
<DynamicResponseField name="balance" type="object | null">
|
|
<Expandable title="properties">
|
|
<DynamicResponseField name="object" type="any" />
|
|
|
|
<DynamicResponseField name="feature_id" type="string" />
|
|
|
|
<DynamicResponseField name="feature" type="object">
|
|
<Expandable title="properties">
|
|
<DynamicResponseField name="id" type="string" />
|
|
|
|
<DynamicResponseField name="name" type="string" />
|
|
|
|
<DynamicResponseField name="type" type="'boolean' | 'metered' | 'credit_system'" />
|
|
|
|
<DynamicResponseField name="consumable" type="boolean" />
|
|
|
|
<DynamicResponseField name="event_names" type="string[]" />
|
|
|
|
<DynamicResponseField name="credit_schema" type="object[]">
|
|
<Expandable title="properties">
|
|
<DynamicResponseField name="metered_feature_id" type="string" />
|
|
|
|
<DynamicResponseField name="credit_cost" type="number" />
|
|
|
|
</Expandable>
|
|
</DynamicResponseField>
|
|
|
|
<DynamicResponseField name="display" type="object">
|
|
<Expandable title="properties">
|
|
<DynamicResponseField name="singular" type="string | null" />
|
|
|
|
<DynamicResponseField name="plural" type="string | null" />
|
|
|
|
</Expandable>
|
|
</DynamicResponseField>
|
|
|
|
<DynamicResponseField name="archived" type="boolean" />
|
|
|
|
</Expandable>
|
|
</DynamicResponseField>
|
|
|
|
<DynamicResponseField name="granted" type="number" />
|
|
|
|
<DynamicResponseField name="remaining" type="number" />
|
|
|
|
<DynamicResponseField name="usage" type="number" />
|
|
|
|
<DynamicResponseField name="unlimited" type="boolean" />
|
|
|
|
<DynamicResponseField name="overage_allowed" type="boolean" />
|
|
|
|
<DynamicResponseField name="max_purchase" type="number | null" />
|
|
|
|
<DynamicResponseField name="next_reset_at" type="number | null" />
|
|
|
|
<DynamicResponseField name="breakdown" type="object[]">
|
|
<Expandable title="properties">
|
|
<DynamicResponseField name="object" type="any" />
|
|
|
|
<DynamicResponseField name="id" type="string" />
|
|
|
|
<DynamicResponseField name="plan_id" type="string | null" />
|
|
|
|
<DynamicResponseField name="included_grant" type="number" />
|
|
|
|
<DynamicResponseField name="prepaid_grant" type="number" />
|
|
|
|
<DynamicResponseField name="remaining" type="number" />
|
|
|
|
<DynamicResponseField name="usage" type="number" />
|
|
|
|
<DynamicResponseField name="unlimited" type="boolean" />
|
|
|
|
<DynamicResponseField name="reset" type="object | null">
|
|
<Expandable title="properties">
|
|
<DynamicResponseField name="interval" type="'one_off' | 'minute' | 'hour' | 'day' | 'week' | 'month' | 'quarter' | 'semi_annual' | 'year'" />
|
|
|
|
<DynamicResponseField name="interval_count" type="number" />
|
|
|
|
<DynamicResponseField name="resets_at" type="number | null" />
|
|
|
|
</Expandable>
|
|
</DynamicResponseField>
|
|
|
|
<DynamicResponseField name="price" type="object | null">
|
|
<Expandable title="properties">
|
|
<DynamicResponseField name="amount" type="number" />
|
|
|
|
<DynamicResponseField name="tiers" type="object[]">
|
|
<Expandable title="properties">
|
|
<DynamicResponseField name="to" type="number" />
|
|
|
|
<DynamicResponseField name="amount" type="number" />
|
|
|
|
</Expandable>
|
|
</DynamicResponseField>
|
|
|
|
<DynamicResponseField name="billing_units" type="number" />
|
|
|
|
<DynamicResponseField name="billing_method" type="'prepaid' | 'usage_based'" />
|
|
|
|
<DynamicResponseField name="max_purchase" type="number | null" />
|
|
|
|
</Expandable>
|
|
</DynamicResponseField>
|
|
|
|
<DynamicResponseField name="expires_at" type="number | null" />
|
|
|
|
</Expandable>
|
|
</DynamicResponseField>
|
|
|
|
<DynamicResponseField name="rollovers" type="object[]">
|
|
<Expandable title="properties">
|
|
<DynamicResponseField name="balance" type="number" />
|
|
|
|
<DynamicResponseField name="expires_at" type="number" />
|
|
|
|
</Expandable>
|
|
</DynamicResponseField>
|
|
|
|
</Expandable>
|
|
</DynamicResponseField>
|
|
|
|
<DynamicResponseField name="balances" type="object" />
|