GuidesHelp CenterRelease notesSign up
API Reference

Redeem Voucher [Deprecated]

post deprecatedhttps://{cluster}.voucherify.io/v1/vouchers//redemption

❗️

Deprecated

This endpoint represents the deprecated version of the API responsible for voucher redemption, and we do not recommend using it. The new Stackable Discounts API introduces additional features and improvements while maintaining backward compatibility, including applying a combination of coupon codes and promotion tiers. Developers are encouraged to migrate to the latest version to take advantage of the latest enhancements and bug fixes. No updates will be provided to the deprecated endpoint.

To redeem a voucher, you create a redemption object. It increments the redemption counter and updates the history of the voucher.

How discounts and order amounts are calculated in the API response?

In the table below, you can see the logic the API follows to calculate discounts and amounts:

FieldCalculationDescription
amountN/AThis field shows the order amount before applying any discount
total_amounttotal_amount = amount - total_discount_amountThis field shows the order amount after applying all the discounts
discount_amountdiscount_amount = previous_discount_amount + applied_discount_amountThis field sums up all order-level discounts applied to a patricular order
items_discount_amountsum(items, i => i.discount_amount)This field sums up all product-specific discounts applied to this order
total_discount_amounttotal_discount_amount = discount_amount + items_discount_amountThis field sums up all order-level and all product-specific discounts applied to this order
applied_discount_amountN/AThis field shows order-level discount applied in a particular request
items_applied_discount_amountsum(items, i => i.applied_discount_amount)This field sums up all product-specific discounts applied in a particular request
total_applied_discount_amounttotal_applied_discount_amount = applied_discount_amount + items_applied_discount_amountThis field sums up all order-level and all product-specific discounts applied in a particular request

SDKs

You can invoke the redemption endpoint with one of the official libraries:

Customer tracking

The redeem operation is a key part of [Customer tracking] (doc:customer-tracking) workflow. There're 3 ways you can identify your end customer in Voucherify within this request. You can either provide a tracking ID (e.g. your customer's login or a generated id), a customer ID (if the customer is already stored in Voucherify) or a full customer object in the payload. Note that you can pass and thus store any customer-related metadata. See examples on the right.

"customer": {
  "source_id": "alice.morgan",
  "name": "Alice Morgan",
  "email": "[email protected]",
  "description": "",
  "metadata": {
    "locale": "en-GB",
    "shoeSize": 5,
    "favourite_brands": ["Armani", "L'Autre Chose", "Vicini"]
  }
}

If you already created a customer profile in Voucherify's database, whether it was implicitly by providing it to the redeem function or explicitly by invoking the Create Customer method, you can identify your customer in redemptions by a generated ID (starting with cust_). 

"customer": {
    "id": "cust_C9qJ3xKgZFqkpMw7b21MF2ow"
}

{
  "customer": "cust_C9qJ3xKgZFqkpMw7b21MF2ow"
}

{
  "customer": "alice.morgan"
}

📘

Redemption rollback

Do you need to undo a redemption? You can do it with redemption rollback.

Redemption failures

There are several reasons why a redemption may fail. You will get the reason in the error key:

  • resource_not_found - voucher with given code does not exist
  • voucher_not_active - voucher is not active yet (before start date)
  • voucher_expired - voucher has already expired (after expiration date)
  • voucher_disabled - voucher has been disabled (active: false)
  • quantity_exceeded - voucher's redemptions limit has been exceeded
  • gift_amount_exceeded - gift amount has been exceeded
  • customer_rules_violated - customer did not match the segment
  • order_rules_violated - order did not match validation rules
  • invalid_order - order was specified incorrectly
  • invalid_amount - order amount was specified incorrectly
  • missing_amount - order amount was not specified
  • missing_order_items - order items were not specified
  • missing_customer - customer was not specified

Order object

The purchase of previously defined products (products are stored in Voucherify) by end customers is handled through the order object. You are obligated to pass the order object in case you use validation rules. You can learn more about the [validation rules structure] (doc:validation-rules).

AttributesDescription
amount
integer		A positive integer representing the total amount for the order.
items
list		List of items constituting the order. Order items can be defined either by product_id or sku_id. Along with every item you must define the quantity.

