Redeem Promotion

curl --request POST \
  --url https://{cluster}.voucherify.io/v1/promotions/tiers/{promotionTierId}/redemption \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --header 'X-App-Id: <api-key>' \
  --header 'X-App-Token: <api-key>' \
  --data '
{
  "customer": {
    "source_id": "annie@lemon.com",
    "name": "Annie Lemon",
    "email": "annie@lemon.com"
  },
  "order": {
    "amount": 200000,
    "items": [
      {
        "source_id": "apple534",
        "product_id": "prod_anJ03RZZq74z4v",
        "related_object": "product",
        "quantity": 2,
        "price": 50000,
        "product": {
          "override": true,
          "name": "Apple iPhone 8",
          "metadata": {
            "shop": "citycenter",
            "category": "electronics"
          }
        },
        "metadata": {
          "series": "2022-783CV"
        }
      },
      {
        "sku_id": "sku_0KtP4rvwEECQ2U",
        "source_id": "apple534-ihd5",
        "related_object": "sku",
        "quantity": 1,
        "price": 100000,
        "sku": {
          "override": true,
          "sku": "Apple iPad 10 Silver 64GB",
          "metadata": {
            "category": "electronics"
          }
        }
      }
    ]
  }
}
'

{
  "id": "r_0ca2699201c03f121b",
  "object": "redemption",
  "date": "2023-03-21T05:49:00.807Z",
  "customer_id": "cust_SolpIN5N4oZbCnrxZ5NHrbVB",
  "tracking_id": "track_VAVW6qltuo1/z+G2GI2LPw==",
  "metadata": null,
  "result": "SUCCESS",
  "order": {
    "id": "ord_IVEF85NZCXmP4S1fGmImSTwH",
    "source_id": null,
    "created_at": "2023-03-21T05:49:00.772Z",
    "updated_at": null,
    "status": "PAID",
    "amount": 200000,
    "discount_amount": 80000,
    "total_discount_amount": 80000,
    "total_amount": 120000,
    "applied_discount_amount": 80000,
    "total_applied_discount_amount": 80000,
    "items": [
      {
        "object": "order_item",
        "source_id": "apple534",
        "related_object": "product",
        "product_id": "prod_anJ03RZZq74z4v",
        "quantity": 2,
        "amount": 100000,
        "price": 50000,
        "subtotal_amount": 100000,
        "product": {
          "id": "prod_0c5d6689b39320059b",
          "source_id": "prod_anJ03RZZq74z4v",
          "name": "Apple iPhone 8",
          "metadata": {
            "shop": "citycenter",
            "category": "electronics"
          }
        },
        "metadata": {
          "series": "2022-783CV"
        }
      },
      {
        "object": "order_item",
        "source_id": "apple534-ihd5",
        "related_object": "sku",
        "sku_id": "sku_0KtP4rvwEECQ2U",
        "quantity": 1,
        "amount": 100000,
        "price": 100000,
        "subtotal_amount": 100000,
        "sku": {
          "sku": "Apple iPad 10 Silver 64GB",
          "metadata": {
            "category": "electronics"
          }
        }
      }
    ],
    "metadata": {},
    "customer": {
      "id": "cust_SolpIN5N4oZbCnrxZ5NHrbVB",
      "object": "customer"
    },
    "customer_id": "cust_SolpIN5N4oZbCnrxZ5NHrbVB",
    "referrer_id": null,
    "object": "order",
    "redemptions": {
      "r_0ca2699201c03f121b": {
        "date": "2023-03-21T05:49:00.807Z",
        "related_object_type": "promotion_tier",
        "related_object_id": "promo_DE1N30D731Tg2F6NoMwNas2W",
        "related_object_parent_id": "camp_w7BUstntAm8jbIDjfM49volj"
      }
    }
  },
  "channel": {
    "channel_id": "e55f3aaa-b303-421a-b562-ca8529ed341d",
    "channel_type": "API"
  },
  "customer": {
    "id": "cust_SolpIN5N4oZbCnrxZ5NHrbVB",
    "name": "Annie Lemon",
    "email": "annie@lemon.com",
    "source_id": "annie@lemon.com",
    "metadata": {
      "age": 2
    },
    "object": "customer"
  },
  "related_object_type": "promotion_tier",
  "related_object_id": "promo_DE1N30D731Tg2F6NoMwNas2W",
  "voucher": null,
  "promotion_tier": {
    "id": "promo_DE1N30D731Tg2F6NoMwNas2W",
    "created_at": "2022-09-23T08:31:23.022Z",
    "updated_at": "2023-02-01T07:47:57.324Z",
    "name": "Percent Discount",
    "banner": "Get 40% off",
    "action": {
      "discount": {
        "type": "PERCENT",
        "percent_off": 40,
        "effect": "APPLY_TO_ORDER"
      }
    },
    "metadata": {},
    "hierarchy": 2,
    "campaign": {
      "id": "camp_w7BUstntAm8jbIDjfM49volj",
      "start_date": "2019-08-16T00:00:00.000Z",
      "expiration_date": null,
      "active": true,
      "object": "campaign"
    },
    "campaign_id": "camp_w7BUstntAm8jbIDjfM49volj",
    "active": true,
    "start_date": "2022-09-21T00:00:00.000Z",
    "validity_day_of_week": [
      1,
      2,
      3,
      4,
      5
    ],
    "summary": {
      "redemptions": {
        "total_redeemed": 5
      },
      "orders": {
        "total_amount": 616000,
        "total_discount_amount": 246400
      }
    },
    "object": "promotion_tier",
    "validation_rule_assignments": {
      "object": "list",
      "data_ref": "data",
      "data": [
        {
          "id": "asgm_z6MvMg2Zf2UABNWN",
          "rule_id": "val_q8qUBMOh5qIQ",
          "related_object_id": "promo_DE1N30D731Tg2F6NoMwNas2W",
          "related_object_type": "promotion_tier",
          "object": "validation_rules_assignment"
        }
      ],
      "total": 1
    },
    "category_id": null,
    "categories": []
  }
}

