Skip to main content
POST
/
v1
/
redemptions
curl --request POST \ --url https://{cluster}.voucherify.io/v1/redemptions \ --header 'Content-Type: application/json' \ --header 'X-App-Id: <api-key>' \ --header 'X-App-Token: <api-key>' \ --data ' { "redeemables": [ { "object": "voucher", "id": "BLCKFRDY" } ], "order": { "amount": 5500 } } '
{
  "redemptions": [
    {
      "id": "r_0bc92f81a6801f9bca",
      "object": "redemption",
      "date": "2021-12-22T10:13:06.487Z",
      "customer_id": "cust_i8t5Tt6eiKG5K79KQlJ0Vs64",
      "tracking_id": "<string>",
      "metadata": {},
      "redemption": "r_0c656311b5878a2031",
      "result": "SUCCESS",
      "status": "SUCCEEDED",
      "order": {
        "id": "<string>",
        "source_id": "<string>",
        "status": "CREATED",
        "amount": 123,
        "initial_amount": 123,
        "discount_amount": 123,
        "items_discount_amount": 123,
        "total_discount_amount": 123,
        "total_amount": 123,
        "applied_discount_amount": 123,
        "items_applied_discount_amount": 123,
        "total_applied_discount_amount": 123,
        "metadata": {},
        "object": "order",
        "created_at": "2021-12-22T10:13:06.487Z",
        "updated_at": "2021-12-22T10:14:45.316Z",
        "customer_id": "cust_7iUa6ICKyU6gH40dBU25kQU1",
        "referrer_id": "cust_nM4jqPiaXUvQdVSA6vTRUnix",
        "redemptions": {},
        "items": [
          {
            "object": "order_item",
            "id": "<string>",
            "sku_id": "<string>",
            "product_id": "<string>",
            "related_object": "product",
            "source_id": "<string>",
            "quantity": 123,
            "discount_quantity": 123,
            "initial_quantity": 123,
            "amount": 123,
            "discount_amount": 123,
            "applied_discount_amount": 123,
            "applied_discount_quantity": 123,
            "applied_quantity": 123,
            "applied_quantity_amount": 123,
            "initial_amount": 123,
            "price": 123,
            "subtotal_amount": 123,
            "product": {
              "id": "<string>",
              "source_id": "<string>",
              "override": true,
              "name": "<string>",
              "metadata": {},
              "price": 123
            },
            "sku": {
              "id": "<string>",
              "source_id": "<string>",
              "override": true,
              "sku": "<string>",
              "price": 123,
              "metadata": {}
            },
            "metadata": {},
            "application_details": [
              {
                "source_index": 1,
                "source_applied_quantity": -2,
                "source_applied_quantity_amount": -1,
                "target_index": 123,
                "target_applied_quantity": 123,
                "target_applied_quantity_amount": 123,
                "target_applied_discount_amount": 123
              }
            ]
          }
        ]
      },
      "channel": {
        "channel_id": "user_g24UoRO3Caxu7FCT4n5tpYEa3zUG0FrH",
        "channel_type": "USER"
      },
      "customer": {
        "id": "<string>",
        "name": "<string>",
        "email": "<string>",
        "source_id": "<string>",
        "metadata": {},
        "object": "customer"
      },
      "related_object_type": "voucher",
      "related_object_id": "<string>",
      "amount": 10000,
      "session": {
        "key": "<string>"
      },
      "related_redemptions": {
        "rollbacks": [
          {
            "id": "rr_0bc92f81a6801f9bca",
            "date": "2021-12-22T10:13:06.487Z",
            "rollback_order_mode": "WITH_ORDER"
          }
        ],
        "redemptions": [
          {
            "id": "r_0bc92f81a6801f9bca",
            "date": "2021-12-22T10:13:06.487Z"
          }
        ]
      },
      "failure_code": "customer_rules_violated",
      "failure_message": "<string>",
      "promotion_tier": {
        "id": "promo_63fYCt81Aw0h7lzyRkrGZh9p",
        "created_at": "2021-12-15T11:34:01.333Z",
        "updated_at": "2022-02-09T09:20:05.603Z",
        "name": "<string>",
        "banner": "<string>",
        "action": {
          "discount": {
            "type": "AMOUNT",
            "amount_off": 123,
            "amount_off_formula": "<string>",
            "aggregated_amount_limit": 123,
            "effect": "APPLY_TO_ORDER",
            "is_dynamic": true
          }
        },
        "metadata": {},
        "hierarchy": 123,
        "promotion_id": "<string>",
        "campaign": {
          "id": "<string>",
          "start_date": "2022-09-22T00:00:00.000Z",
          "expiration_date": "2022-09-30T00:00:00.000Z",
          "validity_timeframe": {
            "duration": "PT1H",
            "interval": "P2D"
          },
          "validity_day_of_week": [
            0
          ],
          "validity_hours": {
            "daily": [
              {
                "start_time": "12:00",
                "days_of_week": [
                  0
                ],
                "expiration_time": "14:00"
              }
            ]
          },
          "active": true,
          "category_id": "cat_0b688929a2476386a6",
          "object": "campaign"
        },
        "campaign_id": "<string>",
        "active": true,
        "start_date": "2022-09-23T00:00:00.000Z",
        "expiration_date": "2022-09-26T00:00:00.000Z",
        "validity_timeframe": {
          "duration": "PT1H",
          "interval": "P2D"
        },
        "validity_day_of_week": [
          0
        ],
        "validity_hours": {
          "daily": [
            {
              "start_time": "12:00",
              "days_of_week": [
                0
              ],
              "expiration_time": "14:00"
            }
          ]
        },
        "summary": {
          "redemptions": {
            "total_redeemed": 123
          },
          "orders": {
            "total_amount": 123,
            "total_discount_amount": 123
          }
        },
        "object": "promotion_tier",
        "category_id": "cat_0c9da30e7116ba6bba",
        "categories": [
          {
            "id": "<string>",
            "name": "<string>",
            "hierarchy": 1,
            "object": "category",
            "created_at": "2022-07-14T10:45:13.156Z",
            "updated_at": "2022-08-16T10:52:08.094Z"
          }
        ]
      },
      "gift": {
        "amount": 123
      },
      "loyalty_card": {
        "points": 123
      },
      "voucher": {
        "id": "v_mkZN9v7vjYUadXnHrMza8W5c34fE5KiV",
        "code": "WVPblOYX",
        "campaign": "Gift Card Campaign",
        "campaign_id": "camp_FNYR4jhqZBM9xTptxDGgeNBV",
        "category": "<string>",
        "category_id": "cat_0bb343dee3cdb5ec0c",
        "type": "GIFT_VOUCHER",
        "discount": {
          "type": "AMOUNT",
          "amount_off": 123,
          "amount_off_formula": "<string>",
          "aggregated_amount_limit": 123,
          "effect": "APPLY_TO_ORDER",
          "is_dynamic": true
        },
        "gift": {
          "amount": 10000,
          "subtracted_amount": 123,
          "balance": 500,
          "effect": "APPLY_TO_ORDER"
        },
        "loyalty_card": {
          "points": 7000,
          "balance": 6970,
          "next_expiration_date": "2023-05-30",
          "next_expiration_points": 123,
          "pending_points": 123,
          "expired_points": 123,
          "subtracted_points": 123
        },
        "start_date": "2021-12-01T00:00:00.000Z",
        "expiration_date": "2021-12-31T00:00:00.000Z",
        "validity_timeframe": {
          "duration": "PT1H",
          "interval": "P2D"
        },
        "validity_day_of_week": [
          0
        ],
        "validity_hours": {
          "daily": [
            {
              "start_time": "12:00",
              "days_of_week": [
                0
              ],
              "expiration_time": "14:00"
            }
          ]
        },
        "active": true,
        "additional_info": "<string>",
        "metadata": {},
        "assets": {
          "qr": {
            "id": "U2FsdGVkX19ucFhvVmBVpVYG5KoswTsjSIaqoKg5L9ie4BK+t4pp7U7oFzjGJzj9q/bmuMOj9mEFiVKDMIkSaruKedMvHbKoPX5Sg+BaZk5QwXMf8k/OzSlOEVybpwSq+AiqPoNtjeuqtIgkDyvT6Q==",
            "url": "https://dev.dl.voucherify.io/api/v1/assets/qr/U2FsdGVkX19ucFhvVmBVpVYG5KoswTsjSIaqoKg5L9ie4BK%2Bt4pp7U7oFzjGJzj9q%2FbmuMOj9mEFiVKDMIkSaruKedMvHbKoPX5Sg%2BBaZk5QwXMf8k%2FOzSlOEVybpwSq%2BAiqPoNtjeuqtIgkDyvT6Q%3D%3D"
          },
          "barcode": {
            "id": "U2FsdGVkX19eJhGfWwUrH9+tulBkON+AnMktic+N6CVWzZ9+fHVxuVx22WakrzxiWXy0skuvvEHSeZIw9HlgyIJ+kJ1iPdUKpyENuNYJKzoZlO0mmTf6WQM6/pFs61apEn9SJx32ttCF6d3oxKISQQ==",
            "url": "https://dev.dl.voucherify.io/api/v1/assets/barcode/U2FsdGVkX19eJhGfWwUrH9%2BtulBkON%2BAnMktic%2BN6CVWzZ9%2BfHVxuVx22WakrzxiWXy0skuvvEHSeZIw9HlgyIJ%2BkJ1iPdUKpyENuNYJKzoZlO0mmTf6WQM6%2FpFs61apEn9SJx32ttCF6d3oxKISQQ%3D%3D"
          }
        },
        "is_referral_code": true,
        "created_at": "2021-12-22T10:13:06.487Z",
        "updated_at": "2021-12-22T10:14:45.316Z",
        "holder_id": "cust_eWgXlBBiY6THFRJwX45Iakv4",
        "referrer_id": "cust_Vzck5i8U3OhcEUFY6MKhN9Rv",
        "object": "voucher",
        "publish": {
          "object": "list",
          "count": 0,
          "url": "/v1/vouchers/WVPblOYX/publications?page=1&limit=10"
        },
        "redemption": {
          "quantity": 123,
          "redeemed_quantity": 1,
          "redeemed_points": 100000,
          "object": "list",
          "url": "/v1/vouchers/WVPblOYX/redemptions?page=1&limit=10"
        },
        "categories": [
          {
            "id": "<string>",
            "name": "<string>",
            "hierarchy": 1,
            "object": "category",
            "created_at": "2022-07-14T10:45:13.156Z",
            "updated_at": "2022-08-16T10:52:08.094Z",
            "stacking_rules_type": "JOINT"
          }
        ],
        "holder": {
          "id": "<string>",
          "name": "<string>",
          "email": "<string>",
          "source_id": "<string>",
          "metadata": {},
          "object": "customer"
        }
      }
    }
  ],
  "order": {
    "id": "<string>",
    "source_id": "<string>",
    "status": "CREATED",
    "amount": 123,
    "initial_amount": 123,
    "discount_amount": 123,
    "items_discount_amount": 123,
    "total_discount_amount": 123,
    "total_amount": 123,
    "applied_discount_amount": 123,
    "items_applied_discount_amount": 123,
    "total_applied_discount_amount": 123,
    "metadata": {},
    "object": "order",
    "created_at": "2021-12-22T10:13:06.487Z",
    "updated_at": "2021-12-22T10:14:45.316Z",
    "customer_id": "cust_7iUa6ICKyU6gH40dBU25kQU1",
    "referrer_id": "cust_nM4jqPiaXUvQdVSA6vTRUnix",
    "redemptions": {},
    "items": [
      {
        "object": "order_item",
        "id": "<string>",
        "sku_id": "<string>",
        "product_id": "<string>",
        "related_object": "product",
        "source_id": "<string>",
        "quantity": 123,
        "discount_quantity": 123,
        "initial_quantity": 123,
        "amount": 123,
        "discount_amount": 123,
        "applied_discount_amount": 123,
        "applied_discount_quantity": 123,
        "applied_quantity": 123,
        "applied_quantity_amount": 123,
        "initial_amount": 123,
        "price": 123,
        "subtotal_amount": 123,
        "product": {
          "id": "<string>",
          "source_id": "<string>",
          "override": true,
          "name": "<string>",
          "metadata": {},
          "price": 123
        },
        "sku": {
          "id": "<string>",
          "source_id": "<string>",
          "override": true,
          "sku": "<string>",
          "price": 123,
          "metadata": {}
        },
        "metadata": {},
        "application_details": [
          {
            "source_index": 1,
            "source_applied_quantity": -2,
            "source_applied_quantity_amount": -1,
            "target_index": 123,
            "target_applied_quantity": 123,
            "target_applied_quantity_amount": 123,
            "target_applied_discount_amount": 123
          }
        ]
      }
    ]
  },
  "inapplicable_redeemables": [
    {
      "status": "INAPPLICABLE",
      "id": "<string>",
      "object": "voucher",
      "result": {
        "details": {
          "message": "<string>",
          "key": "<string>"
        }
      },
      "metadata": {},
      "categories": [
        {
          "id": "<string>",
          "name": "<string>",
          "hierarchy": 1,
          "object": "category",
          "created_at": "2022-07-14T10:45:13.156Z",
          "updated_at": "2022-08-16T10:52:08.094Z",
          "stacking_rules_type": "JOINT"
        }
      ],
      "campaign_name": "<string>",
      "campaign_id": "camp_pqZjuhG6Mgtp4GD0zD7b8hA3",
      "name": "<string>"
    }
  ],
  "skipped_redeemables": [
    {
      "status": "SKIPPED",
      "id": "<string>",
      "object": "voucher",
      "result": {
        "details": {
          "key": "applicable_redeemables_limit_exceeded",
          "message": "Applicable redeemables limit exceeded"
        }
      },
      "metadata": {},
      "categories": [
        {
          "id": "<string>",
          "name": "<string>",
          "hierarchy": 1,
          "object": "category",
          "created_at": "2022-07-14T10:45:13.156Z",
          "updated_at": "2022-08-16T10:52:08.094Z",
          "stacking_rules_type": "JOINT"
        }
      ],
      "campaign_name": "<string>",
      "campaign_id": "camp_pqZjuhG6Mgtp4GD0zD7b8hA3",
      "name": "<string>"
    }
  ]
}

