Viewing Customers

API Documentation for Listing Customers with Filters and Paging

This document provides detailed instructions for developers to list all customers for a specific merchant using the provided API, with added functionality for filtering and paging.

Endpoint

  • URL: /api/merchants/{merchantId}/customers
  • Method: GET
  • Content-Type: application/json

Description

This API endpoint allows you to retrieve all customers for a specific merchant, with options to filter results and paginate the response.

Request URL

Replace {merchantId} with the actual merchant ID.

https://api.paylink.sa/api/merchants/{merchantId}/customers

HTTP Method

  • GET

Request Headers

  • Content-Type: application/json
  • X-API-KEY: your_api_key

Query Parameters

  • status (optional, string): Filter customers by status. Example: ?status=active
  • startDate (optional, string): Filter customers created after this date (inclusive), in YYYY-MM-DD format. Example: ?startDate=2024-01-01
  • endDate (optional, string): Filter customers created before this date (inclusive), in YYYY-MM-DD format. Example: ?endDate=2024-12-31
  • page (optional, integer): The page number for pagination. Example: ?page=1
  • pageSize (optional, integer): The number of customers per page. Example: ?pageSize=10

Example curl Command

curl -X GET 'https://api.paylink.sa/api/merchants/{merchantId}/customers?status=active&startDate=2024-01-01&endDate=2024-12-31&page=1&pageSize=10' \
-H "Content-Type: application/json" \
-H "X-API-KEY: your_api_key"

Replace {merchantId} with the actual merchant ID and your_api_key with your actual API key in the headers.

Success Response

If the request is successful, you will receive a 200 OK status code with the following response body:

{
  "customers": [
    {
      "customerId": "customer123",
      "customerName": "Customer XYZ",
      "customerEmail": "[email protected]",
      "customerPhone": "966123456789"
    }
    // Additional customers
  ],
  "pagination": {
    "currentPage": 1,
    "pageSize": 10,
    "totalPages": 5,
    "totalItems": 50
  }
}

Error Response

If there is an error in the request, you will receive a 400 Bad Request status code with an error message:

{
  "message": "Invalid request data"
}

By following these steps and using the provided documentation, you should be able to successfully list all customers for a specific merchant with filtering and paging options using the API.