feat(customers): add time range filtering and count functionality to customer list endpoints by VenuMadhav2541 · Pull Request #9767 · juspay/hyperswitch

VenuMadhav2541 · 2025-10-09T09:20:05Z

Type of Change

Description

Added time range filter support in the customer list API to fetch customers based on created_at between start_time and end_time.
Implemented count functionality to return both the filtered customer list and total count for pagination.
If customer_id is provided, the time range filter is skipped — only one filter applies at a time.

Additional Changes

This PR modifies the API contract
This PR modifies the database schema
This PR modifies application configuration/environment variables

Motivation and Context

This change enhances the customer list endpoints by adding time range filtering and count functionality. Previously, the API did not allow merchants to filter customers by their creation date, making it difficult to fetch customers within a specific time window.
Additionally, the count functionality enables accurate pagination on the client side by returning the total number of filtered customers along with the list.
Together, these improvements make the customer list API more flexible, efficient, and suitable for large datasets, improving the overall user experience for merchants.

How did you test it?

Verified API manually with time_range[start_time] and time_range[end_time].

curl --location 'http://localhost:9000/api/customers/list_with_count?limit=20&offset=0&start_time=2025-10-06T18%3A30%3A00Z&end_time=2025-10-08T14%3A09%3A23Z' \
--header 'Accept: application/json' \
--header 'api-key: ••••••' \
--header 'Content-Type: text/plain' \
--data-binary '@'

Response

{
    "data": [
        {
            "customer_id": "cus_123",
            "name": "venu 12",
            "email": "guest@example.com",
            "phone": "999999999",
            "phone_country_code": "+65",
            "description": "First customer",
            "address": null,
            "created_at": "2025-10-08T08:10:06.395Z",
            "metadata": {
                "udf1": "value1",
                "new_customer": "true",
                "login_date": "2019-09-10T10:11:12Z"
            },
            "default_payment_method_id": null,
            "tax_registration_id": null
        },
        {
            "customer_id": "cus_124",
            "name": "venu 13",
            "email": "guest@example.com",
            "phone": "999999999",
            "phone_country_code": "+65",
            "description": "First customer",
            "address": null,
            "created_at": "2025-10-08T08:10:11.296Z",
            "metadata": {
                "udf1": "value1",
                "new_customer": "true",
                "login_date": "2019-09-10T10:11:12Z"
            },
            "default_payment_method_id": null,
            "tax_registration_id": null
        },
        {
            "customer_id": "cus_123125",
            "name": "venu 14",
            "email": "guest@example.com",
            "phone": "999999999",
            "phone_country_code": "+65",
            "description": "First customer",
            "address": null,
            "created_at": "2025-10-08T08:10:16.067Z",
            "metadata": {
                "udf1": "value1",
                "new_customer": "true",
                "login_date": "2019-09-10T10:11:12Z"
            },
            "default_payment_method_id": null,
            "tax_registration_id": null
        }
    ],
    "count": 22
}

Verified API manually with time_range[start_time].

curl --location 'http://localhost:9000/api/customers/list_with_count?limit=20&offset=0&start_time=2025-10-06T18%3A30%3A00Z' \
--header 'Accept: application/json' \
--header 'api-key: ••••••' \
--header 'Content-Type: text/plain' \
--data-binary '@'

Response:

{
    "data": [
        {
            "customer_id": "cus_123",
            "name": "venu 12",
            "email": "guest@example.com",
            "phone": "999999999",
            "phone_country_code": "+65",
            "description": "First customer",
            "address": null,
            "created_at": "2025-10-08T08:10:06.395Z",
            "metadata": {
                "udf1": "value1",
                "new_customer": "true",
                "login_date": "2019-09-10T10:11:12Z"
            },
            "default_payment_method_id": null,
            "tax_registration_id": null
        },
        {
            "customer_id": "cus_124",
            "name": "venu 13",
            "email": "guest@example.com",
            "phone": "999999999",
            "phone_country_code": "+65",
            "description": "First customer",
            "address": null,
            "created_at": "2025-10-08T08:10:11.296Z",
            "metadata": {
                "udf1": "value1",
                "new_customer": "true",
                "login_date": "2019-09-10T10:11:12Z"
            },
            "default_payment_method_id": null,
            "tax_registration_id": null
        },
        {
            "customer_id": "cus_123125",
            "name": "venu 14",
            "email": "guest@example.com",
            "phone": "999999999",
            "phone_country_code": "+65",
            "description": "First customer",
            "address": null,
            "created_at": "2025-10-08T08:10:16.067Z",
            "metadata": {
                "udf1": "value1",
                "new_customer": "true",
                "login_date": "2019-09-10T10:11:12Z"
            },
            "default_payment_method_id": null,
            "tax_registration_id": null
        }
    ],
    "count": 22
}

