Create or Get Customer

Creates a customer if they do not exist, or returns the existing customer by your external customer ID.

When to Use

Use this as the primary entrypoint before billing operations so the customer record is always present and up to date. This endpoint is idempotent - calling it multiple times with the same customer_id will return the same customer without creating duplicates.

Request Body

customer_id · string · required

Your unique identifier for the customer. Cannot contain @, spaces, or periods. Only letters, numbers, underscores, and hyphens are allowed.

name · string

Customer’s name.

email · string

Customer’s email address. Must be a valid email format.

fingerprint · string

Unique identifier (eg. serial number, device ID) to detect duplicate customers and prevent free trial abuse. Useful for identifying the same user across different accounts or devices.

metadata · object

Additional metadata for the customer. Can store any custom key-value pairs.

stripe_id · string

Stripe customer ID if you already have one. If provided, Autumn will link to your existing Stripe customer.

create_in_stripe · boolean

Whether to create the customer in Stripe. Defaults to true if not specified.

auto_enable_plan_id · string

The ID of a free plan to automatically enable for the customer upon creation.

send_email_receipts · boolean

Whether to send email receipts to this customer. Defaults to false.

expand · array

Array of fields to expand in the response. Available options:

• invoices - Include customer invoices
• trials_used - Include trial usage information
• rewards - Include rewards information
• entities - Include entity information
• referrals - Include referral information
• payment_method - Include payment method details
• subscriptions.plan - Expand full plan objects in subscriptions
• purchases.plan - Expand full plan objects in purchases
• balances.feature - Expand full feature objects in balances

Response

Returns a Customer object with the following fields:

id · string

Your unique identifier for the customer.

name · string

The name of the customer.

email · string

The email address of the customer.

created_at · number

Timestamp of customer creation in milliseconds since epoch.

fingerprint · string

The fingerprint identifier for the customer.

stripe_id · string

Stripe customer ID.

env · string

The environment this customer was created in (sandbox or live).

metadata · object

The metadata for the customer.

send_email_receipts · boolean

Whether email receipts are enabled for this customer.

subscriptions · array

Active and scheduled recurring plans that this customer has attached. Each subscription includes:

• plan_id - The unique identifier of the subscribed plan
• status - Current status (active or scheduled)
• auto_enable - Whether the plan was automatically enabled
• add_on - Whether this is an add-on plan
• past_due - Whether the subscription has overdue payments
• started_at - Timestamp when subscription started
• current_period_start - Start of current billing period
• current_period_end - End of current billing period
• quantity - Quantity of the subscription
• canceled_at - Timestamp when canceled (if applicable)
• expires_at - Timestamp when it expires (if applicable)
• trial_ends_at - Timestamp when trial ends (if applicable)

purchases · array

One-time purchases made by the customer.

balances · object

Feature balances keyed by feature ID, showing usage limits and remaining amounts. Each balance includes:

• feature_id - The feature identifier
• granted - Total amount granted
• remaining - Amount remaining
• usage - Total usage
• unlimited - Whether the feature is unlimited
• overage_allowed - Whether overage is allowed
• max_purchase - Maximum purchasable amount
• next_reset_at - Timestamp of next reset
• breakdown - Detailed breakdown by entitlement

Example Request

TypeScript SDK

const customer = await autumn.customers.getOrCreate({
  customer_id: "cus_123",
  name: "John Doe",
  email: "[e-mail]",
  metadata: {
    company: "Acme Inc",
    plan_preference: "pro"
  }
});

customer = autumn.customers.get_or_create(
    customer_id="cus_123",
    name="John Doe",
    email="[e-mail]",
    metadata={
        "company": "Acme Inc",
        "plan_preference": "pro"
    }
)

curl -X POST https://api.useautumn.com/v1/customers.get_or_create \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "x-api-version: 2.1" \
  -H "Content-Type: application/json" \
  -d '{
    "customer_id": "cus_123",
    "name": "John Doe",
    "email": "[e-mail]",
    "metadata": {
      "company": "Acme Inc",
      "plan_preference": "pro"
    }
  }'

Example Response

{
  "id": "cus_123",
  "name": "John Doe",
  "email": "[e-mail]",
  "created_at": 1771409161016,
  "fingerprint": null,
  "stripe_id": "cus_U0BKxpq1mFhuJO",
  "env": "sandbox",
  "metadata": {
    "company": "Acme Inc",
    "plan_preference": "pro"
  },
  "send_email_receipts": false,
  "subscriptions": [
    {
      "plan_id": "pro_plan",
      "auto_enable": true,
      "add_on": false,
      "status": "active",
      "past_due": false,
      "canceled_at": null,
      "expires_at": null,
      "trial_ends_at": null,
      "started_at": 1771431921437,
      "current_period_start": 1771431921437,
      "current_period_end": 1771999921437,
      "quantity": 1
    }
  ],
  "purchases": [],
  "balances": {
    "messages": {
      "feature_id": "messages",
      "granted": 100,
      "remaining": 50,
      "usage": 50,
      "unlimited": false,
      "overage_allowed": false,
      "max_purchase": null,
      "next_reset_at": 1773851121437,
      "breakdown": [
        {
          "id": "cus_ent_39qmLooixXLAqMywgXywjAz96rV",
          "plan_id": "pro_plan",
          "included_grant": 100,
          "prepaid_grant": 0,
          "remaining": 50,
          "usage": 50,
          "unlimited": false,
          "reset": {
            "interval": "month",
            "resets_at": 1773851121437
          },
          "price": null,
          "expires_at": null
        }
      ]
    }
  }
}