Skip to main content
POST
/
v1
/
customers.get
Typescript (SDK)
import { Autumn } from 'autumn-js'

const autumn = new Autumn()

const result = await autumn.customers.get({
  customerId: "cus_123",
});
{
  "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": [],
  "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
  }
}

​
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": [],
  "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
  }
}

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
required

ID of the customer to fetch

​
expand
enum<string>[]

Expand related customer data like invoices or entities, or expand nested objects like balances.feature, flags.feature, subscriptions.plan, and purchases.plan.

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

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.

​
config
object

Configuration for the customer.

​
processors
object

Payment processors this customer is connected to (Stripe, Vercel, RevenueCat). Omitted entirely when the customer has not been created in any processor.

​
invoices
object[]

Invoices for this customer.

​
entities
object[]

Entities associated with this customer.

​
trials_used
object[]

Trial usage history for this customer.

​
rewards
object

Rewards earned or applied for this customer.

​
referrals
object[]

Referral records for this customer.

​
payment_method
any | null

The customer's default payment method.