Verified API manually with Customer_Id and Time Range.

curl --location 'http://localhost:9000/api/customers/list_with_count?limit=20&offset=0&start_time=2025-10-06T18%3A30%3A00Z&end_time=2025-10-08T14%3A09%3A23Z&customer_id=cus_123' \
--header 'Accept: application/json' \
--header 'api-key: ••••••' \
--header 'Content-Type: text/plain' \
--data-binary '@'

Response:

{
    "data": [
        {
            "customer_id": "cus_123",
            "name": "venu 12",
            "email": "guest@example.com",
            "phone": "999999999",
            "phone_country_code": "+65",
            "description": "First customer",
            "address": null,
            "created_at": "2025-10-08T08:10:06.395Z",
            "metadata": {
                "udf1": "value1",
                "new_customer": "true",
                "login_date": "2019-09-10T10:11:12Z"
            },
            "default_payment_method_id": null,
            "tax_registration_id": null
        }
    ],
    "count": 22
}

Checklist

I formatted the code cargo +nightly fmt --all
I addressed lints thrown by cargo clippy
I reviewed the submitted code
I added unit tests for my changes where possible

…customer list endpoints

semanticdiff-com · 2025-10-09T09:20:08Z

Review changes with

Changed Files

File	Status
crates/router/src/routes/lock_utils.rs	83% smaller
crates/router/src/types/api/customers.rs	51% smaller
crates/api_models/src/events/customer.rs	9% smaller
crates/router/src/routes/app.rs	9% smaller
crates/storage_impl/src/customers.rs	7% smaller
crates/diesel_models/src/query/customers.rs	1% smaller
crates/diesel_models/src/query/generics.rs	1% smaller
crates/api_models/src/customers.rs	0% smaller
crates/hyperswitch_domain_models/src/customer.rs	0% smaller
crates/router/src/compatibility/stripe/errors.rs	0% smaller
crates/router/src/core/customers.rs	0% smaller
crates/router/src/core/errors/customers_error_response.rs	0% smaller
crates/router/src/core/errors/transformers.rs	0% smaller
crates/router/src/core/locker_migration.rs	0% smaller
crates/router/src/core/utils.rs	0% smaller
crates/router/src/core/utils/customer_validation.rs	0% smaller
crates/router/src/db/kafka_store.rs	0% smaller
crates/router/src/routes/customers.rs	0% smaller
crates/router_env/src/logger/types.rs	0% smaller

apoorvdixit88 · 2025-10-10T09:25:49Z

crates/api_models/src/customers.rs

+    /// List of customers
+    pub data: Vec<CustomerResponse>,
+    /// Total count of customers
+    pub count: usize,


can we call it total_count? count can be the size of data list like we have in other apis.

crates/api_models/src/customers.rs

crates/diesel_models/src/query/customers.rs

crates/diesel_models/src/query/generics.rs

crates/router/src/core/customers.rs

crates/router/src/routes/customers.rs

…nstraints

crates/api_models/src/events/customer.rs

crates/router/src/routes/customers.rs

crates/storage_impl/src/customers.rs

crates/api_models/src/customers.rs

crates/router/src/core/customers.rs

crates/router/src/routes/app.rs

crates/router/src/routes/customers.rs

crates/router_env/src/logger/types.rs

crates/diesel_models/src/query/customers.rs

hrithikesh026 · 2025-10-15T11:55:22Z

crates/api_models/src/events/customer.rs

