Customers - List

GET /v2/customers/list

Example (cURL):

curl

curl --request GET \
  --url https://sandbox.hyperswitch.io/v2/customers/list \
  --header 'api-key: <api-key>'

Response: 200 application/json

200 - 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

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. Do not expose this key on a website or embed it in a mobile application.

---

Response schema (200 — Customers retrieved)

• 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, required) A timestamp (ISO 8601) 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 Example: "Jon Test"

• email (string | null) The customer's email address. Maximum length: 255 Example: "[email protected]"

• 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 attached to a customer object. Maximum length: 255 Example: "First Customer"

• default_billing_address (object) Address details. Fields shown in the example:

  • city

  • country

  • line1

  • line2

  • line3

  • zip

  • state

  • first_name

  • last_name

  • origin_zip

• default_shipping_address (object) Address details (same child attributes as billing address).

• metadata (object) Up to 50 keys, key names up to 40 characters, values up to 500 characters. Useful for storing additional structured information on an object.

• default_payment_method_id (string | null) 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"

---

Suggest edits or raise an issue:

• Edit on GitHub: https://github.com/juspay/hyperswitch/edit/main/api-reference/v2/customers/customers--list.mdx

• Raise issue: https://github.com/juspay/hyperswitch/issues/new?title=Issue%20on%20docs&body=Path:%20/v2/customers/customers--list