Endpoints
- Voucher Object
- GETList Vouchers
- GETGet Voucher
- POSTCreate Voucher
- POSTGenerate Random Code
- PUTUpdate Voucher
- DELDelete Voucher
- POSTEnable Voucher
- POSTDisable Voucher
- POSTAdjust Voucher Balance
- GETList Voucher Transactions
- POSTExport Voucher Transactions
- POSTImport Vouchers
- POSTImport Vouchers using CSV
- POSTUpdate Vouchers in Bulk
- POSTUpdate Vouchers' Metadata in Bulk
- DELRelease Validation Session
- POSTExamine Voucher Qualificationdeprecated
curl --request GET \
--url https://{cluster}.voucherify.io/v1/vouchers \
--header 'Authorization: Bearer <token>' \
--header 'X-App-Id: <api-key>' \
--header 'X-App-Token: <api-key>'{
"object": "list",
"data_ref": "vouchers",
"vouchers": [
{
"id": "v_hrMBBeT4sOP9VSGPmj5KAgJwX202UjiY",
"code": "LOYALTY-CARD-xLPbpbXR",
"campaign": "Loyalty Program Fall 2022",
"campaign_id": "camp_f7fBbQxUuTN7dI7tGOo5XMDA",
"category": "First",
"category_id": "cat_0bb343dee3cdb5ec0c",
"categories": [
{
"id": "cat_0bb343dee3cdb5ec0c",
"name": "First",
"hierarchy": 1,
"created_at": "2022-09-16T11:47:19.568Z",
"object": "category"
}
],
"type": "LOYALTY_CARD",
"discount": null,
"gift": null,
"loyalty_card": {
"points": 110,
"balance": 100,
"next_expiration_date": "2023-12-31",
"next_expiration_points": 100
},
"start_date": null,
"expiration_date": null,
"validity_timeframe": null,
"validity_day_of_week": null,
"active": true,
"additional_info": null,
"metadata": {},
"assets": {
"qr": {
"id": "U2FsdGVkX19OrTPNyUztbNretF7tPRL4ZlUDPAUXVGL9e5UCPh6dic8zXEP8/6I6hUEqtz/F6IMIghWz1ljdjzpdizGHG3HZBw4c19fd8SD/DjhBRDSr8APqKGpZTLKe4QC2gislFTeDAq2lmJb6T1oOTBUGkUEwMgEX1Vlco9A=",
"url": "{{internalVoucherifyURL}}"
},
"barcode": {
"id": "U2FsdGVkX1/SpYuOrU9wd6/o1wzy6E/04wURHJ1xuMutzkIUx6OBTmHX5BO8XZRmEFHkgjC5eWJ27ArgAruJfwRXWuQfTNFD4raI9YvIiQNEzsZ0ydxwKBqJ/FJtiw69djuzQk1f4HdQo8s5gaZ7fd2U+1zbaeAvi9usyvRHZE4=",
"url": "{{internalVoucherifyURL}}"
}
},
"is_referral_code": false,
"created_at": "2022-09-19T07:56:22.355Z",
"updated_at": "2022-09-19T08:04:22.458Z",
"holder_id": "cust_eWgXlBBiY6THFRJwX45Iakv4",
"redemption": {
"quantity": null,
"redeemed_quantity": 1,
"redeemed_points": 10,
"object": "list",
"url": "/v1/vouchers/LOYALTY-CARD-xLPbpbXR/redemptions?page=1&limit=10"
},
"publish": {
"object": "list",
"count": 1,
"url": "/v1/vouchers/LOYALTY-CARD-xLPbpbXR/publications?page=1&limit=10"
},
"object": "voucher"
},
{
"id": "v_OBVfpTVf24DBz0HZmKVZa5UEl1DUg2bn",
"code": "AmountDiscount",
"campaign": null,
"campaign_id": null,
"category": "First",
"category_id": "cat_0bb343dee3cdb5ec0c",
"categories": [
{
"id": "cat_0bb343dee3cdb5ec0c",
"name": "First",
"hierarchy": 1,
"created_at": "2022-09-16T11:47:19.568Z",
"object": "category"
}
],
"type": "DISCOUNT_VOUCHER",
"discount": {
"type": "AMOUNT",
"amount_off": 400,
"amount_off_formula": "IF(CUSTOMER_METADATA(\"favorite_brands\") contains \"Nike\";20;CUSTOMER_METADATA(\"age\"))",
"effect": "APPLY_TO_ORDER"
},
"gift": null,
"loyalty_card": null,
"start_date": "2022-09-01T00:00:00.000Z",
"expiration_date": "2022-10-31T00:00:00.000Z",
"validity_timeframe": null,
"validity_day_of_week": [
1,
2,
3,
4,
5
],
"active": true,
"additional_info": "This voucher discount is based on a formula, payment must be using VISA, and order must be over $100.",
"metadata": {},
"assets": {
"qr": {
"id": "U2FsdGVkX18tV6jdzxWPwEzjeiX4DoM06JpwaoKUNGMNx4Td5e8FwA68uIHQwPaRpJr9CUCpiP4IsSD8nEJn1YtEv6FnY83wIv7uljYoQOYmMPyhKec8Ct3zH7KurMGuj4Fhws3HNA3bqP5MYEy+aA==",
"url": "{{internalVoucherifyURL}}"
},
"barcode": {
"id": "U2FsdGVkX181+WljOgxIt9Jg1Urbuv226+8Ug0DIyZiI0WtThPNYKZZEodzqQpIsGSdrDGXr2chLo+4FH3Ey8G2YXCPM6nUhZRSMF5oL3+uNjcLtBvb7MF5+ynY5fIgpXolwUK0R/BuT4Pa8prhgTg==",
"url": "{{internalVoucherifyURL}}"
}
},
"is_referral_code": false,
"created_at": "2022-09-12T07:51:02.145Z",
"updated_at": "2022-09-19T08:29:12.566Z",
"holder_id": "cust_eWgXlBBiY6THFRJwX45Iakv4",
"redemption": {
"quantity": null,
"redeemed_quantity": 2,
"object": "list",
"url": "/v1/vouchers/AmountDiscount/redemptions?page=1&limit=10"
},
"publish": {
"object": "list",
"count": 1,
"url": "/v1/vouchers/AmountDiscount/publications?page=1&limit=10"
},
"object": "voucher"
}
],
"total": 2
}Returns a list of vouchers. By default, the vouchers are returned sorted by creation date, with the most recent vouchers appearing first. A maximum of 100 vouchers are returned in the response.
When you get a list of vouchers, you can optionally specify query parameters to customize the number of vouchers returned per call using limit, which page of vouchers to return using page, sort the vouchers using the order query parameter and more.
This method will return an error when trying to return a limit of more than 100 vouchers.
curl --request GET \
--url https://{cluster}.voucherify.io/v1/vouchers \
--header 'Authorization: Bearer <token>' \
--header 'X-App-Id: <api-key>' \
--header 'X-App-Token: <api-key>'{
"object": "list",
"data_ref": "vouchers",
"vouchers": [
{
"id": "v_hrMBBeT4sOP9VSGPmj5KAgJwX202UjiY",
"code": "LOYALTY-CARD-xLPbpbXR",
"campaign": "Loyalty Program Fall 2022",
"campaign_id": "camp_f7fBbQxUuTN7dI7tGOo5XMDA",
"category": "First",
"category_id": "cat_0bb343dee3cdb5ec0c",
"categories": [
{
"id": "cat_0bb343dee3cdb5ec0c",
"name": "First",
"hierarchy": 1,
"created_at": "2022-09-16T11:47:19.568Z",
"object": "category"
}
],
"type": "LOYALTY_CARD",
"discount": null,
"gift": null,
"loyalty_card": {
"points": 110,
"balance": 100,
"next_expiration_date": "2023-12-31",
"next_expiration_points": 100
},
"start_date": null,
"expiration_date": null,
"validity_timeframe": null,
"validity_day_of_week": null,
"active": true,
"additional_info": null,
"metadata": {},
"assets": {
"qr": {
"id": "U2FsdGVkX19OrTPNyUztbNretF7tPRL4ZlUDPAUXVGL9e5UCPh6dic8zXEP8/6I6hUEqtz/F6IMIghWz1ljdjzpdizGHG3HZBw4c19fd8SD/DjhBRDSr8APqKGpZTLKe4QC2gislFTeDAq2lmJb6T1oOTBUGkUEwMgEX1Vlco9A=",
"url": "{{internalVoucherifyURL}}"
},
"barcode": {
"id": "U2FsdGVkX1/SpYuOrU9wd6/o1wzy6E/04wURHJ1xuMutzkIUx6OBTmHX5BO8XZRmEFHkgjC5eWJ27ArgAruJfwRXWuQfTNFD4raI9YvIiQNEzsZ0ydxwKBqJ/FJtiw69djuzQk1f4HdQo8s5gaZ7fd2U+1zbaeAvi9usyvRHZE4=",
"url": "{{internalVoucherifyURL}}"
}
},
"is_referral_code": false,
"created_at": "2022-09-19T07:56:22.355Z",
"updated_at": "2022-09-19T08:04:22.458Z",
"holder_id": "cust_eWgXlBBiY6THFRJwX45Iakv4",
"redemption": {
"quantity": null,
"redeemed_quantity": 1,
"redeemed_points": 10,
"object": "list",
"url": "/v1/vouchers/LOYALTY-CARD-xLPbpbXR/redemptions?page=1&limit=10"
},
"publish": {
"object": "list",
"count": 1,
"url": "/v1/vouchers/LOYALTY-CARD-xLPbpbXR/publications?page=1&limit=10"
},
"object": "voucher"
},
{
"id": "v_OBVfpTVf24DBz0HZmKVZa5UEl1DUg2bn",
"code": "AmountDiscount",
"campaign": null,
"campaign_id": null,
"category": "First",
"category_id": "cat_0bb343dee3cdb5ec0c",
"categories": [
{
"id": "cat_0bb343dee3cdb5ec0c",
"name": "First",
"hierarchy": 1,
"created_at": "2022-09-16T11:47:19.568Z",
"object": "category"
}
],
"type": "DISCOUNT_VOUCHER",
"discount": {
"type": "AMOUNT",
"amount_off": 400,
"amount_off_formula": "IF(CUSTOMER_METADATA(\"favorite_brands\") contains \"Nike\";20;CUSTOMER_METADATA(\"age\"))",
"effect": "APPLY_TO_ORDER"
},
"gift": null,
"loyalty_card": null,
"start_date": "2022-09-01T00:00:00.000Z",
"expiration_date": "2022-10-31T00:00:00.000Z",
"validity_timeframe": null,
"validity_day_of_week": [
1,
2,
3,
4,
5
],
"active": true,
"additional_info": "This voucher discount is based on a formula, payment must be using VISA, and order must be over $100.",
"metadata": {},
"assets": {
"qr": {
"id": "U2FsdGVkX18tV6jdzxWPwEzjeiX4DoM06JpwaoKUNGMNx4Td5e8FwA68uIHQwPaRpJr9CUCpiP4IsSD8nEJn1YtEv6FnY83wIv7uljYoQOYmMPyhKec8Ct3zH7KurMGuj4Fhws3HNA3bqP5MYEy+aA==",
"url": "{{internalVoucherifyURL}}"
},
"barcode": {
"id": "U2FsdGVkX181+WljOgxIt9Jg1Urbuv226+8Ug0DIyZiI0WtThPNYKZZEodzqQpIsGSdrDGXr2chLo+4FH3Ey8G2YXCPM6nUhZRSMF5oL3+uNjcLtBvb7MF5+ynY5fIgpXolwUK0R/BuT4Pa8prhgTg==",
"url": "{{internalVoucherifyURL}}"
}
},
"is_referral_code": false,
"created_at": "2022-09-12T07:51:02.145Z",
"updated_at": "2022-09-19T08:29:12.566Z",
"holder_id": "cust_eWgXlBBiY6THFRJwX45Iakv4",
"redemption": {
"quantity": null,
"redeemed_quantity": 2,
"object": "list",
"url": "/v1/vouchers/AmountDiscount/redemptions?page=1&limit=10"
},
"publish": {
"object": "list",
"count": 1,
"url": "/v1/vouchers/AmountDiscount/publications?page=1&limit=10"
},
"object": "voucher"
}
],
"total": 2
}Authorizations
The access token received from the authorization server in the OAuth 2.0 flow.
Query Parameters
Limits the number of objects to be returned. The limit can range between 1 and 100 items. If no limit is set, it returns 10 items.
1 <= x <= 100Which page of results to return. The lowest value is 1, the highest value is 99.
1 <= x <= 99Limit search results to vouchers within the specified category.
Limit search results to vouchers within the specified campaign
"camp_rRsfatlwN7unSeUIJDCYedal"
A tracking identifier of a customer who is the holder of the vouchers. It can be an id generated by Voucherify or the source_id. Remember to use the proper URL escape codes if the source_id contains special characters.
"cust_nk0N1uNQ1YnupAoJGOgvsODC"
A unique campaign name, identifies the parent campaign.
"camp_rRsfatlwN7unSeUIJDCYedal"
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). An example: [created_at][before]=2017-09-08T13:52:18.227Z
Show child attributes
Show child attributes
Timestamp representing the date and time before the voucher was created. The value is shown in the ISO 8601 format.
"2021-12-22T10:13:06.487Z"
Timestamp representing the date and time after the voucher was created. The value is shown in the ISO 8601 format.
"2021-12-22T10:13:06.487Z"
A filter on the list based on the object updated_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). An example: [updated_at][before]=2017-09-08T13:52:18.227Z
Show child attributes
Show child attributes
Timestamp representing the date and time before the voucher was updated. The value is shown in the ISO 8601 format.
"2021-12-22T10:13:06.487Z"
Timestamp representing the date and time after the voucher was updated. The value is shown in the ISO 8601 format.
"2021-12-22T10:13:06.487Z"
Sorts the results using one of the filtering options, where the dash - preceding a sorting option means sorting in a descending order.
created_at, -created_at, updated_at, -updated_at, code, -code "2CpRCE2c"
Response
Returns a dictionary that contains an array of vouchers. Each entry in the array is a separate voucher object. If no more vouchers are available (query parameter page incremented over and above the voucher count), the resulting array will be empty. The result can be narrowed down according to specified (or default) filters.
Response body schema for GET v1/vouchers.
The type of the object represented by JSON.
list Identifies the name of the attribute that contains the array of voucher objects.
vouchers A dictionary that contains an array of vouchers. Each entry in the array is a separate voucher object.
Show child attributes
Show child attributes
Assigned by the Voucherify API, identifies the voucher.
"v_mkZN9v7vjYUadXnHrMza8W5c34fE5KiV"
A code that identifies a voucher. Pattern can use all letters of the English alphabet, Arabic numerals, and special characters.
"WVPblOYX"
A unique campaign name, identifies the voucher's parent campaign.
"Gift Card Campaign"
Assigned by the Voucherify API, identifies the voucher's parent campaign.
"camp_FNYR4jhqZBM9xTptxDGgeNBV"
Tag defining the category that this voucher belongs to. Useful when listing vouchers using the List Vouchers endpoint.
Unique category ID assigned by Voucherify.
"cat_0bb343dee3cdb5ec0c"
Defines the type of the voucher.
GIFT_VOUCHER, DISCOUNT_VOUCHER, LOYALTY_CARD Contains information about discount.
- Discount
- Discount
- Discount
- Discount
- Discount
Show child attributes
Show child attributes
Defines the type of the voucher.
AMOUNT Amount taken off the subtotal of a price. Value is multiplied by 100 to precisely represent 2 decimal places. For example, a $10 discount is written as 1000.
Formula used to dynamically calculate the discount.
Maximum discount amount per order.
Defines how the discount is applied to the customer's order.
APPLY_TO_ORDER, APPLY_TO_ITEMS, APPLY_TO_ITEMS_PROPORTIONALLY, APPLY_TO_ITEMS_PROPORTIONALLY_BY_QUANTITY, APPLY_TO_ITEMS_BY_QUANTITY Flag indicating whether the discount was calculated using a formula.
Object representing gift parameters. Child attributes are present only if type is GIFT_VOUCHER. Defaults to null.
Show child attributes
Show child attributes
Total gift card income over the lifetime of the card. The value is multiplied by 100 to represent 2 decimal places. For example 10000 cents for $100.00.
10000
Total amount of subtracted credits over the gift card lifetime. The value is multiplied by 100 to represent 2 decimal places. For example 10000 cents for $100.00.
Available funds. The value is multiplied by 100 to represent 2 decimal places. For example 10000 cents for $100.00.
500
Defines how the credits are applied to the customer's order.
APPLY_TO_ORDER, APPLY_TO_ITEMS Object representing loyalty card parameters. Child attributes are present only if type is LOYALTY_CARD. Defaults to null.
Show child attributes
Show child attributes
Total number of points added to the loyalty card over its lifespan.
7000
Points available for reward redemption. This is calculated as follows: balance = points - expired_points - subtracted_points - redemption.redeemed_points.
6970
The next closest date when the next set of points are due to expire.
"2023-05-30"
The amount of points that are set to expire next.
Shows the number of pending points that will be added to the loyalty card when they are activated automatically or manually.
Shows the total number of expired points over the lifetime of the loyalty card.
Shows the total number of subtracted points over the lifetime of the loyalty card.
Activation timestamp defines when the code starts to be active in ISO 8601 format. Voucher is inactive before this date.
"2021-12-01T00:00:00.000Z"
Expiration timestamp defines when the code expires in ISO 8601 format. Voucher is inactive after this date.
"2021-12-31T00:00:00.000Z"
Set recurrent time periods when the earning rule is valid. For example, valid for 1 hour every other day.start_date required when including the validity_timeframe.
Show child attributes
Show child attributes
Defines the amount of time an earning rule will be active in ISO 8601 format. For example, an earning rule with a duration of PT1H will be valid for a duration of one hour.
"PT1H"
Defines the intervening time between two time points in ISO 8601 format, expressed as a duration. For example, an earning rule with an interval of P2D will be valid every other day.
"P2D"
Integer array corresponding to the particular days of the week in which the voucher is valid.
0Sunday1Monday2Tuesday3Wednesday4Thursday5Friday6Saturday
0, 1, 2, 3, 4, 5, 6 Determines the hours of validity, e.g. to create a happy hours scenario.
Show child attributes
Show child attributes
Defines the recurring period(s) when the resource is active. The periods should not overlap.
Show child attributes
Show child attributes
Defines the starting hour of validity in the HH:mm format. The resource is inactive before this time.
"12:00"
Integer array corresponding to the particular days of the week in which the resource is valid.
0Sunday1Monday2Tuesday3Wednesday4Thursday5Friday6Saturday
0, 1, 2, 3, 4, 5, 6 Defines the ending hour of validity in the HH:mm format. The resource is inactive after this time.
"14:00"
A flag to toggle the voucher on or off. You can disable a voucher even though it's within the active period defined by the start_date and expiration_date.
trueindicates an active voucherfalseindicates an inactive voucher
An optional field to keep any extra textual information about the code such as a code description and details.
The metadata object stores all custom attributes assigned to the code. A set of key/value pairs that you can attach to a voucher object. It can be useful for storing additional information about the voucher in a structured format.
Stores links to images of QR and barcode that correspond to an encrypted voucher code.
Show child attributes
Show child attributes
Stores Quick Response (QR) representation of encrypted code.
Show child attributes
Show child attributes
Encrypted voucher code ID.
"U2FsdGVkX19ucFhvVmBVpVYG5KoswTsjSIaqoKg5L9ie4BK+t4pp7U7oFzjGJzj9q/bmuMOj9mEFiVKDMIkSaruKedMvHbKoPX5Sg+BaZk5QwXMf8k/OzSlOEVybpwSq+AiqPoNtjeuqtIgkDyvT6Q=="
URL to QR code
Optional: Attach query parameters to base URL to customize the image of the encrypted voucher code.
size: integer value from1to100format: string, eitherpng(default) orsvg
"https://dev.dl.voucherify.io/api/v1/assets/qr/U2FsdGVkX19ucFhvVmBVpVYG5KoswTsjSIaqoKg5L9ie4BK%2Bt4pp7U7oFzjGJzj9q%2FbmuMOj9mEFiVKDMIkSaruKedMvHbKoPX5Sg%2BBaZk5QwXMf8k%2FOzSlOEVybpwSq%2BAiqPoNtjeuqtIgkDyvT6Q%3D%3D"
Stores barcode representation of encrypted code.
Show child attributes
Show child attributes
Encrypted voucher code ID.
"U2FsdGVkX19eJhGfWwUrH9+tulBkON+AnMktic+N6CVWzZ9+fHVxuVx22WakrzxiWXy0skuvvEHSeZIw9HlgyIJ+kJ1iPdUKpyENuNYJKzoZlO0mmTf6WQM6/pFs61apEn9SJx32ttCF6d3oxKISQQ=="
URL to barcode
Optional: Attach query parameters to base URL to customize the image of the encrypted voucher code.
size: integer value from1to100format: string, eitherpng(default) orsvg
"https://dev.dl.voucherify.io/api/v1/assets/barcode/U2FsdGVkX19eJhGfWwUrH9%2BtulBkON%2BAnMktic%2BN6CVWzZ9%2BfHVxuVx22WakrzxiWXy0skuvvEHSeZIw9HlgyIJ%2BkJ1iPdUKpyENuNYJKzoZlO0mmTf6WQM6%2FpFs61apEn9SJx32ttCF6d3oxKISQQ%3D%3D"
Flag indicating whether this voucher is a referral code; true for campaign type REFERRAL_PROGRAM.
Timestamp representing the date and time when the voucher was created. The value is shown in the ISO 8601 format.
"2021-12-22T10:13:06.487Z"
Timestamp representing the date and time when the voucher was last updated in ISO 8601 format.
"2021-12-22T10:14:45.316Z"
Unique customer identifier of the redeemable holder. It equals to the customer ID assigned by Voucherify.
"cust_eWgXlBBiY6THFRJwX45Iakv4"
Unique identifier of the referring person.
"cust_Vzck5i8U3OhcEUFY6MKhN9Rv"
The type of the object represented by JSON. Default is voucher.
Stores a summary of publication events: an event counter and endpoint to return details of each event. Publication is an assignment of a code to a customer, e.g. through a distribution.
Show child attributes
Show child attributes
The type of the object represented is by default list. To get this list, you need to make a call to the endpoint returned in the url attribute.
Publication events counter.
0
The endpoint where this list of publications can be accessed using a GET method. /v1/vouchers/{voucher_code}/publications
"/v1/vouchers/WVPblOYX/publications?page=1&limit=10"
Stores a summary of redemptions that have been applied to the voucher.
Show child attributes
Show child attributes
How many times a voucher can be redeemed. A null value means unlimited.
How many times a voucher has already been redeemed.
1
Total loyalty points redeemed.
100000
The type of the object represented is by default list. To get this list, you need to make a call to the endpoint returned in the url attribute.
The endpoint where this list of redemptions can be accessed using a GET method. /v1/vouchers/{voucher_code}/redemptions
"/v1/vouchers/WVPblOYX/redemptions?page=1&limit=10"
Contains details about the category.
Show child attributes
Show child attributes
Unique category ID assigned by Voucherify.
Category name.
Category hierarchy. Categories with lower hierarchy are processed before categories with higher hierarchy value.
x >= 0The type of the object represented by the JSON. This object stores information about the category.
category Timestamp representing the date and time when the category was created. The value is shown in the ISO 8601 format.
"2022-07-14T10:45:13.156Z"
Timestamp representing the date and time when the category was updated. The value is shown in the ISO 8601 format.
"2022-08-16T10:52:08.094Z"
Returns how many vouchers in the project meet the limits defined by the query parameter definitions.
20
Was this page helpful?