Sign in

v1

latestOpenAPI 3.1.02026-07-265817860.8 KB
customers

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.

post/v1/customers.get_or_create

Headers

x-api-versionstring required

Request body

customer_idstring required

Your unique identifier for the customer

namestring nullable

Customer's name

emailstring email nullable

Customer's email address

fingerprintstring nullable

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

metadataobject nullable

Additional metadata for the customer

stripe_idstring nullable

Stripe customer ID if you already have one

create_in_stripeboolean

Whether to create the customer in Stripe

auto_enable_plan_idstring

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

send_email_receiptsboolean

Whether to send email receipts to this customer

currencystring nullable

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

expandCustomerExpand[]

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

Example request

{
  "customer_id": "cus_123",
  "name": "John Doe",
  "email": "john@example.com"
}

Response

OK

idstring nullable required

Your unique identifier for the customer.

namestring nullable required

The name of the customer.

emailstring nullable required

The email address of the customer.

created_atnumber required

Timestamp of customer creation in milliseconds since epoch.

fingerprintstring nullable required

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

stripe_idstring nullable required

Stripe customer ID.

env'sandbox' | 'live' required

The environment this customer was created in.

metadataobject required

The metadata for the customer.

send_email_receiptsboolean required

Whether to send email receipts to the customer.

balancesobject required

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

flagsobject required

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

{"stackTrail":"components:schemas:Customer:properties:payment_method:anyOf","oasType":"schema","type":"unknown","description":"The customer's default payment method.","nullable":true}

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