Fetching Data

Many API resources support fetches via list API methods. For example, you can list redemptions, publications, customers, products, and more. These list API methods often share query parameters such as limit, created_at, updated_at, and order. Availability and allowed values depend on the endpoint. Check the endpoint page for the full parameter list.

Parameter name	Description
`limit`	Optional. A limit on the number of objects to be returned; between 1 and 100.
`created_at`	Optional on many lists. A filter based on the object `created_at` field. The value is a dictionary with `before` and `after`. Use ISO 8601 (`2016-11-16T14:14:31Z` or `2016-11-16`). Examples: `[created_at][before]=2017-09-08T13:52:18.227Z`, `[created_at][after]=2017-09-08`
`updated_at`	Optional on some lists. Same `before` / `after` shape as `created_at`, applied to `updated_at`.
`order`	Optional on many lists. Sorts results. A leading dash (`-`) means descending order. Allowed values are resource-specific.

Paging the results

Some of the list API methods use the page query parameter to display another page of results. However, the following list API methods use the starting_after_id query parameter:

The response to these methods may include a more_starting_after key that takes a string value with an ID. Use this ID with the starting_after_id query parameter to display another page of results.

Cursor pagination (Loyalty v2)

Loyalty v2 list endpoints use cursor pagination instead of page or starting_after_id. Typical response shape:

{
  "data": [],
  "cursor": {
    "next": "lcrsctx_12989e71c62b6d5baf",
    "expires_at": "2026-06-18T16:32:07.896Z"
  },
  "object": "list"
}

How to page results:

Call the list endpoint without cursor to get the first page.
If cursor.next is present, call the same endpoint again with ?cursor={cursor.next}.
Stop when cursor is null or cursor.next is missing.
Treat cursor.expires_at as the validity window for that cursor value. Request a new first page if the cursor expires.

Cursor prefixes differ by resource (for example lcrsctx_ for card transactions and lcrsmbr_ for members). Always pass the exact cursor.next value returned by the previous response. See the Loyalty v2 endpoint pages under API reference for resource-specific cursor patterns.

Response format

The listing method returns a dictionary with a data property that contains an array of resources. The maximum number of resources returned is determined by the limit query parameter. If no more resources are available, the resulting array on a given page will be empty. The result can be narrowed down according to the specified (or default) filters.

Property name	Description
`object`	A string describing the object type returned.
`data_ref`	The value for this property indicates the property name containing the results array.
`data`	An array that contains objects for a given list endpoint. In older methods, this is replaced by the name of the respective resource, e.g. `publications`.
`total`	Total number of records for given filtering query. In some methods, this field is absent.
`has_more`	It indicates that there are more results to be returned for given filter parameters.
`more_starting_after`	Present in some of the newer endpoints; it provides an ID that can be used with a `starting_after_id` query parameter to return another page of results.

{
    "object": "list",
    "total": 1,
    "data_ref": "vouchers",
    "vouchers": [
        {
            "id": "v_yY3smFaWii1iy3EvtaiJJpZqQxoS9rJn",
            "code": "2018-Heq-mK-2w1",
            "campaign": "Benefit",
            "campaign_id": "camp_FzQCVyac6jAAEephT0i2L14F",
            "type": "DISCOUNT_VOUCHER",
            "discount": {
                "type": "AMOUNT",
                "amount_off": 1000
            },
            "start_date": "2018-09-03T22:00:00.000Z",
            "validity_timeframe": {
                "interval": "P1D",
                "duration": "PT1H"
            },
            "validity_day_of_week": [
                2,
                3
            ],
            "publish": {
                "object": "list",
                "count": 1,
                "url": "/v1/vouchers/2018-Heq-mK-2w1/publications?page=1&limit=10"
            },
            "redemption": {
                "object": "list",
                "quantity": 5,
                "redeemed_quantity": 0,
                "url": "/v1/vouchers/2018-Heq-mK-2w1/redemptions?page=1&limit=10"
            },
            "active": false,
            "assets": {
                "qr": {
                    "id": "U2FsdGVkX1+oNqKQ08m2y1IWJemXXWI7RpgBrrNvmBiQbxe/4XBlAudagPJWbdtDI3S5biYSdslhXIwPyRCx0eUhUqnQmngmBadWq8xX3HeGSjUxMu2/yF9PAc3izKU0MUJ2oXJpjZ/oieEHtIElEA==",
                    "url": "{{voucherify_internal_URL}}"
                },
                "barcode": {
                    "id": "U2FsdGVkX1+anixbnFov/mzPXUmqQp6YDR++HLW2m0WxQBc4t1wbBSKHqP8cAa63CUQE8IdyZEIZIku0RwAQiYflEAq6upaJ5CHiB3LUOh0EsdtnzUCB21EBkaNCs3PKNvFdDwG5UQzqIjN0u5MOGA==",
                    "url": "{{voucherify_internal_URL}}"
                }
            },
            "is_referral_code": false,
            "created_at": "2018-09-04T14:58:25.000Z",
            "updated_at": "2018-09-20T08:03:55Z",
            "object": "voucher"
        }
    ]
}

