Skip to main content

Request: Search invoices (created_date_from, created_date_to)

Warning

This parameter ONLY working with those integration types (Invoices).

This article provides an in-depth look at the Invoice Search feature, a valuable tool for merchants that want to search for invoice within specific range of days. With this feature, merchants can specify the start created_date_from and end created_date_from dates to search for invoices that fall within this range..

By implementing the created_date_from and created_date_from using the invoice search endpoint in a manner that will be explained later, merchants can fetch an array of all invoices within those days.

How this parameter could benefit you?​

Here are some scenarios to help you understand when to use the hide shipping parameter/feature:

  • Transaction Tracking: The returned invoice array includes the status of each invoice and, if paid, provides the transaction reference and date. This helps in tracking payment statuses and reconciling accounts.

  • Efficient Record Management: By narrowing down the search to a specific date range and filtering by cart_id and customer_ref, merchants can quickly locate relevant invoices, improving efficiency in record management.

  • Enhanced Reporting: These parameters facilitate the generation of accurate reports based on specific time periods and customer or cart details, aiding in financial analysis and decision-making.

Name but a few different Businesses/Industries that can benefit from this API parameter:

  • E-commerce: Online retailers can use these parameters to manage and track sales invoices over specific periods and filter by cart/order IDs cart_id or customer reference customer_ref, ensuring accurate financial reporting and customer billing.

  • Subscription Services: Companies offering subscription-based services can monitor recurring invoices and payments, ensuring timely renewals and customer satisfaction.

  • Healthcare: Medical practices and hospitals can track patient billing and insurance claims within defined date ranges and by patient details, improving financial management and patient record accuracy.

  • Education: Educational institutions can manage tuition fees and other payments by searching for invoices within specific academic terms or fiscal periods and filtering by student details.

  • Hospitality: Hotels and restaurants can track guest billing and payments, ensuring accurate financial records and customer service by filtering invoices by booking details.


Limitations​

While the created_date_from, created_date_to, cart_id, and customer_ref parameters offers several filter options, there are some limitations to consider:

  • Date Range Requirement: The parameters created_date_from and created_date_to must be used together. If only one of theme is provided with the other, will be ignored and the default range will be applied.

  • Search Range Limit: The maximum allowed range between created_date_from and created_date_to is 45 days. Any request exceeding this range will occurs a validation error.

  • Default Search Behavior: If both created_date_from and created_date_to are not provided, the API will return invoices from the most recent 45 days.

  • Mutual Exclusivity of Identifiers: The parameters cart_id and customer_ref are exclusive. Only one of them can be used in a single request. Using both simultaneously is not allowed.


How to Use?​

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

  • The first thing you will need to provide the proper endpoint URL to your request, as shown below:
    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
  • Then make the search request, you will use the optional parameter created_date_from and created_date_to within the request payload itself as shown below:

    {
        "profile_id": #####,
        "created_date_from": "02/05/2025",
        "created_date_to": "04/05/2025"
    }

  • Once you post your request, you will receive an array of invoices if exists, otherwise you will get the message "No matching invoices found".



Parameter Specifications​

  • created_date_from

    Parameter
    created_date_from
    DescriptionShow invoices result for a specific date.
    Data TypeDATE
    Required✘
    Validation RulesAn optional parameter to search for invoices from a specific day, date format DD/MM/YYYY
    Sample
    {
        "profile_id": "47157",
        "created_date_from": "01/11/2024",
        "created_date_to": "01/11/2024",
        "page": 2
    }
  • created_date_to

    Parameter
    created_date_to
    DescriptionShow invoices result for a specific date.
    Data TypeDATE
    Required✘
    Validation RulesAn optional parameter to search for invoices for a specific day, created_date_from and created_date_to should be the same date, date format DD/MM/YYYY
    Sample
    {
        "profile_id": "47157",
        "created_date_from": "01/11/2024",
        "created_date_to": "01/11/2024",
        "page": 2
    }
  • customer_ref

    Parameter
    customer_ref
    DescriptionIndicates the customer reference that is provided from the merchant side.
    Data TypeSTRING
    Required✘
    Sample
    {
        "customer_ref": "101"
    }
  • cart_id

    Parameter
    cart_id
    DescriptionIndicates the cart/order id at the merchant end, to easily relate the PayTabs transaction to.
    To know more about this parameter please click here.
    Data TypeSTRING
    Required✔
    Min1
    Max64
    Sample
    {
         "cart_id": "CART#10001"
    }



Request & Response Payloads Samples​

The below sample request payload will show you how you can pass the above-mentioned optional parameters, which are needed to filter the invoice search result.

{
    "profile_id": #####,
    "created_date_from": "06/10/2022",
    "created_date_to": "06/10/2022",
    "customer_ref": "101"
}

Warning

You can use both 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######"
}

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.