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
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:
Special cases:
- Look up your metric in the Fluent Metrics Library
- Check the "Technical details" section
- Note which domain the metric belongs to
| 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 |
- 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.
If Average Order Value only counts COMPLETED orders by default, and you want to also include SHIPPED orders, use:
Scenario A: No status filter exists
The metric doesn't currently filter by status. Add a new parameter with the appropriate domain key.Example: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:
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: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:Example - Include only BOOKED and COMPLETED orders: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.Example - Exclude ESCALATED and REJECTED fulfilments:Result: All fulfilments EXCEPT those in ESCALATED or REJECTED status are counted.Example 1: Exclude Escalated Orders from Total Orders
Scenario: The Total Orders metric currently counts ALL orders regardless of status. You want to exclude
Filter parameter:
Add the status parameter with exclusion:Result: Orders in
`ESCALATED` orders from the count.Domain: `order`Filter parameter:
`order.status`Configuration:Add the status parameter with exclusion: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
Filter parameter:
Override the built-in COMPLETED logic by specifying your custom statuses:Result: Average order value now calculates based on orders in
`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: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:
Filter parameter:
- Numerator: Sum of inventory quantities where type =
`SALE` - Denominator: Inventory position on-hand + sum of all
`ACTIVE`inventory quantities
`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: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
Filter parameters:
`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)
