This endpoint creates a new customer and can optionally create associated accounts in integrated systems like Stripe.
Request Body
Customer’s email address. Must be unique and valid format.Example:
customer@example.comCustomer’s first name. Must be 1-50 characters.Example:
JohnCustomer’s last name. Must be 1-50 characters.Example:
DoeCustomer’s phone number in E.164 format (recommended) or local format.Examples:
+1-555-123-4567, (555) 123-4567Customer’s date of birth in ISO 8601 format (YYYY-MM-DD).Example:
1990-05-15Customer’s primary address information.
Whether the customer has consented to marketing communications.
Customer tier for loyalty programs. Options:
bronze, silver, gold, platinumHow the customer found your business.Options:
organic, paid_search, social_media, referral, email, direct, otherExisting Stripe customer ID if you’re syncing with an external Stripe account.Note: If not provided and Stripe integration is enabled, a new Stripe customer will be created automatically.
Internal notes about the customer (not visible to customer).Max length: 1000 characters
Array of tags for customer segmentation and organization.Example:
["vip", "wholesale", "early-adopter"]Additional custom fields as key-value pairs. Keys must be alphanumeric with underscores.Example:
Customer communication preferences.
Response
Unique identifier for the created customerExample:
cust_1NXWPnCo6bFb1KQto6C8OWvECustomer’s email address
Customer’s first name
Customer’s last name
Customer’s full name (computed field)
Customer’s phone number
Customer’s date of birth
Customer’s address information
Customer’s loyalty tier
Marketing consent status
Associated Stripe customer ID (if Stripe integration is enabled)
ISO 8601 timestamp when the customer was created
ISO 8601 timestamp when the customer was last updated
Customer status:
active, inactive, suspendedCustomer’s lifetime value (computed from order history)
Total number of orders placed by this customer
Array of customer tags
Custom field key-value pairs
Customer communication preferences
Additional Features
Idempotency
Use theIdempotency-Key header to safely retry customer creation requests:
Stripe Integration
When Stripe integration is enabled:- A Stripe customer is automatically created if
stripe_customer_idis not provided - Customer data is synced between StateSet and Stripe
- Payment methods can be attached to the Stripe customer
Webhook Events
Creating a customer triggers these webhook events:customer.created- Fired when customer is successfully createdcustomer.stripe_synced- Fired when Stripe customer is created (if integration enabled)
Validation Rules
| Field | Validation |
|---|---|
email | Must be valid email format, unique across account |
first_name | 1-50 characters, letters and spaces only |
last_name | 1-50 characters, letters and spaces only |
phone | Valid phone number format |
date_of_birth | Valid date, customer must be at least 13 years old |
postal_code | Valid format for specified country |
country | Valid ISO 3166-1 alpha-2 country code |
Rate Limiting
Customer creation is subject to rate limits:- Standard: 100 customers/minute
- Enterprise: 1000 customers/minute