Subscriptions
Create Subscription
Create a new subscription for a customer to a specific plan and price. Automatically associates plan features, handles trial periods, configures dunning, and optionally triggers immediate billing. By default, prevents multiple active subscriptions per customer unless dangerouslyAllowMultipleSubscriptions is true.
Authorization
bearerAuth AuthorizationBearer <token>
Use your secret API key as the bearer token
In: header
Request Body
application/json
customerId*string
Customer ID
priceId*string
Price ID to subscribe to
trialDays?integer
Number of trial days
metadata?
Response Body
application/json
application/json
application/json
application/json
curl -X POST "https://api.getlumen.dev/v1/subscriptions" \ -H "Content-Type: application/json" \ -d '{ "customerId": "cus_01hrwzqrz4ytkwv07syv8k7g3z", "planId": "pln_01hrx123", "effectivePriceId": "prc_01hrx456", "status": "active" }'{
"subscription": {
"id": "sub_01hrwzqrz4ytkwv07syv8k7g3z",
"stableSubscriptionId": "sub_stable_abc123",
"merchantId": "mrc_01hptv3p6xj173pfv96pxd5pke",
"customerId": "cus_01hrx123",
"planId": "pln_01hrx456",
"effectivePriceId": "prc_01hrx789",
"status": "active",
"startTimestamp": "2025-02-20T00:00:00.000Z",
"currentPeriodStart": "2025-02-20T00:00:00.000Z",
"currentPeriodEnd": "2025-03-20T00:00:00.000Z",
"createdAt": "2025-02-20T17:00:00.000Z"
}
}{
"error": "Customer already has an active subscription. Use dangerouslyAllowMultipleSubscriptions to override."
}{
"error": "Customer not found or access denied"
}{
"error": "Failed to create subscription"
}