SubscriptionCreateRequest

ID of the customer to subscribe.

Subscription items. All recurring items must share the same billing interval. Items without recurring are one-time charges captured at creation and excluded from all future billing cycles.

Three-letter ISO currency code. Required at subscription level.

How to collect payment from the customer:

• charge_automatically — charge the default payment method automatically (default)
• send_invoice — (coming soon) send an invoice and require manual payment

Number of days until the invoice is due. Required when collection_method=send_invoice.

ID of the payment method to use for this subscription.

End date of the trial period (ISO 8601 datetime). Mutually exclusive with trial_period_days; provide exactly one.

Number of days for the trial period. Convenience alternative to trial_end — resolved to trial_end = now + trial_period_days at creation time. Mutually exclusive with trial_end.

Controls what happens when a trial period ends.

Defines the billing cycle anchor date (ISO 8601). Mutually exclusive with billing_cycle_anchor_config.

Advanced billing cycle configuration. Allows precise control over when billing cycles occur. All fields are optional integers with specific ranges.

If true, cancel at the end of the current billing period instead of immediately.

Schedule cancellation for a specific date (ISO 8601). Cannot be used with cancel_at_period_end=true.

Controls when and how the first charge is collected.

• default_incomplete (default) — subscription is created as incomplete. Without anchor: charge is attempted inline at creation; success → active; failure → past_due. With billing_cycle_anchor / billing_cycle_anchor_config: subscription stays incomplete until the anchor date; charge fires at the anchor date; success → active; failure → past_due. Up to 3 total charge attempts; exhaustion → incomplete_expired.

• allow_incomplete — subscription is created as incomplete. Without anchor: charge is attempted inline at creation; success → active; failure → past_due. With billing_cycle_anchor / billing_cycle_anchor_config: subscription stays incomplete until the anchor date; charge fires at the anchor date; success → active; failure → past_due. Up to 3 total charge attempts; exhaustion → canceled.

• error_if_incomplete — charge is attempted before the subscription is created. On success: subscription is created as active. On failure: 402 returned, nothing is created. Cannot be combined with trial_end, trial_period_days, billing_cycle_anchor, or billing_cycle_anchor_config.

• send_invoice — (coming soon) skip inline charge; use invoice-based billing.

Account ID for connected account scenarios.

Whether this subscription is in live mode or test mode.

Set of key-value pairs for storing additional information about the subscription.