Data model description
Redemption is the key operation in the voucher and promotion tier lifecycle. A customer can redeem a voucher or promotion tier once or multiple times depending on selected limit (quantity
). Each redemption is recorded in voucher/promotion's history (redemption_entries
). There is also an option to cancel a redemption. We call such operation a redemption rollback.
Attributes | Description | Example |
---|---|---|
idstring | r_iMsIlXpjfQwMWFJPEPJFeJ4h | |
objectstring | Type of the object represented by JSON. Value is redemption . | |
datestring , ISO 8601 date format | 2016-11-16T14:14:31Z | |
tracking_idstring | A tracking identifier of a user that validated a voucher. Identifier generated during voucher validation. | track_122jQVpYAmwtcddM3oHhHh05 |
orderobject | The purchase of previously defined products by end customers is handled through the creation of order objects. Order object is used to evaluate redemption rules based on products and total order volume. Child attributes: - amount ( integer ) - A positive integer representing total order value. Value is multiplied by 100 to precisely represent 2 decimal places. For example, $100 discount is written as 10000.- total_discount_amount ( integer ) - A positive integer representing total discount value. Value is multiplied by 100 to precisely represent 2 decimal places (for example, $100 is 10000).- total_amount - ( integer ) A positive integer representing total order value after applying the discount. Value is multiplied by 100 to precisely represent 2 decimal places (for example, $100 is 10000).- items* ( array ) - A list of Order Items that have been applied to the order. | "order": { "amount": 10000, "items": [ { "product_id": "prod_Bi7sRr3kwvxH2I", "sku_id": null, "quantity": 1 } ] } "order" : { "amount" : 10200, "items": [ { "sku_id": "sku_08c5d46d5b5d787ab6", "quantity": 1, "metadata":{"category":"SALE"} } ] } "order" : { "amount" : 10200, "items": [ { "sku_id": "sku_08c5d46d5b5d787ab6", "quantity": 1, "metadata":{"category":"SALE"} } ] } |
metadataobject | A set of key/value pairs that you can attach to a validation object. It can be useful for storing additional information about the validation in a structured format. | "metadata": { "test": true, "locale": "pl-en" } |
customerobject | If exists, object of the customer validating the code. See The customer object | "customer": { "object": "customer", "id": "cust_PqojQVpYAmwtcddM3oGfRh05", "source_id": "[email protected]", "name": "Joe Doa" } |
validboolean | The result of the validation is either true or false . | "valid": true |
failure_codestring | Error code explaining reason for redemption failure if available (see the errors section for a list of keys ). | |
reasonstring | Informs about a reason for failed validation. | "reason": "order does not match validation rules", |
applicable_toobject | If validation rules specify discounted products, this object in response body lists cart items to which the discount can be applied to. Child attributes: - data array - object string - total number - data_ref string | "applicable_to": { "data": [ { "object": "sku", "id": "sku_08c5d46d5b5d787ab6", "source_id": "sku_08c5d46d5b5d787ab6" } ], "object": "list", "total": 1 } |
inapplicable_toobject | If validation rules specify items that are excluded from applying the discount, they are listed in this object in the response body. Child attributes: - data array - object string - total number - data_ref string | "inapplicable_to": { "data": [ { "object": "product", "id": "prod_08f19eba8d0715dde0", "source_id": "pen-2021track54", "strict": false } ], "total": 1, "data_ref": "data", "object": "list" } |
errorobject | If validation ends with failure, the error object contains details explaining the reason of failure. This object can return native error definitions with the following keys: voucher_not_active, not_found, voucher_expired, voucher_disabled. On the other hand, if campaign administrator defines custom error messages, in this object Voucherify returns error message. In the next column, you can find samples of two responses for both cases - custom error message and native validation error code. | Built-in error:{ "code": "fUtuR3", "valid": false, "reason": "voucher not active yet", "tracking_id": "track_uP6K80aZLxpKYZWvVIVW4A==", "error": { "code": 400, "key": "voucher_not_active", "message": "voucher not active yet", "details": "fUtuR3", "request_id": "v-0942d7e51611c40a21" } } Custom error message: { "valid": false, "reason": "order does not match validation rules", "error": { "message": "Must be L size product!" }, "code": "TEST_11111111", "metadata": {} } |
rewardobject | Read more in the reward object | |
sessionobject | Read more in Validation Session | "session": { "key": "ssn_yQGMTeKBSw8OOuFPwlBEjzGy8d8VA9Ts", "type": "LOCK", "ttl": 7, "ttl_unit": "DAYS" } |
{
"code": "SALE25",
"discount": {
"type": "PERCENT",
"percent_off": 25.0
},
"tracking_id": "track_BX9Qc8nH77gbgQAq1OYBlx2yJcYhWIyyfIQXD6s23u0=",
"metadata": {},
"order": {
"amount": 10200,
"total_discount_amount": 22500,
"total_amount": 0,
"items": [
{
"product_id": "prod_08c5d46d008a4f3e08",
"sku_id": "sku_08c5d46d5b5d787ab6",
"quantity": 1,
"price": 90000,
"amount": 90000,
"discount_amount": 22500,
"product": {
"id": "prod_08c5d46d008a4f3e08",
"name": "Headphones",
"price": 60000,
"metadata": {}
},
"sku": {
"id": "sku_08c5d46d5b5d787ab6",
"sku": "Headphones Limited Edition",
"price": 90000,
"metadata": {
"category": "SALE"
}
}
}
]
},
"valid": true,
"applicable_to": {
"data": [
{
"object": "sku",
"id": "sku_08c5d46d5b5d787ab6",
"source_id": "sku_08c5d46d5b5d787ab6"
}
],
"object": "list",
"total": 1
}
}