Annex B: Working with Metadata

What is metadata in QPilot?

Metadata are dynamic JSON formatted fields that allow developers to send in their own data and extend QPilot's out of the box storage model.
Developers can store key value metadata on supported entities, get the data back and even run queries using metadata keys and values as criteria.

Supported entities

Currrent entities that support metadata are:

  • Sites
  • Customers
  • Scheduled Orders
  • Scheduled Order Items
  • Products

Supported metadata format

An entity metadata is an arrangement of string keys and values.
It needs to be sent on a JSON format, as following:

  "metadataKeyA": "valueA",
  "metadataKeyB": "valueB",
  "metadataKeyC": 4,
  "metadataKeyD": [99, 92]

Unsupported formats:

  • Arrays: e.g. [1, 3, 4, 5].
  • Other non string key formats. e.g. "value"

Querying by Metadata

Every entity that supports metadata allows for querying the API by specifying a metadata keys and values criteria.

e.g. Query for Products that contain a metadata key called "KeyA" and value "A" and a metadata key called "KeyB" and value "B":

GET /Sites/{siteId}/Products?search=criteria&metadatakey=KeyA&metadatakey=KeyB&metadatavalue=A&metadatavalue=B