Vouchers (hidden)

Introduction

Vouchers offer a simple and targeted way to grant relative or absolute discounts on orders or specific order items. They must be manually entered by the customer during checkout and are limited to one voucher per order.

Each voucher is restricted to the shop country it was created in. A default shopCountryId condition is automatically applied during creation to enforce this. Additional conditions - such as maximum number of uses, eligible brands, or customer groups - can be configured to control voucher applicability.

Vouchers are ideal for personalized incentives and customer care use cases.

If you have set up a Headless checkout check this guide for how to use our voucher service. You can also add a voucher to an order via API - here you find instructions on how to. Finally, you can also Bulk activate / deactivate vouchers - for that follow this guide.

It is also possible to consume webhooks to check when vouchers have been created or updated.

Examples: Welcome voucher for new customer registration, Apology voucher for delayed deliveries, etc

Setting Vouchers up via SCAYLE Panel

In the SCAYLE Panel navigate to Shops and select the shop you want to create a Voucher for. On the left hand side menu select Promotion > Voucher.

Here you will be able to see a list of existing Vouchers, manage them and create new Vouchers.

You can also create vouchers using the Customer Service Add-on.

Create a new Voucher

Select the Shop where you want to create your promotion and go to Promotions ➜ Vouchers
Click + NEW VOUCHER.
Name: Select a name, bearing in mind that this information is visible to the end customer if the voucher codes were not created by the system.
Clientele: You decide which customer groups may redeem the voucher. It is possible to make a voucher available to all customers or restrict it to individual customer groups. A restriction can be useful if you want to use different voucher codes for different customer groups (for example, within a newsletter campaign).

Restricting a voucher to new customers limits the usage to logged in customers with no confirmed orders.

Start and end dates (optional): specific start and end date to ensure that the voucher can only be redeemed within this time frame. If necessary, you can even define a precise period of time.
Use Reduction type to select between percentage and absolute, and Reduction to set the value
Min and Max order amount (optional): customers can only redeem the voucher if their order matches a minimum amount and does not exceed a maximum value

Reduction limits are configured in Customer Service Add-on ➜ Configurations (Key: voucherapprovallimits). For example, approval might be set for reductions greater than 30% (or reduction amount > 50). If you enter an amount above the threshold, a dropdown will automatically appear where you select an approver. The selected user is notified.

At Code Generation you can pick between generated (automatic) or custom. If you choose Generated, you decide the Number of unique codes the system will produce. Custom allows you to create an individual voucher and name the code yourself.
You can also set a Usage limit - select between Limited or Unlimited. In the case of multiple uses, customers can redeem the voucher code more than once.
In the last step - Criteria - you decide for which products or assortments the customer can redeem the voucher. With the following criteria you determine which inclusion and exclusion rules apply:

Brand: limited to specific brands
Country: limited to specific shop countries
Customer: limited to a group of customers
Master Category: only applicable to certain master categories
Merchant: limited to products of specific merchants
Product: limited to certain product IDs
Shop Category: only applicable to certain shop-specific categories

Click Save

Examples

Scenario 1: 10% Discount for new users

You decide to give a 10% discount for all new users during the moths of July and August. This discount is valid for all of your assortment as long as the basket has a minimum value of 10€ and a maximum of 500€. This can also only be used once for the defined user group.

Your SCAYLE Panel screen should look like the following:

You can use the section “criteria" to further refine your voucher, for example assign a single user a 10€ compensation for a problem with a previous order. To assign this voucher to a user, please follow this guide

Edit or Delete a Voucher

Navigate to Shops ➜ Promotions ➜ Automatic Discount and Locate the Advanced Discount you want to edit (you can use the search function) ➜ Click on it
Click on Edit
- Note from here you can update your rules on the same template you used to create it OR
- Deactivate the discount, for this click on the 3 vertical dots besides “edit” > select deactivate

Hint: On the right side you can see a nifty summary of all your promotion is doing!

Hit save

Delete a Voucher

