Redeem Voucher

curl --request POST \
  --url https://{cluster}.voucherify.io/v1/vouchers/{code}/redemption \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --header 'X-App-Id: <api-key>' \
  --header 'X-App-Token: <api-key>' \
  --data '
{
  "session": {
    "type": "LOCK",
    "key": "ssn_yQGMTeKBSw8OOuFPwlBEjzGy8d8VA9Ts",
    "ttl_unit": "HOURS",
    "ttl": 123
  },
  "customer": {
    "id": "cust_Vzck5i8U3OhcEUFY6MKhN9Rv"
  },
  "order": {
    "id": "<string>"
  },
  "metadata": {},
  "options": {
    "expand": [
      "category"
    ]
  }
}
'

{
  "id": "r_0c5e8a38730ccec0d5",
  "object": "redemption",
  "date": "2023-01-27T12:34:57.100Z",
  "customer_id": "cust_eWgXlBBiY6THFRJwX45Iakv4",
  "tracking_id": "track_9B0kB92+bJa8a+PegaWREw==",
  "metadata": null,
  "amount": 2000,
  "result": "SUCCESS",
  "order": {
    "id": "ord_S4BvUj64TlGqVZDOeud7z3rU",
    "source_id": null,
    "created_at": "2023-01-27T12:34:57.086Z",
    "updated_at": null,
    "status": "PAID",
    "amount": 6000,
    "discount_amount": 2000,
    "total_discount_amount": 2000,
    "total_amount": 4000,
    "applied_discount_amount": 2000,
    "total_applied_discount_amount": 2000,
    "items": [
      {
        "object": "order_item",
        "product_id": "prod_0a9f9ab4ab019a42d5",
        "quantity": 1,
        "amount": 3300,
        "price": 3000,
        "subtotal_amount": 3300
      },
      {
        "object": "order_item",
        "product_id": "prod_0a9f9aeddb019a42db",
        "quantity": 2,
        "amount": 3400,
        "price": 3000,
        "subtotal_amount": 3400
      }
    ],
    "metadata": {},
    "customer": {
      "id": "cust_eWgXlBBiY6THFRJwX45Iakv4",
      "object": "customer"
    },
    "customer_id": "cust_eWgXlBBiY6THFRJwX45Iakv4",
    "referrer_id": null,
    "object": "order",
    "redemptions": {
      "r_0c5e8a38730ccec0d5": {
        "date": "2023-01-27T12:34:57.100Z",
        "related_object_type": "voucher",
        "related_object_id": "v_UFAc7FTVO0HtJV2hWZls4O7eqHMyn62g",
        "related_object_parent_id": "camp_B2Gx83JsSbmvj05MOwxYbNm6"
      }
    }
  },
  "customer": {
    "id": "cust_eWgXlBBiY6THFRJwX45Iakv4",
    "name": "Bob Jones",
    "email": "bob.jones@email.com",
    "source_id": "36_bob",
    "metadata": {
      "age": 26,
      "favorite_brands": [
        "Nike",
        "Adidas",
        "Reebok"
      ],
      "accepts_marketing": false,
      "acquisition_channel": "Facebook"
    },
    "object": "customer"
  },
  "related_object_type": "voucher",
  "related_object_id": "v_UFAc7FTVO0HtJV2hWZls4O7eqHMyn62g",
  "voucher": {
    "id": "v_UFAc7FTVO0HtJV2hWZls4O7eqHMyn62g",
    "code": "CODE14",
    "campaign": "Gift Card Campaign",
    "campaign_id": "camp_B2Gx83JsSbmvj05MOwxYbNm6",
    "category": "Second",
    "category_id": "cat_0bb343dee3cdb5ec0c",
    "categories": [],
    "type": "GIFT_VOUCHER",
    "discount": null,
    "gift": {
      "amount": 2000,
      "balance": 0,
      "effect": null
    },
    "loyalty_card": null,
    "start_date": "2020-08-16T00:00:00.000Z",
    "expiration_date": null,
    "validity_timeframe": null,
    "validity_day_of_week": null,
    "active": true,
    "additional_info": "secret-code1",
    "metadata": {
      "region": "APAC",
      "season": "Fall"
    },
    "assets": {
      "qr": {
        "id": "U2FsdGVkX1+VibJ6VGxrSVw5qmdbPMP3aP8HfcngMxtQc9Bm649CK1dK36e8YR820Ct26IkvDemEDzV8ozhB3F2BpazbgvCmhAo2Gvmo2WtwBwPh2ISAPJiXQCHRjwmKiqogjqQaNKWLxwDIBUc2jQ==",
        "url": "{{internalVoucherifyURL}}"
      },
      "barcode": {
        "id": "U2FsdGVkX1/GVIi0p5fL5hxAY/ZBmuAU7nYYS03umjd30dwI5v5ZbpNc3Q5MiYbMuIOIT0H2fUTTwd//S4R9AB+60T/x4kSKu3lgfa9KgJmbyrzXm7Ggly06/qph4/asJaZVZIXEba4WJCeHqXCEgg==",
        "url": "{{internalVoucherifyURL}}"
      }
    },
    "is_referral_code": false,
    "created_at": "2022-09-23T11:05:42.164Z",
    "updated_at": "2023-01-27T12:34:57.102Z",
    "validation_rules_assignments": {
      "object": "list",
      "data_ref": "data",
      "data": [],
      "total": 0
    },
    "redemption": {
      "quantity": 18,
      "redeemed_quantity": 1,
      "redeemed_amount": 2000,
      "object": "list",
      "url": "/v1/vouchers/CODE14/redemptions?page=1&limit=10"
    },
    "publish": {
      "object": "list",
      "count": 0,
      "url": "/v1/vouchers/CODE14/publications?page=1&limit=10"
    },
    "object": "voucher",
    "applicable_to": {
      "data": [],
      "total": 0,
      "data_ref": "data",
      "object": "list"
    },
    "inapplicable_to": {
      "data": [],
      "total": 0,
      "data_ref": "data",
      "object": "list"
    }
  },
  "gift": {
    "amount": 2000
  }
}