+
+impl ApiEventMetric for CustomerListResponse {
+    fn get_api_event_type(&self) -> Option<ApiEventsType> {
+        None


Why is this None?

hrithikesh026 · 2025-10-15T12:15:25Z

crates/router/src/core/errors/transformers.rs

                AER::InternalServerError(ApiError::new("HE", 0, "Something went wrong", None))
            }
+            Self::InvalidRequestData { message } => {
+                AER::BadRequest(ApiError::new("IR", 400, message, None))


pass appropriate values as per this doc. https://api-reference.hyperswitch.io/essentials/error_codes

Also pass some meaningful error message

hrithikesh026 · 2025-10-15T12:19:24Z

crates/router/src/core/utils/customer_validation.rs

+pub const CUSTOMER_LIST_UPPER_LIMIT: u16 = 100;
+pub const CUSTOMER_LIST_DEFAULT_LIMIT: u16 = 10;
+
+pub fn validate_customer_list_limit(


can have a domain wrapper type for u16. Which can only exist if the value is within 1 and 100. And 10 as default trait impl.

refer to https://github.com/juspay/hyperswitch/blob/main/crates/common_types/src/primitive_wrappers.rs

hrithikesh026 · 2025-10-15T12:19:48Z

crates/router/src/core/customers.rs

+pub async fn list_customers_with_count(
+    state: SessionState,
+    merchant_id: id_type::MerchantId,
+    _profile_id_list: Option<Vec<id_type::ProfileId>>,


This can be removed if not used

hrithikesh026 · 2025-10-15T12:25:03Z

Also start_time and end_time is not very descriptive.

created_lt, created_lte created_gt would be nice.

apoorvdixit88 · 2025-10-15T12:05:22Z

crates/router/src/core/customers.rs

+        customer_id: None,
+        time_range: None,
    };


Why this is changed to None?

apoorvdixit88 · 2025-10-15T12:07:46Z

crates/router/src/core/customers.rs

+) -> errors::CustomerResponse<customers::CustomerListResponse> {
+    let db = state.store.as_ref();
+    let limit =
+        crate::core::utils::customer_validation::validate_customer_list_limit(request.limit)


Nitpick*: Instead of bid qualification paths, we can import some part always, and then qualify it as utils::something, and this can be done at most of the places.

…_constraints

hrithikesh026

Please Generate Openapi spec for the new api. If not here, then in a separate PR.

…customer list endpoints (#9767) Co-authored-by: hyperswitch-bot[bot] <148525504+hyperswitch-bot[bot]@users.noreply.github.com>

…customer list endpoints (juspay#9767) Co-authored-by: hyperswitch-bot[bot] <148525504+hyperswitch-bot[bot]@users.noreply.github.com>

…customer list endpoints (#9767) Co-authored-by: hyperswitch-bot[bot] <148525504+hyperswitch-bot[bot]@users.noreply.github.com>

feat(customers): add time range filtering and count functionality to …

a906911

…customer list endpoints

VenuMadhav2541 requested review from a team as code owners October 9, 2025 09:20

VenuMadhav2541 added 2 commits October 9, 2025 14:50

Merge branch 'main' into customer_count

c107780

Customer changes unwrap_or_else(common_utils::date_time::now)

39b4e1f

VenuMadhav2541 self-assigned this Oct 9, 2025

VenuMadhav2541 added the C-feature Category: Feature request or enhancement label Oct 9, 2025

VenuMadhav2541 linked an issue Oct 9, 2025 that may be closed by this pull request

[FEAT] Add search and total_count support for customer list API. juspay/hyperswitch-control-center#3639

Closed

hyperswitch-bot bot and others added 2 commits October 9, 2025 09:58

chore: run formatter

abcf9dd

unwrap_or_else(common_utils::date_time::now) in v2

4af766d

VenuMadhav2541 linked an issue Oct 9, 2025 that may be closed by this pull request

[FEATURE] Add filter and Pagination in Customer Page #9768

Closed

2 tasks

VenuMadhav2541 and others added 2 commits October 9, 2025 17:08

diesel_error_to_data_error for V2

de7cf73

chore: run formatter

6bc3d66

VenuMadhav2541 removed a link to an issue Oct 9, 2025

[FEAT] Add search and total_count support for customer list API. juspay/hyperswitch-control-center#3639

Closed

VenuMadhav2541 changed the title ~~feat(customers): add time range filtering and count functionality to …~~ feat(customers): add time range filtering and count functionality to customer list endpoints Oct 9, 2025

apoorvdixit88 reviewed Oct 10, 2025

View reviewed changes

VenuMadhav2541 and others added 5 commits October 12, 2025 12:37

Changes for the new API Request

d5cd720

chore: run formatter

ebc7822

ApiEventsType for the V2

dfbc4cd

ApiEventMetric for the V2

713da97

request for the list_customer_with_count to CustomerListRequestWithCo…

ece3a5a

…nstraints

VenuMadhav2541 requested a review from apoorvdixit88 October 13, 2025 10:39

tsdk02 reviewed Oct 14, 2025

View reviewed changes

VenuMadhav2541 and others added 5 commits October 14, 2025 20:56

Craeted new flow for the new API end point

4fd53d8

chore: run formatter

83bf979

Added Line spacing in every function to follow coding standards

34a7257

chore: run formatter

190191a

CustomerListRequestWithConstraints for V2 change

64dba28

su-shivanshmathur requested changes Oct 15, 2025

View reviewed changes

crates/api_models/src/customers.rs Show resolved Hide resolved

apoorvdixit88 reviewed Oct 15, 2025

View reviewed changes

Naming convention changes in the Customer List APi

d799dd9

VenuMadhav2541 requested review from apoorvdixit88 and su-shivanshmathur October 15, 2025 09:34

VenuMadhav2541 and others added 2 commits October 15, 2025 15:11

Merge branch 'main' into customer_count

45c29cd

Custom Error for the customer list limit

a39fa40

VenuMadhav2541 requested a review from a team as a code owner October 15, 2025 10:06

chore: run formatter

80365bc

hrithikesh026 reviewed Oct 15, 2025

View reviewed changes

apoorvdixit88 reviewed Oct 15, 2025

View reviewed changes

VenuMadhav2541 and others added 4 commits October 15, 2025 19:04

Error message and Customer_id changes

7532d2d

Error correction in InternalServerError

bf3ecc6

Merge branch 'main' into customer_count

4fb7b39

naming convention change in the get_customer_count_by_merchant_id_and…

735dfa0

…_constraints

tsdk02 approved these changes Oct 15, 2025

View reviewed changes

sahkal approved these changes Oct 16, 2025

View reviewed changes

su-shivanshmathur approved these changes Oct 16, 2025

View reviewed changes

hrithikesh026 approved these changes Oct 16, 2025

View reviewed changes

likhinbopanna added this pull request to the merge queue Oct 16, 2025

Merged via the queue into main with commit 587588f Oct 16, 2025
22 of 25 checks passed

likhinbopanna deleted the customer_count branch October 16, 2025 08:13

chaitak-gorai pushed a commit that referenced this pull request Oct 16, 2025

feat(customers): add time range filtering and count functionality to …

35a8f79

…customer list endpoints (#9767) Co-authored-by: hyperswitch-bot[bot] <148525504+hyperswitch-bot[bot]@users.noreply.github.com>

aadityaguptaa pushed a commit that referenced this pull request Nov 10, 2025

feat(customers): add time range filtering and count functionality to …

b5f66c7

…customer list endpoints (#9767) Co-authored-by: hyperswitch-bot[bot] <148525504+hyperswitch-bot[bot]@users.noreply.github.com>

Conversation

VenuMadhav2541 commented Oct 9, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Type of Change

Description

Additional Changes

Motivation and Context

How did you test it?

Checklist

Uh oh!

semanticdiff-com bot commented Oct 9, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

apoorvdixit88 Oct 10, 2025

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

hrithikesh026 Oct 15, 2025

Choose a reason for hiding this comment

Uh oh!

hrithikesh026 Oct 15, 2025

Choose a reason for hiding this comment

Uh oh!

hrithikesh026 Oct 15, 2025

Choose a reason for hiding this comment

Uh oh!

hrithikesh026 Oct 15, 2025

Choose a reason for hiding this comment

Uh oh!

hrithikesh026 commented Oct 15, 2025

Uh oh!

apoorvdixit88 Oct 15, 2025

Choose a reason for hiding this comment

Uh oh!

apoorvdixit88 Oct 15, 2025

Choose a reason for hiding this comment

Uh oh!

hrithikesh026 left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

7 participants

VenuMadhav2541 commented Oct 9, 2025 •

edited

Loading

semanticdiff-com bot commented Oct 9, 2025 •

edited

Loading