Vouchers
General
Vouchers grant a relative or absolute discount on orders or order items and have to be submitted in the checkout flow. Only one voucher per order is allowed. The voucher is limited to the shop country it was created in.
The usage of vouchers can be limited by certain parameters and conditions (for example, max. applicable count, only applicable to certain brands, etc.). Learn more about Voucher criteria.
Examples
- Welcome voucher for registration
- Sorry voucher for delayed delivery
Rate limits
- Create, update voucher operations are scoped to `vouchersWrite`
- Get a single voucher or a collection of vouchers operations are scoped to `vouchersRead`
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.
Examples
Create a Voucher Criterion
Update an existing voucher criterion
You can update voucher criterion type, key and value.
This method can be used to update an existing voucher criterion.
Examples
Update a Voucher Criterion Value
Get an existing voucher criterion
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.
Examples
Get a Voucher Criterion by ID
Get all voucher criteria
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 all voucher criteria by their IDs.
This method can be used to get voucher criteria.
Examples
Get a list of Voucher Criteria
Delete an existing voucher criterion
You can remove restrictions from a voucher.
