Viewing Invoices
API Documentation for Viewing Invoices with Filters and Paging
This document provides detailed instructions for developers to view invoices for a specific merchant using the provided API, with added functionality for filtering and paging.
Endpoint
- URL:
/api/merchants/{merchantId}/invoices
- Method:
GET
- Content-Type:
application/json
Description
This API endpoint allows you to retrieve all invoices 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}/invoices
HTTP Method
GET
Request Headers
Content-Type: application/json
X-API-KEY: your_api_key
Query Parameters
- status (optional, string): Filter invoices by status. Example:
?status=paid
- startDate (optional, string): Filter invoices created after this date (inclusive), in
YYYY-MM-DD
format. Example:?startDate=2024-01-01
- endDate (optional, string): Filter invoices created before this date (inclusive), in
YYYY-MM-DD
format. Example:?endDate=2024-12-31
- customerPhone (optional, string): Filter invoices by customer phone or part of it.
- customerName (optional, string): Filter invoices by customer name or part of it.
- page (optional, integer): The page number for pagination. Example:
?page=1
- pageSize (optional, integer): The number of invoices per page. Example:
?pageSize=10
Example curl
Command
curl
Commandcurl -X GET 'https://api.paylink.sa/api/merchants/{merchantId}/invoices?status=paid&startDate=2024-01-01&endDate=2024-12-31&customerName=Hassan&customerPhone=56789&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:
{
"invoices": [
{
"invoiceId": "unique_invoice_id_1",
"merchantId": "merchant123",
"invoiceNumber": "INV-1001",
"date": "2024-07-10",
"dueDate": "2024-07-31",
"items": [
{
"description": "Web Development Services",
"quantity": 1,
"price": 5000
},
{
"description": "Hosting Services",
"quantity": 1,
"price": 200
}
],
"totalAmount": 5200,
"currency": "SAR",
"customerInfo": {
"customerName": "Customer XYZ",
"customerPhone": "966123456789"
},
"invoicePaymentUrl": "http://yourpaymentgateway.com/invoice/unique_invoice_id",
"status": "paid"
}
// Additional invoices
],
"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 view invoices for a specific merchant with filtering and paging options using the API.
Updated about 2 months ago