StripeKit - Create Subscription

`kit.subscriptions.create()`

Creates a new subscription for an existing customer.

Signature

Parameters

Field	Type	Required	Description
`customerId`	`string`	Yes	The customer to subscribe.
`priceId`	`string`	Yes	The Stripe Price to subscribe them to.
`userId`	`string\|number`	No	Your own internal user ID, stamped on the returned record.
`quantity`	`number`	No, defaults to `1`	Number of units of the price.
`trialPeriodDays`	`number`	No	Length of a free trial before the first charge.
`collectionMethod`	`'charge_automatically'\|'send_invoice'`	No, defaults to `'charge_automatically'`	Whether Stripe charges the default payment method automatically, or emails an invoice for manual payment.
`daysUntilDue`	`number`	Only with `send_invoice`	Defaults to `7`.
`defaultPaymentMethodId`	`string`	No	Payment method used for this subscription's charges.
`promotionCode`	`string`	No	A Stripe promotion code ID (not a plain code string) applied at creation.
`metadata`	`Record<string,string>`	No	Merged with `source: "stripekit"`.
`fieldValues`	`Record<string,string>`	No	Written into metadata as `field_<key>` and surfaced back as `fieldValues` on every subsequent read.

Example request

Example response

...Local fields shown assume timezone: 'Europe/Amsterdam' was configured on init.

Errors

Exception	When
`StripeOperationError`	The customer or price ID does not exist, the customer has no default payment method and one is required, or Stripe otherwise rejects the request.

Notes

If a storage adapter is configured, the record is persisted via saveSubscription() immediately.

Note that promotionCode expects a Stripe promotion code ID, not the plain-text code a customer types in. To apply a code by its plain text, validate it first with kit.coupons.validate(), which returns a stripePromotionCodeId you can use here or with applyPromotionCode().

Create

kit.subscriptions.create()#

Signature#

Parameters#

Example request#

Example response#

Errors#