Changes from version 2.0

The API version 2.1 is based on our new backend, written in Golang. The API structure remains unchanged but improvements have been added, instead of completely modifying it. More significant changes are planned for v3.0 next year. Continue reading to check out the changes. If you find any bugs, let us know on Slack, by email, or by creating a Support Ticket.

Happy Vouchering!

Redemptions

1. Changes in 'Create a Redemption call'

• The Transaction ID is not required anymore

We have changed the Transaction ID to non-obligatory for those who don't create the Transaction ID when creating an unconfirmed voucher redemption. To add the TID once the transaction is confirmed and the TID created on your side, you can use the Update Redemption call and update the Transaction ID based on the Redemption ID.

• Added "Update the Redemption" request

We've added this request to enable you to update the redemption once the Transaction ID is created.

📘

'Validate a voucher' request

Please use Validate a voucher request, if you'd like to check whether a particular voucher is valid for the transaction without starting the redemption process and reserving the voucher.

• Taking Additional Categories out of Product Items

In 2.0v, we were taking the 'Additional Categories' directly from the Product Items. That was quite problematic since the Additional Category, e.g. Payment Option, had to be added to every product. We decided to take it out of Product Items and set it as a separate, optional object.

• Added Key (Category Name) to Product Category

In version 2.0, the Product Categories field only consisted of the Value, so the Category tag. That caused issues when the tag was assigned to multiple categories. To clarify that, we have added the Key - Category name.

• Changes in Product Category Rule logic
  The validation logic of the 2.0v considered whether the category from the Product Category rule was present in the request - when not, the whole redemption was rejected. In this version, we will apply the discount to the Product Categories designated or excluded in the Product Category rule.
• Added the shipping_cost object, enabling the 'Discount on Shipping' promotion.

Enabling the shipping_cost information allows Vouchery Users to create a specific Discount on Shipping promotion. Please keep in mind we do not consider the shipping cost when calculating the Discount on Order value.

• Returning information about discounted items

We have added a new reward type - Discount on Shipping, and we have also enhanced the Discount on Product Items. To make things easier for you, we are now returning in the Create a Redemption API request the information on which items in the basket have been discounted and by how much. We hope this makes your experience even better!

• Changes in the validation of unconfirmed redemption

We will validate the following rules and restrictions during the 1st step of the redemption process -
this relates to the situation when the API request includes a "confirmed": false, parameter.

The parameters we will validate for EVERY campaign:

• whether the voucher code exists and it has the status ‘Active’

• if it's a gift card - whether it has any value left (if it does not, it should change the status according to Voucher Statuses)

• (main) campaign restrictions: max number of voucher redemptions, max budget

• promo limits: max number of redemptions, max promo budget, max unique code redemptions, discount value per unique code (if still not filled)

The parameters we will validate when those parameters have been set for the campaign and exist in the request:

PS. Those additional parameters are not obligatory in the request, so if they are not set in the campaign, we won't validate them.

• time of order - does the current validation time come within the restrictions?

• min transaction value

• campaign duration

• customer redemption limits

• whether a voucher has been assigned to the particular customer ID

• category limitations

• product limitations (discount on the product line items, or whether products exist in the basket)

• customer segment limitations

What if parameters have been set but don’t exist in the request?

There might be situations when the campaign will require customer ID, but it won’t be included in the request. In this case, please return the response:

“Please add XXX (eg. Customer ID) to validate the voucher.”

“Please add product information to validate the voucher.”

What rules and restrictions will be validated during the 2nd step of the redemption process for the voucher to be redeemed?

When the transaction data hasn't changed and the voucher is valid, we will allow the confirmation of the redemption, marking the voucher code as used and saving the Redemption (or rejected redemptions) data.

2. Ability to Cancel Redemption

The 2.0v enabled deleting the redemption only when it was still unconfirmed with the call 'Delete a Redemption'. We changed that - 2.1v allows for canceling any redemption so that when your order gets canceled or returned, you can free up the voucher code and all the related statistics and limits. You don't require the voucher code to do so anymore, but only the Transaction ID.

3. Added Pagination to Get all redemptions for a campaign

We know that some of your campaigns have thousands of redemptions, therefore, we've added pagination to increase the performance and make it more accessible.

4. Added ability to Export redemptions within a date range

Previously, to pull redemptions from all campaigns and load them into your data warehouse, you had to pull ALL existing redemptions from the account. To make it easier, we have added a date range, so you can use that to automate the sync with your internal systems.

5. Added Get all Redemptions

Whenever you need to export all the redemptions from your project, you can easily do so in the 2.1v.

📘

What's coming?

Dynamic Discounts & Multiple Rewards soon come to Vouchery. Plus, the new promo type: Generate Product Item. Stay tuned for more info

Invalid Redemptions

From now on, you can pull all unsuccessful redemptions (the redemptions that we have rejected) not only per campaign but also per the whole project.

📘

What's next?

Our next goal related to Invalid Redemptions is to improve the rejection messages so that your Customers know exactly why the coupon was not valid.

Customers

1. Improved ability to Delete a Customer

Previously, you had to delete all Customer Redemptions and associated Vouchers and Triggers to fully delete the Customer from the Vouchery database. The 2.1v allows you to do that instantly, so you can easily achieve that when your customer request data removal.

