Rollback Redemption

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

redemptionId

string

required

The original redemption ID to be rolled back (undone).

Example:

"r_0ba186c4824e4881e1"

Query Parameters

reason

string

Reason for the rollback.

tracking_id

string

Customer's source_id.

Body

application/json

Add information about the original customer and order. Customer data and Redemption metadata can be updated in Voucherify when passing the customer data in the request body.

Request body schema for POST v1/redemptions/{redemptionId}/rollback.

reason

string

Reason for the rollback.

tracking_id

string

Customer's source_id.

customer

Customer · object

Show child attributes

customer.id

string

The ID of an existing customer.

customer.source_id

string

A unique identifier of the customer who validates a voucher. It can be a customer ID or email from a CRM system, database, or a third-party service. If you also pass a customer ID (unique ID assigned by Voucherify), the source ID will be ignored.

customer.name

string

Customer's first and last name.

customer.description

string

An arbitrary string that you can attach to a customer object.

customer.email

string

Customer's email address.

customer.phone

string

Customer's phone number. This parameter is mandatory when you try to send out codes to customers via an SMS channel.

customer.birthday

string<date>

Deprecated. ~~Customer's birthdate; format YYYY-MM-DD~~.

customer.birthdate

string<date>

Customer's birthdate; format YYYY-MM-DD.

customer.address

object

Customer's address.

Show child attributes

customer.address.city

string

City

customer.address.state

string

State

customer.address.line_1

string

First line of address.

customer.address.line_2

string

Second line of address.

customer.address.country

string

Country.

customer.address.postal_code

string

Postal code.

customer.metadata

object

A set of custom key/value pairs that you can attach to a customer. The metadata object stores all custom attributes assigned to the customer. It can be useful for storing additional information about the customer in a structured format. This metadata can be used for validating whether the customer qualifies for a discount or it can be used in building customer segments.

order

Order · object

Order information. Order information.

Show child attributes

order.id

string

Unique ID assigned by Voucherify of an existing order that will be linked to the redemption of this request.

order.source_id

string | null

Unique source ID of an existing order that will be linked to the redemption of this request.

order.status

enum<string>

The order status.

Available options:

CREATED,

PAID,

CANCELED,

FULFILLED

order.amount

integer

A positive integer in the smallest currency unit (e.g. 100 cents for $1.00) representing the total amount of the order. This is the sum of the order items' amounts.

order.initial_amount

integer

A positive integer in the smallest currency unit (e.g. 100 cents for $1.00) representing the total amount of the order. This is the sum of the order items' amounts.

order.discount_amount

integer

Sum of all order-level discounts applied to the order. It is expressed as an integer in the smallest currency unit (e.g. 100 cents for $1.00).

order.items

Order Item · object[]

Array of items applied to the order. It can include up to 500 items.

Show child attributes

order.items.sku_id

string

Unique identifier of the SKU. It is assigned by Voucherify.

order.items.product_id

string

Unique identifier of the product. It is assigned by Voucherify.

Used along with the source_id property, can be set to either sku or product.

Available options:

product,

sku

order.items.source_id

string

The merchant's product/SKU ID (if it is different from the Voucherify product/SKU ID). It is useful in the integration between multiple systems. It can be an ID from an eCommerce site, a database, or a third-party service.

order.items.quantity

integer

The quantity of the particular item in the cart.

order.items.discount_quantity

integer

Number of dicounted items.

order.items.initial_quantity

integer

A positive integer in the smallest unit quantity representing the total amount of the order; this is the sum of the order items' quantity.

order.items.amount

integer

The total amount of the order item (price * quantity).

order.items.discount_amount

integer

Sum of all order-item-level discounts applied to the order.

order.items.initial_amount

integer

A positive integer in the smallest currency unit (e.g. 100 cents for $1.00) representing the total amount of the order. This is the sum of the order items' amounts.

order.items.price

integer

Unit price of an item. The value is multiplied by 100 to represent 2 decimal places. For example 10000 cents for $100.00.

order.items.product

object

An object containing details of the related product.

Show child attributes

order.items.product.id

string

A unique identifier that represents the product and is assigned by Voucherify.

order.items.product.source_id

string

The merchant's product ID (if it is different than Voucherify's product ID). It is really useful in case of integration between multiple systems. It can be an ID from an eCommerce site, a database or a 3rd party service.

order.items.product.override

boolean

The override set to true is used to store the product information in the system. If the product does not exist, it will be created with a source_id; if it does exist, the provided values for the name, price, and metadata will replace those already stored in the system. Override works only for endpoints that create an order in the database.

order.items.product.name

string

Product name.

order.items.product.metadata

object

A set of custom key/value pairs that you can attach to a product. It can be useful for storing additional information about the product in a structured format. It can be used to create product collections.

order.items.product.price

number

Product price. A positive integer in the smallest currency unit (e.g. 100 cents for $1.00).

order.items.sku

object

An object containing details of the related SKU.

Show child attributes

order.items.sku.id

string

A unique identifier that represents the SKU and is assigned by Voucherify.

order.items.sku.source_id

string

The merchant's SKU ID (if it is different than Voucherify's SKU ID). It is really useful in case of integration between multiple systems. It can be an ID from an eCommerce site, a database or a 3rd party service.

order.items.sku.override

boolean

order.items.sku.sku

string

The SKU name.

order.items.sku.price

number

SKU price. A positive integer in the smallest currency unit (e.g. 100 cents for $1.00).

order.items.sku.metadata

object

A set of custom key/value pairs that you can attach to an order item. It can be useful for storing additional information about the order item in a structured format. It can be used to create product collections.

order.items.metadata

object

order.metadata

object

A set of custom key/value pairs that you can attach to an order. It can be useful for storing additional information about the order in a structured format. It can be used to define business validation rules or discount formulas.

metadata

object

A set of key/value pairs that you can send in the request body to update redemption metadata.

Response

Returns a redemption rollback object indicating the result of the rollback.

Response body schema for POST v1/redemptions/{redemptionId}/rollback.

string

required

Unique identifier of the redemption rollback.

Example:

"rr_0efeb3dab05e62e599"

object

enum<string>

default:redemption_rollback

required

The type of the object represented by the JSON

Available options:

redemption_rollback

date

string<date-time>

required

Timestamp representing the date and time when the object was created. The value is shown in the ISO 8601 format.

Example:

"2021-12-22T10:13:06.487Z"

customer_id

string | null

required

Unique customer ID of the redeeming customer.

Example:

"cust_i8t5Tt6eiKG5K79KQlJ0Vs64"

tracking_id

string | null

required

Hashed customer source ID.

metadata

object

required

The metadata object stores all custom attributes assigned to the redemption.

redemption

string | null

required

Unique redemption ID of the parent redemption.

Example:

"r_0c656311b5878a2031"

result

enum<string>

required

Redemption result.

Available options:

SUCCESS,

FAILURE

status

enum<string>

required

Redemption status.

Available options:

SUCCEEDED,

FAILED

order

Order Calculated No Customer Data · object

required

Order information.

Show child attributes

order.id

string

Unique ID assigned by Voucherify of an existing order that will be linked to the redemption of this request.

order.source_id

string | null

Unique source ID of an existing order that will be linked to the redemption of this request.

order.status

enum<string>

The order status.

Available options:

CREATED,

PAID,

CANCELED,

FULFILLED

order.amount

integer

This is the sum of the order items' amounts. It is expressed as an integer in the smallest currency unit (e.g. 100 cents for $1.00).

order.initial_amount

integer

This is the sum of the order items' amounts before any discount or other effect (e.g. add missing units) is applied. It is expressed as an integer in the smallest currency unit (e.g. 100 cents for $1.00).

order.discount_amount

integer

Sum of all order-level discounts applied to the order. It is expressed as an integer in the smallest currency unit (e.g. 100 cents for $1.00).

order.items_discount_amount

integer

Sum of all product-specific discounts applied to the order. It is expressed as an integer in the smallest currency unit (e.g. 100 cents for $1.00).

order.total_discount_amount

integer

Sum of all order-level AND all product-specific discounts applied to the order. It is expressed as an integer in the smallest currency unit (e.g. 100 cents for $1.00).

