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",
});from autumn_sdk import Autumn
autumn = Autumn(secret_key="am_sk_test...")
res = autumn.customers.get_or_create(
customer_id="cus_123",
name="John Doe",
email="john@example.com",
)curl --request POST \
--url https://api.useautumn.com/v1/customers.get_or_create \
--header 'Authorization: Bearer <token>' \
--header 'Content-Type: application/json' \
--header 'x-api-version: <x-api-version>' \
--data '
{
"customer_id": "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": [],
"licenses": [],
"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,
"disable_overage_billing": 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",
});from autumn_sdk import Autumn
autumn = Autumn(secret_key="am_sk_test...")
res = autumn.customers.get_or_create(
customer_id="cus_123",
name="John Doe",
email="john@example.com",
)curl --request POST \
--url https://api.useautumn.com/v1/customers.get_or_create \
--header 'Authorization: Bearer <token>' \
--header 'Content-Type: application/json' \
--header 'x-api-version: <x-api-version>' \
--data '
{
"customer_id": "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": [],
"licenses": [],
"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,
"disable_overage_billing": false
}
}
Currency
Passcurrency to bill this customer in a currency other than your organization’s default. Their plans must offer a price in that currency via additional_currencies. If omitted, the customer’s currency is set by their first paid attach.
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": [],
"licenses": [],
"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,
"disable_overage_billing": 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
Currency to bill this customer in (e.g. usd, eur). Defaults to the organization's default currency.
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
Billing details to set on the Stripe customer. Creates the Stripe customer if needed.
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, invoice_previews, trials_used, rewards, entities, referrals, payment_method, billing_details, subscriptions.plan, purchases.plan, balances.feature, flags.feature, billing_controls.auto_topups.purchase_limit, pooled_contributions 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
License seat pools granted by the customer's plans, with seat counts.
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
Upcoming invoice for each of this customer's Stripe subscriptions.
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.
Billing details from the linked Stripe customer. Returned only if billing_details is provided in the expand parameter.
Show child attributes
Show child attributes