v55

latestOpenAPI 3.0.1AGPL-3.0raw.githubusercontent.com2026-08-07255473863.1 KB

Subscriptions

Create subscription

Use when onboarding a customer to a plan or starting a new subscription. Ideal for draft subscriptions (activate later) or active from start.

post/subscriptions

Request body

auto_invoice_thresholdstring

AutoInvoiceThreshold triggers a mid-period invoice when usage (in subscription currency) exceeds this amount. Standalone subscriptions only; all plan prices must be usage-based. Immutable after creation.

billing_anchorstring date-time

BillingAnchor overrides the derived anchor for anniversary billing. For monthly billing, the day-of-month defines cycle boundaries (shorter first period if start is before that day).

billing_cycle'anniversary' | 'calendar'

billing_period_countinteger

collection_method'charge_automatically' | 'send_invoice'

commitment_amountstring

couponsstring[]

Deprecated: use SubscriptionCoupons instead.

currencystring required

customer_idstring

CustomerID takes priority over ExternalCustomerID when both are provided.

enable_true_upboolean

end_datestring date-time

external_customer_idstring

gateway_payment_method_idstring

line_item_commitmentsobject

LineItemCommitments sets per-line-item commitment config, keyed by price_id.

line_item_couponsobject

Deprecated: use SubscriptionCoupons instead.

lookup_keystring

metadataobject

overage_factorstring

payment_behavior'allow_incomplete' | 'default_incomplete' | 'error_if_incomplete' | 'default_active'

payment_terms'15 NET' | '30 NET' | '45 NET' | '60 NET' | '75 NET' | '90 NET'

plan_idstring required

proration_behavior'create_prorations' | 'none'

start_datestring date-time

timezonestring

trial_period_daysinteger

TrialPeriodDays: nil = inherit from plan prices, 0 = no trial, >0 = override in days.

Response

Created

active_pause_idstring

ActivePauseID references the current active pause configuration This will be null if no pause is active or scheduled

auto_invoice_thresholdstring

AutoInvoiceThreshold is the usage amount (in subscription currency) that triggers an intermediate invoice. Overrides the plan-level threshold when set. Nil means: inherit from the plan's threshold (which may also be nil = disabled).

billing_anchorstring date-time

BillingAnchor is the reference point that aligns future billing cycle dates. It sets the day of week for week intervals, the day of month for month and year intervals, and the month of year for year intervals. The timestamp is in UTC format.

billing_cadence'RECURRING'

billing_cycle'anniversary' | 'calendar'

billing_period_countinteger

BillingPeriodCount is the total number units of the billing period.

cancel_atstring date-time

CancelAt is the date the subscription will be canceled

cancel_at_period_endboolean

CancelAtPeriodEnd is whether the subscription was canceled at the end of the current period

cancelled_atstring date-time

CanceledAt is the date the subscription was canceled

collection_methodstring

CollectionMethod determines how invoices are collected

commitment_amountstring

CommitmentAmount is the minimum amount a customer commits to paying for a billing period

created_atstring date-time

created_bystring

currencystring

Currency is the currency of the subscription in lowercase 3 digit ISO codes

current_period_endstring date-time

CurrentPeriodEnd is the end of the current period that the subscription has been invoiced for. At the end of this period, a new invoice will be created.

current_period_startstring date-time

CurrentPeriodStart is the end of the current period that the subscription has been invoiced for. At the end of this period, a new invoice will be created.

customer_idstring

CustomerID is the identifier for the customer in our system

enable_true_upboolean

end_datestring date-time

EndDate is the end date of the subscription

environment_idstring

EnvironmentID is the environment identifier for the subscription

gateway_payment_method_idstring

GatewayPaymentMethodID is the gateway payment method ID for this subscription

idstring

ID is the unique identifier for the subscription

invoicing_customer_idstring

InvoicingCustomerID is the customer ID to use for invoicing This can differ from the subscription customer (e.g., parent company invoicing for child company)

lookup_keystring

LookupKey is the key used to lookup the subscription in our system

metadataTypesMetadata

overage_factorstring

OverageFactor is a multiplier applied to usage beyond the commitment amount

parent_subscription_idstring

ParentSubscriptionID is the parent subscription ID for hierarchy (e.g. child subscription under a parent)

pause_status'none' | 'active' | 'scheduled' | 'completed' | 'cancelled'

payment_behaviorstring

PaymentBehavior determines how subscription payments are handled

payment_terms'15 NET' | '30 NET' | '45 NET' | '60 NET' | '75 NET' | '90 NET'

plan_idstring

PlanID is the identifier for the plan in our system

proration_behavior'create_prorations' | 'none'

start_datestring date-time

StartDate is the start date of the subscription

status'published' | 'deleted' | 'archived'

subscription_type'standalone' | 'delegated_invoicing' | 'parent' | 'inherited' | 'grouped_invoicing'

synced_price_sequenceinteger

SyncedPriceSequence is the plan-price sequence up to which this subscription's line items have been reconciled. Bumped by the plan-price sync after a successful pass.

tenant_idstring

timezonestring

trial_endstring date-time

TrialEnd is the end date of the trial period

trial_startstring date-time

TrialStart is the start date of the trial period

updated_atstring date-time

updated_bystring

versioninteger

Version is used for optimistic locking