order.total_amount

integer

Order amount after undoing all the discounts through the rollback redemption. It is expressed as an integer in the smallest currency unit (e.g. 100 cents for $1.00).

order.applied_discount_amount

integer

This field shows the order-level discount applied. It is expressed as an integer in the smallest currency unit (e.g. 100 cents for $1.00).

order.items_applied_discount_amount

integer

Sum of all product-specific discounts applied in a particular request. It is expressed as an integer in the smallest currency unit (e.g. 100 cents for $1.00).
sum(items, i => i.applied_discount_amount)

order.total_applied_discount_amount

integer

Sum of all order-level AND all product-specific discounts applied in a particular request. It is expressed as an integer in the smallest currency unit (e.g. 100 cents for $1.00).
total_applied_discount_amount = applied_discount_amount + items_applied_discount_amount

order.metadata

object

order.object

enum<string>

default:order

The type of the object represented by JSON.

Available options:

order

order.created_at

string<date-time>

Timestamp representing the date and time when the order was created. The value is shown in the ISO 8601 format.

Example:

"2021-12-22T10:13:06.487Z"

order.updated_at

string<date-time> | null

Timestamp representing the date and time when the order was last updated in ISO 8601 format.

Example:

"2021-12-22T10:14:45.316Z"

order.customer_id

string | null

Unique customer identifier of the customer making the purchase. The ID is assigned by Voucherify.

Example:

"cust_7iUa6ICKyU6gH40dBU25kQU1"

order.referrer_id

string | null

Unique referrer ID.

Example:

"cust_nM4jqPiaXUvQdVSA6vTRUnix"

order.customer

Customer Id · object

Show child attributes

order.customer.id

string

required

A unique identifier of an existing customer.

order.customer.object

enum<string>

default:customer

required

The type of the object represented by JSON.

Available options:

customer

order.referrer

Referrer Id · object

Show child attributes

order.referrer.id

string

required

A unique identifier of an existing customer.

order.referrer.object

enum<string>

default:customer

required

The type of the object represented by JSON.

Available options:

customer

order.redemptions

object

Show child attributes

order.redemptions.{key}

Order Redemptions · object

Show child attributes

order.redemptions.{key}.date

string<date-time>

Timestamp representing the date and time when the redemption was created. The value is shown in the ISO 8601 format.

Example:

"2022-09-02T17:06:56.649Z"

order.redemptions.{key}.rollback_id

string

Unique ID of the redemption rollback.

Example:

"rr_0c63c84eb78ee0a6c0"

order.redemptions.{key}.rollback_date

string<date-time>

Timestamp representing the date and time when the redemption rollback was created. The value is shown in the ISO 8601 format.

Example:

"2023-01-31T14:18:37.150Z"

The source of the incentive.

Unique ID of the parent redemption.

Example:

"r_0ba186c4824e4881e1"

Represent's the campaign ID of the voucher if the redemption was based on a voucher that was part of bulk codes generated within a campaign. In case of a promotion tier, this represents the campaign ID of the promotion tier's parent campaign.

order.redemptions.{key}.stacked

string[]

Contains a list of unique IDs of child redemptions, which belong to the stacked incentives.

order.redemptions.{key}.rollback_stacked

string[]

Lists the rollback redemption IDs of the particular child redemptions.

order.items

Order Item Calculated · object[]

Array of items applied to the order. It can include up to 500 items.

Show child attributes

order.items.object

enum<string>

default:order_item

required

The type of the object represented by JSON.

Available options:

order_item

order.items.id

string

Unique identifier of the order line item.

order.items.sku_id

string

Unique identifier of the SKU. It is assigned by Voucherify.

order.items.product_id

string

Unique identifier of the product. It is assigned by Voucherify.

Used along with the source_id property, can be set to either sku or product.

Available options:

product,

sku

order.items.source_id

string

order.items.quantity

integer

The quantity of the particular item in the cart.

order.items.discount_quantity

integer

Number of dicounted items.

order.items.initial_quantity

integer

A positive integer in the smallest unit quantity representing the total amount of the order; this is the sum of the order items' quantity.

order.items.amount

integer

The total amount of the order item (price * quantity).

order.items.discount_amount

integer

Sum of all order-item-level discounts applied to the order.

order.items.applied_discount_amount

integer

This field shows the order-level discount applied.

order.items.applied_discount_quantity

integer

Number of the discounted items applied in the transaction.

order.items.applied_quantity

integer

Quantity of items changed by the application of a new quantity items. It can be positive when an item is added or negative if an item is replaced.

order.items.applied_quantity_amount

integer

Amount for the items changed by the application of a new quantity items. It can be positive when an item is added or negative if an item is replaced.

order.items.initial_amount

integer

A positive integer in the smallest currency unit (e.g. 100 cents for $1.00) representing the total amount of the order. This is the sum of the order items' amounts.

order.items.price

integer

Unit price of an item. The value is multiplied by 100 to represent 2 decimal places. For example 10000 cents for $100.00.

order.items.subtotal_amount

integer

Final order item amount after the applied item-level discount. If there are no item-level discounts applied, this item is equal to the amount.
subtotal_amount=amount-applied_discount_amount

order.items.product

object

An object containing details of the related product.

Show child attributes

order.items.product.id

string

A unique identifier that represents the product and is assigned by Voucherify.

order.items.product.source_id

string

order.items.product.override

boolean

order.items.product.name

string

Product name.

order.items.product.metadata

object

order.items.product.price

number

Product price. A positive integer in the smallest currency unit (e.g. 100 cents for $1.00).

order.items.sku

object

An object containing details of the related SKU.

Show child attributes

order.items.sku.id

string

A unique identifier that represents the SKU and is assigned by Voucherify.

order.items.sku.source_id

string

order.items.sku.override

boolean

order.items.sku.sku

string

The SKU name.

order.items.sku.price

number

SKU price. A positive integer in the smallest currency unit (e.g. 100 cents for $1.00).

order.items.sku.metadata

object

A set of custom key/value pairs that you can attach to an SKU. It can be useful for storing additional information about the SKU in a structured format. It can be used to create product collections.

order.items.metadata

object

A set of custom key/value pairs that you can attach to an item object. It can be useful for storing additional information about the item in a structured format. It can be used to define business validation rules or discount formulas.

channel

object

required

Defines the details of the channel through which the redemption was issued.

Show child attributes

channel.channel_id

string

Unique identifier of the channel which was used by the user performing the redemption rollback. This is either a user ID from the user using the Voucherify Dashboard or an X-APP-Id of a user using the API.

Example:

"user_g24UoRO3Caxu7FCT4n5tpYEa3zUG0FrH"

channel.channel_type

enum<string>

The source of the channel for the redemption. A USER corresponds to the Voucherify Dashboard and an API corresponds to the API.

Available options:

USER,

API

customer

Simple Customer · object

required

Simplified customer data.

Show child attributes

customer.id

string

Unique identifier of an existing customer. It is assigned by Voucherify.

customer.name

string

Customer's first and last name.

customer.email

string

Customer's email address.

customer.source_id

string

A unique identifier of the customer. It can be a customer ID or email from a CRM system, database, or a third-party service.

customer.metadata

object

A set of custom key/value pairs that are attached to the customer. It stores all custom attributes assigned to the customer.

customer.object

enum<string>

The type of the object represented by JSON.

Available options:

customer

Defines the related object.

Available options:

voucher,

promotion_tier,

redemption

Unique identifier of the related object. It is assigned by Voucherify, i.e. v_lfZi4rcEGe0sN9gmnj40bzwK2FH6QUno for a voucher.

amount

integer

For gift cards, this represents the number of the credits restored to the card in the rolledback redemption. The number is a negative integer in the smallest currency unit, e.g. -100 cents for $1.00 added back to the card. For loyalty cards, this represents the number of loyalty points restored to the card in the rolledback redemption. The number is a negative integer.

Example:

-10000

reason

string

System generated cause for the redemption being invalid in the context of the provided parameters.

failure_code

string

If the result is FAILURE, this parameter will provide a generic reason as to why the redemption failed.

Example:

"customer_rules_violated"

failure_message

string

