Pagination, filtering and ordering

Antavo offers several methods to ensure high-quality API performance when handling, processing, and returning large volumes of customer-related loyalty information.

Pagination

Pagination breaks down large data requests into smaller, more manageable pages. Pagination-enabled endpoints use two parameters:

limit: Specifies the number of entries returned in one response, e.g., limit=100.
offset: Determines the starting position for entries returned in one response, e.g., offset=10

Using these parameters a query like ?offset=20&limit=1 will return the entry numbered 20.

Response structure

A typical response from a paginated query contains:

next: Automatically generated link to access the next series of entries.
previous: Automatically generated link to access the previous series of entries.
data: Contains all data within the specified pagination range.

Example API request:

The GET /customers/{customer_id}/activities/rewards?offset=2&limit=1 request might result in a response like this:

 {
  "next": "/customers/a222e90f-2c59-468d-9b81-62f560084379/activities/rewards?offset=3&limit=1",
  "previous": "/customers/a222e90f-2c59-468d-9b81-62f560084379/activities/rewards?offset=1&limit=1",
  "data": [
    {
      "type": "coupon",
      "_actions": {
        "complete": {
          "method": "POST",
          "url": "/customers/a222e90f-2c59-468d-9b81-62f560084379/activities/rewards/5e78c52e5553aa0e00000008/claim"  
        }
      },
      "id": "5e78c52e5553aa0e00000008",
      "status": "active",
      "title": "20% Off on Winter Collection",
      "description": "Enjoy a 20% discount on our Winter Collection items.",
      "image": {
        "small": "https://antavo.{environment}.com/example1",
        "medium": "https://antavo.{environment}.com/example2",
        "large": "https://antavo.{environment}.com/example3"
      },
      "points": 1
    }
  ]

Supported endpoints

The following API endpoints support pagination:

Customer API :

/customers

Display API :

/customers/-/events
/customers/{customer_id}/events
/customers/{customer_id}/transactions
/customers/{customer_id}/transactions/{transaction_id}/events
/customers/{customer_id}/transactions/-/search
/customers/{customer_id}/prize-wheels/
/customers/{customer_id}/rewards
/customers/{customer_id}/activities/rewards
/customers/{customer_id}/activities/quizzes
/v2/customers/{customer_id}/activities/challenges

Entities API :

/entities/{module}/{entity}

Bulk Operations API:

/v1/bulk-operation/reward/claim/{batch_id}/status/error
/v1/bulk-operation/customer-list/{batch_id}/status/errors

Rewards API:

/rewards

Coupons API:

/coupons

Filtering

Filtering entity data within the Display API provides developers with a powerful tool to precisely tailor query results to their specific needs.

Events

Endpoints where filtering is available:

customers/{customer_id}/events
customers/-/events

Available filter parameters:

Filter	Example
`action`	`customers/{customer_id}/events?action=checkout` `customers/{customer_id}/events?action=checkout&action=point_add`
`date`	`customers/{customer_id}/events?date.eq=2024-05-01`

Activities

Endpoints where filtering is available:

/customers/{customer_id}/actitivites

Available filter parameters:

Filter	Example
`activity_types`	`customers/{customer_id}/activities?activity_types=reward,profiling`
`fields`	`customers/{customer_id}/activities?fields=cf\_prize\_cost\`

Rewards

Endpoints where filtering is available:

customers/{customer_id}/activities/rewards
customers/{customer_id}/activities/rewards/{reward_id}
customers/{customer_id}/rewards

Available filter parameters:

Filter	Example
`type`	`customers/{customer_id}/activities/rewards?type=coupon`
`points`	`customers/{customer_id}/activities/rewards?points.eq=100`
`stores`	`customers/{customer_id}/activities/rewards?stores=001,005`
`starts_at`	`customers/{customer_id}/activities/rewards?starts_at.lt=2024-07-01&date.gt=2024-05-01`
`ends_at`	`customers/{customer_id}/activities/rewards?ends_at=2024-07-01`
`status`	`customers/{customer_id}/activities/rewards?status=active` `customers/{customer_id}/activities/rewards?status=completed` `customers/{customer_id}/activities/rewards?status=scheduled`

Challenges

Endpoints where filtering is available:

customers/{customer_id}/activities/challenges
customers/{customer_id}/challenges
/v2/customers/{customer_id}/activities/challenges

Available filter parameters:

Filter	Example
`ends_at` (date)	`customers/{customer_id}/activities/challenges?end_at.eq=2024-03-12`
`points` (number)	`customers/{customer_id}/challenges?points.eq=100`
`tags` (string - list)	`customers/{customer_id}/activities/challenges?tags=2024,in-store`

📘
Note
The "date" filter accepts datetime values in ISO 8601 format (YYYY-MM-DD), ensuring machine-readable entries. Invalid entries, such as ?date=lastyear, will result in an empty query response rather than an error.

📘
Note
For points and date-type parameters (date, ends_at, starts_at), make sure you use query operators. Find instructions on how to use them in the Query operators section.

Custom attributes

Entities within Antavo can be filtered using custom attributes configured via the Custom entities module in the Antavo Management UI. This module allows extending existing built-in entities with new attributes or creating entirely new entities. The list of attributes is available through the Attributes tab of the entity configuration interface.

To enable filtering by an attribute, ensure it is tagged as filterable and api in the Tags section. An attribute can be used for filtering by adding the following query: entity_attribute=query_value

Example:

The Reward entity has a custom boolean attribute cf_priority

To filter based on the value of this attribute, use the following request:

GET https://api.{environment}.antavo.com/customers/{customer_id}/activities/rewards?cf_priority=false

API response:

{  
  "data": [  
      {  
          "type": "download",  
          "_actions": {  
              "complete": {  
                  "method": "POST",  
                  "url": "/customers/001/activities/rewards/637794598bacbc280e4952e4/claim"  
              }  
          },  
          "id": "637794598bacbc280e4952e4",  
          "status": "active",  
          "title": "Low priority reward",  
          "description": "a generic reward",  
          "image": {  
              "small": "https://antavo.{environment}.com/brands/1567/media/1668780684-Gboja.png",  
              "medium": "https://antavo.{environment}.com/brands/1567/media/1668780683-TjuvC.png",  
              "large": "https://antavo.{environment}.com/brands/1567/media/1668780683-ASyuP.png"  
          },  
          "points": 0,  
          "cf_priority": false  
      }  
  ],  
  "time": 0.105  
}

📘
Note
The time attribute indicates the duration in seconds that Antavo took to generate the response.

🚧
Note
While a field marked as filterable allows for filtering, its optimization for performance cannot be assumed. It is crucial to thoroughly test every filtered operation.

Query operators

Filtering can be extended by adding query parameters in the following format:

attributeuniqueid.operator=value

Available operators:

Operator	Explanation
`eq`	equals (default)
`gt`	greater than
`gte`	greater than or equal
`in`	in – accepts a comma-separated list of values
`lt`	less than
`lte`	less than or equal
`ne`	not equals
`nin`	not in – accepts a comma-separated list of values

If an operator is omitted, eq is used by default.

To avoid conflicts with special query parameters (e.g., limit for pagination), explicitly write the eq operator. For example, limit.eq should be used instead of just limit.

Filters can be combined to define ranges, e.g.: ?price.gte=10&price.lte=20.

Ordering

API responses can be ordered based on various criteria. The available ordering options may differ depending on the endpoint.

Operator	Description	Options
`order`	Specifies the order in which the results are returned.	`asc` (ascending, default) `desc` (descending)
`sort`	Defines the attribute by which the results are sorted.	`starts_at` `ends_at` `points` `title`

Example API request:

GET https://api.{environment}.antavo.com/customers/{customer_id}/events?order=desc

Supported endpoints

The following Display API endpoints support the ordering of results:

/customers/-/events
/customers/{customer_id}/events
/customers/{customer_id}/rewards
/customers/{customer_id}/activities/rewards
/v2/customers/{customer_id}/activities/challenges