1483 lines
61 KiB
Plaintext
1483 lines
61 KiB
Plaintext
---
|
|
title: "Get Customer"
|
|
openapi: "openapi POST /v1/customers.get"
|
|
---
|
|
|
|
import { DynamicParamField } from "/snippets/dynamic-param-field.jsx";
|
|
import { DynamicResponseField } from "/snippets/dynamic-response-field.jsx";
|
|
import { DynamicResponseExample } from "/snippets/dynamic-response-example.jsx";
|
|
|
|
### Body Parameters
|
|
|
|
<DynamicParamField body="customer_id" type="string" required>
|
|
ID of the customer to fetch
|
|
</DynamicParamField>
|
|
|
|
<DynamicParamField body="expand" type="('invoices' | 'trials_used' | 'rewards' | 'entities' | 'referrals' | 'payment_method' | 'subscriptions.plan' | 'purchases.plan' | 'balances.feature' | 'flags.feature' | 'billing_controls.auto_topups.purchase_limit')[]">
|
|
Expand related customer data like invoices or entities, or expand nested objects like balances.feature, flags.feature, subscriptions.plan, and purchases.plan.
|
|
</DynamicParamField>
|
|
|
|
|
|
### Response
|
|
|
|
<DynamicResponseField name="id" type="string | null">
|
|
Your unique identifier for the customer.
|
|
</DynamicResponseField>
|
|
|
|
<DynamicResponseField name="name" type="string | null">
|
|
The name of the customer.
|
|
</DynamicResponseField>
|
|
|
|
<DynamicResponseField name="email" type="string | null">
|
|
The email address of the customer.
|
|
</DynamicResponseField>
|
|
|
|
<DynamicResponseField name="created_at" type="number">
|
|
Timestamp of customer creation in milliseconds since epoch.
|
|
</DynamicResponseField>
|
|
|
|
<DynamicResponseField name="fingerprint" type="string | null">
|
|
A unique identifier (eg. serial number) to de-duplicate customers across devices or browsers. For example: apple device ID.
|
|
</DynamicResponseField>
|
|
|
|
<DynamicResponseField name="stripe_id" type="string | null">
|
|
Stripe customer ID.
|
|
</DynamicResponseField>
|
|
|
|
<DynamicResponseField name="env" type="'sandbox' | 'live'">
|
|
The environment this customer was created in.
|
|
</DynamicResponseField>
|
|
|
|
<DynamicResponseField name="metadata" type="object">
|
|
The metadata for the customer.
|
|
</DynamicResponseField>
|
|
|
|
<DynamicResponseField name="send_email_receipts" type="boolean">
|
|
Whether to send email receipts to the customer.
|
|
</DynamicResponseField>
|
|
|
|
<DynamicResponseField name="billing_controls" type="object">
|
|
Billing controls for the customer (auto top-ups, etc.)
|
|
<Expandable title="properties">
|
|
<DynamicResponseField name="auto_topups" type="object[]">
|
|
List of auto top-up configurations per feature.
|
|
<Expandable title="properties">
|
|
<DynamicResponseField name="feature_id" type="string">
|
|
The ID of the feature (credit balance) to auto top-up.
|
|
</DynamicResponseField>
|
|
|
|
<DynamicResponseField name="enabled" type="boolean">
|
|
Whether auto top-up is enabled.
|
|
</DynamicResponseField>
|
|
|
|
<DynamicResponseField name="threshold" type="number">
|
|
When the balance drops below this threshold, an auto top-up will be purchased.
|
|
</DynamicResponseField>
|
|
|
|
<DynamicResponseField name="quantity" type="number">
|
|
Amount of credits to add per auto top-up.
|
|
</DynamicResponseField>
|
|
|
|
<DynamicResponseField name="purchase_limit" type="object">
|
|
Optional rate limit to cap how often auto top-ups occur. Expand billing_controls.auto_topups.purchase_limit for a count of top ups and the next_reset_at.
|
|
<Expandable title="properties">
|
|
<DynamicResponseField name="interval" type="'hour' | 'day' | 'week' | 'month'">
|
|
The time interval for the purchase limit window.
|
|
</DynamicResponseField>
|
|
|
|
<DynamicResponseField name="interval_count" type="number">
|
|
Number of intervals in the purchase limit window.
|
|
</DynamicResponseField>
|
|
|
|
<DynamicResponseField name="limit" type="number">
|
|
Maximum number of auto top-ups allowed within the interval.
|
|
</DynamicResponseField>
|
|
|
|
</Expandable>
|
|
</DynamicResponseField>
|
|
|
|
<DynamicResponseField name="invoice_mode" type="boolean">
|
|
When true, auto top-up creates a send_invoice invoice instead of auto-charging.
|
|
</DynamicResponseField>
|
|
|
|
</Expandable>
|
|
</DynamicResponseField>
|
|
|
|
<DynamicResponseField name="spend_limits" type="object[]">
|
|
List of overage spend limits per feature.
|
|
<Expandable title="properties">
|
|
<DynamicResponseField name="feature_id" type="string">
|
|
Optional feature ID this spend limit applies to.
|
|
</DynamicResponseField>
|
|
|
|
<DynamicResponseField name="enabled" type="boolean">
|
|
Whether this spend limit is enabled.
|
|
</DynamicResponseField>
|
|
|
|
<DynamicResponseField name="overage_limit" type="number">
|
|
Maximum allowed overage spend for the target feature.
|
|
</DynamicResponseField>
|
|
|
|
</Expandable>
|
|
</DynamicResponseField>
|
|
|
|
<DynamicResponseField name="usage_alerts" type="object[]">
|
|
List of usage alert configurations per feature.
|
|
<Expandable title="properties">
|
|
<DynamicResponseField name="feature_id" type="string">
|
|
The feature ID this alert applies to.
|
|
</DynamicResponseField>
|
|
|
|
<DynamicResponseField name="enabled" type="boolean">
|
|
Whether this usage alert is enabled.
|
|
</DynamicResponseField>
|
|
|
|
<DynamicResponseField name="threshold" type="number">
|
|
The threshold value that triggers the alert. For usage or remaining, this is an absolute count. For usage_percentage or remaining_percentage, this is a percentage (0-100).
|
|
</DynamicResponseField>
|
|
|
|
<DynamicResponseField name="threshold_type" type="'usage' | 'usage_percentage' | 'remaining' | 'remaining_percentage'">
|
|
Whether the threshold is an absolute count or a percentage of the usage allowance or remaining balance.
|
|
</DynamicResponseField>
|
|
|
|
<DynamicResponseField name="name" type="string">
|
|
Optional user-defined label to distinguish multiple alerts on the same feature.
|
|
</DynamicResponseField>
|
|
|
|
</Expandable>
|
|
</DynamicResponseField>
|
|
|
|
<DynamicResponseField name="overage_allowed" type="object[]">
|
|
List of overage allowed controls per feature. When enabled, usage can exceed balance.
|
|
<Expandable title="properties">
|
|
<DynamicResponseField name="feature_id" type="string">
|
|
The feature ID this overage allowed control applies to.
|
|
</DynamicResponseField>
|
|
|
|
<DynamicResponseField name="enabled" type="boolean">
|
|
Whether overage is allowed for this feature.
|
|
</DynamicResponseField>
|
|
|
|
</Expandable>
|
|
</DynamicResponseField>
|
|
|
|
</Expandable>
|
|
</DynamicResponseField>
|
|
|
|
<DynamicResponseField name="subscriptions" type="object[]">
|
|
Active and scheduled recurring plans that this customer has attached.
|
|
<Expandable title="properties">
|
|
<DynamicResponseField name="id" type="string">
|
|
The unique identifier of this subscription. If a subscription_id was provided at attach time, it is used; otherwise, falls back to the internal ID.
|
|
</DynamicResponseField>
|
|
|
|
<DynamicResponseField name="plan" type="object">
|
|
The full plan object if expanded.
|
|
<Expandable title="properties">
|
|
<DynamicResponseField name="id" type="string">
|
|
Unique identifier for the plan.
|
|
</DynamicResponseField>
|
|
|
|
<DynamicResponseField name="name" type="string">
|
|
Display name of the plan.
|
|
</DynamicResponseField>
|
|
|
|
<DynamicResponseField name="description" type="string | null">
|
|
Optional description of the plan.
|
|
</DynamicResponseField>
|
|
|
|
<DynamicResponseField name="group" type="string | null">
|
|
Group identifier for organizing related plans. Plans in the same group are mutually exclusive.
|
|
</DynamicResponseField>
|
|
|
|
<DynamicResponseField name="version" type="number">
|
|
Version number of the plan. Incremented when plan configuration changes.
|
|
</DynamicResponseField>
|
|
|
|
<DynamicResponseField name="add_on" type="boolean">
|
|
Whether this is an add-on plan that can be attached alongside a main plan.
|
|
</DynamicResponseField>
|
|
|
|
<DynamicResponseField name="auto_enable" type="boolean">
|
|
If true, this plan is automatically attached when a customer is created. Used for free plans.
|
|
</DynamicResponseField>
|
|
|
|
<DynamicResponseField name="price" type="object | null">
|
|
Base recurring price for the plan. Null for free plans or usage-only plans.
|
|
<Expandable title="properties">
|
|
<DynamicResponseField name="amount" type="number">
|
|
Base price amount for the plan.
|
|
</DynamicResponseField>
|
|
|
|
<DynamicResponseField name="interval" type="'one_off' | 'week' | 'month' | 'quarter' | 'semi_annual' | 'year'">
|
|
Billing interval (e.g. 'month', 'year').
|
|
</DynamicResponseField>
|
|
|
|
<DynamicResponseField name="interval_count" type="number">
|
|
Number of intervals per billing cycle. Defaults to 1.
|
|
</DynamicResponseField>
|
|
|
|
<DynamicResponseField name="display" type="object">
|
|
Display text for showing this price in pricing pages.
|
|
<Expandable title="properties">
|
|
<DynamicResponseField name="primary_text" type="string">
|
|
Main display text (e.g. '$10' or '100 messages').
|
|
</DynamicResponseField>
|
|
|
|
<DynamicResponseField name="secondary_text" type="string">
|
|
Secondary display text (e.g. 'per month' or 'then $0.5 per 100').
|
|
</DynamicResponseField>
|
|
|
|
</Expandable>
|
|
</DynamicResponseField>
|
|
|
|
</Expandable>
|
|
</DynamicResponseField>
|
|
|
|
<DynamicResponseField name="items" type="object[]">
|
|
Feature configurations included in this plan. Each item defines included units, pricing, and reset behavior for a feature.
|
|
<Expandable title="properties">
|
|
<DynamicResponseField name="feature_id" type="string">
|
|
The ID of the feature this item configures.
|
|
</DynamicResponseField>
|
|
|
|
<DynamicResponseField name="feature" type="object">
|
|
The full feature object if expanded.
|
|
<Expandable title="properties">
|
|
<DynamicResponseField name="id" type="string">
|
|
The ID of the feature, used to refer to it in other API calls like /track or /check.
|
|
</DynamicResponseField>
|
|
|
|
<DynamicResponseField name="name" type="string | null">
|
|
The name of the feature.
|
|
</DynamicResponseField>
|
|
|
|
<DynamicResponseField name="type" type="'static' | 'boolean' | 'single_use' | 'continuous_use' | 'credit_system' | 'ai_credit_system'">
|
|
The type of the feature
|
|
</DynamicResponseField>
|
|
|
|
<DynamicResponseField name="display" type="object | null">
|
|
Singular and plural display names for the feature.
|
|
<Expandable title="properties">
|
|
<DynamicResponseField name="singular" type="string">
|
|
The singular display name for the feature.
|
|
</DynamicResponseField>
|
|
|
|
<DynamicResponseField name="plural" type="string">
|
|
The plural display name for the feature.
|
|
</DynamicResponseField>
|
|
|
|
</Expandable>
|
|
</DynamicResponseField>
|
|
|
|
<DynamicResponseField name="credit_schema" type="object[] | null">
|
|
Credit cost schema for credit system features.
|
|
<Expandable title="properties">
|
|
<DynamicResponseField name="metered_feature_id" type="string">
|
|
The ID of the metered feature (should be a single_use feature).
|
|
</DynamicResponseField>
|
|
|
|
<DynamicResponseField name="credit_cost" type="number">
|
|
The credit cost of the metered feature.
|
|
</DynamicResponseField>
|
|
|
|
</Expandable>
|
|
</DynamicResponseField>
|
|
|
|
<DynamicResponseField name="archived" type="boolean | null">
|
|
Whether or not the feature is archived.
|
|
</DynamicResponseField>
|
|
|
|
</Expandable>
|
|
</DynamicResponseField>
|
|
|
|
<DynamicResponseField name="included" type="number">
|
|
Number of free units included. For consumable features, balance resets to this number each interval.
|
|
</DynamicResponseField>
|
|
|
|
<DynamicResponseField name="unlimited" type="boolean">
|
|
Whether the customer has unlimited access to this feature.
|
|
</DynamicResponseField>
|
|
|
|
<DynamicResponseField name="reset" type="object | null">
|
|
Reset configuration for consumable features. Null for non-consumable features like seats where usage persists across billing cycles.
|
|
<Expandable title="properties">
|
|
<DynamicResponseField name="interval" type="'one_off' | 'minute' | 'hour' | 'day' | 'week' | 'month' | 'quarter' | 'semi_annual' | 'year'">
|
|
The interval at which the feature balance resets (e.g. 'month', 'year'). For consumable features, usage resets to 0 and included units are restored.
|
|
</DynamicResponseField>
|
|
|
|
<DynamicResponseField name="interval_count" type="number">
|
|
Number of intervals between resets. Defaults to 1.
|
|
</DynamicResponseField>
|
|
|
|
</Expandable>
|
|
</DynamicResponseField>
|
|
|
|
<DynamicResponseField name="price" type="object | null">
|
|
Pricing configuration for usage beyond included units. Null if feature is entirely free.
|
|
<Expandable title="properties">
|
|
<DynamicResponseField name="amount" type="number">
|
|
Price per billing_units after included usage is consumed. Mutually exclusive with tiers.
|
|
</DynamicResponseField>
|
|
|
|
<DynamicResponseField name="tiers" type="object[]">
|
|
Tiered pricing configuration. Each tier's 'to' INCLUDES the included amount. Either 'tiers' or 'amount' is required.
|
|
<Expandable title="properties">
|
|
<DynamicResponseField name="to" type="number" />
|
|
|
|
<DynamicResponseField name="amount" type="number" />
|
|
|
|
<DynamicResponseField name="flat_amount" type="number" />
|
|
|
|
</Expandable>
|
|
</DynamicResponseField>
|
|
|
|
<DynamicResponseField name="tier_behavior" type="'graduated' | 'volume'" />
|
|
|
|
<DynamicResponseField name="interval" type="'one_off' | 'week' | 'month' | 'quarter' | 'semi_annual' | 'year'">
|
|
Billing interval for this price. For consumable features, should match reset.interval.
|
|
</DynamicResponseField>
|
|
|
|
<DynamicResponseField name="interval_count" type="number">
|
|
Number of intervals per billing cycle. Defaults to 1.
|
|
</DynamicResponseField>
|
|
|
|
<DynamicResponseField name="billing_units" type="number">
|
|
Number of units per price increment. Usage is rounded UP to the nearest billing_units when billed (e.g. billing_units=100 means 101 usage rounds to 200).
|
|
</DynamicResponseField>
|
|
|
|
<DynamicResponseField name="billing_method" type="'prepaid' | 'usage_based'">
|
|
'prepaid' for features like seats where customers pay upfront, 'usage_based' for pay-as-you-go after included usage.
|
|
</DynamicResponseField>
|
|
|
|
<DynamicResponseField name="max_purchase" type="number | null">
|
|
Maximum units a customer can purchase beyond included. E.g. if included=100 and max_purchase=300, customer can use up to 400 total before usage is capped. Null for no limit.
|
|
</DynamicResponseField>
|
|
|
|
</Expandable>
|
|
</DynamicResponseField>
|
|
|
|
<DynamicResponseField name="display" type="object">
|
|
Display text for showing this item in pricing pages.
|
|
<Expandable title="properties">
|
|
<DynamicResponseField name="primary_text" type="string">
|
|
Main display text (e.g. '$10' or '100 messages').
|
|
</DynamicResponseField>
|
|
|
|
<DynamicResponseField name="secondary_text" type="string">
|
|
Secondary display text (e.g. 'per month' or 'then $0.5 per 100').
|
|
</DynamicResponseField>
|
|
|
|
</Expandable>
|
|
</DynamicResponseField>
|
|
|
|
<DynamicResponseField name="rollover" type="object">
|
|
Rollover configuration for unused units. If set, unused included units roll over to the next period.
|
|
<Expandable title="properties">
|
|
<DynamicResponseField name="max" type="number | null">
|
|
Maximum rollover units. Null for unlimited rollover.
|
|
</DynamicResponseField>
|
|
|
|
<DynamicResponseField name="max_percentage" type="number | null">
|
|
Maximum rollover as a percentage (0-100) of included + prepaid grant. Mutually exclusive with max.
|
|
</DynamicResponseField>
|
|
|
|
<DynamicResponseField name="expiry_duration_type" type="'month' | 'forever'">
|
|
When rolled over units expire.
|
|
</DynamicResponseField>
|
|
|
|
<DynamicResponseField name="expiry_duration_length" type="number">
|
|
Number of periods before expiry.
|
|
</DynamicResponseField>
|
|
|
|
</Expandable>
|
|
</DynamicResponseField>
|
|
|
|
</Expandable>
|
|
</DynamicResponseField>
|
|
|
|
<DynamicResponseField name="free_trial" type="object">
|
|
Free trial configuration. If set, new customers can try this plan before being charged.
|
|
<Expandable title="properties">
|
|
<DynamicResponseField name="duration_length" type="number">
|
|
Number of duration_type periods the trial lasts.
|
|
</DynamicResponseField>
|
|
|
|
<DynamicResponseField name="duration_type" type="'day' | 'month' | 'year'">
|
|
Unit of time for the trial duration ('day', 'month', 'year').
|
|
</DynamicResponseField>
|
|
|
|
<DynamicResponseField name="card_required" type="boolean">
|
|
Whether a payment method is required to start the trial. If true, customer will be charged after trial ends.
|
|
</DynamicResponseField>
|
|
|
|
<DynamicResponseField name="on_end" type="'bill' | 'revert'">
|
|
Behavior when the trial ends. 'bill' charges the customer (default). 'revert' expires the trial and restores the customer's previous plan.
|
|
</DynamicResponseField>
|
|
|
|
</Expandable>
|
|
</DynamicResponseField>
|
|
|
|
<DynamicResponseField name="created_at" type="number">
|
|
Unix timestamp (ms) when the plan was created.
|
|
</DynamicResponseField>
|
|
|
|
<DynamicResponseField name="env" type="'sandbox' | 'live'">
|
|
Environment this plan belongs to ('sandbox' or 'live').
|
|
</DynamicResponseField>
|
|
|
|
<DynamicResponseField name="archived" type="boolean">
|
|
Whether the plan is archived. Archived plans cannot be attached to new customers.
|
|
</DynamicResponseField>
|
|
|
|
<DynamicResponseField name="base_variant_id" type="string | null">
|
|
If this is a variant, the ID of the base plan it was created from.
|
|
</DynamicResponseField>
|
|
|
|
<DynamicResponseField name="config" type="object">
|
|
Miscellaneous plan-level configuration flags.
|
|
<Expandable title="properties">
|
|
<DynamicResponseField name="ignore_past_due" type="boolean">
|
|
If true, entitlements attached to this plan will still reset on schedule even when the customer's product is in a past_due state.
|
|
</DynamicResponseField>
|
|
|
|
</Expandable>
|
|
</DynamicResponseField>
|
|
|
|
<DynamicResponseField name="customer_eligibility" type="object">
|
|
<Expandable title="properties">
|
|
<DynamicResponseField name="trial_available" type="boolean">
|
|
Whether the trial on this plan is available to this customer. For example, if the customer used the trial in the past, this will be false.
|
|
</DynamicResponseField>
|
|
|
|
<DynamicResponseField name="status" type="'active' | 'scheduled'">
|
|
The customer's current status with this plan. 'active' if attached, 'scheduled' if pending activation.
|
|
</DynamicResponseField>
|
|
|
|
<DynamicResponseField name="canceling" type="boolean">
|
|
Whether the customer's active instance of this plan is set to cancel.
|
|
</DynamicResponseField>
|
|
|
|
<DynamicResponseField name="trialing" type="boolean">
|
|
Whether the customer is currently on a free trial of this plan.
|
|
</DynamicResponseField>
|
|
|
|
<DynamicResponseField name="attach_action" type="'activate' | 'upgrade' | 'downgrade' | 'none' | 'purchase'">
|
|
The action that would occur if this plan were attached to the customer.
|
|
</DynamicResponseField>
|
|
|
|
</Expandable>
|
|
</DynamicResponseField>
|
|
|
|
</Expandable>
|
|
</DynamicResponseField>
|
|
|
|
<DynamicResponseField name="plan_id" type="string">
|
|
The unique identifier of the subscribed plan.
|
|
</DynamicResponseField>
|
|
|
|
<DynamicResponseField name="auto_enable" type="boolean">
|
|
Whether the plan was automatically enabled for the customer.
|
|
</DynamicResponseField>
|
|
|
|
<DynamicResponseField name="add_on" type="boolean">
|
|
Whether this is an add-on plan rather than a base subscription.
|
|
</DynamicResponseField>
|
|
|
|
<DynamicResponseField name="status" type="'active' | 'scheduled'">
|
|
Current status of the subscription.
|
|
</DynamicResponseField>
|
|
|
|
<DynamicResponseField name="past_due" type="boolean">
|
|
Whether the subscription has overdue payments.
|
|
</DynamicResponseField>
|
|
|
|
<DynamicResponseField name="canceled_at" type="number | null">
|
|
Timestamp when the subscription was canceled, or null if not canceled.
|
|
</DynamicResponseField>
|
|
|
|
<DynamicResponseField name="expires_at" type="number | null">
|
|
Timestamp when the subscription will expire, or null if no expiry set.
|
|
</DynamicResponseField>
|
|
|
|
<DynamicResponseField name="trial_ends_at" type="number | null">
|
|
Timestamp when the trial period ends, or null if not on trial.
|
|
</DynamicResponseField>
|
|
|
|
<DynamicResponseField name="started_at" type="number">
|
|
Timestamp when the subscription started.
|
|
</DynamicResponseField>
|
|
|
|
<DynamicResponseField name="current_period_start" type="number | null">
|
|
Start timestamp of the current billing period.
|
|
</DynamicResponseField>
|
|
|
|
<DynamicResponseField name="current_period_end" type="number | null">
|
|
End timestamp of the current billing period.
|
|
</DynamicResponseField>
|
|
|
|
<DynamicResponseField name="quantity" type="number">
|
|
Number of units of this subscription (for per-seat plans).
|
|
</DynamicResponseField>
|
|
|
|
<DynamicResponseField name="scope" type="'customer' | 'entity'">
|
|
Whether this subscription is attached at the customer level or entity level.
|
|
</DynamicResponseField>
|
|
|
|
</Expandable>
|
|
</DynamicResponseField>
|
|
|
|
<DynamicResponseField name="purchases" type="object[]">
|
|
One-time purchases made by the customer.
|
|
<Expandable title="properties">
|
|
<DynamicResponseField name="plan" type="object">
|
|
The full plan object if expanded.
|
|
<Expandable title="properties">
|
|
<DynamicResponseField name="id" type="string">
|
|
Unique identifier for the plan.
|
|
</DynamicResponseField>
|
|
|
|
<DynamicResponseField name="name" type="string">
|
|
Display name of the plan.
|
|
</DynamicResponseField>
|
|
|
|
<DynamicResponseField name="description" type="string | null">
|
|
Optional description of the plan.
|
|
</DynamicResponseField>
|
|
|
|
<DynamicResponseField name="group" type="string | null">
|
|
Group identifier for organizing related plans. Plans in the same group are mutually exclusive.
|
|
</DynamicResponseField>
|
|
|
|
<DynamicResponseField name="version" type="number">
|
|
Version number of the plan. Incremented when plan configuration changes.
|
|
</DynamicResponseField>
|
|
|
|
<DynamicResponseField name="add_on" type="boolean">
|
|
Whether this is an add-on plan that can be attached alongside a main plan.
|
|
</DynamicResponseField>
|
|
|
|
<DynamicResponseField name="auto_enable" type="boolean">
|
|
If true, this plan is automatically attached when a customer is created. Used for free plans.
|
|
</DynamicResponseField>
|
|
|
|
<DynamicResponseField name="price" type="object | null">
|
|
Base recurring price for the plan. Null for free plans or usage-only plans.
|
|
<Expandable title="properties">
|
|
<DynamicResponseField name="amount" type="number">
|
|
Base price amount for the plan.
|
|
</DynamicResponseField>
|
|
|
|
<DynamicResponseField name="interval" type="'one_off' | 'week' | 'month' | 'quarter' | 'semi_annual' | 'year'">
|
|
Billing interval (e.g. 'month', 'year').
|
|
</DynamicResponseField>
|
|
|
|
<DynamicResponseField name="interval_count" type="number">
|
|
Number of intervals per billing cycle. Defaults to 1.
|
|
</DynamicResponseField>
|
|
|
|
<DynamicResponseField name="display" type="object">
|
|
Display text for showing this price in pricing pages.
|
|
<Expandable title="properties">
|
|
<DynamicResponseField name="primary_text" type="string">
|
|
Main display text (e.g. '$10' or '100 messages').
|
|
</DynamicResponseField>
|
|
|
|
<DynamicResponseField name="secondary_text" type="string">
|
|
Secondary display text (e.g. 'per month' or 'then $0.5 per 100').
|
|
</DynamicResponseField>
|
|
|
|
</Expandable>
|
|
</DynamicResponseField>
|
|
|
|
</Expandable>
|
|
</DynamicResponseField>
|
|
|
|
<DynamicResponseField name="items" type="object[]">
|
|
Feature configurations included in this plan. Each item defines included units, pricing, and reset behavior for a feature.
|
|
<Expandable title="properties">
|
|
<DynamicResponseField name="feature_id" type="string">
|
|
The ID of the feature this item configures.
|
|
</DynamicResponseField>
|
|
|
|
<DynamicResponseField name="feature" type="object">
|
|
The full feature object if expanded.
|
|
<Expandable title="properties">
|
|
<DynamicResponseField name="id" type="string">
|
|
The ID of the feature, used to refer to it in other API calls like /track or /check.
|
|
</DynamicResponseField>
|
|
|
|
<DynamicResponseField name="name" type="string | null">
|
|
The name of the feature.
|
|
</DynamicResponseField>
|
|
|
|
<DynamicResponseField name="type" type="'static' | 'boolean' | 'single_use' | 'continuous_use' | 'credit_system' | 'ai_credit_system'">
|
|
The type of the feature
|
|
</DynamicResponseField>
|
|
|
|
<DynamicResponseField name="display" type="object | null">
|
|
Singular and plural display names for the feature.
|
|
<Expandable title="properties">
|
|
<DynamicResponseField name="singular" type="string">
|
|
The singular display name for the feature.
|
|
</DynamicResponseField>
|
|
|
|
<DynamicResponseField name="plural" type="string">
|
|
The plural display name for the feature.
|
|
</DynamicResponseField>
|
|
|
|
</Expandable>
|
|
</DynamicResponseField>
|
|
|
|
<DynamicResponseField name="credit_schema" type="object[] | null">
|
|
Credit cost schema for credit system features.
|
|
<Expandable title="properties">
|
|
<DynamicResponseField name="metered_feature_id" type="string">
|
|
The ID of the metered feature (should be a single_use feature).
|
|
</DynamicResponseField>
|
|
|
|
<DynamicResponseField name="credit_cost" type="number">
|
|
The credit cost of the metered feature.
|
|
</DynamicResponseField>
|
|
|
|
</Expandable>
|
|
</DynamicResponseField>
|
|
|
|
<DynamicResponseField name="archived" type="boolean | null">
|
|
Whether or not the feature is archived.
|
|
</DynamicResponseField>
|
|
|
|
</Expandable>
|
|
</DynamicResponseField>
|
|
|
|
<DynamicResponseField name="included" type="number">
|
|
Number of free units included. For consumable features, balance resets to this number each interval.
|
|
</DynamicResponseField>
|
|
|
|
<DynamicResponseField name="unlimited" type="boolean">
|
|
Whether the customer has unlimited access to this feature.
|
|
</DynamicResponseField>
|
|
|
|
<DynamicResponseField name="reset" type="object | null">
|
|
Reset configuration for consumable features. Null for non-consumable features like seats where usage persists across billing cycles.
|
|
<Expandable title="properties">
|
|
<DynamicResponseField name="interval" type="'one_off' | 'minute' | 'hour' | 'day' | 'week' | 'month' | 'quarter' | 'semi_annual' | 'year'">
|
|
The interval at which the feature balance resets (e.g. 'month', 'year'). For consumable features, usage resets to 0 and included units are restored.
|
|
</DynamicResponseField>
|
|
|
|
<DynamicResponseField name="interval_count" type="number">
|
|
Number of intervals between resets. Defaults to 1.
|
|
</DynamicResponseField>
|
|
|
|
</Expandable>
|
|
</DynamicResponseField>
|
|
|
|
<DynamicResponseField name="price" type="object | null">
|
|
Pricing configuration for usage beyond included units. Null if feature is entirely free.
|
|
<Expandable title="properties">
|
|
<DynamicResponseField name="amount" type="number">
|
|
Price per billing_units after included usage is consumed. Mutually exclusive with tiers.
|
|
</DynamicResponseField>
|
|
|
|
<DynamicResponseField name="tiers" type="object[]">
|
|
Tiered pricing configuration. Each tier's 'to' INCLUDES the included amount. Either 'tiers' or 'amount' is required.
|
|
<Expandable title="properties">
|
|
<DynamicResponseField name="to" type="number" />
|
|
|
|
<DynamicResponseField name="amount" type="number" />
|
|
|
|
<DynamicResponseField name="flat_amount" type="number" />
|
|
|
|
</Expandable>
|
|
</DynamicResponseField>
|
|
|
|
<DynamicResponseField name="tier_behavior" type="'graduated' | 'volume'" />
|
|
|
|
<DynamicResponseField name="interval" type="'one_off' | 'week' | 'month' | 'quarter' | 'semi_annual' | 'year'">
|
|
Billing interval for this price. For consumable features, should match reset.interval.
|
|
</DynamicResponseField>
|
|
|
|
<DynamicResponseField name="interval_count" type="number">
|
|
Number of intervals per billing cycle. Defaults to 1.
|
|
</DynamicResponseField>
|
|
|
|
<DynamicResponseField name="billing_units" type="number">
|
|
Number of units per price increment. Usage is rounded UP to the nearest billing_units when billed (e.g. billing_units=100 means 101 usage rounds to 200).
|
|
</DynamicResponseField>
|
|
|
|
<DynamicResponseField name="billing_method" type="'prepaid' | 'usage_based'">
|
|
'prepaid' for features like seats where customers pay upfront, 'usage_based' for pay-as-you-go after included usage.
|
|
</DynamicResponseField>
|
|
|
|
<DynamicResponseField name="max_purchase" type="number | null">
|
|
Maximum units a customer can purchase beyond included. E.g. if included=100 and max_purchase=300, customer can use up to 400 total before usage is capped. Null for no limit.
|
|
</DynamicResponseField>
|
|
|
|
</Expandable>
|
|
</DynamicResponseField>
|
|
|
|
<DynamicResponseField name="display" type="object">
|
|
Display text for showing this item in pricing pages.
|
|
<Expandable title="properties">
|
|
<DynamicResponseField name="primary_text" type="string">
|
|
Main display text (e.g. '$10' or '100 messages').
|
|
</DynamicResponseField>
|
|
|
|
<DynamicResponseField name="secondary_text" type="string">
|
|
Secondary display text (e.g. 'per month' or 'then $0.5 per 100').
|
|
</DynamicResponseField>
|
|
|
|
</Expandable>
|
|
</DynamicResponseField>
|
|
|
|
<DynamicResponseField name="rollover" type="object">
|
|
Rollover configuration for unused units. If set, unused included units roll over to the next period.
|
|
<Expandable title="properties">
|
|
<DynamicResponseField name="max" type="number | null">
|
|
Maximum rollover units. Null for unlimited rollover.
|
|
</DynamicResponseField>
|
|
|
|
<DynamicResponseField name="max_percentage" type="number | null">
|
|
Maximum rollover as a percentage (0-100) of included + prepaid grant. Mutually exclusive with max.
|
|
</DynamicResponseField>
|
|
|
|
<DynamicResponseField name="expiry_duration_type" type="'month' | 'forever'">
|
|
When rolled over units expire.
|
|
</DynamicResponseField>
|
|
|
|
<DynamicResponseField name="expiry_duration_length" type="number">
|
|
Number of periods before expiry.
|
|
</DynamicResponseField>
|
|
|
|
</Expandable>
|
|
</DynamicResponseField>
|
|
|
|
</Expandable>
|
|
</DynamicResponseField>
|
|
|
|
<DynamicResponseField name="free_trial" type="object">
|
|
Free trial configuration. If set, new customers can try this plan before being charged.
|
|
<Expandable title="properties">
|
|
<DynamicResponseField name="duration_length" type="number">
|
|
Number of duration_type periods the trial lasts.
|
|
</DynamicResponseField>
|
|
|
|
<DynamicResponseField name="duration_type" type="'day' | 'month' | 'year'">
|
|
Unit of time for the trial duration ('day', 'month', 'year').
|
|
</DynamicResponseField>
|
|
|
|
<DynamicResponseField name="card_required" type="boolean">
|
|
Whether a payment method is required to start the trial. If true, customer will be charged after trial ends.
|
|
</DynamicResponseField>
|
|
|
|
<DynamicResponseField name="on_end" type="'bill' | 'revert'">
|
|
Behavior when the trial ends. 'bill' charges the customer (default). 'revert' expires the trial and restores the customer's previous plan.
|
|
</DynamicResponseField>
|
|
|
|
</Expandable>
|
|
</DynamicResponseField>
|
|
|
|
<DynamicResponseField name="created_at" type="number">
|
|
Unix timestamp (ms) when the plan was created.
|
|
</DynamicResponseField>
|
|
|
|
<DynamicResponseField name="env" type="'sandbox' | 'live'">
|
|
Environment this plan belongs to ('sandbox' or 'live').
|
|
</DynamicResponseField>
|
|
|
|
<DynamicResponseField name="archived" type="boolean">
|
|
Whether the plan is archived. Archived plans cannot be attached to new customers.
|
|
</DynamicResponseField>
|
|
|
|
<DynamicResponseField name="base_variant_id" type="string | null">
|
|
If this is a variant, the ID of the base plan it was created from.
|
|
</DynamicResponseField>
|
|
|
|
<DynamicResponseField name="config" type="object">
|
|
Miscellaneous plan-level configuration flags.
|
|
<Expandable title="properties">
|
|
<DynamicResponseField name="ignore_past_due" type="boolean">
|
|
If true, entitlements attached to this plan will still reset on schedule even when the customer's product is in a past_due state.
|
|
</DynamicResponseField>
|
|
|
|
</Expandable>
|
|
</DynamicResponseField>
|
|
|
|
<DynamicResponseField name="customer_eligibility" type="object">
|
|
<Expandable title="properties">
|
|
<DynamicResponseField name="trial_available" type="boolean">
|
|
Whether the trial on this plan is available to this customer. For example, if the customer used the trial in the past, this will be false.
|
|
</DynamicResponseField>
|
|
|
|
<DynamicResponseField name="status" type="'active' | 'scheduled'">
|
|
The customer's current status with this plan. 'active' if attached, 'scheduled' if pending activation.
|
|
</DynamicResponseField>
|
|
|
|
<DynamicResponseField name="canceling" type="boolean">
|
|
Whether the customer's active instance of this plan is set to cancel.
|
|
</DynamicResponseField>
|
|
|
|
<DynamicResponseField name="trialing" type="boolean">
|
|
Whether the customer is currently on a free trial of this plan.
|
|
</DynamicResponseField>
|
|
|
|
<DynamicResponseField name="attach_action" type="'activate' | 'upgrade' | 'downgrade' | 'none' | 'purchase'">
|
|
The action that would occur if this plan were attached to the customer.
|
|
</DynamicResponseField>
|
|
|
|
</Expandable>
|
|
</DynamicResponseField>
|
|
|
|
</Expandable>
|
|
</DynamicResponseField>
|
|
|
|
<DynamicResponseField name="plan_id" type="string">
|
|
The unique identifier of the purchased plan.
|
|
</DynamicResponseField>
|
|
|
|
<DynamicResponseField name="expires_at" type="number | null">
|
|
Timestamp when the purchase expires, or null for lifetime access.
|
|
</DynamicResponseField>
|
|
|
|
<DynamicResponseField name="started_at" type="number">
|
|
Timestamp when the purchase was made.
|
|
</DynamicResponseField>
|
|
|
|
<DynamicResponseField name="quantity" type="number">
|
|
Number of units purchased.
|
|
</DynamicResponseField>
|
|
|
|
<DynamicResponseField name="scope" type="'customer' | 'entity'">
|
|
Whether this purchase is attached at the customer level or entity level.
|
|
</DynamicResponseField>
|
|
|
|
</Expandable>
|
|
</DynamicResponseField>
|
|
|
|
<DynamicResponseField name="balances.{key}" type="object">
|
|
Feature balances keyed by feature ID, showing usage limits and remaining amounts.
|
|
<Expandable title="properties">
|
|
<DynamicResponseField name="feature_id" type="string">
|
|
The feature ID this balance is for.
|
|
</DynamicResponseField>
|
|
|
|
<DynamicResponseField name="feature" type="object">
|
|
The full feature object if expanded.
|
|
<Expandable title="properties">
|
|
<DynamicResponseField name="id" type="string">
|
|
The unique identifier for this feature, used in /check and /track calls.
|
|
</DynamicResponseField>
|
|
|
|
<DynamicResponseField name="name" type="string">
|
|
Human-readable name displayed in the dashboard and billing UI.
|
|
</DynamicResponseField>
|
|
|
|
<DynamicResponseField name="type" type="'boolean' | 'metered' | 'credit_system' | 'ai_credit_system'">
|
|
Feature type: 'boolean' for on/off access, 'metered' for usage-tracked features, 'credit_system' for unified credit pools, 'ai_credit_system' for model-based token pricing.
|
|
</DynamicResponseField>
|
|
|
|
<DynamicResponseField name="consumable" type="boolean">
|
|
For metered features: true if usage resets periodically (API calls, credits), false if allocated persistently (seats, storage).
|
|
</DynamicResponseField>
|
|
|
|
<DynamicResponseField name="event_names" type="string[]">
|
|
Event names that trigger this feature's balance. Allows multiple features to respond to a single event.
|
|
</DynamicResponseField>
|
|
|
|
<DynamicResponseField name="credit_schema" type="object[]">
|
|
For credit_system features: maps metered features to their credit costs.
|
|
<Expandable title="properties">
|
|
<DynamicResponseField name="metered_feature_id" type="string">
|
|
ID of the metered feature that draws from this credit system.
|
|
</DynamicResponseField>
|
|
|
|
<DynamicResponseField name="credit_cost" type="number">
|
|
Credits consumed per unit of the metered feature.
|
|
</DynamicResponseField>
|
|
|
|
</Expandable>
|
|
</DynamicResponseField>
|
|
|
|
<DynamicResponseField name="model_markups.{key}" type="object | null">
|
|
Per-model markup overrides for AI credit systems.
|
|
<Expandable title="properties">
|
|
<DynamicResponseField name="markup" type="number" />
|
|
|
|
<DynamicResponseField name="input_cost" type="number" />
|
|
|
|
<DynamicResponseField name="output_cost" type="number" />
|
|
|
|
</Expandable>
|
|
</DynamicResponseField>
|
|
|
|
<DynamicResponseField name="default_markup" type="number">
|
|
Default percentage markup for AI credit systems. Use -100 to make usage free.
|
|
</DynamicResponseField>
|
|
|
|
<DynamicResponseField name="provider_markups.{key}" type="object | null">
|
|
Per-provider default markup percentages for AI credit systems.
|
|
<Expandable title="properties">
|
|
<DynamicResponseField name="markup" type="number" />
|
|
|
|
</Expandable>
|
|
</DynamicResponseField>
|
|
|
|
<DynamicResponseField name="display" type="object">
|
|
Display names for the feature in billing UI and customer-facing components.
|
|
<Expandable title="properties">
|
|
<DynamicResponseField name="singular" type="string | null">
|
|
Singular form for UI display (e.g., 'API call', 'seat').
|
|
</DynamicResponseField>
|
|
|
|
<DynamicResponseField name="plural" type="string | null">
|
|
Plural form for UI display (e.g., 'API calls', 'seats').
|
|
</DynamicResponseField>
|
|
|
|
</Expandable>
|
|
</DynamicResponseField>
|
|
|
|
<DynamicResponseField name="archived" type="boolean">
|
|
Whether the feature is archived and hidden from the dashboard.
|
|
</DynamicResponseField>
|
|
|
|
</Expandable>
|
|
</DynamicResponseField>
|
|
|
|
<DynamicResponseField name="granted" type="number">
|
|
Total balance granted (included + prepaid).
|
|
</DynamicResponseField>
|
|
|
|
<DynamicResponseField name="remaining" type="number">
|
|
Remaining balance available for use.
|
|
</DynamicResponseField>
|
|
|
|
<DynamicResponseField name="usage" type="number">
|
|
Total usage consumed in the current period.
|
|
</DynamicResponseField>
|
|
|
|
<DynamicResponseField name="unlimited" type="boolean">
|
|
Whether this feature has unlimited usage.
|
|
</DynamicResponseField>
|
|
|
|
<DynamicResponseField name="overage_allowed" type="boolean">
|
|
Whether usage beyond the granted balance is allowed (with overage charges).
|
|
</DynamicResponseField>
|
|
|
|
<DynamicResponseField name="max_purchase" type="number | null">
|
|
Maximum quantity that can be purchased as a top-up, or null for unlimited.
|
|
</DynamicResponseField>
|
|
|
|
<DynamicResponseField name="next_reset_at" type="number | null">
|
|
Timestamp when the balance will reset, or null for no reset.
|
|
</DynamicResponseField>
|
|
|
|
<DynamicResponseField name="breakdown" type="object[]">
|
|
Detailed breakdown of balance sources when stacking multiple plans or grants.
|
|
<Expandable title="properties">
|
|
<DynamicResponseField name="id" type="string">
|
|
The unique identifier for this balance breakdown.
|
|
</DynamicResponseField>
|
|
|
|
<DynamicResponseField name="plan_id" type="string | null">
|
|
The plan ID this balance originates from, or null for standalone balances.
|
|
</DynamicResponseField>
|
|
|
|
<DynamicResponseField name="included_grant" type="number">
|
|
Amount granted from the plan's included usage.
|
|
</DynamicResponseField>
|
|
|
|
<DynamicResponseField name="prepaid_grant" type="number">
|
|
Amount granted from prepaid purchases or top-ups.
|
|
</DynamicResponseField>
|
|
|
|
<DynamicResponseField name="remaining" type="number">
|
|
Remaining balance available for use.
|
|
</DynamicResponseField>
|
|
|
|
<DynamicResponseField name="usage" type="number">
|
|
Amount consumed in the current period.
|
|
</DynamicResponseField>
|
|
|
|
<DynamicResponseField name="unlimited" type="boolean">
|
|
Whether this balance has unlimited usage.
|
|
</DynamicResponseField>
|
|
|
|
<DynamicResponseField name="reset" type="object | null">
|
|
Reset configuration for this balance, or null if no reset.
|
|
<Expandable title="properties">
|
|
<DynamicResponseField name="interval" type="'one_off' | 'minute' | 'hour' | 'day' | 'week' | 'month' | 'quarter' | 'semi_annual' | 'year'">
|
|
The reset interval (hour, day, week, month, etc.) or 'multiple' if combined from different intervals.
|
|
</DynamicResponseField>
|
|
|
|
<DynamicResponseField name="interval_count" type="number">
|
|
Number of intervals between resets (eg. 2 for bi-monthly).
|
|
</DynamicResponseField>
|
|
|
|
<DynamicResponseField name="resets_at" type="number | null">
|
|
Timestamp when the balance will next reset.
|
|
</DynamicResponseField>
|
|
|
|
</Expandable>
|
|
</DynamicResponseField>
|
|
|
|
<DynamicResponseField name="price" type="object | null">
|
|
Pricing configuration if this balance has usage-based pricing.
|
|
<Expandable title="properties">
|
|
<DynamicResponseField name="amount" type="number">
|
|
The per-unit price amount.
|
|
</DynamicResponseField>
|
|
|
|
<DynamicResponseField name="tiers" type="object[]">
|
|
Tiered pricing configuration if applicable.
|
|
<Expandable title="properties">
|
|
<DynamicResponseField name="to" type="number" />
|
|
|
|
<DynamicResponseField name="amount" type="number" />
|
|
|
|
<DynamicResponseField name="flat_amount" type="number" />
|
|
|
|
</Expandable>
|
|
</DynamicResponseField>
|
|
|
|
<DynamicResponseField name="tier_behavior" type="'graduated' | 'volume'">
|
|
How tiers are applied: graduated (split across bands) or volume (flat rate for the matched tier).
|
|
</DynamicResponseField>
|
|
|
|
<DynamicResponseField name="billing_units" type="number">
|
|
The number of units per billing increment (eg. $9 / 250 units).
|
|
</DynamicResponseField>
|
|
|
|
<DynamicResponseField name="billing_method" type="'prepaid' | 'usage_based'">
|
|
Whether usage is prepaid or billed pay-per-use.
|
|
</DynamicResponseField>
|
|
|
|
<DynamicResponseField name="max_purchase" type="number | null">
|
|
Maximum quantity that can be purchased, or null for unlimited.
|
|
</DynamicResponseField>
|
|
|
|
</Expandable>
|
|
</DynamicResponseField>
|
|
|
|
<DynamicResponseField name="expires_at" type="number | null">
|
|
Timestamp when this balance expires, or null for no expiration.
|
|
</DynamicResponseField>
|
|
|
|
</Expandable>
|
|
</DynamicResponseField>
|
|
|
|
<DynamicResponseField name="rollovers" type="object[]">
|
|
Rollover balances carried over from previous periods.
|
|
<Expandable title="properties">
|
|
<DynamicResponseField name="balance" type="number">
|
|
Amount of balance rolled over from a previous period.
|
|
</DynamicResponseField>
|
|
|
|
<DynamicResponseField name="expires_at" type="number">
|
|
Timestamp when the rollover balance expires.
|
|
</DynamicResponseField>
|
|
|
|
</Expandable>
|
|
</DynamicResponseField>
|
|
|
|
</Expandable>
|
|
</DynamicResponseField>
|
|
|
|
<DynamicResponseField name="flags.{key}" type="object">
|
|
Boolean feature flags keyed by feature ID, showing enabled access for on/off features.
|
|
<Expandable title="properties">
|
|
<DynamicResponseField name="id" type="string">
|
|
The unique identifier for this flag.
|
|
</DynamicResponseField>
|
|
|
|
<DynamicResponseField name="plan_id" type="string | null">
|
|
The plan ID this flag originates from, or null for standalone flags.
|
|
</DynamicResponseField>
|
|
|
|
<DynamicResponseField name="expires_at" type="number | null">
|
|
Timestamp when this flag expires, or null for no expiration.
|
|
</DynamicResponseField>
|
|
|
|
<DynamicResponseField name="feature_id" type="string">
|
|
The feature ID this flag is for.
|
|
</DynamicResponseField>
|
|
|
|
<DynamicResponseField name="feature" type="object">
|
|
The full feature object if expanded.
|
|
<Expandable title="properties">
|
|
<DynamicResponseField name="id" type="string">
|
|
The unique identifier for this feature, used in /check and /track calls.
|
|
</DynamicResponseField>
|
|
|
|
<DynamicResponseField name="name" type="string">
|
|
Human-readable name displayed in the dashboard and billing UI.
|
|
</DynamicResponseField>
|
|
|
|
<DynamicResponseField name="type" type="'boolean' | 'metered' | 'credit_system' | 'ai_credit_system'">
|
|
Feature type: 'boolean' for on/off access, 'metered' for usage-tracked features, 'credit_system' for unified credit pools, 'ai_credit_system' for model-based token pricing.
|
|
</DynamicResponseField>
|
|
|
|
<DynamicResponseField name="consumable" type="boolean">
|
|
For metered features: true if usage resets periodically (API calls, credits), false if allocated persistently (seats, storage).
|
|
</DynamicResponseField>
|
|
|
|
<DynamicResponseField name="event_names" type="string[]">
|
|
Event names that trigger this feature's balance. Allows multiple features to respond to a single event.
|
|
</DynamicResponseField>
|
|
|
|
<DynamicResponseField name="credit_schema" type="object[]">
|
|
For credit_system features: maps metered features to their credit costs.
|
|
<Expandable title="properties">
|
|
<DynamicResponseField name="metered_feature_id" type="string">
|
|
ID of the metered feature that draws from this credit system.
|
|
</DynamicResponseField>
|
|
|
|
<DynamicResponseField name="credit_cost" type="number">
|
|
Credits consumed per unit of the metered feature.
|
|
</DynamicResponseField>
|
|
|
|
</Expandable>
|
|
</DynamicResponseField>
|
|
|
|
<DynamicResponseField name="model_markups.{key}" type="object | null">
|
|
Per-model markup overrides for AI credit systems.
|
|
<Expandable title="properties">
|
|
<DynamicResponseField name="markup" type="number" />
|
|
|
|
<DynamicResponseField name="input_cost" type="number" />
|
|
|
|
<DynamicResponseField name="output_cost" type="number" />
|
|
|
|
</Expandable>
|
|
</DynamicResponseField>
|
|
|
|
<DynamicResponseField name="default_markup" type="number">
|
|
Default percentage markup for AI credit systems. Use -100 to make usage free.
|
|
</DynamicResponseField>
|
|
|
|
<DynamicResponseField name="provider_markups.{key}" type="object | null">
|
|
Per-provider default markup percentages for AI credit systems.
|
|
<Expandable title="properties">
|
|
<DynamicResponseField name="markup" type="number" />
|
|
|
|
</Expandable>
|
|
</DynamicResponseField>
|
|
|
|
<DynamicResponseField name="display" type="object">
|
|
Display names for the feature in billing UI and customer-facing components.
|
|
<Expandable title="properties">
|
|
<DynamicResponseField name="singular" type="string | null">
|
|
Singular form for UI display (e.g., 'API call', 'seat').
|
|
</DynamicResponseField>
|
|
|
|
<DynamicResponseField name="plural" type="string | null">
|
|
Plural form for UI display (e.g., 'API calls', 'seats').
|
|
</DynamicResponseField>
|
|
|
|
</Expandable>
|
|
</DynamicResponseField>
|
|
|
|
<DynamicResponseField name="archived" type="boolean">
|
|
Whether the feature is archived and hidden from the dashboard.
|
|
</DynamicResponseField>
|
|
|
|
</Expandable>
|
|
</DynamicResponseField>
|
|
|
|
</Expandable>
|
|
</DynamicResponseField>
|
|
|
|
<DynamicResponseField name="config" type="object">
|
|
Configuration for the customer.
|
|
<Expandable title="properties">
|
|
<DynamicResponseField name="disable_pooled_balance" type="boolean">
|
|
Whether to disable the shared customer-level pool for entities.
|
|
</DynamicResponseField>
|
|
|
|
</Expandable>
|
|
</DynamicResponseField>
|
|
|
|
<DynamicResponseField name="processors" type="object">
|
|
Payment processors this customer is connected to (Stripe, Vercel, RevenueCat). Omitted entirely when the customer has not been created in any processor.
|
|
<Expandable title="properties">
|
|
<DynamicResponseField name="stripe" type="object">
|
|
Stripe processor connection for the customer.
|
|
<Expandable title="properties">
|
|
<DynamicResponseField name="id" type="string">
|
|
Stripe customer ID.
|
|
</DynamicResponseField>
|
|
|
|
</Expandable>
|
|
</DynamicResponseField>
|
|
|
|
<DynamicResponseField name="vercel" type="object">
|
|
Vercel processor connection for the customer (public-safe subset).
|
|
<Expandable title="properties">
|
|
<DynamicResponseField name="installation_id" type="string">
|
|
Vercel marketplace installation ID for this customer.
|
|
</DynamicResponseField>
|
|
|
|
<DynamicResponseField name="account_id" type="string">
|
|
Vercel account ID associated with the installation.
|
|
</DynamicResponseField>
|
|
|
|
</Expandable>
|
|
</DynamicResponseField>
|
|
|
|
<DynamicResponseField name="revenuecat" type="object">
|
|
RevenueCat processor connection for the customer.
|
|
<Expandable title="properties">
|
|
<DynamicResponseField name="id" type="string | null">
|
|
Customer's external ID, used as the RevenueCat app user ID. Null if the customer has no external ID set.
|
|
</DynamicResponseField>
|
|
|
|
</Expandable>
|
|
</DynamicResponseField>
|
|
|
|
</Expandable>
|
|
</DynamicResponseField>
|
|
|
|
<DynamicResponseField name="invoices" type="object[]">
|
|
Invoices for this customer.
|
|
<Expandable title="properties">
|
|
<DynamicResponseField name="plan_ids" type="string[]">
|
|
Array of plan IDs included in this invoice
|
|
</DynamicResponseField>
|
|
|
|
<DynamicResponseField name="stripe_id" type="string">
|
|
The Stripe invoice ID
|
|
</DynamicResponseField>
|
|
|
|
<DynamicResponseField name="processor_type" type="'stripe' | 'revenuecat'">
|
|
The billing processor that owns this invoice.
|
|
</DynamicResponseField>
|
|
|
|
<DynamicResponseField name="status" type="string">
|
|
The status of the invoice
|
|
</DynamicResponseField>
|
|
|
|
<DynamicResponseField name="total" type="number">
|
|
The total amount of the invoice
|
|
</DynamicResponseField>
|
|
|
|
<DynamicResponseField name="currency" type="string">
|
|
The currency code for the invoice
|
|
</DynamicResponseField>
|
|
|
|
<DynamicResponseField name="created_at" type="number">
|
|
Timestamp when the invoice was created
|
|
</DynamicResponseField>
|
|
|
|
<DynamicResponseField name="hosted_invoice_url" type="string | null">
|
|
URL to the Stripe-hosted invoice page
|
|
</DynamicResponseField>
|
|
|
|
</Expandable>
|
|
</DynamicResponseField>
|
|
|
|
<DynamicResponseField name="entities" type="object[]">
|
|
Entities associated with this customer.
|
|
<Expandable title="properties">
|
|
<DynamicResponseField name="id" type="string | null">
|
|
The unique identifier of the entity
|
|
</DynamicResponseField>
|
|
|
|
<DynamicResponseField name="name" type="string | null">
|
|
The name of the entity
|
|
</DynamicResponseField>
|
|
|
|
<DynamicResponseField name="customer_id" type="string | null">
|
|
The customer ID this entity belongs to
|
|
</DynamicResponseField>
|
|
|
|
<DynamicResponseField name="feature_id" type="string | null">
|
|
The feature ID this entity belongs to
|
|
</DynamicResponseField>
|
|
|
|
<DynamicResponseField name="created_at" type="number">
|
|
Unix timestamp when the entity was created
|
|
</DynamicResponseField>
|
|
|
|
<DynamicResponseField name="env" type="'sandbox' | 'live'">
|
|
The environment (sandbox/live)
|
|
</DynamicResponseField>
|
|
|
|
</Expandable>
|
|
</DynamicResponseField>
|
|
|
|
<DynamicResponseField name="trials_used" type="object[]">
|
|
Trial usage history for this customer.
|
|
<Expandable title="properties">
|
|
<DynamicResponseField name="plan_id" type="string" />
|
|
|
|
<DynamicResponseField name="customer_id" type="string" />
|
|
|
|
<DynamicResponseField name="fingerprint" type="string | null" />
|
|
|
|
</Expandable>
|
|
</DynamicResponseField>
|
|
|
|
<DynamicResponseField name="rewards" type="object | null">
|
|
Rewards earned or applied for this customer.
|
|
<Expandable title="properties">
|
|
<DynamicResponseField name="discounts" type="object[]">
|
|
Array of active discounts applied to the customer
|
|
<Expandable title="properties">
|
|
<DynamicResponseField name="id" type="string">
|
|
The unique identifier for this discount
|
|
</DynamicResponseField>
|
|
|
|
<DynamicResponseField name="name" type="string">
|
|
The name of the discount or coupon
|
|
</DynamicResponseField>
|
|
|
|
<DynamicResponseField name="type" type="'percentage_discount' | 'fixed_discount' | 'free_product' | 'invoice_credits' | 'feature_grant'">
|
|
The type of reward
|
|
</DynamicResponseField>
|
|
|
|
<DynamicResponseField name="discount_value" type="number">
|
|
The discount value (percentage or fixed amount)
|
|
</DynamicResponseField>
|
|
|
|
<DynamicResponseField name="duration_type" type="'one_off' | 'months' | 'forever'">
|
|
How long the discount lasts
|
|
</DynamicResponseField>
|
|
|
|
<DynamicResponseField name="duration_value" type="number | null">
|
|
Number of billing periods the discount applies for repeating durations
|
|
</DynamicResponseField>
|
|
|
|
<DynamicResponseField name="currency" type="string | null">
|
|
The currency code for fixed amount discounts
|
|
</DynamicResponseField>
|
|
|
|
<DynamicResponseField name="start" type="number | null">
|
|
Timestamp when the discount becomes active
|
|
</DynamicResponseField>
|
|
|
|
<DynamicResponseField name="end" type="number | null">
|
|
Timestamp when the discount expires
|
|
</DynamicResponseField>
|
|
|
|
<DynamicResponseField name="subscription_id" type="string | null">
|
|
The Stripe subscription ID this discount is applied to
|
|
</DynamicResponseField>
|
|
|
|
<DynamicResponseField name="total_discount_amount" type="number | null">
|
|
Total amount saved from this discount
|
|
</DynamicResponseField>
|
|
|
|
</Expandable>
|
|
</DynamicResponseField>
|
|
|
|
</Expandable>
|
|
</DynamicResponseField>
|
|
|
|
<DynamicResponseField name="referrals" type="object[]">
|
|
Referral records for this customer.
|
|
<Expandable title="properties">
|
|
<DynamicResponseField name="program_id" type="string" />
|
|
|
|
<DynamicResponseField name="customer" type="object">
|
|
<Expandable title="properties">
|
|
<DynamicResponseField name="id" type="string" />
|
|
|
|
<DynamicResponseField name="name" type="string | null" />
|
|
|
|
<DynamicResponseField name="email" type="string | null" />
|
|
|
|
</Expandable>
|
|
</DynamicResponseField>
|
|
|
|
<DynamicResponseField name="reward_applied" type="boolean" />
|
|
|
|
<DynamicResponseField name="created_at" type="number" />
|
|
|
|
</Expandable>
|
|
</DynamicResponseField>
|
|
|
|
<DynamicResponseField name="payment_method" type="any | null">
|
|
The customer's default payment method.
|
|
</DynamicResponseField>
|
|
|
|
|
|
<ResponseExample>
|
|
```json 200
|
|
{
|
|
"id": "2ee25a41-0d81-4ad2-8451-ec1aadaefe58",
|
|
"name": "Patrick",
|
|
"email": "patrick@useautumn.com",
|
|
"createdAt": 1771409161016,
|
|
"fingerprint": null,
|
|
"stripeId": "cus_U0BKxpq1mFhuJO",
|
|
"processors": {
|
|
"stripe": {
|
|
"id": "cus_U0BKxpq1mFhuJO"
|
|
}
|
|
},
|
|
"env": "sandbox",
|
|
"metadata": {},
|
|
"sendEmailReceipts": false,
|
|
"billingControls": {
|
|
"autoTopups": []
|
|
},
|
|
"subscriptions": [
|
|
{
|
|
"planId": "pro_plan",
|
|
"autoEnable": true,
|
|
"addOn": false,
|
|
"status": "active",
|
|
"pastDue": false,
|
|
"canceledAt": null,
|
|
"expiresAt": null,
|
|
"trialEndsAt": null,
|
|
"startedAt": 1771431921437,
|
|
"currentPeriodStart": 1771431921437,
|
|
"currentPeriodEnd": 1771999921437,
|
|
"quantity": 1
|
|
}
|
|
],
|
|
"purchases": [],
|
|
"balances": {
|
|
"messages": {
|
|
"featureId": "messages",
|
|
"granted": 100,
|
|
"remaining": 0,
|
|
"usage": 100,
|
|
"unlimited": false,
|
|
"overageAllowed": false,
|
|
"maxPurchase": null,
|
|
"nextResetAt": 1773851121437,
|
|
"breakdown": [
|
|
{
|
|
"id": "cus_ent_39qmLooixXLAqMywgXywjAz96rV",
|
|
"planId": "pro_plan",
|
|
"includedGrant": 100,
|
|
"prepaidGrant": 0,
|
|
"remaining": 0,
|
|
"usage": 100,
|
|
"unlimited": false,
|
|
"reset": {
|
|
"interval": "month",
|
|
"resetsAt": 1773851121437
|
|
},
|
|
"price": null,
|
|
"expiresAt": null
|
|
}
|
|
]
|
|
}
|
|
},
|
|
"flags": {
|
|
"advanced_workflows": {
|
|
"id": "cus_ent_abc123",
|
|
"plan_id": "pro_plan",
|
|
"expires_at": null,
|
|
"feature_id": "advanced_workflows"
|
|
}
|
|
},
|
|
"config": {
|
|
"disable_pooled_balance": false
|
|
}
|
|
}
|
|
```
|
|
</ResponseExample>
|