Fluent Commerce Logo
Docs
Help & Feedback

Analytics: Filtering Analytics Queries by Status

How-to Guide

Author:

Holger Lierse

Changed on:

16 Jan 2026

Key Points

  • Purpose: Filter analytics queries by status to include or exclude specific entities from metric calculations
  • Domain-based parameters: Each metric uses a specific domain filter (`order.status` , `fulfilment.status`, `inventory_quantity.status`)
  • Include syntax: List statuses to count only those: `["BOOKED", "COMPLETED"]`
  • Exclude syntax: Prefix with `-` to exclude: `["-ESCALATED", "-REJECTED"]`
  • Don't mix: Use either inclusion OR exclusion, not both (creates confusion and redundancy)
  • Overrides defaults: Adding a status filter replaces any built-in status logic in the metric
  • Conditional filters: Use `.conditional_status` to filter only part of a calculation (e.g., numerator or denominator only)

Prerequisites

Configuring the Fluent Analytics Dashboards: A Step-by-Step Guide
Overriding the default manifest
Analytics Query Structure
Fluent Metrics Library Overview

Steps

Step arrow right iconOverview

This guide shows how to filter analytics queries by status values, including or excluding specific statuses from metric calculations.Status filters allow you to customize which entities (orders, fulfilments, inventory, returns) are counted in a metric. For example, you can exclude escalated orders from revenue calculations or include only completed orders in performance metrics.Use this guide to:
  • Include only entities in specific statuses (e.g., only `COMPLETED` orders)
  • Exclude entities in specific statuses (e.g., exclude `ESCALATED` orders)
  • Override default status filters in metrics

Step arrow right iconPrequisites

Before you start, gather the following information:
  • Identify the target name of the metric you want to configure
    - Find this in the Web App manifest where the visualization is configured (reference manifest)  
    - Look for the `name` field in the analytics query (e.g., `orders_total_revenue`) 
  • Locate the configuration where you'll add the filter
    - Either in the Analytics Query Setting (`fc.analytics.queries.{query_group}`)
    - Or in the Web App manifest's query parameters 
  • Reference the Metrics Library to understand what the metric calculates
    - See Fluent Metrics Library for metric-specific documentation

Step arrow right iconStep 1: Identify the Domain

How to find the domain:
  • Look up your metric in the Fluent Metrics Library
  • Check the "Technical details" section
  • Note which domain the metric belongs to