Redeem Voucher

❗️ 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:

Field	Calculation	Description
amount	N/A	This field shows the order amount before applying any discount
total_amount	total_amount = amount - total_discount_amount	This field shows the order amount after applying all the discounts
discount_amount	discount_amount = previous_discount_amount + applied_discount_amount	This field sums up all order-level discounts applied to a patricular order
items_discount_amount	sum(items, i => i.discount_amount)	This field sums up all product-specific discounts applied to this order
total_discount_amount	total_discount_amount = discount_amount + items_discount_amount	This field sums up all order-level and all product-specific discounts applied to this order
applied_discount_amount	N/A	This field shows order-level discount applied in a particular request
items_applied_discount_amount	sum(items, i => i.applied_discount_amount)	This field sums up all product-specific discounts applied in a particular request
total_applied_discount_amount	total_applied_discount_amount = applied_discount_amount + items_applied_discount_amount	This field sums up all order-level and all product-specific discounts applied in a particular request

POST

vouchers

{code}

redemption

Redeem Voucher

curl --request POST \
  --url https://{cluster}.voucherify.io/v1/vouchers/{code}/redemption \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --header 'X-App-Id: <api-key>' \
  --header 'X-App-Token: <api-key>' \
  --data '
{
  "session": {
    "type": "LOCK",
    "key": "ssn_yQGMTeKBSw8OOuFPwlBEjzGy8d8VA9Ts",
    "ttl_unit": "HOURS",
    "ttl": 123
  },
  "customer": {
    "id": "cust_Vzck5i8U3OhcEUFY6MKhN9Rv"
  },
  "order": {
    "id": "<string>"
  },
  "metadata": {},
  "options": {
    "expand": [
      "category"
    ]
  }
}
'

