Sign in

v1

latestOpenAPI 3.1.02026-07-265817860.8 KB
customers

Fetches a customer by ID, optionally expanding related data such as invoices or entities.

Use this when you know the customer exists or assert they exist without creating them.

post/v1/customers.get

Headers

x-api-versionstring required

Request body

customer_idstring required

ID of the customer to fetch

expandCustomerExpand[]

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

Example request

{
  "customer_id": "cus_123"
}

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":"paths:/v1/customers.get:post:responses:200:content:application/json:schema: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
  }
}