Get or Create Customer

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",
});

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
  }
}

POST

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",
});

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
  }
}

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).

Currency

Pass currency 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

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.3.0

required

Body

application/json

customer_id

string | null

required

Your unique identifier for the customer

name

string | null

Customer's name

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 | null

Additional metadata for the customer

Show child attributes

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

currency

string | null

Currency to bill this customer in (e.g. usd, eur). Defaults to the organization's default currency.

billing_controls

object

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

Show child attributes

config

object

Miscellaneous configurations for the customer.

Show child attributes

expand

enum<string>[]

Fields to expand in the returned customer response, such as subscriptions.plan, purchases.plan, balances.feature, or flags.feature.

Available options:

invoices,

trials_used,

rewards,

entities,

referrals,

payment_method,

subscriptions.plan,

purchases.plan,

balances.feature,

flags.feature,

billing_controls.auto_topups.purchase_limit

Response

200 - application/json

string | null

required

Your unique identifier for the customer.

name

string | null

required

The name of the customer.

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.

Show child attributes

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.)

Show child attributes

subscriptions

object[]

required

Active and scheduled recurring plans that this customer has attached.

Show child attributes

purchases

object[]

required

One-time purchases made by the customer.

Show child attributes

licenses

object[]

required

License seat pools granted by the customer's plans, with seat counts.

Show child attributes

balances

object

required

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

Show child attributes

flags

object

required

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

Show child attributes

config

object

Configuration for the customer.

Show child attributes

processors

object

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

invoices

object[]

Invoices for this customer.

Show child attributes

entities

object[]

Entities associated with this customer.

Show child attributes

trials_used

object[]

Trial usage history for this customer.

Show child attributes

rewards

object | null

Rewards earned or applied for this customer.

Show child attributes

referrals

object[]

Referral records for this customer.

Show child attributes

payment_method

any | null

The customer's default payment method.

Finalize Lock Get Customer

⌘I

Billing

Balances

Customers

Authorization

Events

Entities

Plans

Features

Rewards & Referrals

Webhook Events

Platform (Beta)

Get or Create Customer

Currency

Body Parameters

Response

Authorizations

Headers

Body

Response

​Currency

​Body Parameters

​Response

Authorizations

Headers

Body

Response

Currency

Body Parameters

Response