Skip to main content
GET
/
v1
/
vouchers
List 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

​
X-App-Id
string
header
required
​
X-App-Token
string
header
required
​
Authorization
string
header
required

The access token received from the authorization server in the OAuth 2.0 flow.

Query Parameters

​
limit
integer

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.

Required range: 1 <= x <= 100
​
page
integer

Which page of results to return. The lowest value is 1, the highest value is 99.

Required range: 1 <= x <= 99
​
category
string

Limit search results to vouchers within the specified category.

​
campaign_id
string

Limit search results to vouchers within the specified campaign

Example:

"camp_rRsfatlwN7unSeUIJDCYedal"

​
customer
string

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.

Example:

"cust_nk0N1uNQ1YnupAoJGOgvsODC"

​
campaign
string

A unique campaign name, identifies the parent campaign.

Example:

"camp_rRsfatlwN7unSeUIJDCYedal"

​
created_at
object

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

​
updated_at
object

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

​
order
enum<string>

Sorts the results using one of the filtering options, where the dash - preceding a sorting option means sorting in a descending order.

Available options:
created_at,
-created_at,
updated_at,
-updated_at,
code,
-code
​
code
string
Example:

"2CpRCE2c"

​
ids
string[]

Response

200 - application/json

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.

​
object
enum<string>
default:list

The type of the object represented by JSON.

Available options:
list
​
data_ref
enum<string>
default:vouchers

Identifies the name of the attribute that contains the array of voucher objects.

Available options:
vouchers
​
vouchers
Voucher With Categories · object[]

A dictionary that contains an array of vouchers. Each entry in the array is a separate voucher object.

​
total
integer

Returns how many vouchers in the project meet the limits defined by the query parameter definitions.

Example:

20

Last modified on December 12, 2025