Redeem Promotion

❗️ Deprecated

This endpoint represents the deprecated version of the API responsible for promotion tier 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 promotion, you create a redemption object passing a context.

You can retrieve a list of active promotions through the Validate Promotions endpoint. That validation method will return a list of active promotion tiers identified by thier IDs.

📘 Redemption rollback

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

POST

promotions

tiers

{promotionTierId}

redemption

Redeem Promotion

curl --request POST \
  --url https://{cluster}.voucherify.io/v1/promotions/tiers/{promotionTierId}/redemption \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --header 'X-App-Id: <api-key>' \
  --header 'X-App-Token: <api-key>' \
  --data '
{
  "customer": {
    "source_id": "annie@lemon.com",
    "name": "Annie Lemon",
    "email": "annie@lemon.com"
  },
  "order": {
    "amount": 200000,
    "items": [
      {
        "source_id": "apple534",
        "product_id": "prod_anJ03RZZq74z4v",
        "related_object": "product",
        "quantity": 2,
        "price": 50000,
        "product": {
          "override": true,
          "name": "Apple iPhone 8",
          "metadata": {
            "shop": "citycenter",
            "category": "electronics"
          }
        },
        "metadata": {
          "series": "2022-783CV"
        }
      },
      {
        "sku_id": "sku_0KtP4rvwEECQ2U",
        "source_id": "apple534-ihd5",
        "related_object": "sku",
        "quantity": 1,
        "price": 100000,
        "sku": {
          "override": true,
          "sku": "Apple iPad 10 Silver 64GB",
          "metadata": {
            "category": "electronics"
          }
        }
      }
    ]
  }
}
'

