POST
/
v2
/
customers
Customers - Create
curl --request POST \
  --url https://sandbox.hyperswitch.io/v2/customers \
  --header 'Content-Type: application/json' \
  --header 'api-key: <api-key>' \
  --data '{
  "email": "guest@example.com",
  "name": "John Doe"
}'
{
  "id": "12345_cus_01926c58bc6e77c09e809964e72af8c8",
  "merchant_reference_id": "cus_y3oqhf46pyzuxjbcn2giaqnb44",
  "connector_customer_ids": {},
  "name": "Jon Test",
  "email": "JonTest@test.com",
  "phone": "9123456789",
  "phone_country_code": "+65",
  "description": "First Customer",
  "default_billing_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"
  },
  "default_shipping_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"
  },
  "created_at": "2023-01-18T11:04:09.922Z",
  "metadata": {},
  "default_payment_method_id": "12345_pm_01926c58bc6e77c09e809964e72af8c8",
  "tax_registration_id": "123456789"
}

Authorizations

​
api-key
string
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.

Body

application/json

The customer details

​
name
string
required

The customer's name

Maximum length: 255
Example:

"Jon Test"

​
email
string
required

The customer's email address

Maximum length: 255
Example:

"JonTest@test.com"

​
merchant_reference_id
string | null

The merchant identifier for the customer object.

Required string length: 1 - 64
Example:

"cus_y3oqhf46pyzuxjbcn2giaqnb44"

​
phone
string | null

The customer's phone number

Maximum length: 255
Example:

"9123456789"

​
description
string | null

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

Maximum length: 255
Example:

"First Customer"

​
phone_country_code
string | null

The country code for the customer phone number

Maximum length: 255
Example:

"+65"

​
default_billing_address
object

Address details

​
default_shipping_address
object

Address details

​
metadata
object | null

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
string | null

The customer's tax registration number.

Maximum length: 255
Example:

"123456789"

Response

Customer Created

​
id
string
required

Unique identifier for the customer

Required string length: 32 - 64
Example:

"12345_cus_01926c58bc6e77c09e809964e72af8c8"

​
merchant_reference_id
string
required

The identifier for the customer object

Required string length: 1 - 64
Example:

"cus_y3oqhf46pyzuxjbcn2giaqnb44"

​
created_at
string<date-time>
required

A timestamp (ISO 8601 code) that determines when the customer was created

Example:

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

​
connector_customer_ids
object | null

Connector specific customer reference ids

​
name
string | null

The customer's name

Maximum length: 255
Example:

"Jon Test"

​
email
string | null

The customer's email address

Maximum length: 255
Example:

"JonTest@test.com"

​
phone
string | null

The customer's phone number

Maximum length: 255
Example:

"9123456789"

​
phone_country_code
string | null

The country code for the customer phone number

Maximum length: 255
Example:

"+65"

​
description
string | null

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

Maximum length: 255
Example:

"First Customer"

​
default_billing_address
object

Address details

​
default_shipping_address
object

Address details

​
metadata
object | null

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.

​
default_payment_method_id
string | null

The identifier for the default payment method.

Maximum length: 64
Example:

"12345_pm_01926c58bc6e77c09e809964e72af8c8"

​
tax_registration_id
string | null

The customer's tax registration number.

Maximum length: 255
Example:

"123456789"