How to Query

The listing endpoint allows you to sort, filter, and limit the amount of data returned. Below are the guidelines for effectively utilizing these features

Sorting

To sort data in a specified manner, you should add to your request:

• _orderBy[fieldName]=asc - Ascends by fieldName.

• _orderBy[fieldName]=desc - Descends by fieldName.

Note: Not all visible fields are sortable. If sorting is not specified in the request, data may be returned in any order.

Filtering

For data filtering, you can use the parameter in the following format:

• fieldName[OPERATOR]=value allows for operation-based filtering.

• fieldName=value is equivalent to fieldName[eq]=value, applying an equality filter.

Filters can be combined as follows:

• fieldName[OPERATOR]=value&fieldName2[OPERATOR]=value2, with the filters connected by the logical AND operator.

This structure enables precise control over the data you retrieve, ensuring that the endpoint returns only the information relevant to your needs.

Filtering by Custom Attributes

Some endpoints support filtering based on custom attributes. You can filter customers by specifying custom labels directly in your query. Here's how you can use this feature:

• Basic Filtering: To find members with specific custom attributes, use the following request format: fieldName?labels=(label_key_1;label_value_1),(label_key_2;label_value_2)

  This query retrieves all objects that have either:

  • Custom attribute label_key_1 with the value label_value_1

  • Custom attribute label_key_2 with the value label_value_2

• Filtering Without Specifying a Value: If you want to find objects that have a specific custom attribute, regardless of its value, you can omit the value like this: fieldName?labels=(label_key_1;)

Operators

Operator	Description	Data Types
eq	Equality (case sensitive)	All
like	Substring occurrence (anywhere in the string) (case-insensitive)	Text
hasValue	Checks if the value is defined (empty string counts as defined)	All
notHasValue	Checks if the value is undefined (empty string counts as defined)	All
lt	Less than	Numeric/Datetime
lte	Less than or equal	Numeric/Datetime
gt	Greater than	Numeric/Datetime
gte	Greater than or equal	Numeric/Datetime
in	Check in array	Some array fields

Using the 'IN' Operator

For fields that allow enumeration values, you can use the 'IN' operator to specify multiple possible values. Here's an example:

• Filtering With 'IN' Operator:

  GET /api/{store}/redemption?status[in]=approved,issued

  This query will return redemptions where the status is either approved or issued.

This feature allows you to effectively narrow down your search results to better target specific groups or conditions, enhancing your ability to manage and analyze your data.

Pagination

Open Loyalty provides mechanisms to limit data fetched per request and navigate through large datasets via pagination. Understanding these functionalities allows developers to integrate with the API more effectively, leading to optimized data handling and reduced system overhead.

Request Parameters

1. _itemsOnPage: Limits the number of data items returned within a single request/page. The maximum value that can be specified is 50.

   Example: _itemsOnPage=10

2. _page: Specifies the page number starting from 1. Providing a page number beyond the available limit returns a successful response with zero items.

   Example: _page=2

Combining Operations

Multiple parameters can be combined using the & operator. This allows for specifying pagination alongside filtering and sorting criteria in a single request.

Example:

GET /api/DEFAULT/transaction?_page=1&_itemsOnPage=10&header:documentType[eq]=XY&customerData:email[eq]=[e-mail]&_orderBy[header:documentType]=asc

Response Structure

The structure of the returned data is consistently formatted to facilitate easy parsing and integration:

{
  "items": [
    { /* item details */ },
    { /* item details */ }
  ],
  "total": {
    "all": 10026,
    "filtered": 0,
    "estimated": true
  }
}

• items: Contains search results that meet the specified filters, are sorted according to the specified field, and are limited by the pagination settings.

• total: Provides a summary of the results:

  • all: Total number of items available in the dataset (unfiltered).

  • filtered: Count of items that match the filter criteria (not just those returned).

  • estimated: Indicates whether the counts are approximate; critical decisions should not be based on these values.

Standard Responses

• HTTP 200: Indicates a successful operation. The associated resource is now available for modification and retrieval. Often, this response includes an identifier for the created or modified resource.

  Example:

  {
    "customEventId": "00000000-0000-0000-0000-000000000000"
  }

• HTTP 204: Suggests a successful operation without any data in the response.

• HTTP 202: Indicates that the request has been accepted but processing may not start immediately.