import { Autumn } from 'autumn-js'
const autumn = new Autumn()
const result = await autumn.customers.getOrCreate({
customerId: "cus_123",
name: "John Doe",
email: "john@example.com",
});{
"id": "2ee25a41-0d81-4ad2-8451-ec1aadaefe58",
"name": "Patrick",
"email": "patrick@useautumn.com",
"createdAt": 1771409161016,
"fingerprint": null,
"stripeId": "cus_U0BKxpq1mFhuJO",
"processors": {
"stripe": {
"id": "cus_U0BKxpq1mFhuJO"
}
},
"env": "sandbox",
"metadata": {},
"sendEmailReceipts": false,
"billingControls": {
"autoTopups": []
},
"subscriptions": [
{
"planId": "pro_plan",
"autoEnable": true,
"addOn": false,
"status": "active",
"pastDue": false,
"canceledAt": null,
"expiresAt": null,
"trialEndsAt": null,
"startedAt": 1771431921437,
"currentPeriodStart": 1771431921437,
"currentPeriodEnd": 1771999921437,
"quantity": 1
}
],
"purchases": [],
"balances": {
"messages": {
"featureId": "messages",
"granted": 100,
"remaining": 0,
"usage": 100,
"unlimited": false,
"overageAllowed": false,
"maxPurchase": null,
"nextResetAt": 1773851121437,
"breakdown": [
{
"id": "cus_ent_39qmLooixXLAqMywgXywjAz96rV",
"planId": "pro_plan",
"includedGrant": 100,
"prepaidGrant": 0,
"remaining": 0,
"usage": 100,
"unlimited": false,
"reset": {
"interval": "month",
"resetsAt": 1773851121437
},
"price": null,
"expiresAt": null
}
]
}
},
"flags": {
"advanced_workflows": {
"id": "cus_ent_abc123",
"plan_id": "pro_plan",
"expires_at": null,
"feature_id": "advanced_workflows"
}
},
"config": {
"disable_pooled_balance": false
}
}
Get or Create Customer
Creates a customer if they do not exist, or returns the existing customer by your external customer ID.
Use this as the primary entrypoint before billing operations so the customer record is always present and up to date.
import { Autumn } from 'autumn-js'
const autumn = new Autumn()
const result = await autumn.customers.getOrCreate({
customerId: "cus_123",
name: "John Doe",
email: "john@example.com",
});{
"id": "2ee25a41-0d81-4ad2-8451-ec1aadaefe58",
"name": "Patrick",
"email": "patrick@useautumn.com",
"createdAt": 1771409161016,
"fingerprint": null,
"stripeId": "cus_U0BKxpq1mFhuJO",
"processors": {
"stripe": {
"id": "cus_U0BKxpq1mFhuJO"
}
},
"env": "sandbox",
"metadata": {},
"sendEmailReceipts": false,
"billingControls": {
"autoTopups": []
},
"subscriptions": [
{
"planId": "pro_plan",
"autoEnable": true,
"addOn": false,
"status": "active",
"pastDue": false,
"canceledAt": null,
"expiresAt": null,
"trialEndsAt": null,
"startedAt": 1771431921437,
"currentPeriodStart": 1771431921437,
"currentPeriodEnd": 1771999921437,
"quantity": 1
}
],
"purchases": [],
"balances": {
"messages": {
"featureId": "messages",
"granted": 100,
"remaining": 0,
"usage": 100,
"unlimited": false,
"overageAllowed": false,
"maxPurchase": null,
"nextResetAt": 1773851121437,
"breakdown": [
{
"id": "cus_ent_39qmLooixXLAqMywgXywjAz96rV",
"planId": "pro_plan",
"includedGrant": 100,
"prepaidGrant": 0,
"remaining": 0,
"usage": 100,
"unlimited": false,
"reset": {
"interval": "month",
"resetsAt": 1773851121437
},
"price": null,
"expiresAt": null
}
]
}
},
"flags": {
"advanced_workflows": {
"id": "cus_ent_abc123",
"plan_id": "pro_plan",
"expires_at": null,
"feature_id": "advanced_workflows"
}
},
"config": {
"disable_pooled_balance": false
}
}
Body Parameters
Response
{
"id": "2ee25a41-0d81-4ad2-8451-ec1aadaefe58",
"name": "Patrick",
"email": "patrick@useautumn.com",
"createdAt": 1771409161016,
"fingerprint": null,
"stripeId": "cus_U0BKxpq1mFhuJO",
"processors": {
"stripe": {
"id": "cus_U0BKxpq1mFhuJO"
}
},
"env": "sandbox",
"metadata": {},
"sendEmailReceipts": false,
"billingControls": {
"autoTopups": []
},
"subscriptions": [
{
"planId": "pro_plan",
"autoEnable": true,
"addOn": false,
"status": "active",
"pastDue": false,
"canceledAt": null,
"expiresAt": null,
"trialEndsAt": null,
"startedAt": 1771431921437,
"currentPeriodStart": 1771431921437,
"currentPeriodEnd": 1771999921437,
"quantity": 1
}
],
"purchases": [],
"balances": {
"messages": {
"featureId": "messages",
"granted": 100,
"remaining": 0,
"usage": 100,
"unlimited": false,
"overageAllowed": false,
"maxPurchase": null,
"nextResetAt": 1773851121437,
"breakdown": [
{
"id": "cus_ent_39qmLooixXLAqMywgXywjAz96rV",
"planId": "pro_plan",
"includedGrant": 100,
"prepaidGrant": 0,
"remaining": 0,
"usage": 100,
"unlimited": false,
"reset": {
"interval": "month",
"resetsAt": 1773851121437
},
"price": null,
"expiresAt": null
}
]
}
},
"flags": {
"advanced_workflows": {
"id": "cus_ent_abc123",
"plan_id": "pro_plan",
"expires_at": null,
"feature_id": "advanced_workflows"
}
},
"config": {
"disable_pooled_balance": false
}
}
Authorizations
Bearer authentication header of the form Bearer <token>, where <token> is your auth token.
Headers
Body
Your unique identifier for the customer
Customer's name
Customer's email address
Unique identifier (eg, serial number) to detect duplicate customers and prevent free trial abuse
Additional metadata for the customer
Show child attributes
Show child attributes
Stripe customer ID if you already have one
Whether to create the customer in Stripe
The ID of the free plan to auto-enable for the customer
Whether to send email receipts to this customer
Billing controls for the customer (auto top-ups, etc.)
Show child attributes
Show child attributes
Miscellaneous configurations for the customer.
Show child attributes
Show child attributes
Fields to expand in the returned customer response, such as subscriptions.plan, purchases.plan, balances.feature, or flags.feature.
invoices, trials_used, rewards, entities, referrals, payment_method, subscriptions.plan, purchases.plan, balances.feature, flags.feature, billing_controls.auto_topups.purchase_limit Response
OK
Your unique identifier for the customer.
The name of the customer.
The email address of the customer.
Timestamp of customer creation in milliseconds since epoch.
A unique identifier (eg. serial number) to de-duplicate customers across devices or browsers. For example: apple device ID.
Stripe customer ID.
The environment this customer was created in.
sandbox, live The metadata for the customer.
Show child attributes
Show child attributes
Whether to send email receipts to the customer.
Billing controls for the customer (auto top-ups, etc.)
Show child attributes
Show child attributes
Active and scheduled recurring plans that this customer has attached.
Show child attributes
Show child attributes
One-time purchases made by the customer.
Show child attributes
Show child attributes
Feature balances keyed by feature ID, showing usage limits and remaining amounts.
Show child attributes
Show child attributes
Boolean feature flags keyed by feature ID, showing enabled access for on/off features.
Show child attributes
Show child attributes
Configuration for the customer.
Show child attributes
Show child attributes
Payment processors this customer is connected to (Stripe, Vercel, RevenueCat). Omitted entirely when the customer has not been created in any processor.
Show child attributes
Show child attributes
Invoices for this customer.
Show child attributes
Show child attributes
Entities associated with this customer.
Show child attributes
Show child attributes
Trial usage history for this customer.
Show child attributes
Show child attributes
Rewards earned or applied for this customer.
Show child attributes
Show child attributes
Referral records for this customer.
Show child attributes
Show child attributes
The customer's default payment method.