Enrollment
Enroll User
Enroll a user by creating a free subscription. If a matching enrollment rule exists for the user's email or domain, that plan is used; otherwise the first free plan in active pricing tables is selected. Passing planId forces a specific plan (must have a free price).
Authorization
bearerAuth AuthorizationBearer <token>
Use your secret API key as the bearer token
In: header
Request Body
application/json
userId*string
External user ID from your application (stored as externalCustomerId)
customerEmail*string
User's email address for rule matching
Format
emailcustomerName*string
User's name
planId?string
Optional plan ID to enroll into (overrides rule matching)
Match
^plan_int_[A-Za-z0-9]{22}$billingAddressLine1?string|null
Billing address line 1
billingAddressLine2?string|null
Billing address line 2
billingCity?string|null
billingPostalCode?string|null
billingCountry?string|null
ISO 2-letter country code
taxId?string|null
Tax ID (VAT/ABN/etc)
Response Body
application/json
application/json
application/json
application/json
application/json
curl -X POST "https://api.getlumen.dev/v1/enrollment/enroll" \ -H "Content-Type: application/json" \ -d '{ "userId": "user-48291", "customerEmail": "jane@example.com", "customerName": "Jane Smith", "billingAddressLine1": "500 Market St", "billingCity": "San Francisco", "billingPostalCode": "94105", "billingCountry": "US" }'{
"message": "Enrollment subscription created successfully",
"subscription": {
"id": "sub_int_bXpaJQwRq9e17g8c2kFYLr",
"customerId": "cus_01j23abc456def789ghi0jklm",
"planId": "plan_int_6FJ7xXk8Qp9zR2tSa1BcDe",
"status": "active",
"subscriptionDetails": [],
"subscriptionFeatures": []
},
"invoice": null,
"plan": {
"id": "plan_int_6FJ7xXk8Qp9zR2tSa1BcDe"
},
"credit_grants_created": 0
}{
"error": "Selected plan has no pure free price; cannot auto-enroll"
}{
"error": "Plan not found or access denied"
}{
"error": "Subscription already exists for this customer",
"subscription": {
"id": "sub_int_existing123",
"status": "active"
}
}{
"error": "Failed to create enrollment subscription"
}