Typical Domain to parameter mapping:
DomainFilter ParameterExample Metrics
Orders`order.status`Total Orders, Total Revenue, Average Order, Orders Value
Fulfilments`fulfilment.status`On-Time Rate, Pick Rate, Fulfilment Volume
Inventory`inventory_quantity.status` or `inventory_position.status`Sell-Through Rate, Total On-Hand, Total Available
Returns`return.status`Return Processing Time
Special cases:
  • Some inventory metrics use `inventory_quantity.status` (for quantities) or `inventory_position.status` (for positions)
  • Some metrics support `.conditional_status` parameters that apply to only part of a calculation (documented on the metric's page)
  • Most domains are named after the entity type, but some metrics have an exception. E.G. Return Rate's domain is `order_item_return_rate` 

Step arrow right iconStep 2: Add the Status Filter Parameter

Depending on the metric's current configuration, you'll either add a new parameter or modify an existing one.
Scenario A: No status filter exists
The metric doesn't currently filter by status. Add a new parameter with the appropriate domain key.Example:
1{
2  "key": "order.status",
3  "value": ["COMPLETED"]
4}

Language: json

Name: Adding a new status filter

Scenario B: Metric has built-in status logic (but no explicit parameter)
The metric's calculation already considers status, but there's no parameter defined. Adding a status filter will override the built-in logic.Example:
If Average Order Value only counts COMPLETED orders by default, and you want to also include SHIPPED orders, use:
1{
2  "key": "order.status",
3  "value": ["COMPLETED", "SHIPPED"]
4}

Language: json

Name: Overriding a new status filter

Scenario C: Status parameter already exists
The metric already has a status filter defined. Skip to Step 3 and modify the existing parameter's value.
Conditional Status Filters
Some metrics with numerator/denominator calculations support `.conditional_status` parameters that filter only part of the calculation.Example:
1{
2  "key": "order.conditional_status",
3  "value": ["ACTIVE", "SCHEDULED"]
4}

Language: json

Name: Example Conditional Status

Check the metric's documentation in the Fluent Metrics Library to see if conditional status filters are available.

Step arrow right iconStep 3: Specify Status Values

Including Specific Statuses
List status values separated by commas. The query will include ONLY entities matching these statuses (OR logic).Syntax:
1{
2  "key": "{domain}.status",
3  "value": ["STATUS_1", "STATUS_2"]
4}

Language: json

Name: Including Specific Statuses Syntax

Example - Include only BOOKED and COMPLETED orders:
1{
2  "key": "order.status",
3  "value": ["BOOKED", "COMPLETED"]
4}

Language: json

Name: Including Specific Statuses Example

Result: Only orders in BOOKED or COMPLETED status are counted in the metric.
Excluding Specific Statuses
Add a `-` prefix to each status you want to exclude. The query will include ALL entities EXCEPT those in the excluded statuses.
1{
2  "key": "{domain}.status",
3  "value": ["-STATUS_1", "-STATUS_2"]
4}

Language: json

Name: Excluding Specific Statuses Syntax

Example - Exclude ESCALATED and REJECTED fulfilments:
1{
2  "key": "fulfilment.status",
3  "value": ["-ESCALATED", "-REJECTED"]
4}

Language: json

Name: Exclude Specific Statuses Example

Result: All fulfilments EXCEPT those in ESCALATED or REJECTED status are counted.

Step arrow right iconExample 1: Exclude Escalated Orders from Total Orders

Scenario: The Total Orders metric currently counts ALL orders regardless of status. You want to exclude `ESCALATED` orders from the count.Domain: `order`
Filter parameter: `order.status`Configuration:
Add the status parameter with exclusion:
1{
2  "name": "orders_total_orders",
3  "parameters": [
4    {
5      "key": "order.created_date",
6      "value": ["{{params.orders_created_on}}"]
7    },
8    {
9      "key": "retailer.ref",
10      "value": ["{{readArrayFromParams 'retailer_ref[]'}}"]
11    },
12    {
13      "key": "order.type",
14      "value": ["{{params.order_type}}"]
15    },
16    {
17      "key": "order.status",
18      "value": ["-ESCALATED"]
19    }
20  ]
21}

Language: json

Name: Code Sample

Description:

In this case, it is a metric based on orders, so our filter parameter key will be the `order.status`. So in order to adjust the metric to exclude escalated orders, we just need to add the order.status to the end of our parameter list with the ESCALATED status filter. And since we are excluding, we will want to add the - character to the beginning of the status.
Result: Orders in `ESCALATED` status are now excluded from the total count.

Step arrow right iconExample 2: Override Default Status in Average Order Value

Scenario: The Average Order Value metric only considers orders in the `COMPLETED` status by default. Your business uses multiple statuses to indicate completed orders: `SHIPPED`, `RECEIVED`, and `PAYMENT_CONFIRMED`.Domain: `order`
Filter parameter: `order.status`Configuration:
Override the built-in COMPLETED logic by specifying your custom statuses:
1{
2  "name": "orders_average_order_value",
3  "parameters": [
4    {
5      "key": "order.created_date",
6      "value": ["{{params.orders_created_on}}"]
7    },
8    {
9      "key": "retailer.ref",
10      "value": ["{{readArrayFromParams 'retailer_ref[]'}}"]
11    },
12    {
13      "key": "order.type",
14      "value": ["{{params.order_type}}"]
15    },
16    {
17      "key": "order.status",
18      "value": ["SHIPPED", "RECEIVED", "PAYMENT_CONFIRMED"]
19    }
20  ]
21}

Language: json

Name: Code Sample

Result: Average order value now calculates based on orders in `SHIPPED`, `RECEIVED`, or `PAYMENT_CONFIRMED` status instead of only `COMPLETED`.

Step arrow right iconExample 3: Use Conditional Status Filter in Sell-Through Rate

Scenario: The Sell Through Rate metric has a complex calculation:
  • Numerator: Sum of inventory quantities where type = `SALE`
  • Denominator: Inventory position on-hand + sum of all `ACTIVE` inventory quantities
The denominator currently only includes `ACTIVE` inventory quantities. You want to also include `SCHEDULED` quantities.Domain: `inventory_quantity`
Filter parameter: `inventory_quantity.conditional_status` (applies only to denominator)Original configuration: The metric has a built-in conditional status filter set to `["ACTIVE"]` for the denominator.Updated configuration:Add the conditional status parameter to include both ACTIVE and SCHEDULED:
1{
2  "name": "inventory_sell_through_rate",
3  "parameters": [
4    {
5      "key": "inventory_quantity.created_date",
6      "value": ["{{params.inventory_created_on}}"]
7    },
8    {
9      "key": "inventory_catalogue.ref",
10      "value": ["{{params.inventoryCatalogueRef}}"]
11    },
12    {
13      "key": "location.ref",
14      "value": ["{{readArrayFromParams 'locations_ref[]'}}"]
15    },
16    {
17      "key": "retailer.ref",
18      "value": ["{{readArrayFromParams 'retailer_ref[]'}}"]
19    },
20    {
21      "key": "inventory_position.product_ref",
22      "value": ["{{readArrayFromParams 'products_ref[]'}}"]
23    },
24    {
25      "key": "inventory_quantity.conditional_status",
26      "value": ["ACTIVE", "SCHEDULED"]
27    }
28  ]
29}

Language: json

Name: Code Snippet

Description:

If we wanted to increase that to include more, we should add the parameter `inventory_quantity.conditional_status`. We also will want to keep the existing `ACTIVE` status value, but also add in our own as well.
Result: The denominator now includes both `ACTIVE` and `SCHEDULED` inventory quantities, providing a more complete view of available inventory.

Step arrow right iconExample 4: Combine Conditional and Standard Status Filters

Scenario: Building on Example 3, you now want to exclude `FORECASTED` inventory quantities from the ENTIRE calculation (both numerator and denominator), while keeping the conditional filter that adds `SCHEDULED` to the denominator.Domain: `inventory_quantity`
Filter parameters:
  • `inventory_quantity.conditional_status` (applies to denominator only)
  • `inventory_quantity.status` (applies to entire calculation)
Configuration:Add both parameters - they work together:
1{
2  "name": "inventory_sell_through_rate",
3  "parameters": [
4    {
5      "key": "inventory_quantity.created_date",
6      "value": ["{{params.inventory_created_on}}"]
7    },
8    {
9      "key": "inventory_catalogue.ref",
10      "value": ["{{params.inventoryCatalogueRef}}"]
11    },
12    {
13      "key": "location.ref",
14      "value": ["{{readArrayFromParams 'locations_ref[]'}}"]
15    },
16    {
17      "key": "retailer.ref",
18      "value": ["{{readArrayFromParams 'retailer_ref[]'}}"]
19    },
20    {
21      "key": "inventory_position.product_ref",
22      "value": ["{{readArrayFromParams 'products_ref[]'}}"]
23    },
24    {
25      "key": "inventory_quantity.conditional_status",
26      "value": ["ACTIVE", "SCHEDULED"]
27    },
28    {
29      "key": "inventory_quantity.status",
30      "value": ["-FORECASTED"]
31    }
32  ]
33}

Language: json

Name: Code Sample

Description:

How it works:

- The `.status` filter excludes `FORECASTED` quantities from all calculations
- The `.conditional_status` filter adds `SCHEDULED` quantities to the denominator only
- Both filters apply: `FORECASTED` is excluded everywhere, `SCHEDULED` is included in denominator
Result: A refined calculation that excludes forecasted inventory while including scheduled inventory in stock on hand calculations.

Related content

Analytics Query Structure
Edited 6 days ago
This document defines the structure and syntax for querying the Fluent Analytics backend services. Analytics Queries reference pre-configured metrics by name (called "targets"), rather than defining individual fields like standard GraphQL queries. Targets provide controlled access to analytics metrics with built-in role-based permissions. Use this document to: 
  • Understand and construct analytics GraphQL queries 
  • Understand target name format and how it links to query settings
  • Configure filter parameters to refine query results 
  • Integrate analytics into dashboards and web applications
Fluent Metrics Library Overview
Edited 6 days ago
The Fluent Metrics Library is a collection of metrics and dashboards available to Fluent customers. Delivered through the Fluent Analytics feature, it gives retailers real-time visibility into order, fulfillment, returns, and inventory operations to enable faster, smarter decisions.
Designed for retail operations managers, inventory analysts, business intelligence, and many other teams who need visibility across retail operations.
Analytics: Roles & Permissions
Edited 6 days ago
Access to Fluent Analytics is controlled through a combination of permissions and role-based access control (RBAC). This document defines the permission model, role requirements, and configuration patterns for access to Fluent Analytics.Access to Fluent Analytics is controlled through a two-layer model: users must be assigned a role that 
  • has the `ANALYTICS_VIEW` permission AND 
  • is listed in the Analytics Query definition.
Overriding the default manifest
Edited 90 days ago
Holger Lierse

Holger Lierse

Building Blocks
Building Blocks
Packages & Modules
All UI Components
Workflows
Settings
Interface Contracts
All Rules
By Type
All Types
Knowledge Tracks
Extend Knowledge
Glossary
All How-to Guides
Sitemap
Topics
Use Cases
Helpful Resources
Platform Limits
Support Policy
Service Level Agreement (SLA) - Enterprise
Deprecation Policy
Extend Knowledge Content – Terms and Conditions
System and Organization Controls (SOC) 3 Report
Data Privacy Addendum
Security Policy
Quick Links
For Partners
Customer Resources
Webinars and Events
Certifications
Training Resources
Knowledge Tracks
Builders Portal
Product Update Newsletter
Industry Blogs & Events Newsletter
Trust Center Portal

Copyright © 2024-2026 Fluent Retail Pty Ltd (trading as Fluent Commerce). Unless otherwise expressly stated in a current written agreement with Fluent Commerce or any of its affiliates or on any single page of the docs.fluentcommerce.com site, use of the materials on this site is strictly limited to viewing by individuals over 18 years old for legitimate commercially appropriate reasons; and any downloading, copying or other actions or uses of any kind or by any means of the materials on this site, including by artificial intelligence tools, is strictly prohibited. All other rights reserved.

Fluent Logo