---
title: "Get or Create Customer"
openapi: "openapi POST /v1/customers.get_or_create"
---
import { DynamicParamField } from "/components/dynamic-param-field.jsx";
import { DynamicResponseField } from "/components/dynamic-response-field.jsx";
import { DynamicResponseExample } from "/components/dynamic-response-example.jsx";
If the customer already exists and you try to create it again, you will simply be returned the customer object (rather than an error being thrown).
### Body Parameters
Your unique identifier for the customer
Customer's name
Customer's email address
Unique identifier (eg, serial number) to detect duplicate customers and prevent free trial abuse
Additional metadata for the customer
Stripe customer ID if you already have one
Whether to create the customer in Stripe
The ID of the free plan to auto-enable for the customer
Whether to send email receipts to this customer
Customer expand options
### Response
Your unique identifier for the customer.
The name of the customer.
The email address of the customer.
Timestamp of customer creation in milliseconds since epoch.
A unique identifier (eg. serial number) to de-duplicate customers across devices or browsers. For example: apple device ID.
Stripe customer ID.
The environment this customer was created in.
The metadata for the customer.
Whether to send email receipts to the customer.
Active and scheduled recurring plans that this customer has attached.
The full plan object if expanded.
Unique identifier for the plan.
Display name of the plan.
Optional description of the plan.
Group identifier for organizing related plans. Plans in the same group are mutually exclusive.
Version number of the plan. Incremented when plan configuration changes.
Whether this is an add-on plan that can be attached alongside a main plan.
If true, this plan is automatically attached when a customer is created. Used for free plans.
Base recurring price for the plan. Null for free plans or usage-only plans.
Base price amount for the plan.
Billing interval (e.g. 'month', 'year').
Number of intervals per billing cycle. Defaults to 1.
Display text for showing this price in pricing pages.
Main display text (e.g. '$10' or '100 messages').
Secondary display text (e.g. 'per month' or 'then $0.5 per 100').
Feature configurations included in this plan. Each item defines included units, pricing, and reset behavior for a feature.
The ID of the feature this item configures.
The full feature object if expanded.
The ID of the feature, used to refer to it in other API calls like /track or /check.
The name of the feature.
The type of the feature
Singular and plural display names for the feature.
The singular display name for the feature.
The plural display name for the feature.
Credit cost schema for credit system features.
The ID of the metered feature (should be a single_use feature).
The credit cost of the metered feature.
Whether or not the feature is archived.
Number of free units included. For consumable features, balance resets to this number each interval.
Whether the customer has unlimited access to this feature.
Reset configuration for consumable features. Null for non-consumable features like seats where usage persists across billing cycles.
The interval at which the feature balance resets (e.g. 'month', 'year'). For consumable features, usage resets to 0 and included units are restored.
Number of intervals between resets. Defaults to 1.
Pricing configuration for usage beyond included units. Null if feature is entirely free.
Price per billing_units after included usage is consumed. Mutually exclusive with tiers.
Tiered pricing configuration. Each tier's 'to' INCLUDES the included amount. Either 'tiers' or 'amount' is required.
Billing interval for this price. For consumable features, should match reset.interval.
Number of intervals per billing cycle. Defaults to 1.
Number of units per price increment. Usage is rounded UP to the nearest billing_units when billed (e.g. billing_units=100 means 101 usage rounds to 200).
'prepaid' for features like seats where customers pay upfront, 'usage_based' for pay-as-you-go after included usage.
Maximum units a customer can purchase beyond included. E.g. if included=100 and max_purchase=300, customer can use up to 400 total before usage is capped. Null for no limit.
Display text for showing this item in pricing pages.
Main display text (e.g. '$10' or '100 messages').
Secondary display text (e.g. 'per month' or 'then $0.5 per 100').
Rollover configuration for unused units. If set, unused included units roll over to the next period.
Maximum rollover units. Null for unlimited rollover.
When rolled over units expire.
Number of periods before expiry.
Free trial configuration. If set, new customers can try this plan before being charged.
Number of duration_type periods the trial lasts.
Unit of time for the trial duration ('day', 'month', 'year').
Whether a payment method is required to start the trial. If true, customer will be charged after trial ends.
Unix timestamp (ms) when the plan was created.
Environment this plan belongs to ('sandbox' or 'live').
Whether the plan is archived. Archived plans cannot be attached to new customers.
If this is a variant, the ID of the base plan it was created from.
Whether a free trial is available for this customer.
The attach scenario for this customer (e.g. new_subscription, upgrade, downgrade).
The unique identifier of the subscribed plan.
Whether the plan was automatically enabled for the customer.
Whether this is an add-on plan rather than a base subscription.
Current status of the subscription.
Whether the subscription has overdue payments.
Timestamp when the subscription was canceled, or null if not canceled.
Timestamp when the subscription will expire, or null if no expiry set.
Timestamp when the trial period ends, or null if not on trial.
Timestamp when the subscription started.
Start timestamp of the current billing period.
End timestamp of the current billing period.
Number of units of this subscription (for per-seat plans).
One-time purchases made by the customer.
The full plan object if expanded.
Unique identifier for the plan.
Display name of the plan.
Optional description of the plan.
Group identifier for organizing related plans. Plans in the same group are mutually exclusive.
Version number of the plan. Incremented when plan configuration changes.
Whether this is an add-on plan that can be attached alongside a main plan.
If true, this plan is automatically attached when a customer is created. Used for free plans.
Base recurring price for the plan. Null for free plans or usage-only plans.
Base price amount for the plan.
Billing interval (e.g. 'month', 'year').
Number of intervals per billing cycle. Defaults to 1.
Display text for showing this price in pricing pages.
Main display text (e.g. '$10' or '100 messages').
Secondary display text (e.g. 'per month' or 'then $0.5 per 100').
Feature configurations included in this plan. Each item defines included units, pricing, and reset behavior for a feature.
The ID of the feature this item configures.
The full feature object if expanded.
The ID of the feature, used to refer to it in other API calls like /track or /check.
The name of the feature.
The type of the feature
Singular and plural display names for the feature.
The singular display name for the feature.
The plural display name for the feature.
Credit cost schema for credit system features.
The ID of the metered feature (should be a single_use feature).
The credit cost of the metered feature.
Whether or not the feature is archived.
Number of free units included. For consumable features, balance resets to this number each interval.
Whether the customer has unlimited access to this feature.
Reset configuration for consumable features. Null for non-consumable features like seats where usage persists across billing cycles.
The interval at which the feature balance resets (e.g. 'month', 'year'). For consumable features, usage resets to 0 and included units are restored.
Number of intervals between resets. Defaults to 1.
Pricing configuration for usage beyond included units. Null if feature is entirely free.
Price per billing_units after included usage is consumed. Mutually exclusive with tiers.
Tiered pricing configuration. Each tier's 'to' INCLUDES the included amount. Either 'tiers' or 'amount' is required.
Billing interval for this price. For consumable features, should match reset.interval.
Number of intervals per billing cycle. Defaults to 1.
Number of units per price increment. Usage is rounded UP to the nearest billing_units when billed (e.g. billing_units=100 means 101 usage rounds to 200).
'prepaid' for features like seats where customers pay upfront, 'usage_based' for pay-as-you-go after included usage.
Maximum units a customer can purchase beyond included. E.g. if included=100 and max_purchase=300, customer can use up to 400 total before usage is capped. Null for no limit.
Display text for showing this item in pricing pages.
Main display text (e.g. '$10' or '100 messages').
Secondary display text (e.g. 'per month' or 'then $0.5 per 100').
Rollover configuration for unused units. If set, unused included units roll over to the next period.
Maximum rollover units. Null for unlimited rollover.
When rolled over units expire.
Number of periods before expiry.
Free trial configuration. If set, new customers can try this plan before being charged.
Number of duration_type periods the trial lasts.
Unit of time for the trial duration ('day', 'month', 'year').
Whether a payment method is required to start the trial. If true, customer will be charged after trial ends.
Unix timestamp (ms) when the plan was created.
Environment this plan belongs to ('sandbox' or 'live').
Whether the plan is archived. Archived plans cannot be attached to new customers.
If this is a variant, the ID of the base plan it was created from.
Whether a free trial is available for this customer.
The attach scenario for this customer (e.g. new_subscription, upgrade, downgrade).
The unique identifier of the purchased plan.
Timestamp when the purchase expires, or null for lifetime access.
Timestamp when the purchase was made.
Number of units purchased.
Feature balances keyed by feature ID, showing usage limits and remaining amounts.
The feature ID this balance is for.
The full feature object if expanded.
The unique identifier for this feature, used in /check and /track calls.
Human-readable name displayed in the dashboard and billing UI.
Feature type: 'boolean' for on/off access, 'metered' for usage-tracked features, 'credit_system' for unified credit pools.
For metered features: true if usage resets periodically (API calls, credits), false if allocated persistently (seats, storage).
Event names that trigger this feature's balance. Allows multiple features to respond to a single event.
For credit_system features: maps metered features to their credit costs.
ID of the metered feature that draws from this credit system.
Credits consumed per unit of the metered feature.
Display names for the feature in billing UI and customer-facing components.
Singular form for UI display (e.g., 'API call', 'seat').
Plural form for UI display (e.g., 'API calls', 'seats').
Whether the feature is archived and hidden from the dashboard.
Total balance granted (included + prepaid).
Remaining balance available for use.
Total usage consumed in the current period.
Whether this feature has unlimited usage.
Whether usage beyond the granted balance is allowed (with overage charges).
Maximum quantity that can be purchased as a top-up, or null for unlimited.
Timestamp when the balance will reset, or null for no reset.
Detailed breakdown of balance sources when stacking multiple plans or grants.
The unique identifier for this balance breakdown.
The plan ID this balance originates from, or null for standalone balances.
Amount granted from the plan's included usage.
Amount granted from prepaid purchases or top-ups.
Remaining balance available for use.
Amount consumed in the current period.
Whether this balance has unlimited usage.
Reset configuration for this balance, or null if no reset.
The reset interval (hour, day, week, month, etc.) or 'multiple' if combined from different intervals.
Number of intervals between resets (eg. 2 for bi-monthly).
Timestamp when the balance will next reset.
Pricing configuration if this balance has usage-based pricing.
The per-unit price amount.
Tiered pricing configuration if applicable.
How tiers are applied: graduated (split across bands) or volume (flat rate for the matched tier).
The number of units per billing increment (eg. $9 / 250 units).
Whether usage is prepaid or billed pay-per-use.
Maximum quantity that can be purchased, or null for unlimited.
Timestamp when this balance expires, or null for no expiration.
Rollover balances carried over from previous periods.
Amount of balance rolled over from a previous period.
Timestamp when the rollover balance expires.
Array of plan IDs included in this invoice
The Stripe invoice ID
The status of the invoice
The total amount of the invoice
The currency code for the invoice
Timestamp when the invoice was created
URL to the Stripe-hosted invoice page
The unique identifier of the entity
The name of the entity
The customer ID this entity belongs to
The feature ID this entity belongs to
Unix timestamp when the entity was created
The environment (sandbox/live)
Array of active discounts applied to the customer
The unique identifier for this discount
The name of the discount or coupon
The type of reward
The discount value (percentage or fixed amount)
How long the discount lasts
Number of billing periods the discount applies for repeating durations
The currency code for fixed amount discounts
Timestamp when the discount becomes active
Timestamp when the discount expires
The Stripe subscription ID this discount is applied to
Total amount saved from this discount
```json 200
{
"id": "2ee25a41-0d81-4ad2-8451-ec1aadaefe58",
"name": "Patrick",
"email": "patrick@useautumn.com",
"createdAt": 1771409161016,
"fingerprint": null,
"stripeId": "cus_U0BKxpq1mFhuJO",
"env": "sandbox",
"metadata": {},
"sendEmailReceipts": false,
"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
}
]
}
}
}
```