1. Validating a voucher code

Customers enjoy checking their vouchers and rewards, so to ensure a smooth redemption process, you can utilize the Validate a Voucher API request before starting actual redemption. This request confirms the validity of the voucher for a specific transaction without blocking it or altering its status.

2. Redeeming a voucher code

Depending on your store or transaction platform, you can choose to redeem a voucher in a single or a double step, applying the confirmation upon payment. Please see both examples, and when in doubt reach out to the Vouchery team.

Take a closer look at the detailed process for creating a redemption request and determining which transaction information to include:

Single-step redemption

With a Create a Redemption request, redeeming a voucher is a straightforward process. All you need to do is provide the voucher code, a unique transaction ID to identify the transaction in your system, and the total cost of the transaction. Vouchery will then verify the code and any campaign limitations associated with the voucher. If the redemption is successful, you will receive detailed information.

In case of errors, please consult the Errors page and Rejected Redemptions Messages for guidance.

Single-step redemption is ideal for systems that do not have integrated discount verification, such as non-internet-enabled POS systems or cash payments. However, we recommend that you use the two-step voucher redemption process for enhanced security, which we will cover next. Additionally, we have included instructions below on how to include product items in your voucher redemption.

🚧

Each redemption is confirmed

When redeeming a voucher code in a single step, has to be set to "confirmed": true, meaning, we will consider it as fully redeemed (unless the redemption is cancelled).

Simple redemption:

curl --request POST \
     --url https://admin.sandbox.vouchery.app/api/v2.1/vouchers/STARBUCKS_PROMO-DPJ6YD33HT/redemptions \
     --header 'Authorization: {paste here API key}' \
     --header 'accept: application/json' \
     --header 'content-type: application/json' \
     --data '
{
  "confirmed": true,
  "customer_identifier": "12345678",
  "total_transaction_cost": 135,
  "transaction_id": "oiuztfdcvb"
}
'

Redemption with Product Items, their categories, and a shipping cost:

curl --request POST \
     --url https://admin.sandbox.vouchery.app/api/v2.1/vouchers/STARBUCKS_PROMO-XFMXNDJW7Y/redemptions \
     --header 'Authorization: {paste here API key}' \
     --header 'accept: application/json' \
     --header 'content-type: application/json' \
     --data @- <<EOF
{
  "additional_categories": {
    "Platform": [
      "iOS"
    ]
  },
  "confirmed": true,
  "product_items": [
    {
      "categories": {
        "Brand": [
          "Levi's"
        ],
        "Sale": [
          "full price"
        ]
      },
      "name": "Shorts",
      "price": 19.9,
      "product_identifier": "0987ztgf3eghdjkx",
      "quantity": 1
    },
    {
      "categories": {
        "Brand": [
          "Levi's"
        ],
        "Sale": [
          "discounted"
        ]
      },
      "name": "T-shirt",
      "price": 9.9,
      "product_identifier": "9876trdfghjms",
      "quantity": 1
    }
  ],
  "customer_identifier": "12345678",
  "total_transaction_cost": 29.8,
  "transaction_id": "oiuztfdcvbhgf",
  "shipping_cost": 4.9
}
EOF

Double-step redemption

Step 1: Creating the redemption

Double-step redemption also uses a Create a Redemption request. At this stage, a redemption is initiated by the customer to complete the transaction, even though it has not been finalized yet. In order to initiate the redemption process, please make sure to indicate "confirmed": false. This indicates that you will confirm the redemption during the second step.

Here's an example of the request:

curl --request POST \
     --url https://admin.sandbox.vouchery.app/api/v2.1/vouchers/STARBUCKS_PROMO-XFMXNDJW7Y/redemptions \
     --header 'Authorization: ' \
     --header 'accept: application/json' \
     --header 'content-type: application/json' \
     --data @- <<EOF
{
  "additional_categories": {
    "Platform": [
      "iOS"
    ]
  },
  "confirmed": false,
  "product_items": [
    {
      "categories": {
        "Brand": [
          "Levi's"
        ],
        "Sale": [
          "full price"
        ]
      },
      "name": "Shorts",
      "price": 19.9,
      "product_identifier": "0987ztgf3eghdjkx",
      "quantity": 1
    },
    {
      "categories": {
        "Brand": [
          "Levi's"
        ],
        "Sale": [
          "discounted"
        ]
      },
      "name": "T-shirt",
      "price": 9.9,
      "product_identifier": "9876trdfghjms",
      "quantity": 1
    }
  ],
  "customer_identifier": "12345678",
  "total_transaction_cost": 29.8,
  "transaction_id": "oiuztfdcvbhgf",
  "shipping_cost": 4.9
}
EOF

After this step, the voucher will not yet be fully marked as redeemed. The redemption will be 'reserved' however, for a particular period of time, based on the TTL settings, set in Project Settings in the UI.

Step 2: Confirming the redemption

When the Customer pays for the purchase and the transaction is finalized, you'll have to mark the Redemption as 'confirmed' with a Confirm a Redemption API request to complete the voucher redemption. You can Confirm the Redemption using the same Transaction ID from the Create a Redemption request, or using the Redemption ID, from the response you've received in the Create a Redemption request.

curl --request PUT \
     --url 'https://admin.sandbox.vouchery.app/api/v2.1/redemptions/confirm?transaction_id=oiuztfdcvbhgf' \
     --header 'Authorization: <<apiKey>>' \
     --header 'accept: application/json' \
     --header 'content-type: application/json' \
     --data '{"confirmed":true}'

3. Canceling the Redemption

If the purchase transaction is canceled or the order is returned, you have the option to cancel the voucher redemption associated with it, using the Cancel Redemption request. This will release the voucher code and any associated limits, such as the number of allowed redemptions.