If the result is FAILURE, this parameter will provide a more expanded reason as to why the redemption failed.

voucher

Voucher · object

Defines the details of the voucher being originally redeemed.

Show child attributes

voucher.id

string

Assigned by the Voucherify API, identifies the voucher.

Example:

"v_mkZN9v7vjYUadXnHrMza8W5c34fE5KiV"

voucher.code

string

A code that identifies a voucher. Pattern can use all letters of the English alphabet, Arabic numerals, and special characters.

Example:

"WVPblOYX"

voucher.campaign

string

A unique campaign name, identifies the voucher's parent campaign.

Example:

"Gift Card Campaign"

voucher.campaign_id

string

Assigned by the Voucherify API, identifies the voucher's parent campaign.

Example:

"camp_FNYR4jhqZBM9xTptxDGgeNBV"

voucher.category

string

Tag defining the category that this voucher belongs to. Useful when listing vouchers using the List Vouchers endpoint.

voucher.category_id

string

Unique category ID assigned by Voucherify.

Example:

"cat_0bb343dee3cdb5ec0c"

voucher.type

enum<string>

Defines the type of the voucher.

Available options:

GIFT_VOUCHER,

DISCOUNT_VOUCHER,

LOYALTY_CARD

voucher.discount

Discount · object

Contains information about discount.

Discount
Discount
Discount
Discount
Discount

Show child attributes

voucher.discount.type

enum<string>

default:AMOUNT

required

Defines the type of the voucher.

Available options:

AMOUNT

voucher.discount.amount_off

number

required

Amount taken off the subtotal of a price. Value is multiplied by 100 to precisely represent 2 decimal places. For example, a $10 discount is written as 1000.

voucher.discount.amount_off_formula

string

Formula used to dynamically calculate the discount.

voucher.discount.aggregated_amount_limit

integer

Maximum discount amount per order.

voucher.discount.effect

enum<string>

Defines how the discount is applied to the customer's order.

Available options:

APPLY_TO_ORDER,

APPLY_TO_ITEMS,

APPLY_TO_ITEMS_PROPORTIONALLY,

APPLY_TO_ITEMS_PROPORTIONALLY_BY_QUANTITY,

APPLY_TO_ITEMS_BY_QUANTITY

voucher.discount.is_dynamic

boolean

Flag indicating whether the discount was calculated using a formula.

voucher.gift

object

Object representing gift parameters. Child attributes are present only if type is GIFT_VOUCHER. Defaults to null.

Show child attributes

voucher.gift.amount

integer

Total gift card income over the lifetime of the card. The value is multiplied by 100 to represent 2 decimal places. For example 10000 cents for $100.00.

Example:

10000

voucher.gift.subtracted_amount

integer

Total amount of subtracted credits over the gift card lifetime. The value is multiplied by 100 to represent 2 decimal places. For example 10000 cents for $100.00.

voucher.gift.balance

integer

Available funds. The value is multiplied by 100 to represent 2 decimal places. For example 10000 cents for $100.00.

Example:

500

voucher.gift.effect

enum<string>

Defines how the credits are applied to the customer's order.

Available options:

APPLY_TO_ORDER,

APPLY_TO_ITEMS

voucher.loyalty_card

object

Object representing loyalty card parameters. Child attributes are present only if type is LOYALTY_CARD. Defaults to null.

Show child attributes

voucher.loyalty_card.points

integer

Total number of points added to the loyalty card over its lifespan.

Example:

7000

voucher.loyalty_card.balance

integer

Points available for reward redemption. This is calculated as follows: balance = points - expired_points - subtracted_points - redemption.redeemed_points.

Example:

6970

voucher.loyalty_card.next_expiration_date

string<date>

The next closest date when the next set of points are due to expire.

Example:

"2023-05-30"

voucher.loyalty_card.next_expiration_points

integer

The amount of points that are set to expire next.

voucher.loyalty_card.pending_points

integer

Shows the number of pending points that will be added to the loyalty card when they are activated automatically or manually.

voucher.loyalty_card.expired_points

integer

Shows the total number of expired points over the lifetime of the loyalty card.

voucher.loyalty_card.subtracted_points

integer

Shows the total number of subtracted points over the lifetime of the loyalty card.

voucher.start_date

string<date-time>

Activation timestamp defines when the code starts to be active in ISO 8601 format. Voucher is inactive before this date.

Example:

"2021-12-01T00:00:00.000Z"

voucher.expiration_date

string<date-time>

Expiration timestamp defines when the code expires in ISO 8601 format. Voucher is inactive after this date.

Example:

"2021-12-31T00:00:00.000Z"

voucher.validity_timeframe

Validity Timeframe · object

Set recurrent time periods when the earning rule is valid. For example, valid for 1 hour every other day.start_date required when including the validity_timeframe.

Show child attributes

voucher.validity_timeframe.duration

string

Defines the amount of time an earning rule will be active in ISO 8601 format. For example, an earning rule with a duration of PT1H will be valid for a duration of one hour.

Example:

"PT1H"

voucher.validity_timeframe.interval

string

Defines the intervening time between two time points in ISO 8601 format, expressed as a duration. For example, an earning rule with an interval of P2D will be valid every other day.

Example:

"P2D"

voucher.validity_day_of_week

enum<integer>[]

Integer array corresponding to the particular days of the week in which the voucher is valid.

0 Sunday
1 Monday
2 Tuesday
3 Wednesday
4 Thursday
5 Friday
6 Saturday

Available options:

0,

1,

2,

3,

4,

5,

6

voucher.validity_hours

Validity Hours · object

Determines the hours of validity, e.g. to create a happy hours scenario.

Show child attributes

voucher.validity_hours.daily

object[]

Defines the recurring period(s) when the resource is active. The periods should not overlap.

Show child attributes

voucher.validity_hours.daily.start_time

string<time>

Defines the starting hour of validity in the HH:mm format. The resource is inactive before this time.

Example:

"12:00"

voucher.validity_hours.daily.days_of_week

enum<integer>[]

Integer array corresponding to the particular days of the week in which the resource is valid.

0 Sunday
1 Monday
2 Tuesday
3 Wednesday
4 Thursday
5 Friday
6 Saturday

Available options:

0,

1,

2,

3,

4,

5,

6

voucher.validity_hours.daily.expiration_time

string<time>

Defines the ending hour of validity in the HH:mm format. The resource is inactive after this time.

Example:

"14:00"

voucher.active

boolean | null

A flag to toggle the voucher on or off. You can disable a voucher even though it's within the active period defined by the start_date and expiration_date.

true indicates an active voucher
false indicates an inactive voucher

voucher.additional_info

string

An optional field to keep any extra textual information about the code such as a code description and details.

voucher.metadata

object

The metadata object stores all custom attributes assigned to the code. 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.

voucher.assets

Voucher Assets · object

Stores links to images of QR and barcode that correspond to an encrypted voucher code.

Show child attributes

voucher.assets.qr

object

Stores Quick Response (QR) representation of encrypted code.

Show child attributes

voucher.assets.qr.id

string

Encrypted voucher code ID.

Example:

"U2FsdGVkX19ucFhvVmBVpVYG5KoswTsjSIaqoKg5L9ie4BK+t4pp7U7oFzjGJzj9q/bmuMOj9mEFiVKDMIkSaruKedMvHbKoPX5Sg+BaZk5QwXMf8k/OzSlOEVybpwSq+AiqPoNtjeuqtIgkDyvT6Q=="

voucher.assets.qr.url

string

URL to QR code

Optional: Attach query parameters to base URL to customize the image of the encrypted voucher code.

size: integer value from 1 to 100
format: string, either png (default) or svg

Example:

"https://dev.dl.voucherify.io/api/v1/assets/qr/U2FsdGVkX19ucFhvVmBVpVYG5KoswTsjSIaqoKg5L9ie4BK%2Bt4pp7U7oFzjGJzj9q%2FbmuMOj9mEFiVKDMIkSaruKedMvHbKoPX5Sg%2BBaZk5QwXMf8k%2FOzSlOEVybpwSq%2BAiqPoNtjeuqtIgkDyvT6Q%3D%3D"

voucher.assets.barcode