Child attributes:

- product_id (string) - The ID of the associated product object for this line item.

- sku_id (string) - The ID of the associated variant (sku) object for this line item.

- quantity (integer) - A positive integer representing the number of instances of the item that are included in this order line.

- price (integer) - A positive integer representing the cost of an item.

- amount (integer) - quantity * price (you should provide it to retrieve discount_amount for a particular order item if the discount is applied only to this item learn more

🚧

Order ID

If you use the same order id in more than one redemption request, all valid discounts provided in the redemption payload will be applied to the given order. [Read more in this guide] (https://docs.voucherify.io/docs/manage-stackable-discounts).

"order": {
  "amount": 10000,
  "items": [
    {
      "product_id": "prod_Bi7sRr3kwvxH2I",
      "quantity": 1
    }
  ]
}

Gift Vouchers - redeem Gift Card and control redeemed amount

In Voucherify,you can also create a gift card for customers. Customers then can use gift card credits to fulfill the order. A user can specify how many credits he wants to use from the gift card. The available balance of credits is counted based on policy rules attached to the Gift Voucher definition.

When the user wants to define how many gift credits are to be used from the gift card to complete the order, the credits property can be assigned the equivalent value in the lowest currency in the request body. The value of credits being applied to the order cannot be higher than the current balance on the gift card.

curl -i -X **POST** \
   -H "Content-Type:application/json" \
   -H "X-App-Id:c70a6f00-cf91-4756-9df5-47628850002b" \
   -H "X-App-Token:3266b9f8-e246-4f79-bdf0-833929b1380c" \
   -d '{
        "order": {
           "amount": 2500
        },
        "gift": {
           "credits": 1500
        }
      }' \ 
 'https://api.voucherify.io/v1/vouchers/aDm4CRR3/redemption'

Loyalty Coins - redeem loyalty card and pay with points

Voucherify offers the possibility to set up a reward type in the Loyalty Program, which allows using loyalty points as gift credits. The available balance of credits is counted based on policy rules attached to the reward definition.

If a user configures just one reward type of paying in points, in the redemption request, there is no additional information required. Voucherify will automatically select as a proper reward definition and will calculate the discount based on the attached policy. 

{
    "order": {
        "amount": 25000,
        "items": [
            {
                "product_id": "test_source_1",
                "quantity": "1",
                "price": 15000
            },
            {
                "product_id": "test_source_2",
                "quantity": "1",
                "price": 10000
            }
        ]
    },
    "metadata": {
        "category": "vip",
        "shop": "s1",
        "location": "l1"
    }
}

{
    "id": "r_zv5Qn7cF68RbVX4foKxgwUi1",
    "object": "redemption",
    "date": "2020-05-24T13:44:20Z",
    "customer_id": "cust_lXisxEaEHYKTEVf1YnNS8AUh",
    "amount": 250,
    "order": {
        "status": "PROCESSING",
        "items": [
            {
                "object": "order_item",
                "product_id": "test_source_1",
                "quantity": 1,
                "amount": 15000,
                "price": 15000
            },
            {
                "object": "order_item",
                "product_id": "test_source_2",
                "quantity": 1,
                "amount": 10000,
                "price": 10000
            }
        ],
        "customer": {
            "id": "cust_lXisxEaEHYKTEVf1YnNS8AUh",
            "object": "customer",
            "referrals": {
                "campaigns": [],
                "total": 0
            }
        },
        "amount": 25000,
        "object": "order",
        "id": "ord_Tgi2ApelDyl86sm5AYDKCBMZ",
        "created_at": "2020-05-24T13:44:20Z",
        "discount_amount": 25000
    },
    "customer": {
        "id": "cust_lXisxEaEHYKTEVf1YnNS8AUh",
        "source_id": "[email protected]",
        "name": "Tom Loyalty",
        "email": "[email protected]",
        "metadata": {},
        "object": "customer"
    },
    "reward": {
        "assignment_id": "rewa_pHilLjHWOD7oNjJZnog3VoEi",
        "loyalty_tier_id": "ltr_3q5dW6GaRC4QkA1oYmfGy1k1",
        "id": "rew_3qmzGPWJ7LfLXnPAjmbPacIl",
        "name": "1 point - 25 cents",
        "created_at": "2020-05-22T18:39:52Z",
        "updated_at": "2020-05-23T08:18:55Z",
        "parameters": {
            "automation_id": null,
            "coin": {
                "exchange_ratio": 0.25
            }
        },
        "type": "COIN",
        "object": "reward"
    },
    "metadata": {
        "category": "vip",
        "shop": "s1",
        "location": "l1"
    },
    "result": "SUCCESS",
    "tracking_id": "track_IWQYtuUE7phYpPzTHD5uwbyvlrO4nqyzipbQQtsHrRw=",
    "voucher": {
        "id": "v_wjgLC2lrQy1urPOdd35JX0RtkcOcQOmb",
        "code": "Dm1x8MuX",
        "campaign": "TestLoyalty-GivePoints",
        "campaign_id": "camp_qVVaC4vpVlof03eBi8qb5gE7",
        "category": null,
        "type": "LOYALTY_CARD",
        "discount": null,
        "gift": null,
        "loyalty_card": {
            "points": 489,
            "balance": 23
        },
        "start_date": null,
        "expiration_date": null,
        "validity_timeframe": null,
        "validity_day_of_week": null,
        "publish": {
            "object": "list",
            "count": 1,
            "url": "/v1/vouchers/Dm1x8MuX/publications?page=1&limit=10"
        },
        "redemption": {
            "object": "list",
            "quantity": null,
            "redeemed_quantity": 8,
            "url": "/v1/vouchers/Dm1x8MuX/redemptions?page=1&limit=10",
            "redeemed_points": 466
        },
        "active": true,
        "additional_info": null,
        "metadata": {},
        "assets": {
            "qr": {
                "id": "U2FsdGVkX1+9Eo0bLWMZmYK6nQxl3AyR3nqkloGURcpRJcxL3hl5xXSGRYjYdySc9twLaKnYGVXbLtjCGW8FBotl1rTAxLJQm4okoJ385Gd6pc1ty6AnhaHHJjCeLoYYSQCG1EyP9PRxnTihjmsE9g==",
                "url": "https://dev.dl.voucherify.io/api/v1/assets/qr/U2FsdGVkX1%2B9Eo0bLWMZmYK6nQxl3AyR3nqkloGURcpRJcxL3hl5xXSGRYjYdySc9twLaKnYGVXbLtjCGW8FBotl1rTAxLJQm4okoJ385Gd6pc1ty6AnhaHHJjCeLoYYSQCG1EyP9PRxnTihjmsE9g%3D%3D"
            },
            "barcode": {
                "id": "U2FsdGVkX19NfR0ANlhLM7Df9Ec+xqTh6aTbHakk/Gzeh9zTiuj8KUBLswVXkz0gdLVnn1ZtzjCv7oF/BSQTyJx0YSK+HIUG9RGD+9rVhiC7+4WkSKrgAZ+NeqQBIqcespt8WWygXjfkvbyXBSF7Lg==",
                "url": "https://dev.dl.voucherify.io/api/v1/assets/barcode/U2FsdGVkX19NfR0ANlhLM7Df9Ec%2BxqTh6aTbHakk%2FGzeh9zTiuj8KUBLswVXkz0gdLVnn1ZtzjCv7oF%2FBSQTyJx0YSK%2BHIUG9RGD%2B9rVhiC7%2B4WkSKrgAZ%2BNeqQBIqcespt8WWygXjfkvbyXBSF7Lg%3D%3D"
            }
        },
        "is_referral_code": false,
        "holder_id": "cust_lXisxEaEHYKTEVf1YnNS8AUh",
        "updated_at": "2020-05-24T13:44:20Z",
        "holder": {
            "id": "cust_lXisxEaEHYKTEVf1YnNS8AUh",
            "source_id": "[email protected]",
            "name": "Tom Loyalty",
            "email": "[email protected]",
            "metadata": {},
            "object": "customer"
        },
        "object": "voucher",
        "validation_rules_assignments": {
            "data": [],
            "object": "list",
            "total": 0,
            "data_ref": "data"
        }
    }
}

In case the user wants to define how much he spends in points, it is configurable by property points in a request body.

{
    "reward": {
        "points": 10
    },
    "order": {
        "amount": 25000,
        "items": [
            {
                "product_id": "test_source_1",
                "quantity": "1",
                "price": 15000
            },
            {
                "product_id": "test_source_2",
                "quantity": "1",
                "price": 10000
            }
        ]
    },
    "metadata": {
        "category": "vip",
        "shop": "s1",
        "location": "l1"
    }
}

{
    "id": "r_NJIfNYD8uc2lNm3YBAqXr3FF",
    "object": "redemption",
    "date": "2020-05-24T16:28:29Z",
    "customer_id": "cust_lXisxEaEHYKTEVf1YnNS8AUh",
    "amount": 10,
    "order": {
        "status": "PROCESSING",
        "items": [
            {
                "object": "order_item",
                "product_id": "test_source_1",
                "quantity": 1,
                "amount": 15000,
                "price": 15000
            },
            {
                "object": "order_item",
                "product_id": "test_source_2",
                "quantity": 1,
                "amount": 10000,
                "price": 10000
            }
        ],
        "customer": {
            "id": "cust_lXisxEaEHYKTEVf1YnNS8AUh",
            "object": "customer",
            "referrals": {
                "campaigns": [],
                "total": 0
            }
        },
        "amount": 25000,
        "object": "order",
        "id": "ord_70kKdXIKCSx5cfglKSpz9aHy",
        "created_at": "2020-05-24T16:28:29Z",
        "discount_amount": 250
    },
    "customer": {
        "id": "cust_lXisxEaEHYKTEVf1YnNS8AUh",
        "source_id": "[email protected]",
        "name": "Tom Loyalty",
        "email": "[email protected]",
        "metadata": {},
        "object": "customer"
    },
    "reward": {
        "assignment_id": "rewa_pHilLjHWOD7oNjJZnog3VoEi",
        "loyalty_tier_id": null,
        "id": "rew_3qmzGPWJ7LfLXnPAjmbPacIl",
        "name": "1 point - 25 cents",
        "created_at": "2020-05-22T18:39:52Z",
        "updated_at": "2020-05-24T13:44:26Z",
        "parameters": {
            "automation_id": null,
            "coin": {
                "exchange_ratio": 0.25
            }
        },
        "type": "COIN",
        "object": "reward"
    },
    "metadata": {
        "category": "vip",
        "shop": "s1",
        "location": "l1"
    },
    "result": "SUCCESS",
    "tracking_id": "track_IWQYtuUE7phYpPzTHD5uwbyvlrO4nqyzipbQQtsHrRw=",
    "voucher": {
        "id": "v_wjgLC2lrQy1urPOdd35JX0RtkcOcQOmb",
        "code": "Dm1x8MuX",
        "campaign": "TestLoyalty-GivePoints",
        "campaign_id": "camp_qVVaC4vpVlof03eBi8qb5gE7",
        "category": null,
        "type": "LOYALTY_CARD",
        "discount": null,
        "gift": null,
        "loyalty_card": {
            "points": 539,
            "balance": 63
        },
        "start_date": null,
        "expiration_date": null,
        "validity_timeframe": null,
        "validity_day_of_week": null,
        "publish": {
            "object": "list",
            "count": 1,
            "url": "/v1/vouchers/Dm1x8MuX/publications?page=1&limit=10"
        },
        "redemption": {
            "object": "list",
            "quantity": null,
            "redeemed_quantity": 9,
            "url": "/v1/vouchers/Dm1x8MuX/redemptions?page=1&limit=10",
            "redeemed_points": 476
        },
        "active": true,
        "additional_info": null,
        "metadata": {},
        "assets": {
            "qr": {
                "id": "U2FsdGVkX1+9Eo0bLWMZmYK6nQxl3AyR3nqkloGURcpRJcxL3hl5xXSGRYjYdySc9twLaKnYGVXbLtjCGW8FBotl1rTAxLJQm4okoJ385Gd6pc1ty6AnhaHHJjCeLoYYSQCG1EyP9PRxnTihjmsE9g==",
                "url": "https://dev.dl.voucherify.io/api/v1/assets/qr/U2FsdGVkX1%2B9Eo0bLWMZmYK6nQxl3AyR3nqkloGURcpRJcxL3hl5xXSGRYjYdySc9twLaKnYGVXbLtjCGW8FBotl1rTAxLJQm4okoJ385Gd6pc1ty6AnhaHHJjCeLoYYSQCG1EyP9PRxnTihjmsE9g%3D%3D"
            },
            "barcode": {
                "id": "U2FsdGVkX19NfR0ANlhLM7Df9Ec+xqTh6aTbHakk/Gzeh9zTiuj8KUBLswVXkz0gdLVnn1ZtzjCv7oF/BSQTyJx0YSK+HIUG9RGD+9rVhiC7+4WkSKrgAZ+NeqQBIqcespt8WWygXjfkvbyXBSF7Lg==",
                "url": "https://dev.dl.voucherify.io/api/v1/assets/barcode/U2FsdGVkX19NfR0ANlhLM7Df9Ec%2BxqTh6aTbHakk%2FGzeh9zTiuj8KUBLswVXkz0gdLVnn1ZtzjCv7oF%2FBSQTyJx0YSK%2BHIUG9RGD%2B9rVhiC7%2B4WkSKrgAZ%2BNeqQBIqcespt8WWygXjfkvbyXBSF7Lg%3D%3D"
            }
        },
        "is_referral_code": false,
        "holder_id": "cust_lXisxEaEHYKTEVf1YnNS8AUh",
        "updated_at": "2020-05-24T16:28:29Z",
        "holder": {
            "id": "cust_lXisxEaEHYKTEVf1YnNS8AUh",
            "source_id": "[email protected]",
            "name": "Tom Loyalty",
            "email": "[email protected]",
            "metadata": {},
            "object": "customer"
        },
        "object": "voucher",
        "validation_rules_assignments": {
            "data": [],
            "object": "list",
            "total": 0,
            "data_ref": "data"
        }
    }
}

Moreover, it is possible to define many levels of reward in which collected points can be used as gift credits. Per each tier, we can implement different conversion factors. Having many options in the rewards catalog, we will need to select a coins calculation policy (reward ID) that we want to use for calculating a final discount in the redemption request.

{
    "reward": {
        "points": 30,
        "id": "rew_noP2S5H8PEBFT97mennSA531"
    },
    "order": {
        "amount": 25000,
        "items": [
            {
                "product_id": "test_source_1",
                "quantity": "1",
                "price": 15000
            },
            {
                "product_id": "test_source_2",
                "quantity": "1",
                "price": 10000
            }
        ]
    },
    "metadata": {
        "category": "vip",
        "shop": "s1",
        "location": "l1"
    }
}

{
    "id": "r_se17sLon6YX5wMhYVzfQa2dc",
    "object": "redemption",
    "date": "2020-05-24T13:41:16Z",
    "customer_id": "cust_lXisxEaEHYKTEVf1YnNS8AUh",
    "amount": 10,
    "order": {
        "status": "PROCESSING",
        "items": [
            {
                "object": "order_item",
                "product_id": "test_source_1",
                "quantity": 1,
                "amount": 15000,
                "price": 15000
            },
            {
                "object": "order_item",
                "product_id": "test_source_2",
                "quantity": 1,
                "amount": 10000,
                "price": 10000
            }
        ],
        "customer": {
            "id": "cust_lXisxEaEHYKTEVf1YnNS8AUh",
            "object": "customer",
            "referrals": {
                "campaigns": [],
                "total": 0
            }
        },
        "amount": 25000,
        "object": "order",
        "id": "ord_EfMmve84JzQIg2MCM3cAvLgF",
        "created_at": "2020-05-24T13:41:16Z",
        "discount_amount": 25000
    },
    "customer": {
        "id": "cust_lXisxEaEHYKTEVf1YnNS8AUh",
        "source_id": "[email protected]",
        "name": "Tom Loyalty",
        "email": "[email protected]",
        "metadata": {},
        "object": "customer"
    },
    "reward": {
        "assignment_id": "rewa_g3QQwQfhJrjBYzEa1NJkub7N",
        "loyalty_tier_id": null,
        "id": "rew_noP2S5H8PEBFT97mennSA531",
        "name": "1 point 25$",
        "created_at": "2020-05-24T12:57:19Z",
        "parameters": {
            "automation_id": null,
            "coin": {
                "exchange_ratio": 25.0
            }
        },
        "type": "COIN",
        "object": "reward"
    },
    "metadata": {
        "category": "vip",
        "shop": "s1",
        "location": "l1"
    },
    "result": "SUCCESS",
    "tracking_id": "track_IWQYtuUE7phYpPzTHD5uwbyvlrO4nqyzipbQQtsHrRw=",
    "voucher": {
        "id": "v_wjgLC2lrQy1urPOdd35JX0RtkcOcQOmb",
        "code": "Dm1x8MuX",
        "campaign": "TestLoyalty-GivePoints",
        "campaign_id": "camp_qVVaC4vpVlof03eBi8qb5gE7",
        "category": null,
        "type": "LOYALTY_CARD",
        "discount": null,
        "gift": null,
        "loyalty_card": {
            "points": 439,
            "balance": 223
        },
        "start_date": null,
        "expiration_date": null,
        "validity_timeframe": null,
        "validity_day_of_week": null,
        "publish": {
            "object": "list",
            "count": 1,
            "url": "/v1/vouchers/Dm1x8MuX/publications?page=1&limit=10"
        },
        "redemption": {
            "object": "list",
            "quantity": null,
            "redeemed_quantity": 7,
            "url": "/v1/vouchers/Dm1x8MuX/redemptions?page=1&limit=10",
            "redeemed_points": 216
        },
        "active": true,
        "additional_info": null,
        "metadata": {},
        "assets": {
            "qr": {
                "id": "U2FsdGVkX1+9Eo0bLWMZmYK6nQxl3AyR3nqkloGURcpRJcxL3hl5xXSGRYjYdySc9twLaKnYGVXbLtjCGW8FBotl1rTAxLJQm4okoJ385Gd6pc1ty6AnhaHHJjCeLoYYSQCG1EyP9PRxnTihjmsE9g==",
                "url": "https://dev.dl.voucherify.io/api/v1/assets/qr/U2FsdGVkX1%2B9Eo0bLWMZmYK6nQxl3AyR3nqkloGURcpRJcxL3hl5xXSGRYjYdySc9twLaKnYGVXbLtjCGW8FBotl1rTAxLJQm4okoJ385Gd6pc1ty6AnhaHHJjCeLoYYSQCG1EyP9PRxnTihjmsE9g%3D%3D"
            },
            "barcode": {
                "id": "U2FsdGVkX19NfR0ANlhLM7Df9Ec+xqTh6aTbHakk/Gzeh9zTiuj8KUBLswVXkz0gdLVnn1ZtzjCv7oF/BSQTyJx0YSK+HIUG9RGD+9rVhiC7+4WkSKrgAZ+NeqQBIqcespt8WWygXjfkvbyXBSF7Lg==",
                "url": "https://dev.dl.voucherify.io/api/v1/assets/barcode/U2FsdGVkX19NfR0ANlhLM7Df9Ec%2BxqTh6aTbHakk%2FGzeh9zTiuj8KUBLswVXkz0gdLVnn1ZtzjCv7oF%2FBSQTyJx0YSK%2BHIUG9RGD%2B9rVhiC7%2B4WkSKrgAZ%2BNeqQBIqcespt8WWygXjfkvbyXBSF7Lg%3D%3D"
            }
        },
        "is_referral_code": false,
        "holder_id": "cust_lXisxEaEHYKTEVf1YnNS8AUh",
        "updated_at": "2020-05-24T13:41:16Z",
        "holder": {
            "id": "cust_lXisxEaEHYKTEVf1YnNS8AUh",
            "source_id": "[email protected]",
            "name": "Tom Loyalty",
            "email": "[email protected]",
            "metadata": {},
            "object": "customer"
        },
        "object": "voucher",
        "validation_rules_assignments": {
            "data": [],
            "object": "list",
            "total": 0,
            "data_ref": "data"
        }
    }
}
Language
Credentials
URL
Click Try It! to start a request and see the response here!