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
  • createdBy - CreatedBy beta
    Present on resources created after 1/02/2019 except for events not tracked.
  • lastModifiedAt - DateTime
  • lastModifiedBy - LastModifiedBy beta
    Present on resources updated after 1/02/2019 except for events not tracked.
  • 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:

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

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.

This action overwrites any existing custom type and fields.

Set Custom Field

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