Skip to main content

Add a filter

To add a filter, include the filters array in your API request to create or edit a report. In your JSON payload, place the filters array inside the report_metadata object.

The filters array is a list of objects. Each object defines a single filter. Filter objects include these key/value pairs:

Examples

Filter by status (multi_value)

Order reports include a status column. The filter type for this column is multi_value.

To customize an order report to only include orders with a pending status, add a filter with these attributes:

  • The column identifier is status.

  • The list of values contains a single value to match against: ["Pending"].

  • The operator (filter_identifier) required to find an exact match is in.

In the request payload to create or edit the report, the filters array looks like this:

{
…
  "report_metadata": {
    "report_type": "orders",
    "columns": […],
    "filters": [
      {
        "filter_identifier": "in",
        "column_identifier": "status",
        "values": [
          "Pending"
        ]
      }
    ],
  …
  }
…
}

Filter by order_created_date (date)

Order reports include an order_created_date column. The filter type for this column is date.

To customize an order report to only include orders created between the beginning of the current month and now, add a filter with these attributes:

  • The column identifier is order_created_date.

  • The operator (filter_identifier) required to find an order_created_date between now and the beginning of the current month is month_to_date.

  • The list of values is empty. The month_to_date operator determines the date range for matching values.

In the request payload to create or edit the report, the filters array looks like this:

{
…
  "report_metadata": {
    "report_type": "orders",
    "columns": […],
    "filters": [
      {
        "filter_identifier": "month_to_date",
        "column_identifier": "order_created_date",
        "values": []
      }
    ],
  …
  }
…
}

Alternatively, to customize an order report to only include orders created between January 1-7, 2021, add a filter with these attributes:

  • The column identifier is order_created_date.

  • The operator (filter_identifier) required to find an order_created_date within a custom range is custom_date.

  • The list of values contains two elements that define a custom date range. The first element is the start date and the second element is the end date: ["2021-01-01", "2021-01-07"].

In the request payload to create or edit the report, the filters array looks like this:

{
…
  "report_metadata": {
    "report_type": "orders",
    "columns": […],
    "filters": [
      {
        "filter_identifier": "custom_date",
        "column_identifier": "order_created_date",
        "values": [
          "2021-01-01",
          "2021-01-07"
        ]
      }
    ],
  …
  }
…
}

Filter by days_remaining_until_expiration (static)

Order reports include a days_remaining_until_expiration column. The filter type for this column is static. Static filters do not use operators that match against a custom list of values. For static filters, the operator determines the range of acceptable values.

For example, to build an order report that only includes orders that expire within 30 days, add a filter with these attributes:

  • The column identifier is days_remaining_until_expiration.

  • The list of values is empty.

  • The operator (filter_identifier) required to find orders that expire within 30 days is expires_within_30 days.

In the request payload to create or edit the report, the filters array looks like this:

{
…
  "report_metadata": {
    "report_type": "orders",
    "columns": […],
    "filters": [
      {
        "filter_identifier": "expires_within_30_days",
        "column_identifier": "days_remaining_until_expiration",
        "values": []
      }
    ],
  …
  }
…
}

Filter by product_name (product_api)

Order reports include a product_name column. The filter type for this column is product_api. This filter type tells us that we can use the Product list endpoint in the Services API to get the values we can use as filter criteria.

To build an order report that only includes orders for Basic OV certificates, first call the Product list endpoint to get the product name for the Basic OV product. Then add a filter with these attributes:

  • The column identifier is product_name.

  • The list of values contains identifiers for each product the report should include : ["Basic OV"].

  • The operator (filter_identifier) required to find an exact match is in.

In the request payload to create or edit the report, the filters array looks like this:

{
…
  "report_metadata": {
    "report_type": "orders",
    "columns": […],
    "filters": [
      {
        "filter_identifier": "in",
        "column_identifier": "product_name",
        "values": ["Basic OV"]
      }
    ],
  …
  }
…
}
In this section: