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.

  1. 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.

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

gift
object

This object represent gift parameters. Present only if type is GIFT_VOUCHER.

Child attributes:

  • amount (integer, required) - Initial amount associated with the voucher. 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
}

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