Skip to main content

Search invoices (created_date_from, created_date_to)

Warning

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

In the evolving landscape of online payments, flexibility and user-centric options are paramount. PayTabs introduces the Donation Mode feature, designed to enhance the donation experience for users. This feature allows merchants to create a payment page where donors can select an amount within a predefined range, offering a seamless and customizable donation process.

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:

  • 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".

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
    {
     "created_date_from": "01/11/2024",
    }
  • created_date_to

    Parameter
    created_date_to
    DescriptionShow invoices result for a specific date. Mandatory if created_date_from is given in the request
    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
    {
     "created_date_to": "01/11/2024",
    }

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" // this cannot be use with cart_id, only one should be used
}

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 forinvoice 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.