Skip to main content

Search Invoices List

An invoice is a document you provide to your client after they purchase goods or services from you. It serves to both record the sale and request payment. For detailed information about PayTabs invoices, please refer to our articleWhat is PayTabs Invoice?

After your invoices are created and exist in the system, you may need to retrieve a list based on their creation date, regardless of their status: "paid," "pending," or "canceled." This article specifically explains the correct method for searching and retrieving invoice lists using the creation date through the designated API endpoint. Before proceeding with this integration, we strongly recommend reviewing theInvoices | Payment Workflowmanual to understand the business logic behind this process.

In this tutorial, we will rely on the PayTabs Search Invoice List Transaction API Endpoint, mentioned on the PayTabs API endpoints postman collection, which you can access fromhere. he endpoint will need to be accessed with the mentioned HTTP request via the below URL endpoint:

POST{{domain}}/payment/invoice/search
Be Aware Of

Please note that not using the proper endpoint URL {domain} will lead to authentication issues within your responses. To find the your proper domain you can read ourWhat is my (Region)/(endpoint URL)?tutorial article.

https://secure.paytabs.sa/payment/invoice/search
Important

If you created the invoice from the dashboard, cart_id corresponds to the title field, and customer_ref represents the customer ID in the dashboard fields.

Alt text

Request Parameters​

To make a retrieve invoice details request, there are required/optional parameter/s that need to be passed with valid information. The specification of these required parameters is clarified below according to the request type:

You can search using the profile ID only; however, the results will include data from the latest 45 days, starting from the date the request is retrieved.

ParameterData TypeMinMaxRequired
profile_id
INT

STRING		Accept only valid profile number.✔
The merchant Profile ID you can get from your PayTabs dashboard. For more information please check our How to get your account information from PT Dashboard? solution article. To know more about this parameter please click here.
{
 "profile_id": 987654
}

Sample Request/Response Payloads​

If you trigger a request using only profile_id, you will receive an array of invoices created within the last 45 days, which is the default date interval.

{
  "profile_id": 98XXX4
}

Expected Flow Behavior​

To search for the details of invoice/s, follow the steps below. This flow assumes that you have already initiated an invoice and received a valid invoice details

  • Begin by calling the API endpoint responsible for invoice creation. Upon successful creation, you can search for this invoice using the profile ID.

  • If you search directly using the endpoint mentioned in the above section Request Parameters with profile ID only, you will receive an array of invoice objects created within the latest 45 days.

    Example:
    • {
    "profile_id": 98XXX4
    }

  • If you search directly using the endpoint mentioned in the above section Request Parameters with profile ID, created_date_from, and created_date_to, you will receive an array of invoice objects for the specified date range, with a maximum interval of 45 days.

    Example:
    • {
    "profile_id": "8XXX4",
    "created_date_from": "01/11/2024",
    "created_date_to": "15/12/2024" // must be 45 days max interval between created_date_from and created_date_to
    }

We are glad to be always in help. We aim to serve you better each time. As such, please spare a minute to share feedback about your recent experience with PayTabs Developers , on Trustpilot, or Google Reviews.