The Validation object

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

id
string

r_iMsIlXpjfQwMWFJPEPJFeJ4h

object
string

Type of the object represented by JSON. Value is redemption.

date
string, ISO 8601 date format

2016-11-16T14:14:31Z

tracking_id
string

A tracking identifier of a user that validated a voucher. Identifier generated during voucher validation.

track_122jQVpYAmwtcddM3oHhHh05

order
object

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 (for example, $100 is 10000).

"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"}
      }
    ]
  }

metadata
object

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"
}

customer
object

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"
}

valid
boolean

The result of the validation is either true or false.

 "valid": true

failure_code
string

Error code explaining reason for redemption failure if available (see the errors section for a list of keys).

reason
string

Informs about a reason for failed validation.

"reason": "order does not match validation rules",

applicable_to
object

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_to
object

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"
}

error
object

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": {}
}

reward
object

Read more in the reward object

{
  "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
  }
}