Create a subscription

POST {{baseUrl}}/v1/subscriptions

Creates a new subscription on an existing customer. Each customer can have up to 500 active or scheduled subscriptions.

When you create a subscription with collection_method=charge_automatically, the first invoice is finalized as part of the request. The payment_behavior parameter determines the exact behavior of the initial payment.

To start subscriptions where the first invoice always begins in a draft status, use subscription schedules instead. Schedules provide the flexibility to model more complex billing configurations that change over time.

Request Body

[{"name"=>"items[0][billing_thresholds][usage_gte]", "value"=>"<integer>", "datatype"=>"string"}, {"name"=>"items[0][metadata]", "value"=>"<object>", "datatype"=>"string"}, {"name"=>"items[0][price]", "value"=>"<string>", "datatype"=>"string"}, {"name"=>"items[0][price_data][currency]", "value"=>"<string>", "datatype"=>"string"}, {"name"=>"items[0][price_data][product]", "value"=>"<string>", "datatype"=>"string"}, {"name"=>"items[0][price_data][recurring][interval]", "value"=>"<string>", "datatype"=>"string"}, {"name"=>"items[0][price_data][recurring][interval_count]", "value"=>"<integer>", "datatype"=>"string"}, {"name"=>"items[0][price_data][tax_behavior]", "value"=>"<string>", "datatype"=>"string"}, {"name"=>"items[0][price_data][unit_amount]", "value"=>"<integer>", "datatype"=>"string"}, {"name"=>"items[0][price_data][unit_amount_decimal]", "value"=>"<decimal>", "datatype"=>"string"}, {"name"=>"items[0][quantity]", "value"=>"<integer>", "datatype"=>"string"}, {"name"=>"items[0][tax_rates][0]", "value"=>"<string>", "datatype"=>"string"}, {"name"=>"items[0][tax_rates][1]", "value"=>"<string>", "datatype"=>"string"}, {"name"=>"items[1][billing_thresholds][usage_gte]", "value"=>"<integer>", "datatype"=>"string"}, {"name"=>"items[1][metadata]", "value"=>"<object>", "datatype"=>"string"}, {"name"=>"items[1][price]", "value"=>"<string>", "datatype"=>"string"}, {"name"=>"items[1][price_data][currency]", "value"=>"<string>", "datatype"=>"string"}, {"name"=>"items[1][price_data][product]", "value"=>"<string>", "datatype"=>"string"}, {"name"=>"items[1][price_data][recurring][interval]", "value"=>"<string>", "datatype"=>"string"}, {"name"=>"items[1][price_data][recurring][interval_count]", "value"=>"<integer>", "datatype"=>"string"}, {"name"=>"items[1][price_data][tax_behavior]", "value"=>"<string>", "datatype"=>"string"}, {"name"=>"items[1][price_data][unit_amount]", "value"=>"<integer>", "datatype"=>"string"}, {"name"=>"items[1][price_data][unit_amount_decimal]", "value"=>"<decimal>", "datatype"=>"string"}, {"name"=>"items[1][quantity]", "value"=>"<integer>", "datatype"=>"string"}, {"name"=>"items[1][tax_rates][0]", "value"=>"<string>", "datatype"=>"string"}, {"name"=>"items[1][tax_rates][1]", "value"=>"<string>", "datatype"=>"string"}, {"name"=>"customer", "value"=>"<string>", "datatype"=>"string"}, {"name"=>"add_invoice_items[0][price]", "value"=>"<string>", "datatype"=>"string"}, {"name"=>"add_invoice_items[0][price_data][currency]", "value"=>"<string>", "datatype"=>"string"}, {"name"=>"add_invoice_items[0][price_data][product]", "value"=>"<string>", "datatype"=>"string"}, {"name"=>"add_invoice_items[0][price_data][tax_behavior]", "value"=>"<string>", "datatype"=>"string"}, {"name"=>"add_invoice_items[0][price_data][unit_amount]", "value"=>"<integer>", "datatype"=>"string"}, {"name"=>"add_invoice_items[0][price_data][unit_amount_decimal]", "value"=>"<decimal>", "datatype"=>"string"}, {"name"=>"add_invoice_items[0][quantity]", "value"=>"<integer>", "datatype"=>"string"}, {"name"=>"add_invoice_items[0][tax_rates][0]", "value"=>"<string>", "datatype"=>"string"}, {"name"=>"add_invoice_items[0][tax_rates][1]", "value"=>"<string>", "datatype"=>"string"}, {"name"=>"add_invoice_items[1][price]", "value"=>"<string>", "datatype"=>"string"}, {"name"=>"add_invoice_items[1][price_data][currency]", "value"=>"<string>", "datatype"=>"string"}, {"name"=>"add_invoice_items[1][price_data][product]", "value"=>"<string>", "datatype"=>"string"}, {"name"=>"add_invoice_items[1][price_data][tax_behavior]", "value"=>"<string>", "datatype"=>"string"}, {"name"=>"add_invoice_items[1][price_data][unit_amount]", "value"=>"<integer>", "datatype"=>"string"}, {"name"=>"add_invoice_items[1][price_data][unit_amount_decimal]", "value"=>"<decimal>", "datatype"=>"string"}, {"name"=>"add_invoice_items[1][quantity]", "value"=>"<integer>", "datatype"=>"string"}, {"name"=>"add_invoice_items[1][tax_rates][0]", "value"=>"<string>", "datatype"=>"string"}, {"name"=>"add_invoice_items[1][tax_rates][1]", "value"=>"<string>", "datatype"=>"string"}, {"name"=>"application_fee_percent", "value"=>"<number>", "datatype"=>"string"}, {"name"=>"automatic_tax[enabled]", "value"=>"<boolean>", "datatype"=>"string"}, {"name"=>"backdate_start_date", "value"=>"<unix-time>", "datatype"=>"string"}, {"name"=>"billing_cycle_anchor", "value"=>"<unix-time>", "datatype"=>"string"}, {"name"=>"billing_thresholds[amount_gte]", "value"=>"<integer>", "datatype"=>"string"}, {"name"=>"billing_thresholds[reset_billing_cycle_anchor]", "value"=>"<boolean>", "datatype"=>"string"}, {"name"=>"cancel_at", "value"=>"<unix-time>", "datatype"=>"string"}, {"name"=>"cancel_at_period_end", "value"=>"<boolean>", "datatype"=>"string"}, {"name"=>"collection_method", "value"=>"<string>", "datatype"=>"string"}, {"name"=>"coupon", "value"=>"<string>", "datatype"=>"string"}, {"name"=>"currency", "value"=>"<string>", "datatype"=>"string"}, {"name"=>"days_until_due", "value"=>"<integer>", "datatype"=>"string"}, {"name"=>"default_payment_method", "value"=>"<string>", "datatype"=>"string"}, {"name"=>"default_source", "value"=>"<string>", "datatype"=>"string"}, {"name"=>"default_tax_rates[0]", "value"=>"<string>", "datatype"=>"string"}, {"name"=>"default_tax_rates[1]", "value"=>"<string>", "datatype"=>"string"}, {"name"=>"description", "value"=>"<string>", "datatype"=>"string"}, {"name"=>"expand[0]", "value"=>"<string>", "datatype"=>"string"}, {"name"=>"expand[1]", "value"=>"<string>", "datatype"=>"string"}, {"name"=>"off_session", "value"=>"<boolean>", "datatype"=>"string"}, {"name"=>"payment_behavior", "value"=>"<string>", "datatype"=>"string"}, {"name"=>"payment_settings[payment_method_options][acss_debit][mandate_options][transaction_type]", "value"=>"<string>", "datatype"=>"string"}, {"name"=>"payment_settings[payment_method_options][acss_debit][verification_method]", "value"=>"<string>", "datatype"=>"string"}, {"name"=>"payment_settings[payment_method_options][bancontact][preferred_language]", "value"=>"<string>", "datatype"=>"string"}, {"name"=>"payment_settings[payment_method_options][card][mandate_options][amount]", "value"=>"<integer>", "datatype"=>"string"}, {"name"=>"payment_settings[payment_method_options][card][mandate_options][amount_type]", "value"=>"<string>", "datatype"=>"string"}, {"name"=>"payment_settings[payment_method_options][card][mandate_options][description]", "value"=>"<string>", "datatype"=>"string"}, {"name"=>"payment_settings[payment_method_options][card][network]", "value"=>"<string>", "datatype"=>"string"}, {"name"=>"payment_settings[payment_method_options][card][request_three_d_secure]", "value"=>"<string>", "datatype"=>"string"}, {"name"=>"payment_settings[payment_method_options][customer_balance][bank_transfer][eu_bank_transfer][country]", "value"=>"<string>", "datatype"=>"string"}, {"name"=>"payment_settings[payment_method_options][customer_balance][bank_transfer][type]", "value"=>"<string>", "datatype"=>"string"}, {"name"=>"payment_settings[payment_method_options][customer_balance][funding_type]", "value"=>"<string>", "datatype"=>"string"}, {"name"=>"payment_settings[payment_method_options][us_bank_account][financial_connections][permissions][0]", "value"=>"<string>", "datatype"=>"string"}, {"name"=>"payment_settings[payment_method_options][us_bank_account][financial_connections][permissions][1]", "value"=>"<string>", "datatype"=>"string"}, {"name"=>"payment_settings[payment_method_options][us_bank_account][verification_method]", "value"=>"<string>", "datatype"=>"string"}, {"name"=>"payment_settings[payment_method_types][0]", "value"=>"<string>", "datatype"=>"string"}, {"name"=>"payment_settings[payment_method_types][1]", "value"=>"<string>", "datatype"=>"string"}, {"name"=>"payment_settings[save_default_payment_method]", "value"=>"<string>", "datatype"=>"string"}, {"name"=>"pending_invoice_item_interval[interval]", "value"=>"<string>", "datatype"=>"string"}, {"name"=>"pending_invoice_item_interval[interval_count]", "value"=>"<integer>", "datatype"=>"string"}, {"name"=>"promotion_code", "value"=>"<string>", "datatype"=>"string"}, {"name"=>"proration_behavior", "value"=>"<string>", "datatype"=>"string"}, {"name"=>"transfer_data[destination]", "value"=>"<string>", "datatype"=>"string"}, {"name"=>"transfer_data[amount_percent]", "value"=>"<number>", "datatype"=>"string"}, {"name"=>"trial_from_plan", "value"=>"<boolean>", "datatype"=>"string"}, {"name"=>"trial_period_days", "value"=>"<integer>", "datatype"=>"string"}, {"name"=>"trial_settings[end_behavior][missing_payment_method]", "value"=>"<string>", "datatype"=>"string"}]

HEADERS