Analytics: Filtering Analytics Queries by Status

Docs

Help & Feedback

Get Started
Functionality
Learning
Extension
Dev Tooling
APIs
Releases

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

Overview

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

Prequisites

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 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:

Domain	Filter Parameter	Example 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 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}

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.

Important

If you want to keep the original logic and consider the default status, you need to include those status values in your new filter.

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}

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}

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

Step 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}

Example - Include only BOOKED and COMPLETED orders:

1{
2  "key": "order.status",
3  "value": ["BOOKED", "COMPLETED"]
4}

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}

Example - Exclude ESCALATED and REJECTED fulfilments:

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

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

Best Practice: Don't Mix Inclusion and Exclusion

Using both inclusion and exclusion in the same parameter creates confusion. A value like `["BOOKED", "COMPLETED", "-REJECTED"]` is redundant because the inclusion already excludes everything except BOOKED and COMPLETED.Choose either inclusion OR exclusion for cleaner configuration.

Example 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}

Result: Orders in `ESCALATED` status are now excluded from the total count.

Example 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}

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

Example 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}

Result: The denominator now includes both `ACTIVE` and `SCHEDULED` inventory quantities, providing a more complete view of available inventory.

Example 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}

Result: A refined calculation that excludes forecasted inventory while including scheduled inventory in stock on hand calculations.

Related content

Analytics Query Structure

Edited 156 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 156 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 156 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 240 days ago

Overview

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

Prequisites

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 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:

Domain	Filter Parameter	Example 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 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}

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.

Important

If you want to keep the original logic and consider the default status, you need to include those status values in your new filter.

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}

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}

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

Step 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}

Example - Include only BOOKED and COMPLETED orders:

1{
2  "key": "order.status",
3  "value": ["BOOKED", "COMPLETED"]
4}

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}

Example - Exclude ESCALATED and REJECTED fulfilments:

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

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

Example 1: Exclude Escalated Orders from Total Orders

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}

Result: Orders in `ESCALATED` status are now excluded from the total count.

Example 2: Override Default Status in Average Order Value

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}

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

Example 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

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}

Result: The denominator now includes both `ACTIVE` and `SCHEDULED` inventory quantities, providing a more complete view of available inventory.

Example 4: Combine Conditional and Standard Status Filters

`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}

Result: A refined calculation that excludes forecasted inventory while including scheduled inventory in stock on hand calculations.

Analytics: Filtering Analytics Queries by Status

Key Points

Prerequisites

Configuring the Fluent Analytics Dashboards: A Step-by-Step Guide

Overriding the default manifest

Analytics Query Structure

Fluent Metrics Library Overview

Steps

Overview

Prequisites

Step 1: Identify the Domain

Step 2: Add the Status Filter Parameter

Scenario A: No status filter exists

Scenario B: Metric has built-in status logic (but no explicit parameter)

Scenario C: Status parameter already exists

Conditional Status Filters

Step 3: Specify Status Values

Including Specific Statuses

Excluding Specific Statuses

Example 1: Exclude Escalated Orders from Total Orders

Example 2: Override Default Status in Average Order Value

Example 3: Use Conditional Status Filter in Sell-Through Rate

Example 4: Combine Conditional and Standard Status Filters

Related content

Analytics Query Structure

Fluent Metrics Library Overview

Analytics: Roles & Permissions

Overriding the default manifest

Holger Lierse

Building Blocks

By Type

Helpful Resources

Quick Links

Overview

Prequisites

Step 1: Identify the Domain

Step 2: Add the Status Filter Parameter

Scenario A: No status filter exists

Scenario B: Metric has built-in status logic (but no explicit parameter)

Scenario C: Status parameter already exists

Conditional Status Filters

Step 3: Specify Status Values

Including Specific Statuses

Excluding Specific Statuses

Example 1: Exclude Escalated Orders from Total Orders

Example 2: Override Default Status in Average Order Value

Example 3: Use Conditional Status Filter in Sell-Through Rate

Example 4: Combine Conditional and Standard Status Filters