Customers - Create

POST /v2/customers

Try it: cURL

Create customer (cURL)

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

Response (200 - Customer Created)

Example response

{
  "id": "12345_cus_01926c58bc6e77c09e809964e72af8c8",
  "merchant_reference_id": "cus_y3oqhf46pyzuxjbcn2giaqnb44",
  "created_at": "2023-01-18T11:04:09.922Z",
  "connector_customer_ids": {},
  "name": "Jon Test",
  "email": "[email protected]",
  "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"
  },
  "metadata": {},
  "default_payment_method_id": "12345_pm_01926c58bc6e77c09e809964e72af8c8",
  "tax_registration_id": "123456789"
}

---

Authorizations

Header: api-key (string) — 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: "[email protected]"

• 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 (see expandable)

• default_shipping_address — object Address details (see expandable)

• metadata — object You can specify up to 50 keys, with key names up to 40 characters long and values up to 500 characters long.

• tax_registration_id — string | null The customer's tax registration number. Maximum length: 255 Example: "123456789"

default_billing_address / default_shipping_address — Address details

This object contains address fields. (Original content lists this as "Address details" / "Showchild attributes".)

---

Response (200 — application/json)

Customer Created — fields returned:

• 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) of when the customer was created. Example: "2023-01-18T11:04:09.922Z"

• connector_customer_ids — object Connector specific customer reference ids

• name — string | null The customer's name. Maximum length: 255

• email — string | null The customer's email address. Maximum length: 255

• phone — string | null The customer's phone number. Maximum length: 255

• phone_country_code — string | null

• description — string | null

• default_billing_address — object Address details (see expandable above)

• default_shipping_address — object Address details (see expandable above)

• metadata — object Up to 50 keys; key names up to 40 chars; values up to 500 chars

• default_payment_method_id — string | null Identifier for the default payment method. Maximum length: 64

• tax_registration_id — string | null The customer's tax registration number. Maximum length: 255

---

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