POST
/
v1
/
customers
curl -X POST https://api.stateset.com/v1/customers \
  -H "Authorization: Bearer sk_live_51HqJx2eZvKYlo2CXcQhJZPiQdoJO4v_FGtbA8QTy9E4tY" \
  -H "Content-Type: application/json" \
  -d '{
    "email": "john.doe@example.com",
    "first_name": "John",
    "last_name": "Doe",
    "phone": "+1-555-123-4567"
  }'

{
  "id": "cust_1NXWPnCo6bFb1KQto6C8OWvE",
  "email": "sarah.wilson@techcorp.com",
  "first_name": "Sarah",
  "last_name": "Wilson",
  "full_name": "Sarah Wilson",
  "phone": "+1-555-987-6543",
  "date_of_birth": "1985-12-03",
  "address": {
    "street1": "123 Innovation Drive",
    "street2": "Suite 200",
    "city": "San Francisco",
    "state": "CA",
    "postal_code": "94105",
    "country": "US"
  },
  "customer_tier": "gold",
  "marketing_consent": true,
  "referral_source": "paid_search",
  "stripe_customer_id": "cus_ABC123DEF456",
  "status": "active",
  "created_at": "2024-01-15T10:30:00Z",
  "updated_at": "2024-01-15T10:30:00Z",
  "lifetime_value": 0.00,
  "total_orders": 0,
  "tags": ["enterprise", "tech", "high-value"],
  "custom_fields": {
    "company_name": "Tech Corp",
    "job_title": "CTO",
    "industry": "Technology"
  },
  "preferences": {
    "email_notifications": true,
    "sms_notifications": false,
    "language": "en",
    "timezone": "America/Los_Angeles"
  }
}
This endpoint creates a new customer and can optionally create associated accounts in integrated systems like Stripe.

​
Request Body

​
email
string
required
Customer’s email address. Must be unique and valid format.Example: customer@example.com
​
first_name
string
required
Customer’s first name. Must be 1-50 characters.Example: John
​
last_name
string
required
Customer’s last name. Must be 1-50 characters.Example: Doe
​
phone
string
Customer’s phone number in E.164 format (recommended) or local format.Examples: +1-555-123-4567, (555) 123-4567
​
date_of_birth
string
Customer’s date of birth in ISO 8601 format (YYYY-MM-DD).Example: 1990-05-15
​
address
object
Customer’s primary address information.
​
marketing_consent
boolean
default:"false"
Whether the customer has consented to marketing communications.
​
customer_tier
string
default:"bronze"
Customer tier for loyalty programs. Options: bronze, silver, gold, platinum
​
referral_source
string
How the customer found your business.Options: organic, paid_search, social_media, referral, email, direct, other
​
stripe_customer_id
string
Existing 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.
​
notes
string
Internal notes about the customer (not visible to customer).Max length: 1000 characters
​
tags
array
Array of tags for customer segmentation and organization.Example: ["vip", "wholesale", "early-adopter"]
​
custom_fields
object
Additional custom fields as key-value pairs. Keys must be alphanumeric with underscores.Example:
{
  "company_name": "Acme Corp",
  "industry": "Technology",
  "employee_count": "50-100"
}
​
preferences
object
Customer communication preferences.

​
Response

​
id
string
Unique identifier for the created customerExample: cust_1NXWPnCo6bFb1KQto6C8OWvE
​
email
string
Customer’s email address
​
first_name
string
Customer’s first name
​
last_name
string
Customer’s last name
​
full_name
string
Customer’s full name (computed field)
​
phone
string
Customer’s phone number
​
date_of_birth
string
Customer’s date of birth
​
address
object
Customer’s address information
​
customer_tier
string
Customer’s loyalty tier
​
marketing_consent
boolean
Marketing consent status
​
stripe_customer_id
string
Associated Stripe customer ID (if Stripe integration is enabled)
​
created_at
string
ISO 8601 timestamp when the customer was created
​
updated_at
string
ISO 8601 timestamp when the customer was last updated
​
status
string
Customer status: active, inactive, suspended
​
lifetime_value
number
Customer’s lifetime value (computed from order history)
​
total_orders
integer
Total number of orders placed by this customer
​
tags
array
Array of customer tags
​
custom_fields
object
Custom field key-value pairs
​
preferences
object
Customer communication preferences
curl -X POST https://api.stateset.com/v1/customers \
  -H "Authorization: Bearer sk_live_51HqJx2eZvKYlo2CXcQhJZPiQdoJO4v_FGtbA8QTy9E4tY" \
  -H "Content-Type: application/json" \
  -d '{
    "email": "john.doe@example.com",
    "first_name": "John",
    "last_name": "Doe",
    "phone": "+1-555-123-4567"
  }'

{
  "id": "cust_1NXWPnCo6bFb1KQto6C8OWvE",
  "email": "sarah.wilson@techcorp.com",
  "first_name": "Sarah",
  "last_name": "Wilson",
  "full_name": "Sarah Wilson",
  "phone": "+1-555-987-6543",
  "date_of_birth": "1985-12-03",
  "address": {
    "street1": "123 Innovation Drive",
    "street2": "Suite 200",
    "city": "San Francisco",
    "state": "CA",
    "postal_code": "94105",
    "country": "US"
  },
  "customer_tier": "gold",
  "marketing_consent": true,
  "referral_source": "paid_search",
  "stripe_customer_id": "cus_ABC123DEF456",
  "status": "active",
  "created_at": "2024-01-15T10:30:00Z",
  "updated_at": "2024-01-15T10:30:00Z",
  "lifetime_value": 0.00,
  "total_orders": 0,
  "tags": ["enterprise", "tech", "high-value"],
  "custom_fields": {
    "company_name": "Tech Corp",
    "job_title": "CTO",
    "industry": "Technology"
  },
  "preferences": {
    "email_notifications": true,
    "sms_notifications": false,
    "language": "en",
    "timezone": "America/Los_Angeles"
  }
}

​
Additional Features

​
Idempotency

Use the Idempotency-Key header to safely retry customer creation requests: 
curl -X POST https://api.stateset.com/v1/customers \
  -H "Idempotency-Key: customer-signup-form-abc123" \
  -H "Authorization: Bearer sk_live_..." \
  -d '{"email": "customer@example.com", ...}'

​
Stripe Integration

When Stripe integration is enabled:
  • A Stripe customer is automatically created if stripe_customer_id is 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 created
  • customer.stripe_synced - Fired when Stripe customer is created (if integration enabled)

​
Validation Rules

FieldValidation
emailMust be valid email format, unique across account
first_name1-50 characters, letters and spaces only
last_name1-50 characters, letters and spaces only
phoneValid phone number format
date_of_birthValid date, customer must be at least 13 years old
postal_codeValid format for specified country
countryValid ISO 3166-1 alpha-2 country code

​
Rate Limiting

Customer creation is subject to rate limits:
  • Standard: 100 customers/minute
  • Enterprise: 1000 customers/minute
Consider using batch import for large datasets.