Quick filters

GET `/quick-filters`

List the organization's saved quick filters, the one-click presets that sit above each list screen.

Requires the settings:read permission.

Query parameters

limitnumber

The number of records to return.

cursorstring

A pagination cursor. Fetch the next page by passing the nextCursor value from the previous response.

sortname | -name | createdAt | -createdAt

The sort order. Prefix a field with - to sort descending. Defaults to -createdAt.

filterstring

A JSON-encoded filter document, for example {"createdAt":{"$gte":"2025-01-01T00:00:00Z"}}. Filterable fields: id, type, name, createdAt. See Filtering for the syntax.

Request

curl \
  "https://your-store.meisei.app/api/quick-filters" \
  -H "Authorization: Bearer sk_YOUR_SECRET_KEY"

Request

import { client } from "@meisei/api/admin/client"
import { getQuickFilters } from "@meisei/api/admin"

client.setConfig({
  baseUrl: "https://your-store.meisei.app/api",
  headers: { Authorization: "Bearer sk_YOUR_SECRET_KEY" },
})

const { data, error } = await getQuickFilters()

Request

require "meisei"

meisei = Meisei::Client.new(
  secret_key: "sk_YOUR_SECRET_KEY",
  base_url: "https://your-store.meisei.app/api",
)

page = meisei.quick_filters.list

Request

from meisei import Client

meisei = Client(
    secret_key="sk_YOUR_SECRET_KEY",
    base_url="https://your-store.meisei.app/api",
)

page = meisei.quick_filters.list()

Response

{
  "data": [
    {
      "id": "A4Ws1igz",
      "type": "customers",
      "name": "string",
      "filter": "...",
      "createdAt": "2025-01-15T09:30:00Z",
      "updatedAt": "2025-01-15T09:30:00Z"
    }
  ],
  "nextCursor": "string"
}

Response schema

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "type": "object",
  "properties": {
    "data": {
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "id": {
            "type": "string",
            "description": "Unique identifier for the quick filter.",
            "idCodec": "sqid"
          },
          "type": {
            "type": "string",
            "enum": [
              "customers",
              "products",
              "orders",
              "wishlists",
              "tiers",
              "surveys",
              "offers",
              "rewards",
              "reviews",
              "loyalty-activity",
              "loyalty-rewards",
              "loyalty-rules"
            ],
            "description": "Which list screen the quick filter appears on."
          },
          "name": {
            "type": "string",
            "description": "The label shown on the quick filter's button."
          },
          "filter": {
            "type": "object",
            "propertyNames": {
              "type": "string"
            },
            "additionalProperties": {},
            "description": "The filter document applied when the quick filter is picked. Same shape as a list endpoint's `filter` param, but as an object rather than a JSON string."
          },
          "createdAt": {
            "type": "string",
            "format": "date-time",
            "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$",
            "description": "When the quick filter was created."
          },
          "updatedAt": {
            "type": "string",
            "format": "date-time",
            "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$",
            "description": "When the quick filter was last changed."
          }
        },
        "required": ["id", "type", "name", "filter", "createdAt", "updatedAt"],
        "additionalProperties": false
      },
      "description": "The page of records, in the requested sort order."
    },
    "nextCursor": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "description": "Pass this back as `cursor` to fetch the next page. Null once the last page has been returned."
    }
  },
  "required": ["data", "nextCursor"],
  "additionalProperties": false
}

POST `/quick-filters`

Create a quick filter. The filter document is validated against the fields its screen allows, so an unknown field is rejected up front.

Requires the settings:write permission.

Body parameters

Which list screen the quick filter appears on.

namestringrequired

The label to show on the quick filter's button.

filterobjectrequired

The filter document to apply. It is validated against the fields the chosen screen allows.

Request

curl \
  -X POST \
  "https://your-store.meisei.app/api/quick-filters" \
  -H "Authorization: Bearer sk_YOUR_SECRET_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "type": "customers",
  "name": "string",
  "filter": "..."
}'