{
  "id": "r_0ca2699201c03f121b",
  "object": "redemption",
  "date": "2023-03-21T05:49:00.807Z",
  "customer_id": "cust_SolpIN5N4oZbCnrxZ5NHrbVB",
  "tracking_id": "track_VAVW6qltuo1/z+G2GI2LPw==",
  "metadata": null,
  "result": "SUCCESS",
  "order": {
    "id": "ord_IVEF85NZCXmP4S1fGmImSTwH",
    "source_id": null,
    "created_at": "2023-03-21T05:49:00.772Z",
    "updated_at": null,
    "status": "PAID",
    "amount": 200000,
    "discount_amount": 80000,
    "total_discount_amount": 80000,
    "total_amount": 120000,
    "applied_discount_amount": 80000,
    "total_applied_discount_amount": 80000,
    "items": [
      {
        "object": "order_item",
        "source_id": "apple534",
        "related_object": "product",
        "product_id": "prod_anJ03RZZq74z4v",
        "quantity": 2,
        "amount": 100000,
        "price": 50000,
        "subtotal_amount": 100000,
        "product": {
          "id": "prod_0c5d6689b39320059b",
          "source_id": "prod_anJ03RZZq74z4v",
          "name": "Apple iPhone 8",
          "metadata": {
            "shop": "citycenter",
            "category": "electronics"
          }
        },
        "metadata": {
          "series": "2022-783CV"
        }
      },
      {
        "object": "order_item",
        "source_id": "apple534-ihd5",
        "related_object": "sku",
        "sku_id": "sku_0KtP4rvwEECQ2U",
        "quantity": 1,
        "amount": 100000,
        "price": 100000,
        "subtotal_amount": 100000,
        "sku": {
          "sku": "Apple iPad 10 Silver 64GB",
          "metadata": {
            "category": "electronics"
          }
        }
      }
    ],
    "metadata": {},
    "customer": {
      "id": "cust_SolpIN5N4oZbCnrxZ5NHrbVB",
      "object": "customer"
    },
    "customer_id": "cust_SolpIN5N4oZbCnrxZ5NHrbVB",
    "referrer_id": null,
    "object": "order",
    "redemptions": {
      "r_0ca2699201c03f121b": {
        "date": "2023-03-21T05:49:00.807Z",
        "related_object_type": "promotion_tier",
        "related_object_id": "promo_DE1N30D731Tg2F6NoMwNas2W",
        "related_object_parent_id": "camp_w7BUstntAm8jbIDjfM49volj"
      }
    }
  },
  "channel": {
    "channel_id": "e55f3aaa-b303-421a-b562-ca8529ed341d",
    "channel_type": "API"
  },
  "customer": {
    "id": "cust_SolpIN5N4oZbCnrxZ5NHrbVB",
    "name": "Annie Lemon",
    "email": "annie@lemon.com",
    "source_id": "annie@lemon.com",
    "metadata": {
      "age": 2
    },
    "object": "customer"
  },
  "related_object_type": "promotion_tier",
  "related_object_id": "promo_DE1N30D731Tg2F6NoMwNas2W",
  "voucher": null,
  "promotion_tier": {
    "id": "promo_DE1N30D731Tg2F6NoMwNas2W",
    "created_at": "2022-09-23T08:31:23.022Z",
    "updated_at": "2023-02-01T07:47:57.324Z",
    "name": "Percent Discount",
    "banner": "Get 40% off",
    "action": {
      "discount": {
        "type": "PERCENT",
        "percent_off": 40,
        "effect": "APPLY_TO_ORDER"
      }
    },
    "metadata": {},
    "hierarchy": 2,
    "campaign": {
      "id": "camp_w7BUstntAm8jbIDjfM49volj",
      "start_date": "2019-08-16T00:00:00.000Z",
      "expiration_date": null,
      "active": true,
      "object": "campaign"
    },
    "campaign_id": "camp_w7BUstntAm8jbIDjfM49volj",
    "active": true,
    "start_date": "2022-09-21T00:00:00.000Z",
    "validity_day_of_week": [
      1,
      2,
      3,
      4,
      5
    ],
    "summary": {
      "redemptions": {
        "total_redeemed": 5
      },
      "orders": {
        "total_amount": 616000,
        "total_discount_amount": 246400
      }
    },
    "object": "promotion_tier",
    "validation_rule_assignments": {
      "object": "list",
      "data_ref": "data",
      "data": [
        {
          "id": "asgm_z6MvMg2Zf2UABNWN",
          "rule_id": "val_q8qUBMOh5qIQ",
          "related_object_id": "promo_DE1N30D731Tg2F6NoMwNas2W",
          "related_object_type": "promotion_tier",
          "object": "validation_rules_assignment"
        }
      ],
      "total": 1
    },
    "category_id": null,
    "categories": []
  }
}

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

promotionTierId

string

required

ID of the promotion tier to be redeemed.

Example:

"promo_2EnAik6Jt7dKTOMkRTIgEjZH"

Body

application/json

Provide the redemption context in the request body.

Redeem a promotion tier.

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 promotion tiers 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.

Response

Returns a redemption object if the redeem operation succeeded.

This is an object representing a promotion tier 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.

Available options:

promotion_tier

Unique related object ID assigned by Voucherify, i.e. promo_NzjTc3ZXTe7md5SziK3uYtei for a promotion tier.

voucher

object

promotion_tier

Promotion Tier · object

Contains details of the promotion tier and the parent campaign.

Show child attributes

Last modified on December 12, 2025

Redeem Voucher Voucher Object

⌘I

Introduction

Endpoints

Events

Redeem Promotion

Authorizations

Path Parameters

Body

Response