A subscription is a contract between your business and a customer - it defines which plan they're on, what billing period applies, and how charges are generated over time.
Subscriptions progress through a defined lifecycle: pending → trialing → active → past_due → canceled or expired. Each transition can trigger invoicing, proration, or dunning actions.
Key concepts:
- Plan - the pricing template attached to this subscription
- Billing period -
month,quarter, oryear- determines invoice frequency - Trial - an optional free period before charges begin
- Auto-renew - whether the subscription renews automatically at period end
- Billing anchor day - the day of month that billing cycles align to (e.g., the 1st or 15th)
- Proration - when a subscription changes mid-cycle, charges are adjusted proportionally
- Items - the specific products and quantities included in this subscription
List subscriptions
Cursor-paginated list with optional column filters (status, customer_id, plan_id, …), custom_fields.
query Parameters
auto_renewFilter on auto_renew (boolean). Operators: eq — dot grammar, e.g. auto_renew.eq=value; a bare auto_renew=value means eq.
billing_interval_unitFilter on billing_interval_unit (enum). Operators: eq, in — dot grammar, e.g. billing_interval_unit.in=value; a bare billing_interval_unit=value means eq. A bare comma-separated value is in-sugar: billing_interval_unit=a,b means billing_interval_unit.in=a,b. Legal values: week, month, year.
created_atFilter on created_at (date-time). Operators: eq, gt, gte, lt, lte — dot grammar, e.g. created_at.gt=value; a bare created_at=value means eq.
currencyFilter on currency (string). Operators: eq, in — dot grammar, e.g. currency.in=value; a bare currency=value means eq. A bare comma-separated value is in-sugar: currency=a,b means currency.in=a,b.
current_period_endFilter on current_period_end (date-time). Operators: eq, gt, gte, lt, lte — dot grammar, e.g. current_period_end.gt=value; a bare current_period_end=value means eq.
current_period_startFilter on current_period_start (date-time). Operators: eq, gt, gte, lt, lte — dot grammar, e.g. current_period_start.gt=value; a bare current_period_start=value means eq.
customer_idFilter on customer_id (uuid). Operators: eq, in — dot grammar, e.g. customer_id.in=value; a bare customer_id=value means eq. A bare comma-separated value is in-sugar: customer_id=a,b means customer_id.in=a,b.
plan_idFilter on plan_id (uuid). Operators: eq, in — dot grammar, e.g. plan_id.in=value; a bare plan_id=value means eq. A bare comma-separated value is in-sugar: plan_id=a,b means plan_id.in=a,b.
plan_versionFilter on plan_version (number). Operators: eq, in — dot grammar, e.g. plan_version.in=value; a bare plan_version=value means eq. A bare comma-separated value is in-sugar: plan_version=a,b means plan_version.in=a,b.
started_atFilter on started_at (date-time). Operators: eq, gt, gte, lt, lte — dot grammar, e.g. started_at.gt=value; a bare started_at=value means eq.
updated_atFilter on updated_at (date-time). Operators: eq, gt, gte, lt, lte — dot grammar, e.g. updated_at.gt=value; a bare updated_at=value means eq.
limitPage size. Values above the server-side cap are clamped (standard default 50, cap 200; a few document-heavy lists use larger windows). Invalid values fall back to the default.
cursorOpaque continuation token from the previous response's pagination.cursor. Omit for the first page. Cursors are stateless and do not expire, but are only valid for the list and filters that produced them.
searchCase-insensitive substring match over customer name/email and plan name
Case-insensitive substring match over customer name/email and plan name
statusFilter by status. Filterable fields (status, customer_id, plan_id, plan_version, billing_interval_unit, currency, auto_renew, started_at, current_period_start, current_period_end, created_at, updated_at) accept apifilter operator suffixes; custom_fields.
Filter by status. Filterable fields (status, customer_id, plan_id, plan_version, billing_interval_unit, currency, auto_renew, started_at, current_period_start, current_period_end, created_at, updated_at) accept apifilter operator suffixes; custom_fields.
tagFilter by tag name (repeatable, containment semantics)
Filter by tag name (repeatable, containment semantics)
countsComma-separated countable fields (status, billing_cycle_anchor_unit) to include per-value counts for
Comma-separated countable fields (status, billing_cycle_anchor_unit) to include per-value counts for
includeComma/repeat includes. 'drift' attaches {versions_behind, latest_version} per row
Comma/repeat includes. 'drift' attaches {versions_behind, latest_version} per row
versions_behind_minKeep only subscriptions at least N versions behind (mutually exclusive with versions_behind)
Keep only subscriptions at least N versions behind (mutually exclusive with versions_behind)
versions_behindKeep only subscriptions exactly N versions behind
Keep only subscriptions exactly N versions behind
sortversions_behind_desc | versions_behind_asc
versions_behind_desc | versions_behind_asc
Headers
X-Workspace-IdSelects the workspace this request operates in, by workspace UUID or slug (e.g. a sandbox workspace for test integrations). Omitted: the organization's default live workspace. Unknown workspace: 404; workspace outside your organization: 403. Discover workspaces via GET /workspaces.
Workspace UUID or slug.
List subscriptions › Responses
OK
Create a subscription
Creates a subscription for a customer. Items, billing interval and currency derive from the request.
Headers
Idempotency-KeyUnique key that makes this POST safe to retry: repeats with the same key replay the first response instead of re-executing. Replays are scoped to the retrying principal (same API key / user) and kept for 24 hours. Required on every POST.
Client-generated idempotency key (e.g. a UUID).
X-Workspace-IdSelects the workspace this request operates in, by workspace UUID or slug (e.g. a sandbox workspace for test integrations). Omitted: the organization's default live workspace. Unknown workspace: 404; workspace outside your organization: 403. Discover workspaces via GET /workspaces.
Workspace UUID or slug.
Create a subscription › Request Body
auto_renewWhether the subscription renews automatically at period end; false lets it expire when the current period closes.
billing_anchor_dayDay of the month (1-28) each billing period starts on; derived from the activation date when omitted.
billing_interval_countNumber of interval units per billing cycle; defaults to 1.
billing_interval_unitUnit of the billing cycle length: week, month or year; defaults to month.
billing_timingWhen invoices fire relative to the period: in_advance (at period start) or in_arrears (at period end); defaults to in_arrears.
currencyISO 4217 currency the subscription bills in; defaults to the customer/org currency.
Values for the org's configured custom fields.
customer_idCustomer the subscription bills; required.
descriptionInternal operator-facing description; not shown to buyers.
Products, quantities and prices billed by this subscription; defaults from the plan-version snapshot for plan-based subs when omitted.
Arbitrary caller-supplied key/value pairs.
nameInternal operator-facing subscription name.
payment_terms_daysNet payment window in days for this subscription's invoices (0-365); null inherits the org default.
pending_checkout_session_idProvider checkout session to bind an on_checkout_complete DRAFT to; set by the public-checkout finalizer only.
Billing-mode phases; must contain at least one entry (the initial ACTIVE phase), later entries are pre-planned PENDING phases.
plan_idPlan to base the subscription on; mutually exclusive with product_id (plan-or-product XOR).
product_idProduct to bill directly; mutually exclusive with plan_id (plan-or-product XOR).
product_versionProduct version to pin; null follows the product head version.
public_descriptionBuyer-facing description shown in checkout and the customer portal.
Per-subscription billing setting overrides; unset keys inherit from customer, then org, then default.
start_atActivation instant; required when start_trigger is start_date, rejected otherwise.
start_triggerWhat activates the DRAFT subscription: immediate, on_checkout_complete, manual or start_date; defaults to immediate.
Locale-keyed overrides for name, description and public_description.
version_change_strategyMoney policy for auto-upgrades: immediate_prorate, next_period or at_phase_change; required when version_track_mode is latest.
version_track_modeHow the subscription follows plan/product versions: pinned or latest; defaults to pinned (no auto upgrades).
Create a subscription › Responses
Created
Bulk-upgrade a set of subscriptions to a target version
Fans out per-sub change-version calls for each entry in subscription_ids. Honors version_track_mode='pinned' by skipping pinned subs (set force=true to override). Returns the success+skipped breakdown.
Headers
Idempotency-KeyUnique key that makes this POST safe to retry: repeats with the same key replay the first response instead of re-executing. Replays are scoped to the retrying principal (same API key / user) and kept for 24 hours. Required on every POST.
Client-generated idempotency key (e.g. a UUID).
X-Workspace-IdSelects the workspace this request operates in, by workspace UUID or slug (e.g. a sandbox workspace for test integrations). Omitted: the organization's default live workspace. Unknown workspace: 404; workspace outside your organization: 403. Discover workspaces via GET /workspaces.
Workspace UUID or slug.
Bulk-upgrade a set of subscriptions to a target version › Request Body
forceWhen true, upgrade even subscriptions pinned to their current version.
scheduled_atReserved for future scheduling; rejected with a validation error when set (per-sub scheduling parity is a pending followup).
strategyMoney policy for each upgrade: immediate_prorate, next_period or at_phase_change.
subscription_idsSubscriptions to upgrade; at least one, at most 500.
target_plan_versionPlan version to move plan-based subscriptions to; null leaves plan-based subs untouched.
target_product_versionProduct version to move product-based subscriptions to; null leaves product-based subs untouched.
Bulk-upgrade a set of subscriptions to a target version › Responses
OK
Preview subscription prices
Resolves the effective per-line price for a candidate plan + items + customer combo without creating a subscription.
Headers
X-Workspace-IdSelects the workspace this request operates in, by workspace UUID or slug (e.g. a sandbox workspace for test integrations). Omitted: the organization's default live workspace. Unknown workspace: 404; workspace outside your organization: 403. Discover workspaces via GET /workspaces.
Workspace UUID or slug.
Preview subscription prices › Request Body
billing_interval_unitcurrencycustomer_idplan_idPreview subscription prices › Responses
OK
Get a subscription
Returns a subscription with its enrichment payload (MRR/ARR, attached promotions).
path Parameters
idSubscription UUID
Subscription UUID
Headers
X-Workspace-IdSelects the workspace this request operates in, by workspace UUID or slug (e.g. a sandbox workspace for test integrations). Omitted: the organization's default live workspace. Unknown workspace: 404; workspace outside your organization: 403. Discover workspaces via GET /workspaces.
Workspace UUID or slug.
Get a subscription › Responses
OK
Update a subscription's editable fields
Applies operator-editable fields (name, description, public_description, translations, metadata, custom_fields, settings) and the version-tracking configuration (version_track_mode pinned/latest + default version_change_strategy). Setting version_track_mode=latest requires a version_change_strategy. Version tracking is a preference, not a movement — POST /change-version actually moves the version. Lifecycle changes go through dedicated endpoints.
path Parameters
idSubscription UUID
Subscription UUID
Headers
X-Workspace-IdSelects the workspace this request operates in, by workspace UUID or slug (e.g. a sandbox workspace for test integrations). Omitted: the organization's default live workspace. Unknown workspace: 404; workspace outside your organization: 403. Discover workspaces via GET /workspaces.
Workspace UUID or slug.
Update a subscription's editable fields › Request Body
billing_timingNew invoice timing (in_advance/in_arrears); editable only while DRAFT, null leaves it unchanged.
clear_settingsSetting keys to reset back to inherit (NULL the column); use to clear an override that Settings alone cannot.
Values for the org's configured custom fields.
descriptionNew internal operator-facing description; null leaves it unchanged.
Arbitrary caller-supplied key/value pairs; replaces the stored map.
nameNew internal operator-facing name; null leaves it unchanged.
public_descriptionNew buyer-facing description; null leaves it unchanged.
Per-subscription billing setting overrides to set or change; null leaves them unchanged.
Locale-keyed overrides for name, description and public_description.
version_change_strategyNew default money policy for auto-upgrades; null leaves it unchanged.
version_track_modeNew version-track mode (pinned/latest); null leaves it unchanged.
Update a subscription's editable fields › Responses
OK
Activate a subscription
Activates a DRAFT subscription, or resumes one paused via a pause phase. For DRAFT subs this overrides the configured start trigger and starts immediately. (Status is DRAFT/ACTIVE/CANCELLED/EXPIRED; "paused" and "trialing" are phase kinds on an ACTIVE subscription, not statuses.)
path Parameters
idSubscription UUID
Subscription UUID
Headers
Idempotency-KeyUnique key that makes this POST safe to retry: repeats with the same key replay the first response instead of re-executing. Replays are scoped to the retrying principal (same API key / user) and kept for 24 hours. Required on every POST.
Client-generated idempotency key (e.g. a UUID).
X-Workspace-IdSelects the workspace this request operates in, by workspace UUID or slug (e.g. a sandbox workspace for test integrations). Omitted: the organization's default live workspace. Unknown workspace: 404; workspace outside your organization: 403. Discover workspaces via GET /workspaces.
Workspace UUID or slug.
Activate a subscription › Responses
OK
Get subscription allowance state
The current allowance state for each USAGE product in the subscription's plan.
path Parameters
idSubscription UUID
Subscription UUID
Headers
X-Workspace-IdSelects the workspace this request operates in, by workspace UUID or slug (e.g. a sandbox workspace for test integrations). Omitted: the organization's default live workspace. Unknown workspace: 404; workspace outside your organization: 403. Discover workspaces via GET /workspaces.
Workspace UUID or slug.
Get subscription allowance state › Responses
OK
Cancel a subscription
Transitions a subscription to CANCELLED. Final-cycle invoicing and credit-note logic run downstream.
path Parameters
idSubscription UUID
Subscription UUID
Headers
Idempotency-KeyUnique key that makes this POST safe to retry: repeats with the same key replay the first response instead of re-executing. Replays are scoped to the retrying principal (same API key / user) and kept for 24 hours. Required on every POST.
Client-generated idempotency key (e.g. a UUID).
X-Workspace-IdSelects the workspace this request operates in, by workspace UUID or slug (e.g. a sandbox workspace for test integrations). Omitted: the organization's default live workspace. Unknown workspace: 404; workspace outside your organization: 403. Discover workspaces via GET /workspaces.
Workspace UUID or slug.
Cancel a subscription › Responses
OK
Change subscription version
Repins a subscription onto a different version of its CURRENT plan/product. Body must include strategy (immediate_prorate / next_period / at_phase_change). Set target_latest=true to track the head version. For a deferral to an ARBITRARY future date, pass strategy=immediate_prorate with scheduled_at=
path Parameters
idSubscription UUID
Subscription UUID
Headers
Idempotency-KeyUnique key that makes this POST safe to retry: repeats with the same key replay the first response instead of re-executing. Replays are scoped to the retrying principal (same API key / user) and kept for 24 hours. Required on every POST.
Client-generated idempotency key (e.g. a UUID).
X-Workspace-IdSelects the workspace this request operates in, by workspace UUID or slug (e.g. a sandbox workspace for test integrations). Omitted: the organization's default live workspace. Unknown workspace: 404; workspace outside your organization: 403. Discover workspaces via GET /workspaces.
Workspace UUID or slug.
Change subscription version › Request Body
effective_atEffective instant for an immediate-strategy bump; null stamps the server's current time. Ignored by the deferred strategies.
scheduled_atSchedule the bump at an explicit future instant instead of a billing boundary; pair with strategy=immediate_prorate. null = not date-scheduled.
strategyHow the change is realized in money: immediate_prorate, next_period or at_phase_change; required.
target_latestWhen true, resolve to the plan/product head version. Mutually exclusive with target_version.
target_versionConcrete version to pin to; null uses target_latest instead. Mutually exclusive with target_latest.
update_track_modeOptionally flip the track mode (pinned↔latest) as part of the change; null leaves it unchanged.
Change subscription version › Responses
OK
Get a subscription's version-drift summary
How many plan (or product) versions behind a subscription is, the latest active version, the next scheduled version (if any), and an upgradable_to list of candidate versions.
path Parameters
idSubscription UUID
Subscription UUID
Headers
X-Workspace-IdSelects the workspace this request operates in, by workspace UUID or slug (e.g. a sandbox workspace for test integrations). Omitted: the organization's default live workspace. Unknown workspace: 404; workspace outside your organization: 403. Discover workspaces via GET /workspaces.
Workspace UUID or slug.
Get a subscription's version-drift summary › Responses
OK
List items on a subscription
Returns the subscription's current items: rows whose effective window is still open. Historical rows superseded by a quantity change or removal are excluded.
path Parameters
idSubscription UUID
Subscription UUID
Headers
X-Workspace-IdSelects the workspace this request operates in, by workspace UUID or slug (e.g. a sandbox workspace for test integrations). Omitted: the organization's default live workspace. Unknown workspace: 404; workspace outside your organization: 403. Discover workspaces via GET /workspaces.
Workspace UUID or slug.
List items on a subscription › Responses
OK
Add a mid-cycle item to a subscription
Adds a new subscription_items row. An optional ISO-8601 effective_at delays activation to a future instant; past timestamps are rejected.
path Parameters
idSubscription UUID
Subscription UUID
Headers
Idempotency-KeyUnique key that makes this POST safe to retry: repeats with the same key replay the first response instead of re-executing. Replays are scoped to the retrying principal (same API key / user) and kept for 24 hours. Required on every POST.
Client-generated idempotency key (e.g. a UUID).
X-Workspace-IdSelects the workspace this request operates in, by workspace UUID or slug (e.g. a sandbox workspace for test integrations). Omitted: the organization's default live workspace. Unknown workspace: 404; workspace outside your organization: 403. Discover workspaces via GET /workspaces.
Workspace UUID or slug.
Add a mid-cycle item to a subscription › Request Body
auto_renewWhether the committed term auto-renews at term end; only meaningful with a term.
effective_atWhen the new item starts being billed: null adds it now, a future instant queues it at that boundary; past is rejected.
price_keyKey-set entry to bill under; set only for keyed products.
product_idProduct to add as a billable item.
proration_modeHow the mid-period addition is charged: pro_rata, pay_in_full or do_not_charge; defaults to pro_rata.
quantityNumber of units to bill for the new item; must be at least 1.
term_countNumber of term units the item is committed for; set together with term_unit.
term_unitCommitment term unit (week/month/year); set with term_count to bill the whole term upfront, or leave both nil to follow the subscription cadence.
Add a mid-cycle item to a subscription › Responses
Created
Remove a mid-cycle item from a subscription
Closes a subscription_items row's effective_to. proration_mode settles the unused period (default pro_rata). An optional ISO-8601 effective_at schedules removal at a future instant; past timestamps are rejected.
path Parameters
idSubscription UUID
Subscription UUID
itemIdSubscription item UUID
Subscription item UUID
query Parameters
proration_modeHow to settle the removed item's unused period. Defaults to pro_rata (credit the remainder).
How to settle the removed item's unused period. Defaults to pro_rata (credit the remainder).
effective_atISO-8601 instant the item stops being billed. Omit for immediate. Past timestamps are rejected.
ISO-8601 instant the item stops being billed. Omit for immediate. Past timestamps are rejected.
Headers
X-Workspace-IdSelects the workspace this request operates in, by workspace UUID or slug (e.g. a sandbox workspace for test integrations). Omitted: the organization's default live workspace. Unknown workspace: 404; workspace outside your organization: 403. Discover workspaces via GET /workspaces.
Workspace UUID or slug.
Remove a mid-cycle item from a subscription › Responses
No Content
Update a subscription item
Applies the two changes a subscription item accepts, together or separately. new_quantity restates the seat / quantity with proration (an optional ISO-8601 effective_at schedules it for a future instant; past timestamps are rejected). version_pin pins the item to a product version, or unpins it with product_version_id: null to follow products.head_version_id — sending the version_pin object at all means "apply this pin", omitting it leaves the pin untouched. When both are sent the pin applies first, so the quantity prorates against the version it just landed on. Pin-only updates are idempotent. Preview the money impact with change_quantity on POST /subscriptions/{id}/simulate.
path Parameters
idSubscription UUID
Subscription UUID
itemIdSubscription item UUID
Subscription item UUID
Headers
X-Workspace-IdSelects the workspace this request operates in, by workspace UUID or slug (e.g. a sandbox workspace for test integrations). Omitted: the organization's default live workspace. Unknown workspace: 404; workspace outside your organization: 403. Discover workspaces via GET /workspaces.
Workspace UUID or slug.
Update a subscription item › Request Body
effective_atWhen the quantity change takes effect: null applies now, a future instant schedules it; ignored when new_quantity is absent.
new_quantityRestated quantity, prorated over the rest of the period; omit to leave the quantity unchanged.
Version pin to apply (a null product_version_id unpins to head); omit to leave the pin untouched.
Update a subscription item › Responses
OK
Create a customer price override for a subscription item
Convenience wrapper around POST /v1/prices that builds a CreatePriceRequest with kind=CUSTOMER_OVERRIDE, customer_id from the subscription, and product_id + price_key from the targeted subscription_item.
path Parameters
idSubscription UUID
Subscription UUID
itemIdSubscription item UUID
Subscription item UUID
Headers
Idempotency-KeyUnique key that makes this POST safe to retry: repeats with the same key replay the first response instead of re-executing. Replays are scoped to the retrying principal (same API key / user) and kept for 24 hours. Required on every POST.
Client-generated idempotency key (e.g. a UUID).
X-Workspace-IdSelects the workspace this request operates in, by workspace UUID or slug (e.g. a sandbox workspace for test integrations). Omitted: the organization's default live workspace. Unknown workspace: 404; workspace outside your organization: 403. Discover workspaces via GET /workspaces.
Workspace UUID or slug.
Create a customer price override for a subscription item › Request Body
currencyISO 4217 currency the list_price is denominated in.
display_nameOptional override display name shown on invoices.
list_priceList price, MAJOR units, denominated in this request's currency.
valid_fromDate the override starts applying (RFC-3339 date); null starts it immediately.
valid_toDate the override stops applying (RFC-3339 date); null for open-ended.
Create a customer price override for a subscription item › Responses
Created
List price overrides reachable for a subscription
Every CUSTOMER_OVERRIDE row that could resolve against this subscription: phase-scoped plus customer-wide. Surface for the Pricing & Overrides detail tab.
path Parameters
idSubscription UUID
Subscription UUID
Headers
X-Workspace-IdSelects the workspace this request operates in, by workspace UUID or slug (e.g. a sandbox workspace for test integrations). Omitted: the organization's default live workspace. Unknown workspace: 404; workspace outside your organization: 403. Discover workspaces via GET /workspaces.
Workspace UUID or slug.
List price overrides reachable for a subscription › Responses
OK
Pause a subscription
Opens a pause phase on an ACTIVE subscription (status stays ACTIVE; "paused" is a phase kind). Billing freezes until resumed.
path Parameters
idSubscription UUID
Subscription UUID
Headers
Idempotency-KeyUnique key that makes this POST safe to retry: repeats with the same key replay the first response instead of re-executing. Replays are scoped to the retrying principal (same API key / user) and kept for 24 hours. Required on every POST.
Client-generated idempotency key (e.g. a UUID).
X-Workspace-IdSelects the workspace this request operates in, by workspace UUID or slug (e.g. a sandbox workspace for test integrations). Omitted: the organization's default live workspace. Unknown workspace: 404; workspace outside your organization: 403. Discover workspaces via GET /workspaces.
Workspace UUID or slug.
Pause a subscription › Responses
OK
List subscription phases
Returns every phase of the subscription — pending, active, and completed — with translatable fields localized to the caller's locale. Unpaginated.
path Parameters
idSubscription UUID
Subscription UUID
Headers
X-Workspace-IdSelects the workspace this request operates in, by workspace UUID or slug (e.g. a sandbox workspace for test integrations). Omitted: the organization's default live workspace. Unknown workspace: 404; workspace outside your organization: 403. Discover workspaces via GET /workspaces.
Workspace UUID or slug.
List subscription phases › Responses
OK
Create a subscription phase
Appends a new phase in status 'pending' at the next phase order. start_at defaults to now and must not be in the past; the phase's end is declared via the end_kind triplet (duration value/unit, fixed end_at date, or manual). At most one trial phase per subscription, and cancelled subscriptions reject new phases (409).
path Parameters
idSubscription UUID
Subscription UUID
Headers
Idempotency-KeyUnique key that makes this POST safe to retry: repeats with the same key replay the first response instead of re-executing. Replays are scoped to the retrying principal (same API key / user) and kept for 24 hours. Required on every POST.
Client-generated idempotency key (e.g. a UUID).
X-Workspace-IdSelects the workspace this request operates in, by workspace UUID or slug (e.g. a sandbox workspace for test integrations). Omitted: the organization's default live workspace. Unknown workspace: 404; workspace outside your organization: 403. Discover workspaces via GET /workspaces.
Workspace UUID or slug.
Create a subscription phase › Request Body
auto_transitionWhether reaching this phase's end automatically starts the next pending phase.
duration_unitUnit of duration_value: day, week, month or billing_cycle; required when end_kind is duration.
duration_valueLength of the phase in duration_unit units; required when end_kind is duration.
end_atAbsolute instant the phase ends; used when end_kind is date.
end_kindEnd policy: manual, duration or date; determines how the phase's end is computed.
phase_kindBilling mode for this phase: setup, trial, standard, paused or dunning.
start_atAbsolute instant this phase should start; null starts it when the prior phase ends.
Create a subscription phase › Responses
Created
Update a subscription phase
Applies operator-editable fields (name, description, public_description, translations, auto_transition, duration_days, metadata, settings) to a phase.
path Parameters
idSubscription UUID
Subscription UUID
phaseIdPhase UUID
Phase UUID
Headers
X-Workspace-IdSelects the workspace this request operates in, by workspace UUID or slug (e.g. a sandbox workspace for test integrations). Omitted: the organization's default live workspace. Unknown workspace: 404; workspace outside your organization: 403. Discover workspaces via GET /workspaces.
Workspace UUID or slug.
Update a subscription phase › Request Body
auto_transitionNew auto-transition flag; null leaves it unchanged.
duration_unitNew unit of duration_value (day/week/month/billing_cycle); used with a duration end policy.
duration_valueNew phase length in duration_unit units; used with a duration end policy.
end_atNew absolute end instant; used with a date end policy.
end_kindNew end policy (manual/duration/date); empty leaves it unchanged.
Update a subscription phase › Responses
OK
List a subscription's plan-version history
Chronological pin-events for a subscription: each row records which plan/product version was pinned at which instant. Cursor-paginated (default 100, max 200 per page).
path Parameters
idSubscription UUID
Subscription UUID
query Parameters
limitPage size. Values above the server-side cap are clamped (standard default 50, cap 200; a few document-heavy lists use larger windows). Invalid values fall back to the default.
cursorOpaque continuation token from the previous response's pagination.cursor. Omit for the first page. Cursors are stateless and do not expire, but are only valid for the list and filters that produced them.
Headers
X-Workspace-IdSelects the workspace this request operates in, by workspace UUID or slug (e.g. a sandbox workspace for test integrations). Omitted: the organization's default live workspace. Unknown workspace: 404; workspace outside your organization: 403. Discover workspaces via GET /workspaces.
Workspace UUID or slug.
List a subscription's plan-version history › Responses
OK
Set a product's allowance-refresh cadence
Overrides how often the included allowance pool refreshes for one product (e.g. daily). Both fields omitted clears the override (refreshes once per billing cycle).
path Parameters
idSubscription UUID
Subscription UUID
productIdProduct UUID
Product UUID
Headers
X-Workspace-IdSelects the workspace this request operates in, by workspace UUID or slug (e.g. a sandbox workspace for test integrations). Omitted: the organization's default live workspace. Unknown workspace: 404; workspace outside your organization: 403. Discover workspaces via GET /workspaces.
Workspace UUID or slug.
Set a product's allowance-refresh cadence › Request Body
refresh_countHow often the included pool refreshes, as a count of refresh_unit; both fields null clears the override.
refresh_unitUnit of the refresh cadence: day, week, month, year or billing_cycle; both fields null clears the override.
Set a product's allowance-refresh cadence › Responses
No Content
Make a product a durable credit pool
Converts (or creates) the (subscription, product) entitlement into a durable POOL — a cross-period balance that drains as usage is metered. Clears any refresh cadence.
path Parameters
idSubscription UUID
Subscription UUID
productIdProduct UUID
Product UUID
Headers
X-Workspace-IdSelects the workspace this request operates in, by workspace UUID or slug (e.g. a sandbox workspace for test integrations). Omitted: the organization's default live workspace. Unknown workspace: 404; workspace outside your organization: 403. Discover workspaces via GET /workspaces.
Workspace UUID or slug.
Make a product a durable credit pool › Request Body
credit_unit_valueMoney value of one pool unit, as a decimal string in MAJOR units; requires currency.
currencyISO 4217 currency for the money-denominated fields; required when credit_unit_value or spend_limit is set.
spend_limitMaximum pool value in money, as a decimal string in MAJOR units; requires currency, null for no spend ceiling.
unit_limitMaximum pool balance in units, as a decimal string; null for no unit ceiling.
Make a product a durable credit pool › Responses
No Content
List a subscription's booked proration entries
The booked proration ledger (credits/charges generated by quantity, plan, or version changes) in chronological order. Cursor-paginated (default 100, max 200 per page).
path Parameters
idSubscription UUID
Subscription UUID
query Parameters
limitPage size. Values above the server-side cap are clamped (standard default 50, cap 200; a few document-heavy lists use larger windows). Invalid values fall back to the default.
cursorOpaque continuation token from the previous response's pagination.cursor. Omit for the first page. Cursors are stateless and do not expire, but are only valid for the list and filters that produced them.
Headers
X-Workspace-IdSelects the workspace this request operates in, by workspace UUID or slug (e.g. a sandbox workspace for test integrations). Omitted: the organization's default live workspace. Unknown workspace: 404; workspace outside your organization: 403. Discover workspaces via GET /workspaces.
Workspace UUID or slug.
List a subscription's booked proration entries › Responses
OK
Resume a subscription
Closes the pause phase and returns the subscription to a standard active phase (status was ACTIVE throughout; pause is a phase kind).
path Parameters
idSubscription UUID
Subscription UUID
Headers
Idempotency-KeyUnique key that makes this POST safe to retry: repeats with the same key replay the first response instead of re-executing. Replays are scoped to the retrying principal (same API key / user) and kept for 24 hours. Required on every POST.
Client-generated idempotency key (e.g. a UUID).
X-Workspace-IdSelects the workspace this request operates in, by workspace UUID or slug (e.g. a sandbox workspace for test integrations). Omitted: the organization's default live workspace. Unknown workspace: 404; workspace outside your organization: 403. Discover workspaces via GET /workspaces.
Workspace UUID or slug.
Resume a subscription › Responses
OK
List a subscription's scheduled changes
The subscription's pending, upcoming, and historical scheduled version changes — deferred change-version bumps recorded on the shared scheduled-changes surface (entity_type=SUBSCRIPTION). Deferred item/quantity changes are billing-period segmentations and are NOT shown here. Offset-paginated (default 50, max 200); filter with ?status=.
path Parameters
idSubscription UUID
Subscription UUID
query Parameters
statusFilter by scheduled-change status (comma-separated): pending, upcoming, releasing, released, rolled_back, cancelled, superseded
Filter by scheduled-change status (comma-separated): pending, upcoming, releasing, released, rolled_back, cancelled, superseded
limitPage size. Values above the server-side cap are clamped (standard default 50, cap 200; a few document-heavy lists use larger windows). Invalid values fall back to the default.
offsetRows to skip (offset pagination)
Rows to skip (offset pagination)
Headers
X-Workspace-IdSelects the workspace this request operates in, by workspace UUID or slug (e.g. a sandbox workspace for test integrations). Omitted: the organization's default live workspace. Unknown workspace: 404; workspace outside your organization: 403. Discover workspaces via GET /workspaces.
Workspace UUID or slug.
List a subscription's scheduled changes › Responses
OK
Simulate proposed subscription changes
Returns a dry-run preview (proration, MRR delta, …) for a candidate change set without persisting. The change set composes: add_items, remove_items, new_plan_id, change_quantity and change_version may be sent together. change_quantity and change_version price the same math their mutating counterparts book (PATCH /subscriptions/{id}/items/{itemId} and POST /subscriptions/{id}/change-version) and require an ACTIVE subscription. A change_version with a deferred strategy (next_period / at_phase_change) books nothing in the current period and honestly prices to zero.
path Parameters
idSubscription UUID
Subscription UUID
Headers
X-Workspace-IdSelects the workspace this request operates in, by workspace UUID or slug (e.g. a sandbox workspace for test integrations). Omitted: the organization's default live workspace. Unknown workspace: 404; workspace outside your organization: 403. Discover workspaces via GET /workspaces.
Workspace UUID or slug.
Simulate proposed subscription changes › Request Body
Items to add in this dry run.
Quantity restatements to price; each entry prices as one cross-quantity diff.
A version repin to price onto another plan/product version.
new_plan_idPlan to retarget the subscription onto in this dry run; null leaves the plan unchanged.
Items to remove in this dry run.
Simulate proposed subscription changes › Responses
OK
Transition to the next subscription phase
Completes the currently active phase and activates the next pending one in a single transaction, abandoning pending prorations and suspending add-ons orphaned by the change. Responds 409 when there is no active phase, no pending successor, or the active phase has not reached its end date — pass {"force": true} in the otherwise-optional body to override the end-date guard. Returns the newly active phase.
path Parameters
idSubscription UUID
Subscription UUID
Headers
Idempotency-KeyUnique key that makes this POST safe to retry: repeats with the same key replay the first response instead of re-executing. Replays are scoped to the retrying principal (same API key / user) and kept for 24 hours. Required on every POST.
Client-generated idempotency key (e.g. a UUID).
X-Workspace-IdSelects the workspace this request operates in, by workspace UUID or slug (e.g. a sandbox workspace for test integrations). Omitted: the organization's default live workspace. Unknown workspace: 404; workspace outside your organization: 403. Discover workspaces via GET /workspaces.
Workspace UUID or slug.
Transition to the next subscription phase › Request Body
forceWhen true, transition to the next phase even if the current phase's end conditions are not yet met.
Transition to the next subscription phase › Responses
OK
Transition a subscription to a new plan
Switches the subscription to a DIFFERENT plan (upgrade / downgrade / cross-grade) with proration handled by the configured strategy. To move to another version of the SAME plan/product, use POST /subscriptions/{id}/change-version instead.
path Parameters
idSubscription UUID
Subscription UUID
Headers
Idempotency-KeyUnique key that makes this POST safe to retry: repeats with the same key replay the first response instead of re-executing. Replays are scoped to the retrying principal (same API key / user) and kept for 24 hours. Required on every POST.
Client-generated idempotency key (e.g. a UUID).
X-Workspace-IdSelects the workspace this request operates in, by workspace UUID or slug (e.g. a sandbox workspace for test integrations). Omitted: the organization's default live workspace. Unknown workspace: 404; workspace outside your organization: 403. Discover workspaces via GET /workspaces.
Workspace UUID or slug.
Transition a subscription to a new plan › Request Body
new_plan_idPlan to transition the subscription onto.
Per-product key-set selections keyed by product ID, for keyed products on the new plan.
proration_modeHow the transition is charged: pro_rata, pay_in_full or do_not_charge; defaults to pro_rata.
Transition a subscription to a new plan › Responses
OK
Grant usage credits to a subscription
Grants additional usage credits to the subscription. For a product configured as a durable credit POOL this writes a purchased entitlement grant; otherwise the credits are injected via a single-use promotion redemption and applied at the next invoice run. Distinct from POST /wallets/{id}/topup, which credits money to a wallet.
path Parameters
idSubscription UUID
Subscription UUID
Headers
Idempotency-KeyUnique key that makes this POST safe to retry: repeats with the same key replay the first response instead of re-executing. Replays are scoped to the retrying principal (same API key / user) and kept for 24 hours. Required on every POST.
Client-generated idempotency key (e.g. a UUID).
X-Workspace-IdSelects the workspace this request operates in, by workspace UUID or slug (e.g. a sandbox workspace for test integrations). Omitted: the organization's default live workspace. Unknown workspace: 404; workspace outside your organization: 403. Discover workspaces via GET /workspaces.
Workspace UUID or slug.
Grant usage credits to a subscription › Request Body
descriptionOptional note recorded on the top-up grant.
product_idProduct whose allowance pool to top up.
quantity^-?\d+(\.\d+)?$Allowance quantity to top up (metered units, NOT money).
Grant usage credits to a subscription › Responses
Created
Withdraw a subscription (EU 14-day right of withdrawal)
Cancels a CONSUMER subscription still inside the EU 14-day right-of-withdrawal window (Directive 2011/83/EU) with a full refund. Returns NOT_ELIGIBLE_FOR_WITHDRAWAL when ineligible.
path Parameters
idSubscription UUID
Subscription UUID
Headers
Idempotency-KeyUnique key that makes this POST safe to retry: repeats with the same key replay the first response instead of re-executing. Replays are scoped to the retrying principal (same API key / user) and kept for 24 hours. Required on every POST.
Client-generated idempotency key (e.g. a UUID).
X-Workspace-IdSelects the workspace this request operates in, by workspace UUID or slug (e.g. a sandbox workspace for test integrations). Omitted: the organization's default live workspace. Unknown workspace: 404; workspace outside your organization: 403. Discover workspaces via GET /workspaces.
Workspace UUID or slug.
Withdraw a subscription (EU 14-day right of withdrawal) › Responses
OK