Authorizations

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

Body

application/json

Response body schema for POST v1/redemptions.

​
redeemables
(Voucher Redeemable · object | Promotion Tier Redeemable · object | Promotion Stack Redeemable · object | Gift Card Redeemable · object | Loyalty Card Redeemable · object)[]
required

An array of redeemables. You can combine voucher(s) and promotion_tier(s). Alternatively, send one uniquepromotion_stack in the array. Each unique redeemable can be sent in one request only once.

Required array length: 1 - 30 elements

Validate or redeem a discount code.

​
options
object

Configure parameters returned in the response.

​
order
Order · object

Order information.

​
customer
Customer · object

Customer's information.

​
session
Session · 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.

​
tracking_id
string

Is correspondent to Customer's source_id

​
metadata
object

A set of key/value pairs that you can attach to a redemption object. It can be useful for storing additional information about the redemption in a structured format.

Response

200 - application/json

Depending on your project settings: all redeemables must be valid or just one must be valid to result as valid redemption. Read more in the Stacking Rule Documentation.

Response body schema for POST v1/redemptions.

​
redemptions
Redemption · object[]
​
parent_redemption
Redemption · object

This is an object representing a redemption for POST v1/redemptions and POST /client/v1/redemptions.

​
order
Order Calculated No Customer Data · object

Contains the order details associated with the redemption.

​
inapplicable_redeemables
Inapplicable Redeemable · object[]

Lists validation results of each inapplicable redeemable.

​
skipped_redeemables
Skipped Redeemable · object[]

Lists validation results of each redeemable. If a redeemable can be applied, the API returns "status": "APPLICABLE".

Last modified on April 2, 2026