object

Stores barcode representation of encrypted code.

Show child attributes

voucher.assets.barcode.id

string

Encrypted voucher code ID.

Example:

"U2FsdGVkX19eJhGfWwUrH9+tulBkON+AnMktic+N6CVWzZ9+fHVxuVx22WakrzxiWXy0skuvvEHSeZIw9HlgyIJ+kJ1iPdUKpyENuNYJKzoZlO0mmTf6WQM6/pFs61apEn9SJx32ttCF6d3oxKISQQ=="

voucher.assets.barcode.url

string

URL to barcode

Optional: Attach query parameters to base URL to customize the image of the encrypted voucher code.

size: integer value from 1 to 100
format: string, either png (default) or svg

Example:

"https://dev.dl.voucherify.io/api/v1/assets/barcode/U2FsdGVkX19eJhGfWwUrH9%2BtulBkON%2BAnMktic%2BN6CVWzZ9%2BfHVxuVx22WakrzxiWXy0skuvvEHSeZIw9HlgyIJ%2BkJ1iPdUKpyENuNYJKzoZlO0mmTf6WQM6%2FpFs61apEn9SJx32ttCF6d3oxKISQQ%3D%3D"

voucher.is_referral_code

boolean | null

Flag indicating whether this voucher is a referral code; true for campaign type REFERRAL_PROGRAM.

voucher.created_at

string<date-time>

Timestamp representing the date and time when the voucher was created. The value is shown in the ISO 8601 format.

Example:

"2021-12-22T10:13:06.487Z"

voucher.updated_at

string<date-time>

Timestamp representing the date and time when the voucher was last updated in ISO 8601 format.

Example:

"2021-12-22T10:14:45.316Z"

voucher.holder_id

string

Unique customer identifier of the redeemable holder. It equals to the customer ID assigned by Voucherify.

Example:

"cust_eWgXlBBiY6THFRJwX45Iakv4"

voucher.referrer_id

string

Unique identifier of the referring person.

Example:

"cust_Vzck5i8U3OhcEUFY6MKhN9Rv"

voucher.object

string

default:voucher

The type of the object represented by JSON. Default is voucher.

voucher.publish

object

Stores a summary of publication events: an event counter and endpoint to return details of each event. Publication is an assignment of a code to a customer, e.g. through a distribution.

Show child attributes

voucher.publish.object

string

default:list

The type of the object represented is by default list. To get this list, you need to make a call to the endpoint returned in the url attribute.

voucher.publish.count

integer

Publication events counter.

Example:

0

voucher.publish.url

string

The endpoint where this list of publications can be accessed using a GET method. /v1/vouchers/{voucher_code}/publications

Example:

"/v1/vouchers/WVPblOYX/publications?page=1&limit=10"

voucher.redemption

object

Stores a summary of redemptions that have been applied to the voucher.

Show child attributes

voucher.redemption.quantity

integer

How many times a voucher can be redeemed. A null value means unlimited.

voucher.redemption.redeemed_quantity

integer

How many times a voucher has already been redeemed.

Example:

1

voucher.redemption.redeemed_points

integer

Total loyalty points redeemed.

Example:

100000

voucher.redemption.object

string

default:list

The type of the object represented is by default list. To get this list, you need to make a call to the endpoint returned in the url attribute.

voucher.redemption.url

string

The endpoint where this list of redemptions can be accessed using a GET method. /v1/vouchers/{voucher_code}/redemptions

Example:

"/v1/vouchers/WVPblOYX/redemptions?page=1&limit=10"

voucher.categories

Category · object[]

Contains details about the category.

Show child attributes

voucher.categories.id

string

required

Unique category ID assigned by Voucherify.

voucher.categories.name

string

required

Category name.

voucher.categories.hierarchy

integer

required

Category hierarchy. Categories with lower hierarchy are processed before categories with higher hierarchy value.

Required range: x >= 0

voucher.categories.object

enum<string>

default:category

required

The type of the object represented by the JSON. This object stores information about the category.

Available options:

category

voucher.categories.created_at

string<date-time>

required

Timestamp representing the date and time when the category was created. The value is shown in the ISO 8601 format.

Example:

"2022-07-14T10:45:13.156Z"

voucher.categories.updated_at

string<date-time>

Timestamp representing the date and time when the category was updated. The value is shown in the ISO 8601 format.

Example:

"2022-08-16T10:52:08.094Z"

voucher.validation_rules_assignments

Validation Rules Assignments List · object

List of Validation Rules Assignments

Show child attributes

voucher.validation_rules_assignments.object

enum<string>

default:list

required

The type of the object represented by JSON. This object stores information about validation rules assignments.

Available options:

list

voucher.validation_rules_assignments.data_ref

enum<string>

default:data

required

Identifies the name of the attribute that contains the array of validation rules assignments.

Available options:

data

voucher.validation_rules_assignments.data

Business Validation Rule Assignment · object[]

required

Contains array of validation rules assignments.

Show child attributes

voucher.validation_rules_assignments.data.id

string

required

The unique identifier for a assignment

voucher.validation_rules_assignments.data.rule_id

string

required

The unique identifier for a rule

The unique identifier for a related object

The type of related object

voucher.validation_rules_assignments.data.object

enum<string>

default:validation_rules_assignment

required

The type of the object represented by JSON.

Available options:

validation_rules_assignment

voucher.validation_rules_assignments.data.created_at

string<date-time>

Timestamp representing the date and time when the object was created. The value is shown in the ISO 8601 format.

Example:

"2022-03-09T11:19:04.819Z"

voucher.validation_rules_assignments.data.updated_at

string<date-time>

Timestamp representing the date and time when the object was last updated in ISO 8601 format.

Example:

"2022-03-09T11:19:04.819Z"

voucher.validation_rules_assignments.data.validation_status

enum<string>

The validation status of the assignment

Available options:

VALID,

PARTIALLY_VALID,

INVALID

voucher.validation_rules_assignments.data.validation_omitted_rules

string[]

The list of omitted rules

voucher.validation_rules_assignments.total

integer

required

Total number of validation rules assignments.

Required range: x >= 0

promotion_tier

Promotion Tier · object

Contains details of the promotion tier and the parent campaign.

Show child attributes

promotion_tier.id

string

Unique promotion tier ID.

Example:

"promo_63fYCt81Aw0h7lzyRkrGZh9p"

promotion_tier.created_at

string<date-time>

Timestamp representing the date and time when the promotion tier was created. The value is shown in the ISO 8601 format.

Example:

"2021-12-15T11:34:01.333Z"

promotion_tier.updated_at

string<date-time>

Timestamp representing the date and time when the promotion tier was updated. The value is shown in the ISO 8601 format.

Example:

"2022-02-09T09:20:05.603Z"

promotion_tier.name

string

Name of the promotion tier.

promotion_tier.banner

string

Text to be displayed to your customers on your website.

promotion_tier.action

object

Contains details about the discount applied by the promotion tier.

Show child attributes

promotion_tier.action.discount

Discount · object

Contains information about discount.

Discount
Discount
Discount
Discount
Discount

Show child attributes

promotion_tier.action.discount.type

enum<string>

default:AMOUNT

required

Defines the type of the voucher.

Available options:

AMOUNT

promotion_tier.action.discount.amount_off

number

required

Amount taken off the subtotal of a price. Value is multiplied by 100 to precisely represent 2 decimal places. For example, a $10 discount is written as 1000.

promotion_tier.action.discount.amount_off_formula

string

Formula used to dynamically calculate the discount.

promotion_tier.action.discount.aggregated_amount_limit

integer

Maximum discount amount per order.

promotion_tier.action.discount.effect

enum<string>

Defines how the discount is applied to the customer's order.

Available options:

APPLY_TO_ORDER,

APPLY_TO_ITEMS,

APPLY_TO_ITEMS_PROPORTIONALLY,

APPLY_TO_ITEMS_PROPORTIONALLY_BY_QUANTITY,

APPLY_TO_ITEMS_BY_QUANTITY

promotion_tier.action.discount.is_dynamic

boolean

Flag indicating whether the discount was calculated using a formula.

promotion_tier.metadata

object

