Onboard new customer

📘
API Refs

Staging: Onboard new customer

Request body

Name	Type	Description	Required
email	string	Customer email address	yes
firstName	string	Customer first name	no
lastName	string	Customer last name	no
phone	string	Customer phone number	no
address	object	Customer address	no

Address Object Structure

Name	Type	Description	Required
street	string	Street address	no
city	string	City	no
state	string	State or province	no
postalCode	string	Postal/ZIP code	no

Example Request

{
  "email": "[email protected]",
  "firstName": "John",
  "lastName": "Doe",
  "phone": "+1234567890",
  "address": {
    "street": "123 Main St",
    "city": "New York",
    "state": "NY",
    "postalCode": "10001"
  }
}

Response

Success Response (201 Created)

Field	Type	Description
customer	object	The created/found customer object
stripeCustomerId	string	The Stripe customer ID
message	string	Success message

Customer Object Structure

Field	Type	Description
id	string	Customer ID
email	string	Customer email address
firstName	string	Customer first name
lastName	string	Customer last name
phone	string	Customer phone number
address	object	Customer address
stripeCustomerId	string	Stripe customer ID
createdAt	string	Customer creation date
updatedAt	string	Last update date

Response

{
  "customer": {
    "id": "123",
    "email": "[email protected]",
    "firstName": "John",
    "lastName": "Doe",
    "phone": "+1234567890",
    "address": {
      "street": "123 Main St",
      "city": "New York",
      "state": "NY",
      "postalCode": "10001"
    },
    "stripeCustomerId": "cus_ExampleCustomerID123",
    "createdAt": "2024-01-01T00:00:00.000Z",
    "updatedAt": "2024-01-01T00:00:00.000Z"
  },
  "stripeCustomerId": "cus_ExampleCustomerID123",
  "message": "Customer successfully onboarded"
}

Important Notes

Idempotent Operation: If a customer with the same email already exists, the API will return the existing customer instead of creating a duplicate.
Stripe Integration: This endpoint automatically creates a corresponding customer in Stripe, enabling payment processing capabilities.
Payment Method: While this endpoint creates the customer, you'll need to use Stripe's payment method APIs or the billing portal to add payment methods.
Required Fields: Only email is required. Other fields can be added later using the update customer endpoint.

Error Responses

400 Bad Request: Invalid customer data or payment method setup failed
401 Unauthorized: Invalid or missing authorization token
403 Forbidden: Insufficient permissions

Use Cases

New Customer Registration: Use when a new customer signs up for your service
Pre-subscription Setup: Create customer account before setting up subscriptions
Customer Import: Bulk import customers from other systems