The voucher object

Data model description

Vouchers are essential resources in Voucherify. Every voucher has a unique code that a customer needs to know in order to redeem. Voucherify provides 2 types of vouchers - discount vouchers and gift vouchers. They are also used to represent referral codes.

Discount

You can choose one of three types of discounts:

amount (e.g. $10 off),
percent (e.g. 20% off),
unit (e.g. 2 piano lessons).

Gift vouchers

They are like pre-paid gift cards. Redeemable once e.g. a fixed-price voucher for 3 hours golf course or redeemable multiple times against any of your product or service given a positive balance.

You can group vouchers in campaigns and categories. Depending on your strategy vouchers can be valid only once or multiple times. Marketers and developers can activate vouchers at any time. Voucher's lifetime is either limited or unlimited. Vouchers include a detailed history of their redemptions.

Attributes	Description	Example
code `string`	A code that identifies the voucher.
object `string`	Type of the object represented by JSON. Value is `voucher`.
type `string`	Voucher's type.	`DISCOUNT_VOUCHER` or `GIFT_VOUCHER` (see above)
campaign `string`	The campaign name this voucher belongs to.
category `string`	The category this voucher belongs to.
discount `object`	This object represents discount parameters. Present only if type is `DISCOUNT_VOUCHER`. Child attributes: - type (`string`) - Type of the discount - `AMOUNT`, `PERCENT` or `UNIT`. - percent_off (`float`, optional) - A percentage that will be taken off the subtotal of any amount to pay. For example, a discount with percent_off of 50 will make a $100 bill $50 instead. You can also cap the maximum amount to be discounted with `amount_limit`. - amount_off (`integer`, optional) - An amount that will be taken off the subtotal of a price. Value is multiplied by 100 to precisely represent 2 decimal places. For example, $10 discount is written as 1000. - unit_off (`float`, optional) - Number of units that will be taken off the subtotal of any bill to pay. For example, 1 hour discount for booking a football court. - unit_type (`string`, optional) - Type of unit discount (e.g. time, items). - effect (`string`, optional) effect defines how the discount is applied to customer's order: 1. specific for unit discount type: ADD_MISSING_ITEMS (default option) - free item units will be added to the customer's order in a number that depends on how many units the customer already has in the order. For example, if a customer has one item in the cart and the discount gives one free unit, it won't be added to the cart, instead, the discount will be applied to the item unit that is already in the order. The sum of item units in the order will always match the number defined in the unit_off. ADD_NEW_ITEMS - free item units in the number defined by unit_off will be added to the customer's order. For example, if a customer has two item units in the cart and the discount gives one free unit, it will be added to the cart and discounted regardless of the remaining two items that won't be discounted. ADD_MANY_ITEMS - you can add multiple item types and customize each one with each of the two above discount effects. If you choose this effect, then an additional units array is required. - units - Array of objects defining items to be offered for free. Each object can have the following parameters: - unit_off (`integer`) - number of units to subtract from the subtotal. - unit_type (`string`) - The product deemed as free, chosen from product inventory (e.g. time, items) - effect (`string`, either `ADD_NEW_ITEMS` or `ADD_MISSING_ITEMS`) - defines how the unit is added to the customer's order. 2. available for percent type APPLY_TO_ORDER - the discount is applied to the total order amount. APPLY_TO_ITEMS - discount is applied to particular items defined using validation rules. 3. available for amount type: APPLY_TO_ORDER APPLY_TO_ITEMS APPLY_TO_ITEMS_PROPORTIONALLY - the discount is divided proportionally to items amount (applied only to particular items defined by validation rules). APPLY_TO_ITEMS_PROPORTIONALLY_BY_QUANTITY - the discount is divided proportionally to items quantity (applied only to particular items defined by validation rules). Read more on Discount Effects.	`"discount": { "type": "PERCENT", "percent_off": 10, "amount_limit": 10000 }` `"discount": { "type": "AMOUNT", "amount_off": 1000 }` `"discount": { "type": "UNIT", "unit_off": 1.0, "unit_type": "prod_3ttSkdxGuAfcv3", "effect": "ADD_NEW_ITEMS" }` `"discount": { "type": "UNIT", "unit_off": 1.0, "unit_type": "prod_3ttSkdxGuAfcv3", "effect": "ADD_MISSING_ITEMS" }` `"discount": { "type": "AMOUNT", "amount_off": 1000, "effect": "APPLY_TO_ITEMS" }` `{ "type": "UNIT", "effect": "ADD_MANY_ITEMS", "units": [ { "unit_off": 2, "unit_type": "prod_0a65b3ff8592d7a5b5", "effect": "ADD_MISSING_ITEMS" }, { "unit_off": 3, "unit_type": "prod_0a493557e21c5dbae9", "effect": "ADD_NEW_ITEMS" } ] }`
gift `object`	This object represents gift parameters. Present only if type is `GIFT_VOUCHER`. Child attributes: - amount (`integer`, required) - Total voucher income. Value is multiplied by 100 to precisely represent 2 decimal places. For example, $100 amount is written as 10000. - balance (`integer`) - Funds that are available to be used. Value is multiplied by 100 to precisely represent 2 decimal places. For example, $100 amount is written as 10000.	`"gift": { "amount": 10000, "balance": 10000 }`
loyalty_card	This object represents loyalty parameters. Present only if type is `LOYALTY_CARD`. - points (`integer`) - Total number of points accrued over the lifetime of the loyalty card. - balance (`integer`) - Remaining balance that customer is able to spend. - next_expiration_date (`string`) - `YYYY-MM-DD`, when the next set of points are due to expire - next_expiration_points - (`integer`) - number of points that are next in line to expire	"loyalty_card": { "points": 1100, "balance": 970, "next_expiration_date": "2022-09-30", "next_expiration_points": 100 }
start_date `string`, ISO 8601 date format	Voucher's activation date.	`2016-11-16T14:14:31Z`
expiration_date `string`, ISO 8601 date format	Voucher's expiration date.	`2099-11-16T14:14:31Z`
active `boolean`	A flag that allows to disable a voucher even though it's within its activity period.
redemption `list`	A list of redemptions that have been applied to the voucher. Child attributes: - quantity (`integer`, required) - Default: `null`. How many times a voucher can be redeemed. A `null` value means unlimited. - redeemed_quantity (`integer`, required) - How many times a voucher has already been redeemed. - redeemed_amount (`integer`) - Total Amount redeemed by the voucher. Value is multiplied by 100 to precisely represent 2 decimal places. For example, $100 balance is written as 10000. - redemption_entries (`array`) - A list of redemptions and rollbacks that have been applied to the voucher. - url (`string`) - The URL where this list can be accessed.	`"redemption": { "object": "list", "total": 2, "data_ref": "redemption_entries", "quantity": null, "redeemed_quantity": 2, "redeemed_amount": 20000, "redemption_entries": [ {}, {} ] }`
publish `list`	An object gets updated whenever a voucher has been published (e.g. through Export to MailChimp or publish voucher API method). It stores an array of each publish event details and the events counter.	`"publish": { "object": "list", "count": 1, "data_ref": "entries", "entries": [ { "customer_id": "", "channel": "API", "published_at": "", "metadata": { "test": true, "app": "postman" } } ] }`
assets `object`	An object stores links to images with QR codes in which Voucherify encrypts voucher code. As a query string params you can attach following attributes to URL: - size (`integer`) - value from 1 to 100 - format (`string`) - `png` (default) or `svg`	`"assets": { "qr": { "id": "", "url": "" } }`
metadata `object`	A set of key/value pairs that you can attach to a voucher object. It can be useful for storing additional information about the voucher in a structured format.	`"metadata": { "test": true, "locale": "pl-en" }`
additional_info `string`	A field to keep any extra textual information.
validation_rules_assignments `object`	List of The validation rule assignment object