The metadata object stores all custom attributes assigned to the promotion tier. A set of key/value pairs that you can attach to a promotion tier object. It can be useful for storing additional information about the promotion tier in a structured format.

promotion_tier.hierarchy

integer

The promotions hierarchy defines the order in which the discounts from different tiers will be applied to a customer's order. If a customer qualifies for discounts from more than one tier, discounts will be applied in the order defined in the hierarchy.

promotion_tier.promotion_id

string

Promotion unique ID.

promotion_tier.campaign

object

Contains details about promotion tier's parent campaign.

Show child attributes

promotion_tier.campaign.id

string

Unique campaign ID.

promotion_tier.campaign.start_date

string<date-time>

Activation timestamp defines when the campaign starts to be active in ISO 8601 format. Campaign is inactive before this date.

Example:

"2022-09-22T00:00:00.000Z"

promotion_tier.campaign.expiration_date

string<date-time>

Expiration timestamp defines when the campaign expires in ISO 8601 format. Campaign is inactive after this date.

Example:

"2022-09-30T00:00:00.000Z"

promotion_tier.campaign.validity_timeframe

Validity Timeframe · object

Set recurrent time periods when the earning rule is valid. For example, valid for 1 hour every other day.start_date required when including the validity_timeframe.

Show child attributes

promotion_tier.campaign.validity_timeframe.duration

string

Defines the amount of time an earning rule will be active in ISO 8601 format. For example, an earning rule with a duration of PT1H will be valid for a duration of one hour.

Example:

"PT1H"

promotion_tier.campaign.validity_timeframe.interval

string

Defines the intervening time between two time points in ISO 8601 format, expressed as a duration. For example, an earning rule with an interval of P2D will be valid every other day.

Example:

"P2D"

promotion_tier.campaign.validity_day_of_week

enum<integer>[]

Integer array corresponding to the particular days of the week in which the voucher is valid.

0 Sunday
1 Monday
2 Tuesday
3 Wednesday
4 Thursday
5 Friday
6 Saturday

Available options:

0,

1,

2,

3,

4,

5,

6

promotion_tier.campaign.validity_hours

Validity Hours · object

Determines the hours of validity, e.g. to create a happy hours scenario.

Show child attributes

promotion_tier.campaign.validity_hours.daily

object[]

Defines the recurring period(s) when the resource is active. The periods should not overlap.

Show child attributes

promotion_tier.campaign.validity_hours.daily.start_time

string<time>

Defines the starting hour of validity in the HH:mm format. The resource is inactive before this time.

Example:

"12:00"

promotion_tier.campaign.validity_hours.daily.days_of_week

enum<integer>[]

Integer array corresponding to the particular days of the week in which the resource is valid.

0 Sunday
1 Monday
2 Tuesday
3 Wednesday
4 Thursday
5 Friday
6 Saturday

Available options:

0,

1,

2,

3,

4,

5,

6

promotion_tier.campaign.validity_hours.daily.expiration_time

string<time>

Defines the ending hour of validity in the HH:mm format. The resource is inactive after this time.

Example:

"14:00"

promotion_tier.campaign.active

boolean

A flag indicating whether the campaign is active or not active. A campaign can be disabled even though it's within the active period defined by the start_date and expiration_date using the Disable Campaign endpoint.

true indicates an active campaign
false indicates an inactive campaign

promotion_tier.campaign.category_id

string

Unique category ID that this campaign belongs to.

Example:

"cat_0b688929a2476386a6"

promotion_tier.campaign.object

string

default:campaign

The type of the object represented by the campaign object. This object stores information about the campaign.

promotion_tier.campaign_id

string

Promotion tier's parent campaign's unique ID.

promotion_tier.active

boolean

A flag to toggle the promotion tier on or off. You can disable a promotion tier even though it's within the active period defined by the start_date and expiration_date.

true indicates an active promotion tier
false indicates an inactive promotion tier

promotion_tier.start_date

string<date-time>

Activation timestamp defines when the promotion tier starts to be active in ISO 8601 format. Promotion tier is inactive before this date.

Example:

"2022-09-23T00:00:00.000Z"

promotion_tier.expiration_date

string<date-time>

Activation timestamp defines when the promotion tier expires in ISO 8601 format. Promotion tier is inactive after this date.

Example:

"2022-09-26T00:00:00.000Z"

promotion_tier.validity_timeframe

Validity Timeframe · object

Set recurrent time periods when the earning rule is valid. For example, valid for 1 hour every other day.start_date required when including the validity_timeframe.

Show child attributes

promotion_tier.validity_timeframe.duration

string

Defines the amount of time an earning rule will be active in ISO 8601 format. For example, an earning rule with a duration of PT1H will be valid for a duration of one hour.

Example:

"PT1H"

promotion_tier.validity_timeframe.interval

string

Defines the intervening time between two time points in ISO 8601 format, expressed as a duration. For example, an earning rule with an interval of P2D will be valid every other day.

Example:

"P2D"

promotion_tier.validity_day_of_week

enum<integer>[]

Integer array corresponding to the particular days of the week in which the voucher is valid.

0 Sunday
1 Monday
2 Tuesday
3 Wednesday
4 Thursday
5 Friday
6 Saturday

Available options:

0,

1,

2,

3,

4,

5,

6

promotion_tier.validity_hours

Validity Hours · object

Determines the hours of validity, e.g. to create a happy hours scenario.

Show child attributes

promotion_tier.validity_hours.daily

object[]

Defines the recurring period(s) when the resource is active. The periods should not overlap.

Show child attributes

promotion_tier.validity_hours.daily.start_time

string<time>

Defines the starting hour of validity in the HH:mm format. The resource is inactive before this time.

Example:

"12:00"

promotion_tier.validity_hours.daily.days_of_week

enum<integer>[]

Integer array corresponding to the particular days of the week in which the resource is valid.

0 Sunday
1 Monday
2 Tuesday
3 Wednesday
4 Thursday
5 Friday
6 Saturday

Available options:

0,

1,

2,

3,

4,

5,

6

promotion_tier.validity_hours.daily.expiration_time

string<time>

Defines the ending hour of validity in the HH:mm format. The resource is inactive after this time.

Example:

"14:00"

promotion_tier.summary

object

Contains statistics about promotion tier redemptions and orders.

Show child attributes

promotion_tier.summary.redemptions

object

Contains statistics about promotion tier redemptions.

Show child attributes

promotion_tier.summary.redemptions.total_redeemed

integer

Number of times the promotion tier was redeemed.

promotion_tier.summary.orders

object

Contains statistics about orders related to the promotion tier.

Show child attributes

promotion_tier.summary.orders.total_amount

integer

Sum of order totals.

promotion_tier.summary.orders.total_discount_amount

integer

Sum of total discount applied using the promotion tier.

promotion_tier.object

string

default:promotion_tier

The type of the object represented by JSON. This object stores information about the promotion tier.

promotion_tier.validation_rule_assignments

Validation Rule Assignments List · object

Validation Rule Assignments List

Show child attributes

promotion_tier.validation_rule_assignments.object

string

default:list

required

The type of the object represented by JSON. This object stores information about validation rule assignments.

promotion_tier.validation_rule_assignments.data_ref

string

default:data

required

Identifies the name of the JSON property that contains the array of validation rule assignments.

promotion_tier.validation_rule_assignments.data

Validation Rule Assignment · object[]

required

A dictionary that contains an array of validation rule assignments.

Show child attributes

promotion_tier.validation_rule_assignments.data.id

string

required

Validation rule assignment ID.

Example:

"asgm_74F7QZoYbUoljwQO"

promotion_tier.validation_rule_assignments.data.rule_id

string

required

Validation rule ID.

Example:

"val_4j7DCRm2IS59"

The resource ID to which the validation rule was assigned.

Example:

"v_JtWunK6jUo7X2qOFj0SyRHq4p9tgENlT"

The type of resource to which the validation rule was assigned.

Available options:

voucher,

campaign,

earning_rule,

reward_assignment,

promotion_tier,

distribution

promotion_tier.validation_rule_assignments.data.created_at

string<date-time>

required

Timestamp representing the date and time when the validation rule assignment was created. The value is shown in the ISO 8601 format.

