Discount Codes

With discount codes it is possible to give specific cart discounts to an eligible set of users. They are defined by a string value which can be added to a cart so that specific cart discounts can be applied to the cart.

Representations

DiscountCode

id - String
The unique ID of the discount code.
version - Number
createdAt - DateTime
lastModifiedAt - DateTime
name - LocalizedString - Optional
description - LocalizedString - Optional
code - String
Unique identifier of this discount code. This value is added to the cart to enable the related cart discounts in the cart.
cartDiscounts - Array of Reference to a CartDiscount
The referenced matching cart discounts can be applied to the cart once the DiscountCode is added.
cartPredicate - Cart predicate - Optional
The discount code can only be applied to carts that match this predicate.
groups - Array of String
The groups to which this discount code belong.
isActive - Boolean
validFrom - DateTime - Optional
The time from which the discount can be applied on a cart. Before that time the code is invalid.
validUntil - DateTime - Optional
The time until the discount can be applied on a cart. After that time the code is invalid.
references - Array of Reference
The platform will generate this array from the cart predicate. It contains the references of all the resources that are addressed in the predicate.
maxApplications - Number - Optional
The discount code can only be applied maxApplications times.
maxApplicationsPerCustomer - Number - Optional
The discount code can only be applied maxApplicationsPerCustomer times per customer.
custom - CustomFields - Optional

DiscountCodeDraft

name - LocalizedString - Optional
description - LocalizedString - Optional
code - String
Unique identifier of this discount code. This value is added to the cart to enable the related cart discounts in the cart.
cartDiscounts - Array of Reference to a CartDiscount
The referenced matching cart discounts can be applied to the cart once the discount code is added. The number of cart discounts in a discount code is limited to 10.
cartPredicate - Cart predicate - Optional
The discount code can only be applied to carts that match this predicate.
groups - Array of String - Optional
The groups to which this discount code shall belong to.
isActive - Boolean
validFrom - DateTime - Optional
The time from which the discount can be applied on a cart. Before that time the code is invalid.
validUntil - DateTime - Optional
The time until the discount can be applied on a cart. After that time the code is invalid.
maxApplications - Number - Optional
maxApplicationsPerCustomer - Number - Optional
custom - CustomFieldsDraft - Optional

Get DiscountCode by ID

Endpoint: /{projectKey}/discount-codes/{id}
Method: GET
OAuth2 Scopes: view_orders:{projectKey}
Response Representation: DiscountCode

Query DiscountCodes

Endpoint: /{projectKey}/discount-codes
Method: GET
OAuth2 Scopes: view_orders:{projectKey}
Response Representation: PagedQueryResult with the results array of DiscountCode
Query Parameters:

where - Query Predicate - Optional
sort - Sort - Optional
expand - Expansion - Optional
limit - Number - Optional
offset - Number - Optional

Create a DiscountCode

Endpoint: /{projectKey}/discount-codes
Method: POST
OAuth2 Scopes: manage_orders:{projectKey}
Request Representation: DiscountCodeDraft
Response Representation: DiscountCode

Update DiscountCode

Endpoint: /{projectKey}/discount-codes/{id}
Method: POST
OAuth2 Scopes: manage_orders:{projectKey}
Response Representation: DiscountCode
Fields:

version - Number - Required
The expected version of the channel on which the changes should be applied. If the expected version does not match the actual version, a 409 Conflict will be returned.
actions - Array of UpdateAction - Required
The list of update actions to be performed on the discount code.

Update Actions
Please find below the individual update actions provided on this endpoint.

Set Name

action - String - "setName"
name - LocalizedString
If the name parameter is not included, the field will be emptied.

Set Description

action - String - "setDescription"
description - LocalizedString - Optional
If the description parameter is not included, the field will be emptied.

Set Cart Predicate

action - String - "setCartPredicate"
cartPredicate - Cart predicate - Optional
If the cartPredicate parameter is not included, the field will be emptied.

Set Max Applications

action - String - "setMaxApplications"
maxApplications - Number - Optional
If the maxApplications parameter is not included, the field will be emptied.

Set Max Applications Per Customer

action - String - "setMaxApplicationsPerCustomer"
maxApplicationsPerCustomer - Number - Optional
If the maxApplicationsPerCustomer parameter is not included, the field will be emptied.

Set Custom Type

This action sets or removes the custom type for an existing discount code.

action - String - "setCustomType"
type - ResourceIdentifier to a Type - Optional
If absent, the custom type and any existing CustomFields are removed.
fields - * - Optional
A valid JSON object, based on the FieldDefinitions of the Type. Sets the custom fields to this value.

This action overwrites any existing custom type and fields.

Set Custom Field

action - String - "setCustomField"
name - String - Required
value - * - Optional
If value is absent or null, this field will be removed if it exists.
If value is provided, set the value of the field defined by the name.
The FieldDefinition determines the format for the value to be provided.
In particular, for the fields definitions, value has to be provided as:
- for EnumType and LocalizedEnumType fields: the key of the EnumValue or the LocalizedEnumValue
- for LocalizedStringType fields: the LocalizedString object
- for MoneyType fields: the Money object
- for SetType fields: the entire Set object
- for ReferenceType fields: the Reference object

Change CartDiscounts

action - String - "changeCartDiscounts"
cartDiscounts - Array of Reference to a CartDiscount - Required

The number of cart discounts in a discount code is limited to 10.

Change Groups

action - String - "changeGroups"
groups - Array of String - Required
The groups to which this discount code shall belong to. Use empty array to remove the code from all groups.

Change IsActive

action - String - "changeIsActive"
isActive - Boolean - Required

Set Valid From

Sets the time from which the discount can be applied on a cart. Before that time the code is invalid.

action - String - "setValidFrom"
validFrom - DateTime - Optional
If absent, the field with the value is removed in case a value was set before.

Set Valid Until

Sets the time until the discount can be applied on a cart. After that time the code is invalid.

action - String - "setValidUntil"
validUntil - DateTime - Optional
If absent, the field with the value is removed in case a value was set before.

Set Valid From and Until

Sets the time period the discount can be applied on a cart. Outside of that time period the code is invalid.

action - String - "setValidFromAndUntil"
validFrom - DateTime - Optional
If absent, the field with the value is removed in case a value was set before.
validUntil - DateTime - Optional
If absent, the field with the value is removed in case a value was set before.

Delete DiscountCode

This request deletes discount codes only if it’s not referenced by carts.

Endpoint: /{projectKey}/discount-code/{id}
Method: DELETE
OAuth2 Scopes: manage_orders:{projectKey} Query Parameters:

version - Number - Required
dataErasure - Boolean - Optional, defaults to false