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 |
---|---|
| A limit on the number of objects to be returned, between 1 and 100. |
| Which page of results to return. |
| A filter on the list based on the object
|
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 |
---|---|
| A string describing the object type returned. |
| Total number of records for given filtering query |
| 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 |
|
|
Redemptions |
|
|
Customers |
|
|
Publications |
|
|
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 |
|
Campaigns |
|
Products and Skus |
|
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 | [filters][type][conditions][$is]={{voucher_type} |
Voucher | metadata | [filters][metadata.{{Voucher metadata key}}][conditions][$is]={{voucher_metadata_value}} |
Voucher | holder_id | [filters][holder_id][conditions][$in]={{customer_id}} |
Voucher | campaign_ids | [filters][campaign_id][conditions][$in]={{campaign_id}} |