Navigate to Shops ➜ Promotions ➜ Automatic Discount and locate the Advanced Discount you want to delete (you can use the search function) ➜ Click on it
Click on the 3 vertical dots besides “Edit” > Delete
Confirm on pop up

View Voucher Statistics & History

For a given voucher, you can view usage statistics as well as the history of actions and state changes. After selecting a voucher from the overview list, you can select the tabs: Voucher, Statistics, History.

Voucher: displays the original voucher information fields. From here, you can edit the voucher.
Statistics: shows key data associated with the voucher including the number of codes used and a list of orders where the voucher was used.
History: shows actions associated with the voucher including voucher creation, approvals, and edits/updates with the associated user ID.

Setting Vouchers up via Admin API

Create a voucher

This method is used to create a new voucher.

Apply voucher code to customers' orders including a validation check. Upon successful validation, the orders' total price in the state response will automatically reflect the discount provided by the voucher.

Parameters

Parameter	Details/ Type
`id`	Integer READ-ONLY
`code`	String
`constraints`	VoucherConstraints
`criteria`	VoucherCriterion[]
`isApplicableToPromotions`	Boolean
`name`	String
`status`	String
`summary`	String
`type`	String
`value`	Double

The voucher code must be unique. If the code matches and existing voucher, you will get an error message.

When you create a voucher in a particular shop country and criteria are not provided in the payload, then one default criterion of the shopCountryId type is applied under the hood. This criterion limits the voucher to the given shop country. The criterion can be modified or removed using the respective endpoint.

Examples

Update a voucher

You can update the voucher information by providing the respective data with new values to replace the old ones.

This method can be used to update an existing voucher.

Modifying criteria is not supported on voucher update.

Examples

Get a voucher

This endpoint is not bound to a specific shop country; however, it still requires the shop country details, identified by the shopKey and countryCode, without filtering by the shop country.

SCAYLE allows you to retrieve a specific voucher by its ID.

Examples

Get a voucher by ID

Get a collection of vouchers

This endpoint is not bound to a specific shop country; however, it still requires the shop country details, identified by the shopKey and countryCode, without filtering by the shop country.

When requesting vouchers, the filters[code] query parameter allows you to get all vouchers with the given code, regardless of their status. You can further filter them by using filters[status]. As search results are paginated, you can set the amount of vouchers displayed per page.

This method can be used to get a collection of existing vouchers. It is possible to refine the search by applying filters in the options.

Options

The operation can be used with optional parameters - called options:

param	type	required	description
limit	integer	false	Maximum number of items in the result. (default: 100)
filters[code]	string	false	A specific code for a voucher. Must be provided.
filters[status]	string	false	A specific status for a voucher.

Examples

List Vouchers by Code

Get a list of vouchers filtered by code:

List 10 Vouchers by Code

Get a list of 10 vouchers filtered by code:

Delete a voucher

This method is used to delete an existing voucher.

The voucher is not hard deleted in SCAYLE . The status of the voucher switches to archived.

Examples

Delete a Voucher by ID

Voucher criteria

In SCAYLE, you can add additional restrictions on a voucher. For example, you can allow vouchers to be applied to products of a particular category or a brand. You can also create a reverse criterion to allow vouchers for any brand except the given one.

Note that when you create a voucher in a particular shop country, one default criterion of the shopCountryId type is applied under the hood. This criterion limits the voucher to the given shop country. The criterion can be modified or removed using the respective endpoint.

This behavior can be controlled by the criterion type field, which accepts include or exclude values. The criterion key field defines entities the voucher is restricted to: shopCategoryId, masterCategoryId, customerId, emailHash, brandId, productId, customerGroup, shopCountryId.

In case shopCategoryId key used that should be corresponded for country type of application instead of shop.

Parameters

Parameter	Details
id	Integer READ-ONLY
key	String
type	String If the 'shopCategoryId' key is utilized, it should be associated with a 'country' type of application rather than 'shop'.
value	Array[]

You can limit a voucher to a specific category, brand, customer and more.

This method is used to create a new voucher criterion.

It's not possible to create multiple criteria with the same key for one voucher.

This method can be used to get voucher criteria.