Customers

The Customers module in Kashier's API allows merchants to store, manage, and retrieve customer information. It enables the creation of customer profiles and links them to transactions at checkout. Merchants can update customer details, track payment history, and personalize the experience. This module simplifies recurring payments and improves customer insights for both businesses and customers.

Customer object structure

The customer interface.

{
  "_id": "67ba0311bf4f31001203c6c2",
  "name": "John Doe",
  "phoneNumber": "01XXXXXXXXX",
  "emailAddress": "",
  "customerId": "C-XXXXXXXXXXXXX",
  "merchantId": "MID-XXXXX-XXX",
  "customFields": [
    {
      "name": "custom-key-1",
      "value": "custom-value-1"
    },
    {
      "name": "custom-key-2",
      "value": "custom-value-2"
    }
  ],
  "createdByUserId": "5f8d0d55b54764421b7156c3",
  "__v": 0,
  "createdAt": "2025-02-22T17:02:10.098Z",
  "updatedAt": "2025-02-25T12:31:40.474Z",
  "id": "67ba0311bf4f31001203c6c2"
}

List all customers

Retrieve a list of all customers.

Endpoint	Value
TEST URL	https://test-api.kashier.io/v2/customers?page=1&limit=20&sortType=-1&sortBy=name
LIVE URL	https://api.kashier.io/v2/customers?page=1&limit=20&sortType=-1&sortBy=name
Method	GET

Query parameters

All of these are optional — call the route with no query string to get the first page with the defaults.

Key	Description
`page`	Page number. Default `1`.
`limit`	Records per page. Default `20`.
`sortBy`	Sort field: `name` or `createdAt`.
`sortType`	Sort order: `1` ascending, `-1` descending. Default `-1`.
`search`	Search term.
`searchBy`	Field to search in, for example `name`.
`startDate` / `endDate`	Date range filter, `YYYY-MM-DD`.
`labels`	Comma-separated label names.
`branchIds`	Comma-separated branch IDs.

curl --location 'https://test-api.kashier.io/v2/customers?page=1&limit=20&sortType=-1&sortBy=name'
      --header 'Authorization: YOUR_TEST_SECRET_KEY'

Headers

Key	Description
Authorization	The Authorization is the secret key that is used to identify the merchant. You can obtain it from Kashier dashboard. Learn more about Authorization.

Full parameter and response reference → List all customers.

Get customer details

Retrieve details of a specific customer.

Endpoint	Value
TEST URL	https://test-api.kashier.io/v2/customers/:id
LIVE URL	https://api.kashier.io/v2/customers/:id
Method	GET

curl --location 'https://test-api.kashier.io/v2/customers/:id' 
  --header 'Authorization: YOUR_TEST_SECRET_KEY'

Headers

Key	Description
Authorization	The Authorization is the secret key that is used to identify the merchant. You can obtain it from Kashier dashboard. Learn more about Authorization.

Full parameter and response reference → Get customer details.

Add new customer

Add a new customer.

Endpoint	Value
TEST URL	https://test-api.kashier.io/v2/customers
LIVE URL	https://api.kashier.io/v2/customers
Method	POST

curl --location 'https://test-api.kashier.io/v2/customers' 
  --header 'Authorization: YOUR_TEST_SECRET_KEY' 
  --data-raw '{
      "name": "John doe",
      "phoneNumber": "01123456789",
      "emailAddress": "[email protected]",
      "customFields": [
          {
              "name": "custom-key-1",
              "value": "custom-value-1"
          }
      ],
      "preferredCommunicationChannel":"sms"
  }'

Headers

Key	Description
Authorization	The Authorization is the secret key that is used to identify the merchant. You can obtain it from Kashier dashboard. Learn more about Authorization.

Full parameter and response reference → Add a new customer.

Update customer

Update a customer.

Endpoint	Value
TEST URL	https://test-api.kashier.io/v2/customers/:id
LIVE URL	https://api.kashier.io/v2/customers/:id
Method	PUT

curl --location --request PUT 'https://test-api.kashier.io/v2/customers/:id' 
  --header 'Authorization: YOUR_TEST_SECRET_KEY' 
  --data-raw '{
      "name": "John doe",
      "phoneNumber": "01123456789",
      "emailAddress": "[email protected]",
      "customFields": [
          {
              "name": "custom-key-1",
              "value": "custom-value-1"
          }
      ],
      "preferredCommunicationChannel":"sms"
  }'

Headers

Key	Description
Authorization	The Authorization is the secret key that is used to identify the merchant. You can obtain it from Kashier dashboard. Learn more about Authorization.

Full parameter and response reference → Update a customer.

Delete customer

Delete a customer.

Endpoint	Value
TEST URL	https://test-api.kashier.io/v2/customers/:id
LIVE URL	https://api.kashier.io/v2/customers/:id
Method	DELETE

curl --location --request DELETE 'https://test-api.kashier.io/v2/customers/:id' 
  --header 'Authorization: YOUR_TEST_SECRET_KEY'

Headers

Key	Description
Authorization	The Authorization is the secret key that is used to identify the merchant. You can obtain it from Kashier dashboard. Learn more about Authorization.

Full parameter and response reference → Delete a customer.

Bulk import

The process for importing customers from an Excel sheet requires two sequential API calls.

Upload Excel file API

Purpose: Upload and validate the Excel file containing customer data
Response:
- If errors are found in the data, they will be returned for correction.
- If validation passes, the API returns a correlationId
The correlationId serves as a reference to your validated data

Endpoint	Value
TEST URL	https://test-api.kashier.io/v2/customers/import
LIVE URL	https://api.kashier.io/v2/customers/import
Method	POST

curl --location --request POST 'https://test-api.kashier.io/v2/customers/import' 
      --header 'Authorization: YOUR_TEST_SECRET_KEY' 
      --form 'file=@"/home/boody/Downloads/customers.xlsx"'

Headers

Key	Description
Authorization	The Authorization is the secret key that is used to identify the merchant. You can obtain it from Kashier dashboard. Learn more about Authorization.

Full parameter and response reference → Upload a customers sheet for review.

Save customers API

Purpose: Permanently save the validated customer data to the system
Required: Include the correlationId as a query string parameter
This API finalizes the import process using the previously validated data

Endpoint	Value
TEST URL	https://test-api.kashier.io/v2/customers/savecustomers?correlationId=:correlationId
LIVE URL	https://api.kashier.io/v2/customers/savecustomers?correlationId=:correlationId
Method	GET

curl --location 'https://test-api.kashier.io/v2/customers/savecustomers?correlationId={{correlationId}}'
      --header 'Authorization: YOUR_TEST_SECRET_KEY'

Headers

Key	Description
Authorization	The Authorization is the secret key that is used to identify the merchant. You can obtain it from Kashier dashboard. Learn more about Authorization.

Full parameter and response reference → Save the uploaded customers.

This two-step approach ensures data integrity by separating validation from the actual import process.

On this page