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

In order for you to start use the invoice search feature, you need to follow the below simple steps:


  • To search for invoices, you may use only the profile_id in your request. In this case, the system will return invoices from the last 45 days, counted from today.


  • If you choose to use Created_date_from, you must also include created_date_to. The interval between them must not exceed 45 days (it may be less).



    {
      "profile_id": 123456,
      "created_date_from": "01/02/2025",
      "created_date_to": "15/03/2025"
    }

  • If the invoice is older than 45 days and you know the customer_ref, you must provide Created_date_from and created_date_to as well, ensuring the chosen date range roughly matches the invoice period.



    {
      "profile_id": 123456,
      "customer_ref": "CUST-8899",
      "created_date_from": "01/09/2024",
      "created_date_to": "20/09/2024"
    }

  • Similarly, if you know the cart_id of an invoice older than 45 days, you must include Created_date_from and created_date_to with an approximate matching period.



    {
      "profile_id": 123456,
      "cart_id": "CART-5588",
      "created_date_from": "10/08/2024",
      "created_date_to": "25/08/2024"
    }
    • Warning

    You can use any of those parameters customer_ref, and cart_id, to filter the search results, but not together.

    If you use both of them in the same search request, you will get the error: 422 Unprocessable Entity. 

    {
      "code": 2,
      "message": "Invalid search parameters. Please provide either 'customer_ref' or 'cart_id', not both, for search operation.",
      "trace": "PMN######.682######.000######"
    }

  • If the invoice you are searching for (via cart_id or customer_ref) was created within the last 45 days, you do not need to include Created_date_from or created_date_to.



    {
      "profile_id": 123456,
      "cart_id": "CART-1122"
    }

  • Once the request is submitted, you will receive an array of invoices if matching records exist. Otherwise, the response will return: "No matching invoices found".

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.