---
title: "Custom exports: using the Expression Builder"
description: ""
url: https://help.qargo.com/us/articles/467741-custom-exports-using-the-expression-builder
locale: us
updated: 2026-01-21
---

# Custom exports: using the Expression Builder

This article explains what the Expression Builder is, why to use it for custom exports, and the common terminology. It also includes a step‑by‑step walkthrough with an example. Features and terms reflect the current implementation of the Expression Builder and its underlying query model.

* * *

## What is the Expression Builder? {#h_803d36f484}

The Expression Builder shapes data for custom exports without any code. It can:

-   Filter lists down to just the items needed
-   Aggregate values such as sum, count, min, or max
-   Format dates, date/times, and numbers for the target system
-   Preview results during configuration

![](https://help.qargo.com/media/edadf93be393-image.png)

:::callout{tone="info"}
🧰 Admins can optionally switch to a raw expression mode for advanced use cases.
:::

## Why use it? {#h_56502845d4}

-   **Flexibility:** Create tailored CSV or spreadsheet outputs for partners, BI tools, or finance systems.
-   **Consistency:** Save and reuse export mappings across teams.
-   **Precision:** Filter and aggregate directly at export time so downstream spreadsheets stay simple.

* * *

## Terminology {#h_511127b78a}

| **Term** | **Definition** |
| --- | --- |
| Path | A pointer to the data to extract. For example, trip > charges points to the list of charges on a load. |
| Filter | A condition that narrows a list to only matching items. Example: charge\_type = "Transport". |
| Operator | The comparison used in a filter, such as EQ, NEQ, GT, GTE, LT, LTE, IN, NONE\_IN. |
| Aggregation | A way to reduce a list into a single value. Options include SUM, COUNT, DISTINCT, MIN, MAX, EXISTS, NOT\_EXISTS. |
| Formatting | Output presentation controls for dates, date/times, and numbers, and an optional cast to string for CSV safety. |
| Expression mode\
(advanced) | A raw expression editor available to admins for complex transformations. |
| Preview | A live rendering that shows the result of the configuration before export. |

## Notes and current limitations {#h_2367fd4031}

-   Enum values are not yet translated.
-   Filtering inside certain nested lists may require workarounds if a typed path is not available.
-   Unit conversions and "combine multiple fields into one column" are tracked separately.

* * *

## Walkthrough: configure and use the Expression Builder {#h_b8fb12beff}

Below is a common scenario built as two export columns: exporting a load's transport charge total and a formatted pickup date/time.\
Before starting:

-   Open an existing custom export mapping or create a new one.
-   Identify the entity to export from, such as orders.

**Column A: Total transport charges**

1.  Add a new column

    1.  Name: Total Transport Charge
2.  Choose a path

    1.  Path: orders > charges
    2.  This points to the list of all charges on the load.
3.  Add a filter

    1.  Filter path: charge\_type
    2.  Operator: EQ
    3.  Value: Transport
    4.  Result: Only charges with type Transport are considered.
4.  Set an aggregation

    1.  Aggregation: SUM
    2.  Field summed: amount
    3.  Result: Sums the amount across the filtered charges.
5.  Formatting

    1.  Numeric format: #,###.00
    2.  Cast to string: On, to ensure CSV cells are never blank and are treated as text if required.
6.  Preview

    1.  Use Preview to confirm the resulting number matches expectations.

**What this does**

-   Starts from the charges list
-   Filters to charge\_type = Transport
-   Sums the amount
-   Outputs a formatted string fit for CSV importing in accounting tools.

![](https://help.qargo.com/media/61a78e4500c6-image.png)

:::callout{tone="info"}
📚 Where an expression is included, details are shown in parentheses.
:::

**Column B: Pickup date/time (US format)**

1.  Add a new column

    1.  Name: Pickup Date/time (US)
2.  Choose a path

    1.  Path: trip > pickup\_datetime
3.  Formatting

    1.  Datetime format: yyyy-MM-dd HH:mm:ss
    2.  Example: 2025-12-31 16:45:00
    3.  Cast to string: On, to keep CSV output consistent.
4.  Preview

    1.  Confirm the date and time appear in the requested format.

**What this does**

-   Reads the load's pickup date/time and outputs it in a clear, consistent format for downstream tools.

**Export**

-   Save the mapping and run the export. The CSV includes both columns, using the configured transformation rules.

![](https://help.qargo.com/media/944797f23713-image.png)

* * *

## Charge type filter options {#h_a24f4be658}

Filters can now be applied to expressions that reference charges. This gives full control over which charges are included in the calculation.

## 1\. Surcharges: now fully supported {#h_fc206e4ec9}

Previously, the Data Feed only exposed _index_ surcharges (fuel surcharges), which meant UI and export logic were not aligned.\
The Expression Builder now supports two configuration options:

-   **Surcharges (all types)**\
    Includes all surcharge types used in the UI:

    -   General surcharges
    -   Index surcharges (FSC)
    -   Any future surcharge types
-   **Other surcharges (excluding FSC)**\
    Designed for cases like Mulgrews, where FSC should not be mixed into the surcharge bucket.

This gives teams the flexibility to choose the behavior that matches their reporting model.

## 2\. Extras revenue (new category) {#h_e8db65929b}

**Extras** can now be selected as a dedicated category.\
Extras include:

-   All charges where `addon_type` ≠ surcharge
-   Any **ad-hoc charges**

This makes it easy to calculate "All revenue except transport/fuel" or to report on miscellaneous charge items.

## 3\. Consistent filtering across UI and export {#h_50c6323269}

The Expression Builder now uses the same charge-filtering logic as Qargo's rating UI, including:

-   Filtering out approved **DONT\_INVOICE** charges
-   Correct handling of transport charges
-   Full alignment with existing frontend behavior

This ensures that what users see in the UI matches what they get in exports and automated calculations, with no surprises.

## 4\. Include documentation {#h_63907c8bd4}

Users can now include documentation details in reporting, using the Expression Builder aggregation option "Exists". Details include:

-   Name, description, date/time stamps
-   Using the aggregation 'exists' adds the column with 'true/false' descriptions

    -   True = documentation attached to the order
    -   False = no documentation attached to the order

* * *

## Tips {#h_8ed973ddbf}

-   Start with a path and a single filter, then add aggregation and formatting once the preview looks right.
-   Use COUNT or EXISTS when a yes/no or a simple quantity of matches is needed.
-   Use DISTINCT to deduplicate values when exporting lists into a single cell.

* * *

## Advanced: expression mode {#h_ed398cdae2}

Workspace admins can switch to a raw expression mode to author complex logic directly. This is useful for edge cases where the form-based builder is too limited. Saved expressions should be documented for maintainability.

* * *

## Troubleshooting {#h_2ef0cd8a1b}

-   Empty cells: Turn on Cast to string to avoid blank values being misread by spreadsheet tools.
-   Unexpected totals: Check the filter operator and value spelling. Verify that the path points to the intended list.
-   Date formatting: Confirm the date/time format string and whether the source field contains a date or a date‑time.


## Related articles

- [How to configure custom export files](https://help.qargo.com/us/articles/202699-how-to-configure-custom-export-files.md)
- [Document templates: what, why & how.](https://help.qargo.com/us/articles/246339-document-templates-what-why-how.md)
- [Fuel surcharge dashboard: what, why, and how](https://help.qargo.com/us/articles/618720-fuel-surcharge-dashboard-what-why-and-how.md)
- [Orders: orders list view functions](https://help.qargo.com/us/articles/133839-orders-orders-list-view-functions.md)
- [Integrations - Importing orders into Qargo](https://help.qargo.com/us/articles/450378-integrations-importing-orders-into-qargo.md)