{
  "id": "r_0c5e8a38730ccec0d5",
  "object": "redemption",
  "date": "2023-01-27T12:34:57.100Z",
  "customer_id": "cust_eWgXlBBiY6THFRJwX45Iakv4",
  "tracking_id": "track_9B0kB92+bJa8a+PegaWREw==",
  "metadata": null,
  "amount": 2000,
  "result": "SUCCESS",
  "order": {
    "id": "ord_S4BvUj64TlGqVZDOeud7z3rU",
    "source_id": null,
    "created_at": "2023-01-27T12:34:57.086Z",
    "updated_at": null,
    "status": "PAID",
    "amount": 6000,
    "discount_amount": 2000,
    "total_discount_amount": 2000,
    "total_amount": 4000,
    "applied_discount_amount": 2000,
    "total_applied_discount_amount": 2000,
    "items": [
      {
        "object": "order_item",
        "product_id": "prod_0a9f9ab4ab019a42d5",
        "quantity": 1,
        "amount": 3300,
        "price": 3000,
        "subtotal_amount": 3300
      },
      {
        "object": "order_item",
        "product_id": "prod_0a9f9aeddb019a42db",
        "quantity": 2,
        "amount": 3400,
        "price": 3000,
        "subtotal_amount": 3400
      }
    ],
    "metadata": {},
    "customer": {
      "id": "cust_eWgXlBBiY6THFRJwX45Iakv4",
      "object": "customer"
    },
    "customer_id": "cust_eWgXlBBiY6THFRJwX45Iakv4",
    "referrer_id": null,
    "object": "order",
    "redemptions": {
      "r_0c5e8a38730ccec0d5": {
        "date": "2023-01-27T12:34:57.100Z",
        "related_object_type": "voucher",
        "related_object_id": "v_UFAc7FTVO0HtJV2hWZls4O7eqHMyn62g",
        "related_object_parent_id": "camp_B2Gx83JsSbmvj05MOwxYbNm6"
      }
    }
  },
  "customer": {
    "id": "cust_eWgXlBBiY6THFRJwX45Iakv4",
    "name": "Bob Jones",
    "email": "bob.jones@email.com",
    "source_id": "36_bob",
    "metadata": {
      "age": 26,
      "favorite_brands": [
        "Nike",
        "Adidas",
        "Reebok"
      ],
      "accepts_marketing": false,
      "acquisition_channel": "Facebook"
    },
    "object": "customer"
  },
  "related_object_type": "voucher",
  "related_object_id": "v_UFAc7FTVO0HtJV2hWZls4O7eqHMyn62g",
  "voucher": {
    "id": "v_UFAc7FTVO0HtJV2hWZls4O7eqHMyn62g",
    "code": "CODE14",
    "campaign": "Gift Card Campaign",
    "campaign_id": "camp_B2Gx83JsSbmvj05MOwxYbNm6",
    "category": "Second",
    "category_id": "cat_0bb343dee3cdb5ec0c",
    "categories": [],
    "type": "GIFT_VOUCHER",
    "discount": null,
    "gift": {
      "amount": 2000,
      "balance": 0,
      "effect": null
    },
    "loyalty_card": null,
    "start_date": "2020-08-16T00:00:00.000Z",
    "expiration_date": null,
    "validity_timeframe": null,
    "validity_day_of_week": null,
    "active": true,
    "additional_info": "secret-code1",
    "metadata": {
      "region": "APAC",
      "season": "Fall"
    },
    "assets": {
      "qr": {
        "id": "U2FsdGVkX1+VibJ6VGxrSVw5qmdbPMP3aP8HfcngMxtQc9Bm649CK1dK36e8YR820Ct26IkvDemEDzV8ozhB3F2BpazbgvCmhAo2Gvmo2WtwBwPh2ISAPJiXQCHRjwmKiqogjqQaNKWLxwDIBUc2jQ==",
        "url": "{{internalVoucherifyURL}}"
      },
      "barcode": {
        "id": "U2FsdGVkX1/GVIi0p5fL5hxAY/ZBmuAU7nYYS03umjd30dwI5v5ZbpNc3Q5MiYbMuIOIT0H2fUTTwd//S4R9AB+60T/x4kSKu3lgfa9KgJmbyrzXm7Ggly06/qph4/asJaZVZIXEba4WJCeHqXCEgg==",
        "url": "{{internalVoucherifyURL}}"
      }
    },
    "is_referral_code": false,
    "created_at": "2022-09-23T11:05:42.164Z",
    "updated_at": "2023-01-27T12:34:57.102Z",
    "validation_rules_assignments": {
      "object": "list",
      "data_ref": "data",
      "data": [],
      "total": 0
    },
    "redemption": {
      "quantity": 18,
      "redeemed_quantity": 1,
      "redeemed_amount": 2000,
      "object": "list",
      "url": "/v1/vouchers/CODE14/redemptions?page=1&limit=10"
    },
    "publish": {
      "object": "list",
      "count": 0,
      "url": "/v1/vouchers/CODE14/publications?page=1&limit=10"
    },
    "object": "voucher",
    "applicable_to": {
      "data": [],
      "total": 0,
      "data_ref": "data",
      "object": "list"
    },
    "inapplicable_to": {
      "data": [],
      "total": 0,
      "data_ref": "data",
      "object": "list"
    }
  },
  "gift": {
    "amount": 2000
  }
}

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.

