Customers - List

GET /customers/list

cURL

curl

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

Successful response (200)

Example 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.

• name: api-key

• type: string

• in: header

• required: true

Query parameters

• offset (integer | null)

  • Offset for pagination

  • Required range: x >= 0

• limit (integer | null)

  • Limit for pagination

  • Required range: x >= 0

Response schema (200 — application/json)

Customers retrieved — array of customer objects. Key fields:

• customer_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"

• name (string | null)

  • The customer's name

  • Max length: 255

  • Example: "Jon Test"

• email (string | null)

  • The customer's email address

  • Max length: 255

  • Example: "[email protected]"

• phone (string | null)

  • The customer's phone number

  • Max length: 255

  • Example: "9123456789"

• phone_country_code (string | null)

  • The country code for the customer phone number

  • Max length: 255

  • Example: "+65"

• description (string | null)

  • An arbitrary string attached to a customer object

  • Max length: 255

  • Example: "First Customer"

• address (object)

  • Address details (child attributes shown in example response)

• metadata (object)

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

• default_payment_method_id (string | null)

  • Identifier for the default payment method

  • Max length: 64

  • Example: "pm_djh2837dwduh890123"

• tax_registration_id (string | null)

  • The customer's tax registration number

  • Max length: 255

  • Example: "123456789"

Useful links

• Documentation: https://api-reference.hyperswitch.io/introduction

• Locker API Reference: https://api-reference.hyperswitch.io/locker-api-reference/overview

• Intelligent Router API Reference: https://api-reference.hyperswitch.io/intelligent-router-api-reference/overview

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