Example:

"2022-02-17T08:18:15.085Z"

promotion_tier.validation_rule_assignments.data.object

enum<string>

default:validation_rules_assignment

required

The type of the object represented by the ID.

Available options:

validation_rules_assignment

promotion_tier.validation_rule_assignments.total

integer

required

Total number of validation rule assignments.

promotion_tier.category_id

string

Promotion tier category ID.

Example:

"cat_0c9da30e7116ba6bba"

promotion_tier.categories

Category · object[]

Show child attributes

promotion_tier.categories.id

string

required

Unique category ID assigned by Voucherify.

promotion_tier.categories.name

string

required

Category name.

promotion_tier.categories.hierarchy

integer

required

Category hierarchy. Categories with lower hierarchy are processed before categories with higher hierarchy value.

Required range: x >= 0

promotion_tier.categories.object

enum<string>

default:category

required

The type of the object represented by the JSON. This object stores information about the category.

Available options:

category

promotion_tier.categories.created_at

string<date-time>

required

Timestamp representing the date and time when the category was created. The value is shown in the ISO 8601 format.

Example:

"2022-07-14T10:45:13.156Z"

promotion_tier.categories.updated_at

string<date-time>

Timestamp representing the date and time when the category was updated. The value is shown in the ISO 8601 format.

Example:

"2022-08-16T10:52:08.094Z"

reward

Redemption Reward Result · object

Show child attributes

reward.customer

Simple Customer · object

required

Simplified customer data.

Show child attributes

reward.customer.id

string

Unique identifier of an existing customer. It is assigned by Voucherify.

reward.customer.name

string

Customer's first and last name.

reward.customer.email

string

Customer's email address.

reward.customer.source_id

string

A unique identifier of the customer. It can be a customer ID or email from a CRM system, database, or a third-party service.

reward.customer.metadata

object

A set of custom key/value pairs that are attached to the customer. It stores all custom attributes assigned to the customer.

reward.customer.object

enum<string>

The type of the object represented by JSON.

Available options:

customer

reward.assignment_id

string | null

required

Unique reward assignment ID assigned by Voucherify.

reward.voucher

Voucher · object

required

This is an object representing a voucher with categories and validation rules assignments.

Show child attributes

reward.voucher.id

string

Assigned by the Voucherify API, identifies the voucher.

Example:

"v_mkZN9v7vjYUadXnHrMza8W5c34fE5KiV"

reward.voucher.code

string

A code that identifies a voucher. Pattern can use all letters of the English alphabet, Arabic numerals, and special characters.

Example:

"WVPblOYX"

reward.voucher.campaign

string

A unique campaign name, identifies the voucher's parent campaign.

Example:

"Gift Card Campaign"

reward.voucher.campaign_id

string

Assigned by the Voucherify API, identifies the voucher's parent campaign.

Example:

"camp_FNYR4jhqZBM9xTptxDGgeNBV"

reward.voucher.category

string

Tag defining the category that this voucher belongs to. Useful when listing vouchers using the List Vouchers endpoint.

reward.voucher.category_id

string

Unique category ID assigned by Voucherify.

Example:

"cat_0bb343dee3cdb5ec0c"

reward.voucher.type

enum<string>

Defines the type of the voucher.

Available options:

GIFT_VOUCHER,

DISCOUNT_VOUCHER,

LOYALTY_CARD

reward.voucher.discount

Discount · object

Contains information about discount.

Discount
Discount
Discount
Discount
Discount

Show child attributes

reward.voucher.discount.type

enum<string>

default:AMOUNT

required

Defines the type of the voucher.

Available options:

AMOUNT

reward.voucher.discount.amount_off

number

required

Amount taken off the subtotal of a price. Value is multiplied by 100 to precisely represent 2 decimal places. For example, a $10 discount is written as 1000.

reward.voucher.discount.amount_off_formula

string

Formula used to dynamically calculate the discount.

reward.voucher.discount.aggregated_amount_limit

integer

Maximum discount amount per order.

reward.voucher.discount.effect

enum<string>

Defines how the discount is applied to the customer's order.

Available options:

APPLY_TO_ORDER,

APPLY_TO_ITEMS,

APPLY_TO_ITEMS_PROPORTIONALLY,

APPLY_TO_ITEMS_PROPORTIONALLY_BY_QUANTITY,

APPLY_TO_ITEMS_BY_QUANTITY

reward.voucher.discount.is_dynamic

boolean

Flag indicating whether the discount was calculated using a formula.

reward.voucher.gift

object

Object representing gift parameters. Child attributes are present only if type is GIFT_VOUCHER. Defaults to null.

Show child attributes

reward.voucher.gift.amount

integer

Total gift card income over the lifetime of the card. The value is multiplied by 100 to represent 2 decimal places. For example 10000 cents for $100.00.

Example:

10000

reward.voucher.gift.subtracted_amount

integer

Total amount of subtracted credits over the gift card lifetime. The value is multiplied by 100 to represent 2 decimal places. For example 10000 cents for $100.00.

reward.voucher.gift.balance

integer

Available funds. The value is multiplied by 100 to represent 2 decimal places. For example 10000 cents for $100.00.

Example:

500

reward.voucher.gift.effect

enum<string>

Defines how the credits are applied to the customer's order.

Available options:

APPLY_TO_ORDER,

APPLY_TO_ITEMS

reward.voucher.loyalty_card

object

Object representing loyalty card parameters. Child attributes are present only if type is LOYALTY_CARD. Defaults to null.

Show child attributes

reward.voucher.loyalty_card.points

integer

Total number of points added to the loyalty card over its lifespan.

Example:

7000

reward.voucher.loyalty_card.balance

integer

Points available for reward redemption. This is calculated as follows: balance = points - expired_points - subtracted_points - redemption.redeemed_points.

Example:

6970

reward.voucher.loyalty_card.next_expiration_date

string<date>

The next closest date when the next set of points are due to expire.

Example:

"2023-05-30"

reward.voucher.loyalty_card.next_expiration_points

integer

The amount of points that are set to expire next.

reward.voucher.loyalty_card.pending_points

integer

Shows the number of pending points that will be added to the loyalty card when they are activated automatically or manually.

reward.voucher.loyalty_card.expired_points

integer

Shows the total number of expired points over the lifetime of the loyalty card.

reward.voucher.loyalty_card.subtracted_points

integer

Shows the total number of subtracted points over the lifetime of the loyalty card.

reward.voucher.start_date

string<date-time>

Activation timestamp defines when the code starts to be active in ISO 8601 format. Voucher is inactive before this date.

Example:

"2021-12-01T00:00:00.000Z"

reward.voucher.expiration_date

string<date-time>

Expiration timestamp defines when the code expires in ISO 8601 format. Voucher is inactive after this date.

Example:

"2021-12-31T00:00:00.000Z"

reward.voucher.validity_timeframe

Validity Timeframe · object

Set recurrent time periods when the earning rule is valid. For example, valid for 1 hour every other day.start_date required when including the validity_timeframe.

Show child attributes

reward.voucher.validity_timeframe.duration

string

Defines the amount of time an earning rule will be active in ISO 8601 format. For example, an earning rule with a duration of PT1H will be valid for a duration of one hour.

Example:

"PT1H"

reward.voucher.validity_timeframe.interval

string

Defines the intervening time between two time points in ISO 8601 format, expressed as a duration. For example, an earning rule with an interval of P2D will be valid every other day.

Example:

"P2D"

reward.voucher.validity_day_of_week

enum<integer>[]

Integer array corresponding to the particular days of the week in which the voucher is valid.

0 Sunday
1 Monday
2 Tuesday
3 Wednesday
4 Thursday
5 Friday
6 Saturday

Available options:

0,

1,

2,

3,

4,

5,

6

reward.voucher.validity_hours

Validity Hours · object

Determines the hours of validity, e.g. to create a happy hours scenario.

Show child attributes

reward.voucher.validity_hours.daily

object[]

Defines the recurring period(s) when the resource is active. The periods should not overlap.

Show child attributes

reward.voucher.validity_hours.daily.start_time

string<time>