Path Parameters

code

string

required

A code that identifies the voucher.

Example:

"2CpRCE2c"

Query Parameters

tracking_id

string

A tracking identifier of a user that redeemed a voucher. Identifier generated during voucher validation based on your internal id (e.g., email, database ID). This is a hashed customer source ID. If you also pass a customer ID, the tracking ID must be the ID of a source of the customer object. Otherwise, if you do not pass a customer ID, the tracking you provide must either be a token, like the ones returned by voucher validation, or a string identifying customer, with the options described below. Although not all information is required, the extra info helps prevent fraud.

Body

application/json

Provide the redemption context in the request body.

Discount Code
Gift Card
Loyalty Card

Redeem a discount code.

session

Discount Code Session Lock · object

Schema model for session lock object. The session object is required to establish a session between multiple parallel validation and redemption requests. If you only send the type parameter in the request, then by default the session lock will be established for 7 days. Read more on establishing a validation session.

Show child attributes

customer

Customer ID · object

Customer's information.

Customer ID
Customer Source ID
Customer

Show child attributes

order

Order ID · object

Order information.

Order ID
Order Source ID
Orders Create Request Body

Show child attributes

metadata

object

A set of key/value pairs that you can send in the request body to check against vouchers requiring redemption metadata validation rules to be satisfied. The validation runs against rules that are defined through the Create Validation Rules endpoint or via the Dashboard; in the Advanced Rule Builder → Advanced → Redemption metadata satisfy or Basic Builder → Attributes match → REDEMPTION METADATA. Read more.

options

object

Configure parameters returned in the response.

Show child attributes

Response

Returns a redemption object if the redeem operation succeeded.

Redeem Voucher Response Body
Redeem Voucher Response Body
Redeem Voucher Response Body

Response body schema for POST v1/vouchers/{code}/redemption.

string

Unique redemption ID.

Example:

"r_0bc92f81a6801f9bca"

object

string

default:redemption

The type of the object represented by the JSON. This object stores information about the redemption.

date

string<date-time>

Timestamp in ISO 8601 format indicating when the redemption occured.

Example:

"2022-10-03T12:24:58.008Z"

customer_id

string

Unique customer ID of the redeeming customer.

Example:

"cust_i8t5Tt6eiKG5K79KQlJ0Vs64"

tracking_id

string

Hashed customer source ID.

Example:

"track_fxEMFiLowFHg=="

metadata

object

The metadata object stores all custom attributes in the form of key/value pairs assigned to the redemption.

result

enum<string>

Redemption result.

Available options:

SUCCESS,

FAILURE

order

Order object - Effect: Apply to order · object

Defines the details of the order that is related to the redemption.

Order object - Effect: Apply to order
Order object - Effect: Apply to items

Show child attributes

channel

object

Defines the details of the channel through which the redemption was issued.

Show child attributes

customer

object

Defines the customer that is related to the redemption.

Show child attributes

Defines the related object.

Related Object	Definition
voucher	Either a discount voucher, gift card, or loyalty card.

Available options:

voucher

Unique related object ID assigned by Voucherify, i.e. v_lfZi4rcEGe0sN9gmnj40bzwK2FH6QUno for a voucher.

voucher

Voucher Holder · object

Defines the details of the voucher being redeemed.

Show child attributes

Last modified on December 12, 2025

Rollback Stackable Redemptions Redeem Promotion

⌘I

Introduction

Endpoints

Events

Redeem Voucher

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

Authorizations

Path Parameters

Query Parameters

Body

Response