Navigating Customer Group Exclusions: A Deep Dive into ESHOPMAN Admin API Filtering

Understanding Customer Group Filtering Challenges in ESHOPMAN Admin API

At Move My Store, we often see ESHOPMAN users leveraging the powerful Admin API for precise customer segmentation. However, a recent community discussion highlighted a specific challenge when attempting to filter customers who do not belong to a particular customer group. This insight delves into the technical nuances of this issue, offering clarity for ESHOPMAN developers and merchants.

The Core Problem: Excluding Customers from Specific Groups

An ESHOPMAN user reported difficulties when trying to retrieve a list of customers that are explicitly not members of a given customer group. This is a common requirement for targeted marketing campaigns, access control, or specialized reporting within the ESHOPMAN Admin Hub. The user's attempts using various query string formats with negation operators like $nin (not in) or $ne (not equal) consistently led to either API validation errors or, more critically, incorrect results where customers who should have been excluded were still returned.

Here are some of the problematic query string examples shared by the user:

Attempted queries leading to "Invalid request: Expected type: 'string, array' for field 'groups', got: '[object Object]'":

/admin/customers?groups[id][$nin][]=cusgroup_123
/admin/customers?groups[id][$not][$eq]=cusgroup_123

Attempted queries returning customers who are members of the specified group:

/admin/customers?groups[$ne]==cusgroup_123
/admin/customers?groups[$or][0][id][$eq]=&groups[$or][1][id][$ne]=cusgroup_123

Technical Deep Dive: Why the Filters Fail

The ESHOPMAN team acknowledged this as a bug, providing a detailed breakdown of the underlying causes within the Node.js/TypeScript framework:

• API Validation Mismatch: The primary issue for queries using $nin or $not stems from the ESHOPMAN Admin API's internal validation schema. Specifically, the id field within the customer group parameters was typed as a simple string or array, rather than supporting the more complex operator map required for advanced filtering. This caused Zod validation (an internal schema validation library) to reject valid negation syntax, resulting in the "Invalid request" error.
• Silent Key Stripping in Query Processing: For queries using $ne directly on the groups field, the problem was more subtle. During the API's internal parsing, the unknown $ne key was silently stripped. This resulted in an empty object being passed to the underlying data querying logic, which then incorrectly interpreted it as a request to find customers with any group, effectively performing an INNER JOIN without specific conditions. This produced the opposite of the intended result, including customers who should have been excluded.

Beyond Basic Validation: Challenges with Advanced Graph Queries

Further investigation revealed that the issue extends beyond initial API validation. Even when using ESHOPMAN's advanced query.graph() function, which allows for more complex relational filtering, the problem persisted. The user demonstrated this with a scenario involving three customer groups (Good, Bad, Ugly) and three customers (One, Two, Three) with specific group assignments.

The goal was to retrieve customers not in the 'Bad' group. Here's the query.graph() syntax used:

const { data } = await query.graph({
  entity: "customer",
  fields: [
    "id",
    "first_name",
    "groups.name",
  ],
  filters: {
    groups: {
      $or: [
        {
          name: {
            $eq: null,
          },
        },
        {
          name: {
            $ne: 'Bad',
          }
        }
      ]
    }
  },
})

Despite this explicit filtering, the results still included "Customer One," who was a member of the 'Bad' group. This indicates a deeper challenge in how ESHOPMAN's data querying pipeline handles negation across Many-to-Many relationships, where a customer might belong to multiple groups, and the filter needs to ensure none of their associated groups match the exclusion criteria.

What This Means for ESHOPMAN Users

This community insight highlights a known limitation in the current ESHOPMAN Admin API's ability to precisely exclude customers based on group membership using negation operators. While a fix for the API validation aspect is considered straightforward, achieving full, robust support for Many-to-Many negation through the entire query and filter pipeline may require more significant updates to the ESHOPMAN framework.

For ESHOPMAN developers, understanding these underlying mechanisms is crucial when building custom logic or integrations that rely on detailed customer segmentation. Merchants should be aware of this behavior when using the Admin API for advanced customer filtering, and may need to consider alternative approaches for now, such as client-side filtering after retrieving a broader dataset, or awaiting future ESHOPMAN updates that address these complex negation scenarios.