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

Admin API

Create vouchers

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.

let response = await adminApi.apis.Vouchers.createVoucher({shopKey: shopKey, countryCode: countryCode}, {requestBody: voucher});
let voucher = response.body;

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

let newVoucher = {
    "code": "testcode",
    "constraints": {
        "date": {
            "max": "2022-12-23T11:30:58+00:00",
            "min": "2022-01-23T11:30:58+00:00"
        },
        "isValidOnCampaigns": true,
        "maxApplications": {
            "count": 1,
            "restriction": "customer"
        },
        "orderValue": {
            "max": 200000,
            "min": 7500
        }
    },
    "isApplicableToPromotions": true,
    "name": "Testvoucher",
    "status": "active",
    "summary": "Checkout: Voucher utilized for automated testing",
    "type": "relative",
    "value": 1
};

let response = await adminApi.apis.Vouchers.createVoucher({shopKey: 'ms', countryCode: 'DE'}, {requestBody: newVoucher});
let createdVoucher = response.body;

console.log(createdVoucher.id);

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.

let response = await adminApi.apis.Vouchers.updateVoucher({shopKey: shopKey, countryCode: countryCode, voucherId: voucherId},{requestBody: voucher});
let voucher = response.body

Examples

let response = await adminApi.apis.Vouchers.getVoucher({ 
    shopKey: 'ms',
    countryCode: 'DE',
    voucherId: 1
    });
let voucher = response.body;

voucher.name = "Testvoucher";
voucher.type = "relative";
voucher.value = 1;

response = await adminApi.apis.Vouchers.updateVoucher(
    {
        shopKey: 'ms',
        countryCode: 'DE',
        voucherId: voucher.id
    },
    {
        requestBody: voucher
    }
);
let updatedVoucher = response.body;

console.log(updatedVoucher.name);

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.

let response = await adminApi.apis.Vouchers.getVoucher({shopKey: shopKey, countryCode: countryCode, voucherId: voucherId);
let voucher = response.body;

Examples

Get a voucher by ID

response = await adminApi.apis.Vouchers.getVoucher({shopKey: 'ms', countryCode: 'DE', voucherId: 1});
let voucher = response.body;

console.log(voucher.name);

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.

let response = await adminApi.apis.Vouchers.getVouchers({shopKey: shopKey, countryCode: countryCode});
let vouchers = response.body.entities;

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:

let response = await adminApi.apis.Vouchers.getVouchers({
     shopKey: 'ms',
     countryCode: 'DE',
    'filters[code]': 'testcode'
});
let vouchers = response.body.entities;

vouchers.forEach(
    voucher => console.log(voucher.name)
);

List 10 Vouchers by Code

Get a list of 10 vouchers filtered by code:

let response = await adminApi.apis.Vouchers.getVouchers({
    shopKey: 'ms',
    countryCode: 'DE',
    filters[code]: 'testcode',
    limit: 10
});
let vouchers = response.body.entities;

vouchers.forEach(
    voucher => console.log(voucher.name)
);

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.

adminApi.apis.Vouchers.deleteVoucher({shopKey: shopKey, countryCode: countryCode, voucherId: voucherId});

Examples

Delete a Voucher by ID

adminApi.apis.Vouchers.deleteVoucher({shopKey: 'ms', countryCode: 'DE', voucherId: 1});

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.

let response = await adminApi.apis.Vouchers.createVoucherCriterion({shopKey: shopKey, countryCode: countryCode, voucherId: voucherId}, {requestBody: voucherCriterion});
let voucherCriterion = response.body;

Examples

Create a Voucher Criterion

let voucherCriterion = {
     "key": "customerId",
     "type": "include",
     "value": [1, 2]
};

let response = await adminApi.apis.Vouchers.createVoucherCriterion({shopKey: 'ms', countryCode: 'DE', voucherId: 1}, {requestBody: voucherCriterion});
voucherCriterion = response.body;

console.log(voucherCriterion.id);

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.

let response = await adminApi.apis.Vouchers.updateVoucherCriterion({shopKey: shopKey, countryCode: countryCode, voucherId: voucherId, voucherCriterionId: voucherCriterionId}, {requestBody: voucherCriterion});
let voucherCriterion = response.body;

Examples

Update a Voucher Criterion Value

let response = await adminApi.apis.Vouchers.getVoucherCriterion({shopKey: 'ms', countryCode: 'DE', voucherId: 1, voucherCriterionId: 1});
let voucherCriterion = response.body;

voucherCriterion.value = [3];

response = await adminApi.apis.Vouchers.updateVoucherCriterion({shopKey: 'ms', countryCode: 'DE', voucherId: 1, voucherCriterionId: voucherCriterion.id}, {requestBody: voucherCriterion});
voucherCriterion = response.body;

console.log(voucherCriterion.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.

let response = await adminApi.apis.Vouchers.getVoucherCriterion({shopKey: shopKey, countryCode: countryCode, voucherId: voucherId, voucherCriterionId: voucherCriterionId});
let voucherCriterion = response.body;

Examples

Get a Voucher Criterion by ID

let response = await adminApi.apis.Vouchers.getVoucherCriterion({shopKey: 'ms', countryCode: 'DE', voucherId: 1, voucherCriterionId: 1});
let voucherCriterion = response.body; 

console.log(voucherCriterion.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.

let response = await adminApi.apis.Vouchers.getVoucherCriteria({shopKey: shopKey, countryCode: countryCode, voucherId: voucherId});
let voucherCriteria = response.body.entities;

Examples

Get a list of Voucher Criteria

let response = await adminApi.apis.Vouchers.getVoucherCriteria({shopKey: 'ms', countryCode: 'DE', voucherId: 1});
let voucherCriteria = response.body.entities; 

voucherCriteria.forEach(
    voucherCriterion => console.log(voucherCriterion.id)
);

Delete an existing voucher criterion

You can remove restrictions from a voucher.

adminApi.apis.Vouchers.deleteVoucherCriterion({shopKey: shopKey, countryCode: countryCode, voucherId: voucherId, voucherCriterionId: voucherCriterionId});

Examples

Delete a Voucher Criterion by ID

adminApi.apis.Vouchers.deleteVoucherCriterion({shopKey: 'ms', countryCode: 'DE', voucherId: 1, voucherCriterionId: 1});