{
  "code": "GIFT_1",
  "campaign": null,
  "category": "test",
  "type": "GIFT_VOUCHER",
  "discount": null,
  "gift": {
    "amount": 100000000,
    "balance": 90000000
  },
  "start_date": "2016-10-31T23:00:00Z",
  "expiration_date": null,
  "publish": {
    "object": "list",
    "count": 1,
    "url": "/v1/vouchers/GIFT_1/publications",
    "data_ref": "entries",
    "entries": [
      {
        "customer_id": "cust_BXduSjtFw9aMrLoW8sfewWLv",
        "customer": "[email protected]",
        "channel": "API",
        "published_at": "2016-11-26T17:24:05Z",
        "metadata": {
          "test": true,
          "app": "postman"
        }
      }
    ]
  },
  "redemption": {
    "object": "list",
    "total": 2,
    "url": "/v1/vouchers/GIFT_1/redemptions",
    "data_ref": "redemption_entries",
    "quantity": null,
    "redeemed_quantity": 2,
    "redeemed_amount": 20000,
    "redemption_entries": [
      {
        "id": "r_RaqsHhD5sPWw1yb0CGXASpPI",
        "object": "redemption",
        "date": "2016-11-23T13:49:15Z",
        "customer_id": "cust_ibxhJgzsXNplC3ojggfnOWWl",
        "tracking_id": "(tracking_id not set)",
        "amount": 10000,
        "order": {
          "amount": 10000,
          "items": []
        },
        "result": "SUCCESS"
      },
      {
        "id": "r_WdQGoDAaPT19kFWIGp434yzS",
        "object": "redemption",
        "date": "2016-11-23T13:50:35Z",
        "customer_id": "cust_ibxhJgzsXNplC3ojggfnOWWl",
        "tracking_id": "(tracking_id not set)",
        "amount": 10000,
        "order": {
          "amount": 10000,
          "items": []
        },
        "result": "SUCCESS"
      }
    ]
  },
  "active": true,
  "additional_info": null,
  "metadata": {},
  "assets": {
    "qr": {
      "id": "U2FsdGVkX18q6LE4stziCYvdHckywW5lCzMB3UdcK29ZZhzzc1YZ+vYnk3FTFrqsxaWqQXwGTf9RdS+qqUuAJzu1uM6QcohRLR6XkJWOQvZcZ11h0rglPIF2lFtC4E0SrLGsUWFUKH3N8SA1uSz7lA==",
      "url": "https://dl.voucherify.io/api/v1/assets/qr/U2FsdGVkX18q6LE4stziCYvdHckywW5lCzMB3UdcK29ZZhzzc1YZ%2BvYnk3FTFrqsxaWqQXwGTf9RdS%2BqqUuAJzu1uM6QcohRLR6XkJWOQvZcZ11h0rglPIF2lFtC4E0SrLGsUWFUKH3N8SA1uSz7lA%3D%3D"
    }
  }
}