Request

import { client } from "@meisei/api/admin/client"
import { postQuickFilters } from "@meisei/api/admin"

client.setConfig({
  baseUrl: "https://your-store.meisei.app/api",
  headers: { Authorization: "Bearer sk_YOUR_SECRET_KEY" },
})

const { data, error } = await postQuickFilters({
  body: {
    type: "customers",
    name: "string",
    filter: "...",
  },
})

Request

require "meisei"

meisei = Meisei::Client.new(
  secret_key: "sk_YOUR_SECRET_KEY",
  base_url: "https://your-store.meisei.app/api",
)

result = meisei.quick_filters.create(
  type: "customers",
  name: "string",
  filter: "...",
)

Request

from meisei import Client

meisei = Client(
    secret_key="sk_YOUR_SECRET_KEY",
    base_url="https://your-store.meisei.app/api",
)

result = meisei.quick_filters.create(type="customers", name="string", filter={})

Response

{
  "id": "A4Ws1igz",
  "type": "customers",
  "name": "string",
  "filter": "...",
  "createdAt": "2025-01-15T09:30:00Z",
  "updatedAt": "2025-01-15T09:30:00Z"
}

Response schema

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "type": "object",
  "properties": {
    "id": {
      "type": "string",
      "description": "Unique identifier for the quick filter.",
      "idCodec": "sqid"
    },
    "type": {
      "type": "string",
      "enum": [
        "customers",
        "products",
        "orders",
        "wishlists",
        "tiers",
        "surveys",
        "offers",
        "rewards",
        "reviews",
        "loyalty-activity",
        "loyalty-rewards",
        "loyalty-rules"
      ],
      "description": "Which list screen the quick filter appears on."
    },
    "name": {
      "type": "string",
      "description": "The label shown on the quick filter's button."
    },
    "filter": {
      "type": "object",
      "propertyNames": {
        "type": "string"
      },
      "additionalProperties": {},
      "description": "The filter document applied when the quick filter is picked. Same shape as a list endpoint's `filter` param, but as an object rather than a JSON string."
    },
    "createdAt": {
      "type": "string",
      "format": "date-time",
      "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$",
      "description": "When the quick filter was created."
    },
    "updatedAt": {
      "type": "string",
      "format": "date-time",
      "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$",
      "description": "When the quick filter was last changed."
    }
  },
  "required": ["id", "type", "name", "filter", "createdAt", "updatedAt"],
  "additionalProperties": false,
  "description": "The new quick filter."
}

GET `/quick-filters/{id}`

Get a single quick filter by ID.

Requires the settings:read permission.

Path parameters

idstringrequired

The ID of the quick filter.

Request

curl \
  "https://your-store.meisei.app/api/quick-filters/A4Ws1igz" \
  -H "Authorization: Bearer sk_YOUR_SECRET_KEY"

Request

import { client } from "@meisei/api/admin/client"
import { getQuickFiltersById } from "@meisei/api/admin"

client.setConfig({
  baseUrl: "https://your-store.meisei.app/api",
  headers: { Authorization: "Bearer sk_YOUR_SECRET_KEY" },
})

const { data, error } = await getQuickFiltersById({
  path: { id: "A4Ws1igz" },
})

Request

require "meisei"

meisei = Meisei::Client.new(
  secret_key: "sk_YOUR_SECRET_KEY",
  base_url: "https://your-store.meisei.app/api",
)

result = meisei.quick_filters.retrieve("A4Ws1igz")

Request

from meisei import Client

meisei = Client(
    secret_key="sk_YOUR_SECRET_KEY",
    base_url="https://your-store.meisei.app/api",
)

result = meisei.quick_filters.retrieve("A4Ws1igz")

Response

{
  "id": "A4Ws1igz",
  "type": "customers",
  "name": "string",
  "filter": "...",
  "createdAt": "2025-01-15T09:30:00Z",
  "updatedAt": "2025-01-15T09:30:00Z"
}

