Skip to main content
POST
/
v1
/
customers.get_or_create
Typescript (SDK)
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",
  "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"
    }
  }
}
If the customer already exists and you try to create it again, you will simply be returned the customer object (rather than an error being thrown).

​
Body Parameters

​
Response

{
  "id": "2ee25a41-0d81-4ad2-8451-ec1aadaefe58",
  "name": "Patrick",
  "email": "patrick@useautumn.com",
  "createdAt": 1771409161016,
  "fingerprint": null,
  "stripeId": "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"
    }
  }
}

Authorizations

​
Authorization
string
header
required

Bearer authentication header of the form Bearer <token>, where <token> is your auth token.

Headers

​
x-api-version
string
default:2.1
required

Body

application/json
​
customer_id
string | null
required

Your unique identifier for the customer

​
name
string | null

Customer's name

​
email
string<email> | null

Customer's email address

​
fingerprint
string | null

Unique identifier (eg, serial number) to detect duplicate customers and prevent free trial abuse

​
metadata
object

Additional metadata for the customer

​
stripe_id
string | null

Stripe customer ID if you already have one

​
create_in_stripe
boolean

Whether to create the customer in Stripe

​
auto_enable_plan_id
string

The ID of the free plan to auto-enable for the customer

​
send_email_receipts
boolean

Whether to send email receipts to this customer

​
billing_controls
object

Billing controls for the customer (auto top-ups, etc.)

​
expand
string[]

Response

200 - application/json

OK

​
id
string | null
required

Your unique identifier for the customer.

​
name
string | null
required

The name of the customer.

​
email
string | null
required

The email address of the customer.

​
created_at
number
required

Timestamp of customer creation in milliseconds since epoch.

​
fingerprint
string | null
required

A unique identifier (eg. serial number) to de-duplicate customers across devices or browsers. For example: apple device ID.

​
stripe_id
string | null
required

Stripe customer ID.

​
env
enum<string>
required

The environment this customer was created in.

Available options:
sandbox,
live
​
metadata
object
required

The metadata for the customer.

​
send_email_receipts
boolean
required

Whether to send email receipts to the customer.

​
billing_controls
object
required

Billing controls for the customer (auto top-ups, etc.)

​
subscriptions
object[]
required

Active and scheduled recurring plans that this customer has attached.

​
purchases
object[]
required

One-time purchases made by the customer.

​
balances
object
required

Feature balances keyed by feature ID, showing usage limits and remaining amounts.

​
flags
object
required

Boolean feature flags keyed by feature ID, showing enabled access for on/off features.

​
invoices
object[]
​
entities
object[]
​
trials_used
object[]
​
rewards
object
​
referrals
object[]
​
payment_method
unknown