Customers - Create

POST /customers

Create a customer.

Try it: cURL example below.

cURL

curl --request POST \
  --url https://sandbox.hyperswitch.io/customers \
  --header 'Content-Type: application/json' \
  --header 'api-key: <api-key>' \
  --data '
{
  "email": "[email protected]",
  "name": "John Doe"
}
'

Response (200 - Customer Created):

Response (application/json)

{
  "customer_id": "cus_y3oqhf46pyzuxjbcn2giaqnb44",
  "created_at": "2023-01-18T11:04:09.922Z",
  "name": "Jon Test",
  "email": "[email protected]",
  "phone": "9123456789",
  "phone_country_code": "+65",
  "description": "First Customer",
  "address": {
    "city": "New York",
    "country": "AF",
    "line1": "123, King Street",
    "line2": "Powelson Avenue",
    "line3": "Bridgewater",
    "zip": "08807",
    "state": "New York",
    "first_name": "John",
    "last_name": "Doe",
    "origin_zip": "08807"
  },
  "metadata": {},
  "default_payment_method_id": "pm_djh2837dwduh890123",
  "tax_registration_id": "123456789"
}

---

Authorizations

api-key (header, required)

Use the API key created under your merchant account from the HyperSwitch dashboard. API key is used to authenticate API requests from your merchant server only. Don't expose this key on a website or embed it in a mobile application.

Do not expose the API key in client-side code or public repositories.

---

Body (application/json)

The customer details. All fields are optional unless otherwise noted.

customer_id

• Type: string | null

• Description: The identifier for the customer object. If not provided the customer ID will be autogenerated.

• Required string length: 1 - 64

• Example: "cus_y3oqhf46pyzuxjbcn2giaqnb44"

name

• Type: string | null

• Description: The customer's name

• Maximum length: 255

• Example: "Jon Test"

email

• Type: string | null

• Description: The customer's email address

• Maximum length: 255

• Example: "[email protected]"

phone

• Type: string | null

• Description: The customer's phone number

• Maximum length: 255

• Example: "9123456789"

phone_country_code

• Type: string | null

• Description: The country code for the customer phone number

• Maximum length: 255

• Example: "+65"

description

• Type: string | null

• Description: An arbitrary string that you can attach to a customer object.

• Maximum length: 255

• Example: "First Customer"

address

• Type: object

• Description: Address details

• Note: child attributes shown in the response example (city, country, line1, line2, line3, zip, state, first_name, last_name, origin_zip)

metadata

• Type: object

• Description: You can specify up to 50 keys, with key names up to 40 characters long and values up to 500 characters long. Metadata is useful for storing additional, structured information on an object.

tax_registration_id

• Type: string | null

• Description: Customer's tax registration ID

• Maximum length: 255

• Example: "123456789"

---

Response (200 - application/json)

Fields returned when a customer is created.

customer_id

• Type: string

• Required string length: 1 - 64

• Example: "cus_y3oqhf46pyzuxjbcn2giaqnb44"

created_at

• Type: string (date-time)

• Description: A timestamp (ISO 8601) that determines when the customer was created

• Example: "2023-01-18T11:04:09.922Z"

name

• Type: string | null

• Example: "Jon Test"

email

• Type: string | null

• Example: "[email protected]"

phone

• Type: string | null

• Example: "9123456789"

phone_country_code

• Type: string | null

• Example: "+65"

description

• Type: string | null

• Example: "First Customer"

address

• Type: object

• Description: Address details (see example above for child attributes)

metadata

• Type: object

• Description: Up to 50 keys; keys up to 40 chars; values up to 500 chars

default_payment_method_id

• Type: string | null

• Maximum length: 64

• Example: "pm_djh2837dwduh890123"

tax_registration_id

• Type: string | null

• Maximum length: 255

• Example: "123456789"

---

Related:

• Payment Method - Set Default Payment Method for Customer: https://api-reference.hyperswitch.io/v1/customer-set-default-payment-method/customers--set-default-payment-method

• Customers - Retrieve: https://api-reference.hyperswitch.io/v1/customers/customers--retrieve

Suggest edits: https://github.com/juspay/hyperswitch/edit/main/api-reference/v1/customers/customers--create.mdx Raise issue: https://github.com/juspay/hyperswitch/issues/new?title=Issue%20on%20docs&body=Path:%20/v1/customers/customers--create