Get Customer

Retrieves a customer by their ID.

For most use cases, prefer using the Create or Get Customer endpoint, which ensures the customer exists and returns up-to-date information in a single call.

Path Parameters

customer_id · string · required

The unique identifier of the customer to retrieve.

Query Parameters

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.get("cus_123");

customer = autumn.customers.get("cus_123")

curl -X GET https://api.useautumn.com/v1/customers/cus_123 \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "x-api-version: 2.1"

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