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

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

Path Parameters

code

string

required

Example:

Query Parameters

tracking_id

string

Body

application/json

Discount Code
Gift Card
Loyalty Card

session

object

Show child attributes

customer

object

Customer ID
Customer Source ID
Customer

Show child attributes

order

object

Order ID
Order Source ID
Order Customer And Referrer Ids Objects

Show child attributes

metadata

object

options

object

Show child attributes

Response

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

string

Example:

object

string

default:redemption

date

string<date-time>

Example:

customer_id

string

Example:

tracking_id

string

Example:

metadata

object

result

enum<string>

Available options:

SUCCESS,

FAILURE

order

object

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

Show child attributes

channel

object

Show child attributes

customer

object

Show child attributes

Available options:

voucher

voucher

object

Show child attributes

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