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, …) and custom_fields.
query Parameters
limitPage size
cursorPagination cursor
statusFilter by status
customer_idFilter by customer UUID
plan_idFilter by plan UUID
List subscriptions › Responses
Paginated list with data and pagination envelope
allowed_transitionsauto_renewbilling_anchor_daybilling_interval_countbilling_interval_unitbilling_timingcancellation_reasoncancelled_atcreated_atcurrent_period_endcurrent_period_startcustomer_iddeleted_atdescriptionDrift is populated only when the operator passes ?include=drift on the List endpoint (versioning-ux workstream 05). Computed per-row from plan_versions / product_versions — no storage cost, no schema change.
idnamenext_billing_dateorganization_idpayment_terms_daysplan_idplan_versionpublic_descriptionstarted_atstatusupdated_atCreate a subscription
Creates a subscription for a customer. Items, billing interval and currency derive from the request.
Create a subscription › Request Body
auto_renewbilling_anchor_daybilling_interval_countbilling_interval_unitbilling_timingBillingTiming defaults to in_arrears when unset - matches the effective behavior every legacy / public-checkout subscription has today (no first invoice on activation; renewal tick picks up the closed period at period_end).
currencycustomer_iddescriptionItems defines the products/quantities/prices billed by this subscription (M116+). When omitted and the subscription is plan-based, items default from the plan-version snapshot.
namepayment_terms_daysPhases must contain at least one entry. The first entry is the initial ACTIVE phase; subsequent entries are pre-planned PENDING phases. M116+: phases are pure billing-mode markers — items live on the subscription, not the phase.
plan_idPlan-or-product XOR (M102+). When PlanID is set the plan template drives initial phase config; when ProductID is set the subscription is a single-product setup. Exactly one of these may be non-null. PlanID may also be inferred from Phases[0].PlanID for backward- compat — the service prefers the top-level field if set.
product_idproduct_versionpublic_descriptionstart_atstart_triggerStartTrigger picks the activation path. Defaults to "immediate". "start_date" requires StartAt to be set.
version_change_strategyversion_track_modeVersion pin/track and change strategy. Defaults: pinned + null strategy (no auto upgrades).
Create a subscription › Responses
Wrapped in data envelope
auto_renewbilling_anchor_daybilling_interval_countbilling_interval_unitbilling_timingcancellation_reasonDiscriminates how the subscription reached CANCELLED. Nil unless status == CANCELLED. See CancellationReason constants.
cancelled_atcreated_atcurrencycurrent_period_endcurrent_period_startcurrent_phase_idCurrentPhaseID is the cached pointer to the ACTIVE phase row; derivable but kept hot for the invoice path. Set during ActivatePhase, cleared during Cancel.
customer_iddeleted_atdescriptionidItems is the canonical product list for this subscription. Populated by GetByID / List from subscription_items (M116+).
nameorganization_idpayment_terms_daysPhases is the chain of phase records (M116+: pure billing-mode markers — items don't live on phases anymore).
plan_idPlan-or-product XOR (M102+). Exactly one of PlanID/ProductID set (or both null while DRAFT and undecided). PlanVersion/ProductVersion pin the snapshot; VersionTrackMode/VersionChangeStrategy govern auto upgrades when a new version of the plan or product is published.
plan_versionproduct_idproduct_versionpublic_descriptionSettings overrides - NULL = inherit from the next layer (customer → org → default). See subscription_settings.go for the resolver.
start_atStartAt is required when StartTrigger == start_date; null otherwise.
start_triggerStartTrigger says what activates a DRAFT subscription. See StartTrigger constants. Default for legacy rows is "immediate".
started_atStartedAt is the zero time while in DRAFT; populated on first transition into ACTIVE. Use !StartedAt.IsZero() to test "started".
statusupdated_atversion_change_strategyversion_track_modeBulk-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.
Bulk-upgrade a set of subscriptions to a target version › Request Body
forcescheduled_atstrategysubscription_idstarget_plan_versiontarget_product_versionBulk-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.
Preview subscription prices › Request Body
billing_interval_unitcurrencyCurrency forces price resolution into a specific currency when the plan exposes prices in multiple ones. Nil falls back to the resolver's implicit pick (customer preferred currency → first available). When set, the field flows verbatim into the per-line ResolvePriceRequest the preview service builds.
customer_idplan_idPreview subscription prices › Responses
Wrapped in data envelope
currencyGet a subscription
Returns a subscription with its enrichment payload (MRR/ARR, attached promotions).
path Parameters
idSubscription UUID
Get a subscription › Responses
Wrapped in data envelope
allowed_transitionsauto_renewbilling_anchor_daybilling_interval_countbilling_interval_unitbilling_timingcancellation_reasoncancelled_atcreated_atcurrent_period_endcurrent_period_startcustomer_iddeleted_atdescriptionDrift is populated only when the operator passes ?include=drift on the List endpoint (versioning-ux workstream 05). Computed per-row from plan_versions / product_versions — no storage cost, no schema change.
idnamenext_billing_dateorganization_idpayment_terms_daysplan_idplan_versionpublic_descriptionstarted_atstatusupdated_atUpdate a subscription's editable fields
Applies operator-editable fields (name, description, public_description, translations, metadata, custom_fields, settings) to a subscription. Lifecycle and pricing changes go through dedicated endpoints (cancel, pause, change-quantity, etc.).
path Parameters
idSubscription UUID
Update a subscription's editable fields › Request Body
descriptionnamepublic_descriptionUpdate a subscription's editable fields › Responses
OK
allowed_transitionsauto_renewbilling_anchor_daybilling_interval_countbilling_interval_unitbilling_timingcancellation_reasoncancelled_atcreated_atcurrent_period_endcurrent_period_startcustomer_iddeleted_atdescriptionDrift is populated only when the operator passes ?include=drift on the List endpoint (versioning-ux workstream 05). Computed per-row from plan_versions / product_versions — no storage cost, no schema change.
idnamenext_billing_dateorganization_idpayment_terms_daysplan_idplan_versionpublic_descriptionstarted_atstatusupdated_atActivate a subscription
Flips a DRAFT/TRIALING/PAUSED subscription to ACTIVE. For DRAFT subs this overrides the configured start trigger and starts the subscription immediately.
path Parameters
idSubscription UUID
Activate a subscription › Responses
Wrapped in data envelope
auto_renewbilling_anchor_daybilling_interval_countbilling_interval_unitbilling_timingcancellation_reasonDiscriminates how the subscription reached CANCELLED. Nil unless status == CANCELLED. See CancellationReason constants.
cancelled_atcreated_atcurrencycurrent_period_endcurrent_period_startcurrent_phase_idCurrentPhaseID is the cached pointer to the ACTIVE phase row; derivable but kept hot for the invoice path. Set during ActivatePhase, cleared during Cancel.
customer_iddeleted_atdescriptionidItems is the canonical product list for this subscription. Populated by GetByID / List from subscription_items (M116+).
nameorganization_idpayment_terms_daysPhases is the chain of phase records (M116+: pure billing-mode markers — items don't live on phases anymore).
plan_idPlan-or-product XOR (M102+). Exactly one of PlanID/ProductID set (or both null while DRAFT and undecided). PlanVersion/ProductVersion pin the snapshot; VersionTrackMode/VersionChangeStrategy govern auto upgrades when a new version of the plan or product is published.
plan_versionproduct_idproduct_versionpublic_descriptionSettings overrides - NULL = inherit from the next layer (customer → org → default). See subscription_settings.go for the resolver.
start_atStartAt is required when StartTrigger == start_date; null otherwise.
start_triggerStartTrigger says what activates a DRAFT subscription. See StartTrigger constants. Default for legacy rows is "immediate".
started_atStartedAt is the zero time while in DRAFT; populated on first transition into ACTIVE. Use !StartedAt.IsZero() to test "started".
statusupdated_atversion_change_strategyversion_track_modeAdd a mid-cycle item to a subscription
Adds a new subscription_items row. Pass an optional ISO-8601 effective_at to delay activation to a future instant — the segmenter then excludes the item from [periodStart, effective_at) and includes it from [effective_at, periodEnd). Past timestamps are rejected.
path Parameters
idSubscription UUID
Add a mid-cycle item to a subscription › Request Body
auto_reneweffective_atEffectiveAt (Pass B) — when the new item starts being billed. nil → now (immediate add). Future timestamp queues the row for activation at that boundary; the segmenter splits the period at T so [T, periodEnd) includes the new item. Past timestamps are rejected.
price_keyproduct_idproration_modequantityterm_countterm_unitOptional per-item term (R2/R4). When set, the item bills the whole term upfront on the invoice covering term start and emits no line on subsequent invoices inside the term. See SubscriptionItemInput for the field semantics.
Add a mid-cycle item to a subscription › Responses
Wrapped in data envelope
auto_renewcreated_atcurrent_term_endcurrent_term_starteffective_fromEffectiveFrom / EffectiveTo: the temporal window this row is billable for (Pass B). EffectiveTo NULL = open-ended / currently billable. Quantity changes and item add/remove are append-only — the prior row gets EffectiveTo=T, a new row covers [T, NULL).
effective_toidorganization_idprice_keyproduct_idproduct_version_idProductVersionID pins the item to a specific product version. nil = follow products.head_version_id (default).
quantityrenewal_anchor_atsubscription_idterm_countterm_unitTerm* fields make item-level commitment first-class. All optional; NULL means "follows the subscription's cadence" (the pre-R2 default). When set, the invoice pipeline amortizes the item's charges over the term instead of treating it as a normal per-period recurring line.
updated_atCancel a subscription
Transitions a subscription to CANCELLED. Final-cycle invoicing and credit-note logic run downstream.
path Parameters
idSubscription UUID
Cancel a subscription › Responses
Wrapped in data envelope
auto_renewbilling_anchor_daybilling_interval_countbilling_interval_unitbilling_timingcancellation_reasonDiscriminates how the subscription reached CANCELLED. Nil unless status == CANCELLED. See CancellationReason constants.
cancelled_atcreated_atcurrencycurrent_period_endcurrent_period_startcurrent_phase_idCurrentPhaseID is the cached pointer to the ACTIVE phase row; derivable but kept hot for the invoice path. Set during ActivatePhase, cleared during Cancel.
customer_iddeleted_atdescriptionidItems is the canonical product list for this subscription. Populated by GetByID / List from subscription_items (M116+).
nameorganization_idpayment_terms_daysPhases is the chain of phase records (M116+: pure billing-mode markers — items don't live on phases anymore).
plan_idPlan-or-product XOR (M102+). Exactly one of PlanID/ProductID set (or both null while DRAFT and undecided). PlanVersion/ProductVersion pin the snapshot; VersionTrackMode/VersionChangeStrategy govern auto upgrades when a new version of the plan or product is published.
plan_versionproduct_idproduct_versionpublic_descriptionSettings overrides - NULL = inherit from the next layer (customer → org → default). See subscription_settings.go for the resolver.
start_atStartAt is required when StartTrigger == start_date; null otherwise.
start_triggerStartTrigger says what activates a DRAFT subscription. See StartTrigger constants. Default for legacy rows is "immediate".
started_atStartedAt is the zero time while in DRAFT; populated on first transition into ACTIVE. Use !StartedAt.IsZero() to test "started".
statusupdated_atversion_change_strategyversion_track_modeChange subscription quantity
Updates the seat / quantity on a subscription item. Returns the updated subscription plus generated proration records. Pass an optional ISO-8601 effective_at to schedule the change for a future instant — the subscription_items row is superseded at that boundary and the segmenter splits the next billing period accordingly. Omitting effective_at makes the change immediate. Past timestamps are rejected.
path Parameters
idSubscription UUID
Change subscription quantity › Request Body
effective_atnew_quantitysubscription_item_idChange subscription quantity › Responses
Wrapped in data envelope
Change subscription version
Repins a subscription onto a different version of its plan/product. Body must include strategy (immediate_prorate / next_period / at_phase_change). Set target_latest=true to track the head version.
path Parameters
idSubscription UUID
Change subscription version › Request Body
strategytarget_latesttrue → resolve to head version
target_versionnil → use TargetLatest
update_track_modeoptional — flip pinned↔latest as part of the change
Change subscription version › Responses
Wrapped in data envelope
auto_renewbilling_anchor_daybilling_interval_countbilling_interval_unitbilling_timingcancellation_reasonDiscriminates how the subscription reached CANCELLED. Nil unless status == CANCELLED. See CancellationReason constants.
cancelled_atcreated_atcurrencycurrent_period_endcurrent_period_startcurrent_phase_idCurrentPhaseID is the cached pointer to the ACTIVE phase row; derivable but kept hot for the invoice path. Set during ActivatePhase, cleared during Cancel.
customer_iddeleted_atdescriptionidItems is the canonical product list for this subscription. Populated by GetByID / List from subscription_items (M116+).
nameorganization_idpayment_terms_daysPhases is the chain of phase records (M116+: pure billing-mode markers — items don't live on phases anymore).
plan_idPlan-or-product XOR (M102+). Exactly one of PlanID/ProductID set (or both null while DRAFT and undecided). PlanVersion/ProductVersion pin the snapshot; VersionTrackMode/VersionChangeStrategy govern auto upgrades when a new version of the plan or product is published.
plan_versionproduct_idproduct_versionpublic_descriptionSettings overrides - NULL = inherit from the next layer (customer → org → default). See subscription_settings.go for the resolver.
start_atStartAt is required when StartTrigger == start_date; null otherwise.
start_triggerStartTrigger says what activates a DRAFT subscription. See StartTrigger constants. Default for legacy rows is "immediate".
started_atStartedAt is the zero time while in DRAFT; populated on first transition into ACTIVE. Use !StartedAt.IsZero() to test "started".
statusupdated_atversion_change_strategyversion_track_modeGet a subscription's version-drift summary
Returns 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. Drift is computed on demand from plan_versions / product_versions.
path Parameters
idSubscription UUID
Get a subscription's version-drift summary › Responses
OK
current_versionlatest_published_atlatest_scheduled_atlatest_versionplan_idproduct_idsub_idtrack_modeversions_behindList items on a subscription
path Parameters
idSubscription UUID
List items on a subscription › Responses
Wrapped in data envelope
auto_renewcreated_atcurrent_term_endcurrent_term_starteffective_fromEffectiveFrom / EffectiveTo: the temporal window this row is billable for (Pass B). EffectiveTo NULL = open-ended / currently billable. Quantity changes and item add/remove are append-only — the prior row gets EffectiveTo=T, a new row covers [T, NULL).
effective_toidorganization_idprice_keyproduct_idproduct_version_idProductVersionID pins the item to a specific product version. nil = follow products.head_version_id (default).
quantityrenewal_anchor_atsubscription_idterm_countterm_unitTerm* fields make item-level commitment first-class. All optional; NULL means "follows the subscription's cadence" (the pre-R2 default). When set, the invoice pipeline amortizes the item's charges over the term instead of treating it as a normal per-period recurring line.
updated_atPause a subscription
Transitions an ACTIVE subscription to PAUSED. Billing freezes until resumed.
path Parameters
idSubscription UUID
Pause a subscription › Responses
Wrapped in data envelope
auto_renewbilling_anchor_daybilling_interval_countbilling_interval_unitbilling_timingcancellation_reasonDiscriminates how the subscription reached CANCELLED. Nil unless status == CANCELLED. See CancellationReason constants.
cancelled_atcreated_atcurrencycurrent_period_endcurrent_period_startcurrent_phase_idCurrentPhaseID is the cached pointer to the ACTIVE phase row; derivable but kept hot for the invoice path. Set during ActivatePhase, cleared during Cancel.
customer_iddeleted_atdescriptionidItems is the canonical product list for this subscription. Populated by GetByID / List from subscription_items (M116+).
nameorganization_idpayment_terms_daysPhases is the chain of phase records (M116+: pure billing-mode markers — items don't live on phases anymore).
plan_idPlan-or-product XOR (M102+). Exactly one of PlanID/ProductID set (or both null while DRAFT and undecided). PlanVersion/ProductVersion pin the snapshot; VersionTrackMode/VersionChangeStrategy govern auto upgrades when a new version of the plan or product is published.
plan_versionproduct_idproduct_versionpublic_descriptionSettings overrides - NULL = inherit from the next layer (customer → org → default). See subscription_settings.go for the resolver.
start_atStartAt is required when StartTrigger == start_date; null otherwise.
start_triggerStartTrigger says what activates a DRAFT subscription. See StartTrigger constants. Default for legacy rows is "immediate".
started_atStartedAt is the zero time while in DRAFT; populated on first transition into ACTIVE. Use !StartedAt.IsZero() to test "started".
statusupdated_atversion_change_strategyversion_track_modeList subscription phases
path Parameters
idSubscription UUID
List subscription phases › Responses
Wrapped in data envelope
auto_transitioncompleted_atcreated_atdunning_stageDunning stage tracking (M115+). Populated only when phase_kind = 'dunning'; the WARNED → GRACED → SUSPENDED progression doesn't re-enter the lifecycle FSM, it just advances on the phase row.
dunning_stage_atduration_unitduration_valueend_atend_kindEnd policy (M103+). When the phase reaches this boundary the AutoTransition flag (above) decides whether the next pending phase starts automatically.
ends_atderived; mirrors EndAt for end_kind=date or computed from duration
idorganization_idphase_kindA phase is purely a billing-mode marker: which condition is the
subscription operating under right now (trial / standard / paused /
dunning / setup) + when does it end. Operator-facing chrome (name,
translations, descriptions), per-phase setting overrides, arbitrary
metadata, and the legacy duration_days / phase_type fields all
lived here once and have been dropped — phases handle conditions and
nothing else (M118 trim).
phase_orderstarted_atstatussubscription_idCreate a subscription phase
path Parameters
idSubscription UUID
Create a subscription phase › Request Body
auto_transitionduration_unitduration_valueend_atend_kindEnd policy (M103+).
phase_kindPhases are billing-mode markers (M118 trim) — they carry just
phase_kind + an end policy + auto_transition. Operator-facing
metadata (name / description / translations) and per-phase
setting overrides used to ride this struct; they've been removed
in favour of subscription-level fields.
start_atCreate a subscription phase › Responses
Wrapped in data envelope
auto_transitioncompleted_atcreated_atdunning_stageDunning stage tracking (M115+). Populated only when phase_kind = 'dunning'; the WARNED → GRACED → SUSPENDED progression doesn't re-enter the lifecycle FSM, it just advances on the phase row.
dunning_stage_atduration_unitduration_valueend_atend_kindEnd policy (M103+). When the phase reaches this boundary the AutoTransition flag (above) decides whether the next pending phase starts automatically.
ends_atderived; mirrors EndAt for end_kind=date or computed from duration
idorganization_idphase_kindA phase is purely a billing-mode marker: which condition is the
subscription operating under right now (trial / standard / paused /
dunning / setup) + when does it end. Operator-facing chrome (name,
translations, descriptions), per-phase setting overrides, arbitrary
metadata, and the legacy duration_days / phase_type fields all
lived here once and have been dropped — phases handle conditions and
nothing else (M118 trim).
phase_orderstarted_atstatussubscription_idUpdate a subscription phase
Applies operator-editable fields (name, description, public_description, translations, auto_transition, duration_days, metadata, settings) to a phase. Lifecycle (transition, status) goes through dedicated endpoints.
path Parameters
idSubscription UUID
phaseIdPhase UUID
Update a subscription phase › Request Body
auto_transitionduration_unitduration_valueend_atend_kindUpdate a subscription phase › Responses
OK
auto_transitioncompleted_atcreated_atdunning_stageDunning stage tracking (M115+). Populated only when phase_kind = 'dunning'; the WARNED → GRACED → SUSPENDED progression doesn't re-enter the lifecycle FSM, it just advances on the phase row.
dunning_stage_atduration_unitduration_valueend_atend_kindEnd policy (M103+). When the phase reaches this boundary the AutoTransition flag (above) decides whether the next pending phase starts automatically.
ends_atderived; mirrors EndAt for end_kind=date or computed from duration
idorganization_idphase_kindA phase is purely a billing-mode marker: which condition is the
subscription operating under right now (trial / standard / paused /
dunning / setup) + when does it end. Operator-facing chrome (name,
translations, descriptions), per-phase setting overrides, arbitrary
metadata, and the legacy duration_days / phase_type fields all
lived here once and have been dropped — phases handle conditions and
nothing else (M118 trim).
phase_orderstarted_atstatussubscription_idList a subscription's plan-version history
path Parameters
idSubscription UUID
List a subscription's plan-version history › Responses
OK
change_reasoncreated_ateffective_fromeffective_toidplan_idplan_versionproduct_idproduct_versionsubscription_idPreview a subscription quantity change
Runs the same price-resolution + proration math the mutating /change-quantity endpoint uses, but never writes — returns the charge / credit / net amounts the operator would see if they commit. ACTIVE subs only. Currency, period window, and remaining days are echoed for display.
path Parameters
idSubscription UUID
Preview a subscription quantity change › Request Body
effective_atnew_quantitysubscription_item_idPreview a subscription quantity change › Responses
OK
currencydays_remainingnew_quantityold_quantityperiod_endperiod_startList a subscription's booked proration entries
path Parameters
idSubscription UUID
List a subscription's booked proration entries › Responses
Wrapped in data envelope
appliedchange_datecurrencydescriptionidinvoice_line_idperiod_endperiod_startproration_typeRemove a mid-cycle item from a subscription
Closes a subscription_items row's effective_to. Pass an optional ISO-8601 effective_at to schedule removal at a future instant — the segmenter keeps the item for [periodStart, effective_at) and drops it from [effective_at, periodEnd). Past timestamps are rejected.
path Parameters
idSubscription UUID
Remove a mid-cycle item from a subscription › Request Body
effective_atEffectiveAt (Pass B) — when this item stops being billed. nil → now (immediate close). Future timestamp queues a clean effective_to set at that boundary; segmenter excludes the row from [T, periodEnd) but keeps it for [periodStart, T). Past timestamps are rejected.
proration_modesubscription_item_idRemove a mid-cycle item from a subscription › Responses
No content
Resume a subscription
Transitions a PAUSED subscription back to ACTIVE.
path Parameters
idSubscription UUID
Resume a subscription › Responses
Wrapped in data envelope
auto_renewbilling_anchor_daybilling_interval_countbilling_interval_unitbilling_timingcancellation_reasonDiscriminates how the subscription reached CANCELLED. Nil unless status == CANCELLED. See CancellationReason constants.
cancelled_atcreated_atcurrencycurrent_period_endcurrent_period_startcurrent_phase_idCurrentPhaseID is the cached pointer to the ACTIVE phase row; derivable but kept hot for the invoice path. Set during ActivatePhase, cleared during Cancel.
customer_iddeleted_atdescriptionidItems is the canonical product list for this subscription. Populated by GetByID / List from subscription_items (M116+).
nameorganization_idpayment_terms_daysPhases is the chain of phase records (M116+: pure billing-mode markers — items don't live on phases anymore).
plan_idPlan-or-product XOR (M102+). Exactly one of PlanID/ProductID set (or both null while DRAFT and undecided). PlanVersion/ProductVersion pin the snapshot; VersionTrackMode/VersionChangeStrategy govern auto upgrades when a new version of the plan or product is published.
plan_versionproduct_idproduct_versionpublic_descriptionSettings overrides - NULL = inherit from the next layer (customer → org → default). See subscription_settings.go for the resolver.
start_atStartAt is required when StartTrigger == start_date; null otherwise.
start_triggerStartTrigger says what activates a DRAFT subscription. See StartTrigger constants. Default for legacy rows is "immediate".
started_atStartedAt is the zero time while in DRAFT; populated on first transition into ACTIVE. Use !StartedAt.IsZero() to test "started".
statusupdated_atversion_change_strategyversion_track_modeSimulate proposed subscription changes
Top up usage credits on a subscription
Creates a single-use promotion + redemption for the subscription's customer that grants additional usage credits applied at the next invoice run.
path Parameters
idSubscription UUID
Top up usage credits on a subscription › Request Body
descriptionproduct_idquantityTop up usage credits on a subscription › Responses
Wrapped in data envelope
Transition to the next subscription phase
path Parameters
idSubscription UUID
Transition to the next subscription phase › Responses
Wrapped in data envelope
auto_transitioncompleted_atcreated_atdunning_stageDunning stage tracking (M115+). Populated only when phase_kind = 'dunning'; the WARNED → GRACED → SUSPENDED progression doesn't re-enter the lifecycle FSM, it just advances on the phase row.
dunning_stage_atduration_unitduration_valueend_atend_kindEnd policy (M103+). When the phase reaches this boundary the AutoTransition flag (above) decides whether the next pending phase starts automatically.
ends_atderived; mirrors EndAt for end_kind=date or computed from duration
idorganization_idphase_kindA phase is purely a billing-mode marker: which condition is the
subscription operating under right now (trial / standard / paused /
dunning / setup) + when does it end. Operator-facing chrome (name,
translations, descriptions), per-phase setting overrides, arbitrary
metadata, and the legacy duration_days / phase_type fields all
lived here once and have been dropped — phases handle conditions and
nothing else (M118 trim).
phase_orderstarted_atstatussubscription_idTransition a subscription to a new plan
Switches the subscription's plan (upgrade / downgrade / cross-grade) with proration handled by the configured strategy.
path Parameters
idSubscription UUID
Transition a subscription to a new plan › Request Body
new_plan_idproration_modeTransition a subscription to a new plan › Responses
Wrapped in data envelope
auto_renewbilling_anchor_daybilling_interval_countbilling_interval_unitbilling_timingcancellation_reasonDiscriminates how the subscription reached CANCELLED. Nil unless status == CANCELLED. See CancellationReason constants.
cancelled_atcreated_atcurrencycurrent_period_endcurrent_period_startcurrent_phase_idCurrentPhaseID is the cached pointer to the ACTIVE phase row; derivable but kept hot for the invoice path. Set during ActivatePhase, cleared during Cancel.
customer_iddeleted_atdescriptionidItems is the canonical product list for this subscription. Populated by GetByID / List from subscription_items (M116+).
nameorganization_idpayment_terms_daysPhases is the chain of phase records (M116+: pure billing-mode markers — items don't live on phases anymore).
plan_idPlan-or-product XOR (M102+). Exactly one of PlanID/ProductID set (or both null while DRAFT and undecided). PlanVersion/ProductVersion pin the snapshot; VersionTrackMode/VersionChangeStrategy govern auto upgrades when a new version of the plan or product is published.
plan_versionproduct_idproduct_versionpublic_descriptionSettings overrides - NULL = inherit from the next layer (customer → org → default). See subscription_settings.go for the resolver.
start_atStartAt is required when StartTrigger == start_date; null otherwise.
start_triggerStartTrigger says what activates a DRAFT subscription. See StartTrigger constants. Default for legacy rows is "immediate".
started_atStartedAt is the zero time while in DRAFT; populated on first transition into ACTIVE. Use !StartedAt.IsZero() to test "started".
statusupdated_atversion_change_strategyversion_track_modeUpdate version-tracking mode
Sets a subscription's version-track mode (pinned/latest) and default change strategy. Use POST /change-version to actually move the version.
path Parameters
idSubscription UUID
Update version-tracking mode › Request Body
modestrategyUpdate version-tracking mode › Responses
Wrapped in data envelope
auto_renewbilling_anchor_daybilling_interval_countbilling_interval_unitbilling_timingcancellation_reasonDiscriminates how the subscription reached CANCELLED. Nil unless status == CANCELLED. See CancellationReason constants.
cancelled_atcreated_atcurrencycurrent_period_endcurrent_period_startcurrent_phase_idCurrentPhaseID is the cached pointer to the ACTIVE phase row; derivable but kept hot for the invoice path. Set during ActivatePhase, cleared during Cancel.
customer_iddeleted_atdescriptionidItems is the canonical product list for this subscription. Populated by GetByID / List from subscription_items (M116+).
nameorganization_idpayment_terms_daysPhases is the chain of phase records (M116+: pure billing-mode markers — items don't live on phases anymore).
plan_idPlan-or-product XOR (M102+). Exactly one of PlanID/ProductID set (or both null while DRAFT and undecided). PlanVersion/ProductVersion pin the snapshot; VersionTrackMode/VersionChangeStrategy govern auto upgrades when a new version of the plan or product is published.
plan_versionproduct_idproduct_versionpublic_descriptionSettings overrides - NULL = inherit from the next layer (customer → org → default). See subscription_settings.go for the resolver.
start_atStartAt is required when StartTrigger == start_date; null otherwise.
start_triggerStartTrigger says what activates a DRAFT subscription. See StartTrigger constants. Default for legacy rows is "immediate".
started_atStartedAt is the zero time while in DRAFT; populated on first transition into ACTIVE. Use !StartedAt.IsZero() to test "started".
statusupdated_atversion_change_strategyversion_track_modeWithdraw a subscription (EU 14-day right of withdrawal)
Cancels a CONSUMER subscription that is still inside the EU 14-day right-of-withdrawal window (Directive 2011/83/EU). Triggers a full refund of any payment made for the contract, distinct from the prorated refund a regular Cancel produces. Returns 422 NOT_ELIGIBLE_FOR_WITHDRAWAL when the customer type or contract age makes the call ineligible.
path Parameters
idSubscription UUID
Withdraw a subscription (EU 14-day right of withdrawal) › Responses
Wrapped in data envelope
auto_renewbilling_anchor_daybilling_interval_countbilling_interval_unitbilling_timingcancellation_reasonDiscriminates how the subscription reached CANCELLED. Nil unless status == CANCELLED. See CancellationReason constants.
cancelled_atcreated_atcurrencycurrent_period_endcurrent_period_startcurrent_phase_idCurrentPhaseID is the cached pointer to the ACTIVE phase row; derivable but kept hot for the invoice path. Set during ActivatePhase, cleared during Cancel.
customer_iddeleted_atdescriptionidItems is the canonical product list for this subscription. Populated by GetByID / List from subscription_items (M116+).
nameorganization_idpayment_terms_daysPhases is the chain of phase records (M116+: pure billing-mode markers — items don't live on phases anymore).
plan_idPlan-or-product XOR (M102+). Exactly one of PlanID/ProductID set (or both null while DRAFT and undecided). PlanVersion/ProductVersion pin the snapshot; VersionTrackMode/VersionChangeStrategy govern auto upgrades when a new version of the plan or product is published.
plan_versionproduct_idproduct_versionpublic_descriptionSettings overrides - NULL = inherit from the next layer (customer → org → default). See subscription_settings.go for the resolver.
start_atStartAt is required when StartTrigger == start_date; null otherwise.
start_triggerStartTrigger says what activates a DRAFT subscription. See StartTrigger constants. Default for legacy rows is "immediate".
started_atStartedAt is the zero time while in DRAFT; populated on first transition into ACTIVE. Use !StartedAt.IsZero() to test "started".
statusupdated_atversion_change_strategyversion_track_mode