Sign in
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

billing_cadence'RECURRING' | 'ONETIME' required
billing_cycle'anniversary' | 'calendar'
billing_period'MONTHLY' | 'ANNUAL' | 'WEEKLY' | 'DAILY' | 'QUARTERLY' | 'HALF_YEARLY' required
billing_period_countinteger
collection_method'charge_automatically' | 'send_invoice'
commitment_amountstring

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

commitment_duration'MONTHLY' | 'ANNUAL' | 'WEEKLY' | 'DAILY' | 'QUARTERLY' | 'HALF_YEARLY'
couponsstring[]
currencystring required
customer_idstring

customer_id is the flexprice customer id and it is prioritized over external_customer_id in case both are provided.

customer_timezonestring

Timezone of the customer. If not set, the default value is UTC.

enable_true_upboolean

Enable Commitment True Up Fee

end_datestring
external_customer_idstring

external_customer_id is the customer id in your DB and must be same as what you provided as external_id while creating the customer in flexprice.

gateway_payment_method_idstring
invoice_billing'invoice_to_parent' | 'invoice_to_self'
line_item_commitmentsobject

LineItemCommitments allows setting commitment configuration per line item (keyed by price_id)

line_item_couponsobject
lookup_keystring
metadataobject
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)

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
subscription_status'active' | 'paused' | 'cancelled' | 'incomplete' | 'trialing' | 'draft'
trial_endstring
trial_startstring

Response

Created

active_pause_idstring

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

billing_anchorstring

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' | 'ONETIME'
billing_cycle'anniversary' | 'calendar'
billing_period'MONTHLY' | 'ANNUAL' | 'WEEKLY' | 'DAILY' | 'QUARTERLY' | 'HALF_YEARLY'
billing_period_countinteger

BillingPeriodCount is the total number units of the billing period.

cancel_atstring

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

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

commitment_duration'MONTHLY' | 'ANNUAL' | 'WEEKLY' | 'DAILY' | 'QUARTERLY' | 'HALF_YEARLY'
created_atstring
created_bystring
currencystring

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

current_period_endstring

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

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

customer_timezonestring
enable_true_upboolean
end_datestring

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

StartDate is the start date of the subscription

status'published' | 'deleted' | 'archived'
subscription_status'active' | 'paused' | 'cancelled' | 'incomplete' | 'trialing' | 'draft'
tenant_idstring
trial_endstring

TrialEnd is the end date of the trial period

trial_startstring

TrialStart is the start date of the trial period

updated_atstring
updated_bystring
versioninteger

Version is used for optimistic locking

Changes