Response schema

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "type": "object",
  "properties": {
    "id": {
      "type": "string",
      "description": "Unique identifier for the quick filter.",
      "idCodec": "sqid"
    },
    "type": {
      "type": "string",
      "enum": [
        "customers",
        "products",
        "orders",
        "wishlists",
        "tiers",
        "surveys",
        "offers",
        "rewards",
        "reviews",
        "loyalty-activity",
        "loyalty-rewards",
        "loyalty-rules"
      ],
      "description": "Which list screen the quick filter appears on."
    },
    "name": {
      "type": "string",
      "description": "The label shown on the quick filter's button."
    },
    "filter": {
      "type": "object",
      "propertyNames": {
        "type": "string"
      },
      "additionalProperties": {},
      "description": "The filter document applied when the quick filter is picked. Same shape as a list endpoint's `filter` param, but as an object rather than a JSON string."
    },
    "createdAt": {
      "type": "string",
      "format": "date-time",
      "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$",
      "description": "When the quick filter was created."
    },
    "updatedAt": {
      "type": "string",
      "format": "date-time",
      "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$",
      "description": "When the quick filter was last changed."
    }
  },
  "required": ["id", "type", "name", "filter", "createdAt", "updatedAt"],
  "additionalProperties": false,
  "description": "The requested quick filter."
}

PUT `/quick-filters/{id}`

Rename a quick filter or change what it matches. Its screen cannot be changed.

Requires the settings:write permission.

Path parameters

idstringrequired

The ID of the quick filter to update.

Body parameters

namestring

The label shown on the quick filter's button.

filterobject

Replaces the filter document wholesale. Omit to leave it alone.

Request

curl \
  -X PUT \
  "https://your-store.meisei.app/api/quick-filters/A4Ws1igz" \
  -H "Authorization: Bearer sk_YOUR_SECRET_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "name": "string",
  "filter": "..."
}'

Request

import { client } from "@meisei/api/admin/client"
import { putQuickFiltersById } from "@meisei/api/admin"

client.setConfig({
  baseUrl: "https://your-store.meisei.app/api",
  headers: { Authorization: "Bearer sk_YOUR_SECRET_KEY" },
})

const { data, error } = await putQuickFiltersById({
  path: { id: "A4Ws1igz" },
  body: {
    name: "string",
    filter: "...",
  },
})

Request

require "meisei"

meisei = Meisei::Client.new(
  secret_key: "sk_YOUR_SECRET_KEY",
  base_url: "https://your-store.meisei.app/api",
)

result = meisei.quick_filters.update("A4Ws1igz", name: "string", filter: "...")

Request

from meisei import Client

meisei = Client(
    secret_key="sk_YOUR_SECRET_KEY",
    base_url="https://your-store.meisei.app/api",
)

result = meisei.quick_filters.update("A4Ws1igz", name="string", filter={})

Response

{
  "id": "A4Ws1igz",
  "type": "customers",
  "name": "string",
  "filter": "...",
  "createdAt": "2025-01-15T09:30:00Z",
  "updatedAt": "2025-01-15T09:30:00Z"
}

Response schema

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "type": "object",
  "properties": {
    "id": {
      "type": "string",
      "description": "Unique identifier for the quick filter.",
      "idCodec": "sqid"
    },
    "type": {
      "type": "string",
      "enum": [
        "customers",
        "products",
        "orders",
        "wishlists",
        "tiers",
        "surveys",
        "offers",
        "rewards",
        "reviews",
        "loyalty-activity",
        "loyalty-rewards",
        "loyalty-rules"
      ],
      "description": "Which list screen the quick filter appears on."
    },
    "name": {
      "type": "string",
      "description": "The label shown on the quick filter's button."
    },
    "filter": {
      "type": "object",
      "propertyNames": {
        "type": "string"
      },
      "additionalProperties": {},
      "description": "The filter document applied when the quick filter is picked. Same shape as a list endpoint's `filter` param, but as an object rather than a JSON string."
    },
    "createdAt": {
      "type": "string",
      "format": "date-time",
      "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$",
      "description": "When the quick filter was created."
    },
    "updatedAt": {
      "type": "string",
      "format": "date-time",
      "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$",
      "description": "When the quick filter was last changed."
    }
  },
  "required": ["id", "type", "name", "filter", "createdAt", "updatedAt"],
  "additionalProperties": false,
  "description": "The updated quick filter."
}