Defines the starting hour of validity in the HH:mm format. The resource is inactive before this time.

Example:

"12:00"

reward.voucher.validity_hours.daily.days_of_week

enum<integer>[]

Integer array corresponding to the particular days of the week in which the resource is valid.

0 Sunday
1 Monday
2 Tuesday
3 Wednesday
4 Thursday
5 Friday
6 Saturday

Available options:

0,

1,

2,

3,

4,

5,

6

reward.voucher.validity_hours.daily.expiration_time

string<time>

Defines the ending hour of validity in the HH:mm format. The resource is inactive after this time.

Example:

"14:00"

reward.voucher.active

boolean | null

A flag to toggle the voucher on or off. You can disable a voucher even though it's within the active period defined by the start_date and expiration_date.

true indicates an active voucher
false indicates an inactive voucher

reward.voucher.additional_info

string

An optional field to keep any extra textual information about the code such as a code description and details.

reward.voucher.metadata

object

reward.voucher.assets

Voucher Assets · object

Stores links to images of QR and barcode that correspond to an encrypted voucher code.

Show child attributes

reward.voucher.assets.qr

object

Stores Quick Response (QR) representation of encrypted code.

Show child attributes

reward.voucher.assets.qr.id

string

Encrypted voucher code ID.

Example:

"U2FsdGVkX19ucFhvVmBVpVYG5KoswTsjSIaqoKg5L9ie4BK+t4pp7U7oFzjGJzj9q/bmuMOj9mEFiVKDMIkSaruKedMvHbKoPX5Sg+BaZk5QwXMf8k/OzSlOEVybpwSq+AiqPoNtjeuqtIgkDyvT6Q=="

reward.voucher.assets.qr.url

string

URL to QR code

Optional: Attach query parameters to base URL to customize the image of the encrypted voucher code.

size: integer value from 1 to 100
format: string, either png (default) or svg

Example:

reward.voucher.assets.barcode

object

Stores barcode representation of encrypted code.

Show child attributes

reward.voucher.assets.barcode.id

string

Encrypted voucher code ID.

Example:

"U2FsdGVkX19eJhGfWwUrH9+tulBkON+AnMktic+N6CVWzZ9+fHVxuVx22WakrzxiWXy0skuvvEHSeZIw9HlgyIJ+kJ1iPdUKpyENuNYJKzoZlO0mmTf6WQM6/pFs61apEn9SJx32ttCF6d3oxKISQQ=="

reward.voucher.assets.barcode.url

string

URL to barcode

Optional: Attach query parameters to base URL to customize the image of the encrypted voucher code.

size: integer value from 1 to 100
format: string, either png (default) or svg

Example:

reward.voucher.is_referral_code

boolean | null

Flag indicating whether this voucher is a referral code; true for campaign type REFERRAL_PROGRAM.

reward.voucher.created_at

string<date-time>

Timestamp representing the date and time when the voucher was created. The value is shown in the ISO 8601 format.

Example:

"2021-12-22T10:13:06.487Z"

reward.voucher.updated_at

string<date-time>

Timestamp representing the date and time when the voucher was last updated in ISO 8601 format.

Example:

"2021-12-22T10:14:45.316Z"

reward.voucher.holder_id

string

Unique customer identifier of the redeemable holder. It equals to the customer ID assigned by Voucherify.

Example:

"cust_eWgXlBBiY6THFRJwX45Iakv4"

reward.voucher.referrer_id

string

Unique identifier of the referring person.

Example:

"cust_Vzck5i8U3OhcEUFY6MKhN9Rv"

reward.voucher.object

string

default:voucher

The type of the object represented by JSON. Default is voucher.

reward.voucher.publish

object

Stores a summary of publication events: an event counter and endpoint to return details of each event. Publication is an assignment of a code to a customer, e.g. through a distribution.

Show child attributes

reward.voucher.publish.object

string

default:list

The type of the object represented is by default list. To get this list, you need to make a call to the endpoint returned in the url attribute.

reward.voucher.publish.count

integer

Publication events counter.

Example:

0

reward.voucher.publish.url

string

The endpoint where this list of publications can be accessed using a GET method. /v1/vouchers/{voucher_code}/publications

Example:

"/v1/vouchers/WVPblOYX/publications?page=1&limit=10"

reward.voucher.redemption

object

Stores a summary of redemptions that have been applied to the voucher.

Show child attributes

reward.voucher.redemption.quantity

integer

How many times a voucher can be redeemed. A null value means unlimited.

reward.voucher.redemption.redeemed_quantity

integer

How many times a voucher has already been redeemed.

Example:

1

reward.voucher.redemption.redeemed_points

integer

Total loyalty points redeemed.

Example:

100000

reward.voucher.redemption.object

string

default:list

The type of the object represented is by default list. To get this list, you need to make a call to the endpoint returned in the url attribute.

reward.voucher.redemption.url

string

The endpoint where this list of redemptions can be accessed using a GET method. /v1/vouchers/{voucher_code}/redemptions

Example:

"/v1/vouchers/WVPblOYX/redemptions?page=1&limit=10"

reward.voucher.categories

Category · object[]

Contains details about the category.

Show child attributes

reward.voucher.categories.id

string

required

Unique category ID assigned by Voucherify.

reward.voucher.categories.name

string

required

Category name.

reward.voucher.categories.hierarchy

integer

required

Category hierarchy. Categories with lower hierarchy are processed before categories with higher hierarchy value.

Required range: x >= 0

reward.voucher.categories.object

enum<string>

default:category

required

The type of the object represented by the JSON. This object stores information about the category.

Available options:

category

reward.voucher.categories.created_at

string<date-time>

required

Timestamp representing the date and time when the category was created. The value is shown in the ISO 8601 format.

Example:

"2022-07-14T10:45:13.156Z"

reward.voucher.categories.updated_at

string<date-time>

Timestamp representing the date and time when the category was updated. The value is shown in the ISO 8601 format.

Example:

"2022-08-16T10:52:08.094Z"

reward.voucher.validation_rules_assignments

Validation Rules Assignments List · object

List of Validation Rules Assignments

Show child attributes

reward.voucher.validation_rules_assignments.object

enum<string>

default:list

required

The type of the object represented by JSON. This object stores information about validation rules assignments.

Available options:

list

reward.voucher.validation_rules_assignments.data_ref

enum<string>

default:data

required

Identifies the name of the attribute that contains the array of validation rules assignments.

Available options:

data

reward.voucher.validation_rules_assignments.data

Business Validation Rule Assignment · object[]

required

Contains array of validation rules assignments.

Show child attributes

reward.voucher.validation_rules_assignments.data.id

string

required

The unique identifier for a assignment

reward.voucher.validation_rules_assignments.data.rule_id

string

required

The unique identifier for a rule

The unique identifier for a related object

The type of related object

reward.voucher.validation_rules_assignments.data.object

enum<string>

default:validation_rules_assignment

required

The type of the object represented by JSON.

Available options:

validation_rules_assignment

reward.voucher.validation_rules_assignments.data.created_at

string<date-time>

Timestamp representing the date and time when the object was created. The value is shown in the ISO 8601 format.

Example:

"2022-03-09T11:19:04.819Z"

reward.voucher.validation_rules_assignments.data.updated_at

string<date-time>

Timestamp representing the date and time when the object was last updated in ISO 8601 format.

Example:

"2022-03-09T11:19:04.819Z"

reward.voucher.validation_rules_assignments.data.validation_status

enum<string>

The validation status of the assignment

Available options:

VALID,

PARTIALLY_VALID,

INVALID

reward.voucher.validation_rules_assignments.data.validation_omitted_rules

string[]

The list of omitted rules

reward.voucher.validation_rules_assignments.total

integer

required

Total number of validation rules assignments.

Required range: x >= 0

reward.product

Product · object

required

This is an object representing a product.

This entity should be used to map product items from your inventory management system. The aim of products is to build which reflect product-specific campaigns.

Show child attributes

reward.product.id

string

required

Unique product ID assigned by Voucherify.

Example:

"prod_0b1da8105693710357"

reward.product.source_id

string | null

required

Unique product source ID.

Example:

"productSourceID16"

reward.product.name

string | null

required

