Fetching Data

All top-level API resources have support for fetches via "list" API methods. For instance, you can list redemptions, list publications, list customers, and list products. These list API methods share a common structure, taking at least these three parameters: limit, page, and created_at .

Parameter name

Description

limit

A limit on the number of objects to be returned, between 1 and 100.

page

Which page of results to return.

created_at

A filter on the list based on the object created_at field. The value is a dictionary with the following options: before, after. A date value must be presented in ISO 8601 format (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.

Response format

The listing method returns a dictionary with a data property that contains an array of up to limit resources. Each entry in the array is a separate object. If no more resources are available, the resulting array will be empty. The result can be narrowed down according to specified (or default) filters.

Property name

Description

object

A string describing the object type returned.

total

Total number of records for given filtering query

data_ref

A value for this property directs to the property name which points to the results array

{
    "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": "https://dl.voucherify.io/api/v1/assets/qr/U2FsdGVkX1%2BoNqKQ08m2y1IWJemXXWI7RpgBrrNvmBiQbxe%2F4XBlAudagPJWbdtDI3S5biYSdslhXIwPyRCx0eUhUqnQmngmBadWq8xX3HeGSjUxMu2%2FyF9PAc3izKU0MUJ2oXJpjZ%2FoieEHtIElEA%3D%3D"
                },
                "barcode": {
                    "id": "U2FsdGVkX1+anixbnFov/mzPXUmqQp6YDR++HLW2m0WxQBc4t1wbBSKHqP8cAa63CUQE8IdyZEIZIku0RwAQiYflEAq6upaJ5CHiB3LUOh0EsdtnzUCB21EBkaNCs3PKNvFdDwG5UQzqIjN0u5MOGA==",
                    "url": "https://dl.voucherify.io/api/v1/assets/barcode/U2FsdGVkX1%2BanixbnFov%2FmzPXUmqQp6YDR%2B%2BHLW2m0WxQBc4t1wbBSKHqP8cAa63CUQE8IdyZEIZIku0RwAQiYflEAq6upaJ5CHiB3LUOh0EsdtnzUCB21EBkaNCs3PKNvFdDwG5UQzqIjN0u5MOGA%3D%3D"
                }
            },
            "is_referral_code": false,
            "created_at": "2018-09-04T14:58:25.000Z",
            "updated_at": "2018-09-20T08:03:55Z",
            "object": "voucher"
        }
    ]
}

Shortcuts

"List" API methods offer a list of query parameters which easily allows filtering results. Each API resource enables a specific set of options which can be used for simplifying a query. If you need advanced options, you can read the next section.

Resource

Shortcuts

Example

Vouchers

customer
campaign
category

{api-url}/vouchers?customer=source_id

Redemptions

campaign_name
customer
voucher_code
related_object_id
related_object_parent_id

{api-url}/redemptions?customer=customer_id

{api-url}/redemptions?customer=source_id

Customers

email
name

{api-url}/[email protected]

Publications

campaign_name
customer_id
voucher_code
result
voucher_type
is_referral_code
parent_object_id
related_object_id

{api-url}/publications?campaign_name=TEST

Advanced filters for fetching resources

Moreover, API methods for fetching resources offer extended capabilities for filtering data. A user​ can build advanced queries by passing parameters describing search 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.redeemed_quantity][conditions][$is]=0
[filters][is_referral_code][conditions][$is]=true
[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

Advanced filters for qualification API

Examine qualifications methods display all vouchers or campaigns qualified to the given customer and context (e.g., order). Using the advanced filters listed below you can limit qualification results:

Resource

Filter

Example

Campaigns

category

[filters][categories][conditions][$is]={{category_name}}

Campaigns

voucher type (DISCOUNT_VOUCHER, GIFT_VOUCHER or LOYALTY_CARD)

[filters][voucher_type][conditions][$is]={{voucher_type}}

Campaigns

metadata

[filters][metadata.{{Campaign metadata key}}][conditions][$is]={{campaign_metadata_value}}

Voucher

category

[filters][categories][conditions][$is]={{category_name}}

Voucher

voucher type
(GIFT_VOUCHER, or DISCOUNT_VOUCHER)

[filters][type][conditions][$is]={{voucher_type}

Voucher

metadata

[filters][metadata.{{Voucher metadata key}}][conditions][$is]={{voucher_metadata_value}}

Voucher

holder_id
(when a code is published to a customer, he/she becomes its holder)

[filters][holder_id][conditions][$in]={{customer_id}}

Voucher

campaign_ids

[filters][campaign_id][conditions][$in]={{campaign_id}}