DELETE `/quick-filters/{id}`

Delete a quick filter. The records it matched are untouched.

Requires the settings:write permission.

Path parameters

idstringrequired

The ID of the quick filter to delete.

Request

curl \
  -X DELETE \
  "https://your-store.meisei.app/api/quick-filters/A4Ws1igz" \
  -H "Authorization: Bearer sk_YOUR_SECRET_KEY"

Request

import { client } from "@meisei/api/admin/client"
import { deleteQuickFiltersById } from "@meisei/api/admin"

client.setConfig({
  baseUrl: "https://your-store.meisei.app/api",
  headers: { Authorization: "Bearer sk_YOUR_SECRET_KEY" },
})

const { data, error } = await deleteQuickFiltersById({
  path: { id: "A4Ws1igz" },
})

Request

require "meisei"

meisei = Meisei::Client.new(
  secret_key: "sk_YOUR_SECRET_KEY",
  base_url: "https://your-store.meisei.app/api",
)

result = meisei.quick_filters.delete("A4Ws1igz")

Request

from meisei import Client

meisei = Client(
    secret_key="sk_YOUR_SECRET_KEY",
    base_url="https://your-store.meisei.app/api",
)

result = meisei.quick_filters.delete("A4Ws1igz")

Response

{
  "id": "A4Ws1igz",
  "type": "customers",
  "name": "string",
  "filter": "...",
  "createdAt": "2025-01-15T09:30:00Z",
  "updatedAt": "2025-01-15T09:30:00Z"
}

Response schema

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "type": "object",
  "properties": {
    "id": {
      "type": "string",
      "description": "Unique identifier for the quick filter.",
      "idCodec": "sqid"
    },
    "type": {
      "type": "string",
      "enum": [
        "customers",
        "products",
        "orders",
        "wishlists",
        "tiers",
        "surveys",
        "offers",
        "rewards",
        "reviews",
        "loyalty-activity",
        "loyalty-rewards",
        "loyalty-rules"
      ],
      "description": "Which list screen the quick filter appears on."
    },
    "name": {
      "type": "string",
      "description": "The label shown on the quick filter's button."
    },
    "filter": {
      "type": "object",
      "propertyNames": {
        "type": "string"
      },
      "additionalProperties": {},
      "description": "The filter document applied when the quick filter is picked. Same shape as a list endpoint's `filter` param, but as an object rather than a JSON string."
    },
    "createdAt": {
      "type": "string",
      "format": "date-time",
      "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$",
      "description": "When the quick filter was created."
    },
    "updatedAt": {
      "type": "string",
      "format": "date-time",
      "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$",
      "description": "When the quick filter was last changed."
    }
  },
  "required": ["id", "type", "name", "filter", "createdAt", "updatedAt"],
  "additionalProperties": false,
  "description": "The deleted quick filter."
}

#Quick filters

GET /quick-filters

Query parameters

POST /quick-filters

Body parameters

GET /quick-filters/{id}

Path parameters

PUT /quick-filters/{id}

Path parameters

Body parameters

DELETE /quick-filters/{id}

Path parameters

Quick filters

GET `/quick-filters`

POST `/quick-filters`

GET `/quick-filters/{id}`

PUT `/quick-filters/{id}`

DELETE `/quick-filters/{id}`