2. Not possible to Update a Customer ID

Because of past issues, we are not allowing to update the Customer ID anymore. Please get in touch with us directly when that's required or create a Support Ticket.

Improved Customer Segments Update in Update a Customer

In the past, adding a new customer category (segment) required adding all existing segments; otherwise, they were removed. Now, you can add a new Customer Category, and it will be added, not replaced. To remove Customer from Category, add a Category name and leave it blank.

3. Customer Birthday notification

In this API version, you can notify us about your Customer's birthday to fully automate sending a Customer Birthday voucher.

4. Pull all available promo codes and vouchers for a Customer ID - Get available vouchers

This endpoint makes it easier to display available promotions for the customer. It will return vouchers from particular promotions:

• Vouchers from active generic campaigns ( displaying the first generic voucher active for the campaign)

• Vouchers from campaigns with unique coupons (displaying the first voucher with a status: ‘Created’ from the campaign)

• Vouchers that have been assigned to that customer already

From that list, we will exclude, however, those vouchers that the customer has already redeemed and is NOT eligible for anymore.

Important: When you request a Customer ID, which we don't have in our database, we will simply return voucher(s) from available active campaigns.

🚧

COMING SOON: Improved promo voucher query

To make querying the available promotions even more efficient, we will soon consider:

• supporting a situation when the 'Customer Maximum Redemptions' per promotion limit is more than 1
• considering customer segment restrictions when returning the available promos (we would exclude campaigns that don't match the customer segment category)
• supporting time-frame restrictions
• returning promotions based on the basket information, eg. related to product bundles

Campaigns

1. Get all Campaigns replaces Get Main Campaigns with Children...

Let's keep it simple and treat the children as adults. All is all. Plus, we've added pagination to improve performance.

❗️

Fake endpoints

You may see a lot of Endpoints like "This is a fake endpoint to describe a variant of...". This is because we haven't yet found a way how to set up the view as nicely as we've done in 2.0v yet ( we have changed to Swagger 2). Please bear with us - we are working to improve that. In the meantime, we have separated the endpoints. For instance, each 'fake' endpoint describes how to create a Main Campaign or a Sub Campaign.

2. Create a Campaign

• Setting the Main Campaign currency when Creating the Main Campaign or a Sub-Campaign

To make it easier to work in multi-language, multi-currency markets, we have added the currency option into the Main Campaign and Promotion (sub-campaign) settings. Keep in mind the default campaign or promo currency will be the one set in Project Settings.

3. Improved 'Delete a Campaign' option

Deleting the campaign in the 2.0v required removing all its dependencies, like triggers, vouchers, and redemptions.

4. Get a Main Campaign campaign status fixed in the response

We fixed the bug of each main campaign being in 'Draft'. Now all active Main Campaigns will show the status 'Active'.

5. Ability to pull Campaign statistics with "Get stats for campaign"

Rewards

1. Added a Reward Type - Add to Segment

That means, you can automatically add a Customer to a Segment as a specific reward, for example, as a Premium Membership'

2. Added Category operator to Discount on Product Item

From now you can set discount on specific categories of product(s).

Vouchers

1. Ability to use the same prefix when adding more Vouchers to the Campaign

This is something our Marketing Users will love - you don't have to come up with a new prefix each time you generate more unique vouchers for a campaign, you can reuse the same one, so all your vouchers will keep the same structure.

2. Extended Voucher Statuses

Since there were some voucher statuses that cause us many issues in the past, we have vastly extended them, and implemented the following:

• Generic voucher

• Unique voucher

• Gift card

3. 'Validate a voucher' Endpoint

Please use Validate a voucher request, if you'd like to check whether a particular voucher is valid for the transaction without starting the redemption process and reserving the voucher.

📘

What's coming next?

We are working on adding a 'Possible vouchers for a Customer' endpoint that would return a unique and generic vouchers that the customer could potentially redeem. Please bear with us one more week.

Rules

1. Changes in Product Category Rule logic

We have mentioned that already in Redemptions, but we will repeat it here again. The validation logic of the 2.0v considered whether the category from the Product Category rule was present in the request - when not, the whole redemption was rejected. In this version, we will apply the discount to the Product Categories designated or excluded in the Product Category rule.

2. We have added 'Categories' to Product Item Exists Rule

That means there has to be a certain category product in the basket, for the promo reward to be valid.

Categories

No changes here

Excluded Products

Those new endpoints describe products that should be excluded from the promotion: you can add them to the promotions, update it or delete it from the promotion.

Triggers and Events

We have extended the triggers management and will add events management later on.

1. Create a Trigger - new trigger types

We have added a new trigger types, like Customer Birthday.

2. Get all Triggers for a Campaign

This endpoint will return all triggers that have been assign to activate the campaign.

3. Create a Custom Trigger is now Invoke a Custom Trigger

Triggers Management

From now on, you can update the trigger, get the trigger to see its details

📘

Coming soon: Loyalty and Referral triggers.

We're working on Loyalty Program triggers and Referral triggers to make it easier to execute both programs via our API.

UI Management

This section is completely new. Here, you will find endpoints that would enable you to create your own UI for Vouchery API to build an integration or your own white-label solution. This part also gives you an option to manage multiple projects or create a new one.