Filter

Filters allow you to retrieve only the records relevant to your integration.

Different queries expose different filter fields. Use GraphiQL or SpectaQL to check the filters available for a specific entity.

Filter Structure

Filters are passed through the filter argument of a query.

Filterable fields generally use typed comparison objects consisting of an operator and a value.

For example, to retrieve a Sales Order by its external ID:

query {
  salesOrders(
    filter: {
      externalId: {
        operator: eq
        value: ["ORDER-12345"]
      }
    }
  ) {
    totalCount
    data {
      ... on SalesOrder {
        externalId
        number
        status
        orderDate
      }
    }
  }
}

Do not pass a raw value such as:

externalId: "ORDER-12345"

Use the comparison object defined by the schema instead.

Available Operators

The available operators depend on the field type.

Not every operator is available for every field. GraphiQL and SpectaQL show the exact comparison type used by each filter.

Filter by Multiple Values

Use the in operator when a field should match one of several values.

For example, to retrieve Return Order Parcels by tracking number:

query {
  returnOrderParcels(
    filter: {
      trackingNumber: {
        operator: in
        value: [
          "65170178590003"
          "09985052960063"
        ]
      }
    }
  ) {
    totalCount
    data {
      ... on ReturnOrderParcel {
        number
        trackingNumber
        status
      }
    }
  }
}

Filter by Status

Status values are GraphQL enums and are therefore written without quotation marks.

For example:

filter: {
  status: {
    operator: eq
    value: [finished]
  }
}

The available status values depend on the entity being queried.

Filter by Date

Date and datetime filters support comparison operators such as gt, gte, lt, and lte.

For example:

filter: {
  createdAt: [
    {
      operator: gte
      value: "2026-08-01T00:00:00+00:00"
    }
    {
      operator: lt
      value: "2026-09-01T00:00:00+00:00"
    }
  ]
}

This is useful for incremental synchronization, for example when retrieving records created or updated since the previous synchronization.

Nested Filters

Some filters allow you to filter by related entities.

For example, the schema allows Return Orders to be filtered using Return Order Parcel attributes, and Items using Item Variation attributes.

The available nested filters depend on the query and are defined directly in the GraphQL schema.

Pagination and Sorting

Filters can be combined with pagination:

• offset – starting position, using 0-based indexing
• limit – maximum number of records returned, up to 100

Example:

query {
  salesOrders(
    filter: {
      status: {
        operator: eq
        value: [finished]
      }
    }
    offset: 0
    limit: 50
  ) {
    totalCount
    data {
      ... on SalesOrder {
        externalId
        number
        status
      }
    }
  }
}

Queries that support sorting additionally provide an orderBy argument.

Check the Schema

Filter fields differ between entities and can evolve with the API.

Use GraphiQL or SpectaQL as the source of truth for:

• available filter fields
• comparison types
• supported operators
• enum values
• nested filters
• sorting options

Build and test filters against your test system or sandbox environment before using them in production.