{
    "object": "list",
    "data_ref": "data",
    "data": [
        {
            "id": "rh_0f35d7ba9300a8e8e4",
            "created_at": "2024-08-14T10:29:19.542Z",
            "redeemable_id": "v_YdDGS5yBnLCp79vfPbHhkoRrqPwkgyiy",
            "redeemable_object": "voucher",
            "campaign_id": "camp_vVk4unz3k4gA023fk9XoSiTh",
            "campaign_type": "REFERRAL_PROGRAM",
            "voucher_type": "DISCOUNT_VOUCHER",
            "customer_id": "cust_K11DXLfeJIZz7LZpxgiLhZpX",
            "holder_role": "REFEREE",
            "object": "redeemable_holder",
            "metadata": {
                "influencer_code": true
            }
        },
        {
            "id": "rh_0f35d7ba9300a8e8e3",
            "created_at": "2024-08-14T10:29:19.542Z",
            "redeemable_id": "v_YdDGS5yBnLCp79vfPbHhkoRrqPwkgyiy",
            "redeemable_object": "voucher",
            "campaign_id": "camp_vVk4unz3k4gA023fk9XoSiTh",
            "campaign_type": "REFERRAL_PROGRAM",
            "voucher_type": "DISCOUNT_VOUCHER",
            "customer_id": "cust_6P4K6p7PxEuK37sDtiLOii0A",
            "holder_role": "REFEREE",
            "object": "redeemable_holder",
            "metadata": {
                "influencer_code": false
            }
        }
    ],
    "total": 2,
    "has_more": true,
    "more_starting_after": "rh_0f35d7ba9300a8e8e3"
}

Shortcuts

List API methods offer query parameter shortcuts that map to internal filters. Each resource enables a specific set. If you need advanced options, read the next section.

Resource	Shortcuts	Example
Vouchers	`customer` `campaign` `category`	`{api-url}/vouchers?customer=source_id`
Redemptions	`campaign` `customer` `voucher` `related_object` `related_object_parent_id` `result` `object`	`{api-url}/redemptions?customer=customer_id` `{api-url}/redemptions?customer=source_id`
Customers	`email` `name` `city` `segment_id`	`{api-url}/customers?email=john@example.com`
Publications	`campaign` `customer` `voucher` `result` `voucher_type` `is_referral_code` `parent_object_id` `related_object_id` `source_id`	`{api-url}/publications?campaign=TEST`
Validation Rule Assignments	`related_object_id` `rule`	`{api-url}/validation-rules-assignments?related_object_id=promo_id`

For publications, voucher_type matches with a starts-with condition, not an exact match.

Advanced filters for fetching resources

API methods for fetching resources also accept nested filters query parameters for more precise criteria.

Resource	Examples
Vouchers	`[filters][active][conditions][$active]=true` `[filters][active][conditions][$expired]=true` `[filters][active][conditions][$enabled]=true` `[filters][active][conditions][$disabled]=true` `[filters][redemption_status][conditions][$redeemed]=true` `[filters][redemption_status][conditions][$redeemable]=true` `[filters][redemption.redeemed_quantity][conditions][$is]=0` `[filters][is_referral_code][conditions][$is]=true` `[filters][expiration_date][conditions][$before]=2024-04-29T00:00:00.000Z` `[filters][metadata.seq_number][conditions][$is]=1`
Campaigns	`[filters][metadata.seq_number][conditions][$is]=1` `[filters][metadata.test][conditions][$is]=true`
Products and Skus	`[filters][updated_at][conditions][$after][0]=2020-08-20T14:17:09Z` `[filters][updated_at][conditions][$before][0]=2020-08-20T14:17:09Z` `[filters][created_at][conditions][$after][0]=2020-08-20T14:17:09Z` `[filters][created_at][conditions][$before][0]=2020-08-20T14:17:09Z`
List all promotion stacks	`[created_at][before]=2021-12-30T13:52:18.227Z` `[created_at][after]=2021-12-30T13:52:18.227Z` `[filters][created_at][conditions][$before][0]=2021-12-30T13:52:18.227Z` `[filters][created_at][conditions][$after][0]=2021-12-30T13:52:18.227Z` `[updated_at][before]=2021-12-30T13:52:18.227Z` `[updated_at][after]=2021-12-30T13:52:18.227Z` `[filters][updated_at][conditions][$before][0]=2021-12-30T13:52:18.227Z` `[filters][updated_at][conditions][$after][0]=2021-12-30T13:52:18.227Z`

For voucher filters[active] and filters[redemption_status], send one condition key per request. Only the first condition key is applied.

Introduction

Endpoints

Events

Paging the results

Response format

Shortcuts

Advanced filters for fetching resources