Unique user-defined product name.

Example:

"T-shirt"

reward.product.price

integer | null

required

Unit price. It is represented by a value multiplied by 100 to accurately reflect 2 decimal places, such as $100.00 being expressed as 10000.

reward.product.attributes

string[]

required

A list of product attributes whose values you can customize for given SKUs: ["color","size","ranking"]. Each child SKU can have a unique value for a given attribute.

reward.product.metadata

object

required

The metadata object stores all custom attributes assigned to the product. A set of key/value pairs that you can attach to a product object. It can be useful for storing additional information about the product in a structured format. It can be used to create product collections.

reward.product.object

enum<string>

default:product

required

The type of the object represented by JSON. This object stores information about the product.

Available options:

product

reward.product.image_url

string | null

The HTTPS URL pointing to the .png or .jpg file that will be used to render the product image.

Example:

"https://images.com/original.jpg"

reward.product.created_at

string<date-time>

Timestamp representing the date and time when the product was created. The value is shown in the ISO 8601 format.

Example:

"2022-05-23T06:52:55.008Z"

reward.product.updated_at

string<date-time> | null

Timestamp representing the date and time when the product was updated. The value is shown in the ISO 8601 format.

Example:

"2022-05-23T09:24:07.405Z"

reward.product.skus

Skus List For Product · object

Contains information about child SKUs.

Show child attributes

reward.product.skus.object

string

default:list

required

The type of the object represented by JSON. This object stores information about SKUs.

reward.product.skus.data_ref

string

default:data

required

Identifies the name of the JSON property that contains the array of SKUs.

reward.product.skus.data

SKU Object · object[]

required

A dictionary that contains an array of SKUs.

Show child attributes

reward.product.skus.data.id

string

required

A unique identifier that represents the SKU and is assigned by Voucherify.

Example:

"sku_0b1621b319d248b79f"

reward.product.skus.data.source_id

string | null

required

A unique SKU identifier from your inventory system.

Example:

"sku_source_id_4"

reward.product.skus.data.product_id

string

required

The parent product's unique ID.

Example:

"prod_0b15f6b9f650c16990"

reward.product.skus.data.sku

string | null

required

Unique user-defined SKU name.

Example:

"Large Pink Shirt"

reward.product.skus.data.price

integer | null

required

Unit price. It is represented by a value multiplied by 100 to accurately reflect 2 decimal places, such as $100.00 being expressed as 10000.

reward.product.skus.data.attributes

object

required

The attributes object stores values for all custom attributes inherited by the SKU from the parent product. A set of key/value pairs that are attached to a SKU object and are unique to each SKU within a product family.

reward.product.skus.data.image_url

string | null

required

The HTTPS URL pointing to the .png or .jpg file that will be used to render the SKU image.

reward.product.skus.data.metadata

object

required

The metadata object stores all custom attributes assigned to the SKU. A set of key/value pairs that you can attach to a SKU object. It can be useful for storing additional information about the SKU in a structured format. It can be used to create product collections.

reward.product.skus.data.created_at

string<date-time>

required

Timestamp representing the date and time when the SKU was created. The value is shown in the ISO 8601 format.

Example:

"2022-05-17T10:36:30.187Z"

reward.product.skus.data.updated_at

string<date-time> | null

required

Timestamp representing the date and time when the SKU was updated. The value is shown in the ISO 8601 format.

Example:

"2022-05-17T10:55:09.137Z"

reward.product.skus.data.object

enum<string>

default:sku

required

The type of the object represented by JSON. This object stores information about the SKU.

Available options:

sku

reward.product.skus.data.currency

string | null

SKU price currency.

Example:

"USD"

reward.product.skus.total

integer

required

Total number of SKUs in the product.

reward.sku

SKU Object · object

required

This is an object representing a product SKU.

Show child attributes

reward.sku.id

string

required

A unique identifier that represents the SKU and is assigned by Voucherify.

Example:

"sku_0b1621b319d248b79f"

reward.sku.source_id

string | null

required

A unique SKU identifier from your inventory system.

Example:

"sku_source_id_4"

reward.sku.product_id

string

required

The parent product's unique ID.

Example:

"prod_0b15f6b9f650c16990"

reward.sku.sku

string | null

required

Unique user-defined SKU name.

Example:

"Large Pink Shirt"

reward.sku.price

integer | null

required

Unit price. It is represented by a value multiplied by 100 to accurately reflect 2 decimal places, such as $100.00 being expressed as 10000.

reward.sku.attributes

object

required

reward.sku.image_url

string | null

required

The HTTPS URL pointing to the .png or .jpg file that will be used to render the SKU image.

reward.sku.metadata

object

required

reward.sku.created_at

string<date-time>

required

Timestamp representing the date and time when the SKU was created. The value is shown in the ISO 8601 format.

Example:

"2022-05-17T10:36:30.187Z"

reward.sku.updated_at

string<date-time> | null

required

Timestamp representing the date and time when the SKU was updated. The value is shown in the ISO 8601 format.

Example:

"2022-05-17T10:55:09.137Z"

reward.sku.object

enum<string>

default:sku

required

The type of the object represented by JSON. This object stores information about the SKU.

Available options:

sku

reward.sku.currency

string | null

SKU price currency.

Example:

"USD"

reward.loyalty_tier_id

string | null

required

Unique loyalty tier ID assigned by Voucherify.

reward.id

string

Unique reward ID.

Example:

"rew_0bc92f81a6801f9bca"

reward.name

string

Name of the reward.

Example:

"Reward Name"

reward.object

enum<string>

default:reward

The type of the object represented by the JSON

Available options:

reward

reward.created_at

string<date-time>

Timestamp representing the date and time when the redemption was created. The value is shown in the ISO 8601 format.

Example:

"2021-12-22T10:13:06.487Z"

reward.updated_at

string<date-time>

Timestamp in ISO 8601 format indicating when the reward was updated.

Example:

"2022-10-03T12:24:58.008Z"

reward.parameters

object

These are parameters representing a material reward.

Show child attributes

reward.parameters.campaign

object

Defines the product redeemed as a reward.

Show child attributes

reward.parameters.campaign.id

string

Campaign unique ID.

Example:

"camp_13BbZ0kQsNinhqsX3wUts2UP"

reward.parameters.campaign.balance

integer

Points available for reward redemption. This is calculated as follows: balance = points - expired_points - subtracted_points - redemption.redeemed_points.

reward.parameters.campaign.type

string

Defines the type of the campaign.

reward.parameters.product

object

Defines the product redeemed as a reward.

Show child attributes

reward.parameters.product.id

string

Unique product ID, assigned by Voucherify.

Example:

"prod_0b7d7dfb05cbe5c616"

reward.parameters.product.sku_id

string

Unique identifier of the SKU. It is assigned by Voucherify.

Example:

"sku_0a41e31c7b41c28358"

reward.parameters.coin

object

Defines the ratio by mapping the number of loyalty points in points_ratio to a predefined cash amount in exchange_ratio.

Show child attributes

reward.parameters.coin.exchange_ratio

integer

The cash equivalent of the points defined in the points_ratio property.

reward.parameters.coin.points_ratio

integer

The number of loyalty points that will map to the predefined cash amount defined by the exchange_ratio property.

reward.metadata

object

A set of custom key/value pairs that you can attach to a reward. The metadata object stores all custom attributes assigned to the reward.

reward.type

enum<string>

Reward type.

Available options:

CAMPAIGN,

COIN,

MATERIAL

gift

object

Contains the amount returned to the gift card in the redemption rollback. It is expressed as a negative integer.

Show child attributes

gift.amount

integer

Amount returned to the gift card as a result of the redemption rollback and expressed as a negative integer. The amount is expressed as the smallest currency unit (e.g. -100 cents for $1.00 returned).

loyalty_card

object

Contains the number of points returned to the loyalty card in the reward redemption rollback. It is expressed as a negative integer.

Show child attributes

loyalty_card.points

integer

Number of points being returned to the loyalty card for the reward redemption rollback. It is expressed as a negative integer.

Introduction

Endpoints

Events

Effect

Returned funds

Authorizations

Path Parameters

Query Parameters

Body

Response