Create Subscription

Overview

Create a new subscription for a customer. Associate them with a plan and optionally apply a coupon or trial period.

Example: A customer selects your Premium Annual plan. Create a subscription with their user_id, plan_id, and source_id to start billing immediately.

Conditional Requirements

Condition	Required Fields
Always	`plan_id` OR `plan_old_provider_id`
Always	`user_id` OR `customer_old_provider_id`
`collection_method=charge_automatically` (default)	`source_id`
`collection_method=send_invoice`	`source_id` is optional
Account has `taxes_enabled=true`	`address_id` OR `address_old_provider_id` required for tax calculation (subscription created without taxes if missing)
Plan's product has `address_required=true` AND customer has no shipping address	Full `address` object (`first_name`, `last_name`, `line1`, `city`, `state`, `country`, `postal_code`)
Plan's product has `address_required=true` AND customer has shipping address	`address_id` OR `address_old_provider_id`
`is_gift_donor=true`	`gift_recipient_email`, `gift_recipient_first_name`, `gift_recipient_last_name` allowed
`gift_donor_old_provider_id` OR `gift_donor_subscription_id` is set	Cannot use `is_gift_donor` (mutually exclusive)
`current_period_end` is set	Cannot use `trial_period_days` (mutually exclusive)
`trial_period_days` is set	Cannot use `current_period_end` (mutually exclusive)
`next_invoice_date` is set	`current_period_end` must also be set and have same value
Both `user_id` AND `customer_old_provider_id` are set	Must reference the same customer
Both `address_id` AND `address_old_provider_id` are set	Must reference the same address
Both `plan_id` AND `plan_old_provider_id` are set	Must reference the same plan
Both `source_id` AND `source_old_provider_id` are set	Must reference the same source
Customer has reached max subscription limit	Request will fail

Related Endpoints

Subscriptions - Overview of the subscriptions API