Discount Codes
With Discount Codes it is possible to give specific Cart Discounts to eligible customers. 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.
A DiscountCode can apply up to 10
CartDiscounts.
For an introduction to Discount Codes and to understand how they work in Composable Commerce, see the Discount Codes overview.
Representations
DiscountCode
id String | Unique identifier of the DiscountCode. |
version Int | Current version of the DiscountCode. |
key String | User-defined unique identifier of the DiscountCode. MinLength:2 MaxLength: 256 Pattern: ^[A-Za-z0-9_-]+$ |
name | Name of the DiscountCode. |
description | Description of the DiscountCode. |
code String | User-defined unique identifier of the DiscountCode added to the Cart to apply the related CartDiscounts. |
cartDiscounts Array of CartDiscountReference | Reference to CartDiscounts that can be applied to the Cart once the DiscountCode is applied. MaxItems:10 |
cartPredicate String | DiscountCode can only be applied to Carts that match this predicate. |
isActive Boolean | Indicates if the DiscountCode is active and can be applied to the Cart. |
references Array of Reference | Array generated from the Cart predicate. It contains the references of all the resources that are addressed in the predicate. |
maxApplications Int | Number of times the DiscountCode can be applied. DiscountCode application is counted at the time of Order creation or edit. However, Order cancellation or deletion does not decrement the count. |
maxApplicationsPerCustomer Int | Number of times the DiscountCode can be applied per Customer (anonymous Carts are not supported). DiscountCode application is counted at the time of Order creation or edit. However, Order cancellation or deletion does not decrement the count. |
groups Array of String | Groups to which the DiscountCode belongs to. |
validFrom | Date and time (UTC) from which the DiscountCode is effective. |
validUntil | Date and time (UTC) until which the DiscountCode is effective. |
applicationVersion Int | Used and managed by the API and must not be used in customer logic. The value can change at any time due to internal and external factors. |
custom | Custom Fields of the DiscountCode. |
createdAt | Date and time (UTC) the DiscountCode was initially created. |
createdBy BETA | IDs and references that created the DiscountCode. |
lastModifiedAt | Date and time (UTC) the DiscountCode was last updated. |
lastModifiedBy BETA | IDs and references that last modified the DiscountCode. |
DiscountCodeDraft
key String | User-defined unique identifier for the DiscountCode. This field is optional for backwards compatibility reasons, but we strongly recommend setting it. Keys are mandatory for importing Discount Codes with the Import API and the Merchant Center. MinLength:2 MaxLength: 256 Pattern: ^[A-Za-z0-9_-]+$ |
name | Name of the DiscountCode. |
description | Description of the DiscountCode. |
code String | User-defined unique identifier for the DiscountCode that can be added to the Cart to apply the related CartDiscounts. It cannot be modified after the DiscountCode is created. |
cartDiscounts Array of CartDiscountResourceIdentifier | Specify what CartDiscounts the API applies when you add the DiscountCode to the Cart. MinItems:1 MaxItems: 10 |
cartPredicate String | DiscountCode can only be applied to Carts that match this predicate. |
isActive Boolean | Only active DiscountCodes can be applied to the Cart. Default:true |
maxApplications Int | Number of times the DiscountCode can be applied. If not set, the DiscountCode can be applied any number of times. |
maxApplicationsPerCustomer Int | Number of times the DiscountCode can be applied per Customer. If not set, the DiscountCode can be applied any number of times. |
groups Array of String | Groups to which the DiscountCode will belong to. |
validFrom | Date and time (UTC) from which the DiscountCode is effective. Must be earlier than |
validUntil | Date and time (UTC) until which the DiscountCode is effective. Must be later than |
custom | Custom Fields for the DiscountCode. |
DiscountCodePagedQueryResponse
PagedQueryResult with results
containing an array of DiscountCode.
limit Int | Number of results requested. |
offset Int | Number of elements skipped. |
count Int | Actual number of results returned. |
total Int | Total number of results matching the query.
This number is an estimation that is not strongly consistent.
This field is returned by default.
For improved performance, calculating this field can be deactivated by using the query parameter |
results Array of DiscountCode | DiscountCodes matching the query. |
DiscountCodeReference
Reference to a DiscountCode.
id String | Unique identifier of the referenced DiscountCode. |
typeId | "discount-code" References a DiscountCode. |
obj | Contains the representation of the expanded DiscountCode. Only present in responses to requests with Reference Expansion for DiscountCodes. |
DiscountCodeResourceIdentifier
ResourceIdentifier to a DiscountCode. Either id
or key
is required. If both are set, an InvalidJsonInput error is returned.
id String | Unique identifier of the referenced DiscountCode. Required if |
key String | User-defined unique identifier of the referenced DiscountCode. Required if |
typeId | "discount-code" References a DiscountCode. |
Get DiscountCode
Get DiscountCode by ID
Deprecated OAuth 2.0 Scope: view_orders:{projectKey}
view_discount_codes:{projectKey}
region String | Region in which the Project is hosted. |
projectKey String |
|
id String |
|
expand | The parameter can be passed multiple times. |
application/json
curl --get https://api.{region}.commercetools.com/{projectKey}/discount-codes/{id} -i \--header "Authorization: Bearer ${BEARER_TOKEN}"
{"id": "3b3327a4-06c2-4129-8d87-83d5ce53e038","version": 2,"code": "SAVE10","name": {"en": "Save10"},"cartDiscounts": [{"typeId": "cart-discount","id": "fdbaf4ea-fbc9-4fea-bac4-1d7e6c1995b3"}],"isActive": true,"cartPredicate": "1=1","references": [],"groups": [],"createdAt": "2015-09-15T09:02:29.323Z","lastModifiedAt": "2015-09-15T09:04:06.910Z"}
Get DiscountCode by Key
Deprecated OAuth 2.0 Scope: view_orders:{projectKey}
view_discount_codes:{projectKey}
region String | Region in which the Project is hosted. |
projectKey String |
|
key String |
|
expand | The parameter can be passed multiple times. |
application/json
curl --get https://api.{region}.commercetools.com/{projectKey}/discount-codes/key={key} -i \--header "Authorization: Bearer ${BEARER_TOKEN}"
{"id": "3b3327a4-06c2-4129-8d87-83d5ce53e038","version": 2,"code": "SAVE10","name": {"en": "Save10"},"cartDiscounts": [{"typeId": "cart-discount","id": "fdbaf4ea-fbc9-4fea-bac4-1d7e6c1995b3"}],"isActive": true,"cartPredicate": "1=1","references": [],"groups": [],"createdAt": "2015-09-15T09:02:29.323Z","lastModifiedAt": "2015-09-15T09:04:06.910Z"}
Query DiscountCodes
Deprecated OAuth 2.0 Scope: view_orders:{projectKey}
view_discount_codes:{projectKey}
region String | Region in which the Project is hosted. |
projectKey String |
|
where | The parameter can be passed multiple times. |
/^var[.][a-zA-Z0-9]+$/ Any string parameter matching this regular expression | Predicate parameter values. The parameter can be passed multiple times. |
sort | The parameter can be passed multiple times. |
expand | The parameter can be passed multiple times. |
limit Int | Number of results requested. |
offset Int | Number of elements skipped. |
withTotal Boolean | Controls the calculation of the total number of query results. Set to Default: true |
application/json
curl --get https://api.{region}.commercetools.com/{projectKey}/discount-codes -i \--header "Authorization: Bearer ${BEARER_TOKEN}"
{"limit": 20,"offset": 0,"count": 1,"total": 1,"results": [{"id": "3b3327a4-06c2-4129-8d87-83d5ce53e038","version": 2,"code": "SAVE10","name": {"en": "Save10"},"cartDiscounts": [{"typeId": "cart-discount","id": "fdbaf4ea-fbc9-4fea-bac4-1d7e6c1995b3"}],"isActive": true,"cartPredicate": "1=1","references": [],"groups": [],"attributeTypes": {},"cartFieldTypes": {},"lineItemFieldTypes": {},"customLineItemFieldTypes": {},"createdAt": "2015-09-15T09:02:29.323Z","lastModifiedAt": "2015-09-15T09:04:06.910Z"}]}
Check if DiscountCode exists
Check if DiscountCode exists by ID
Checks if a DiscountCode exists for a given id
. Returns a 200 OK
status if the DiscountCode exists or a 404 Not Found
otherwise.
view_discount_codes:{projectKey}
region String | Region in which the Project is hosted. |
projectKey String |
|
id String |
|
curl --head https://api.{region}.commercetools.com/{projectKey}/discount-codes/{id} -i \--header "Authorization: Bearer ${BEARER_TOKEN}"
Check if DiscountCode exists by Key
Checks if a DiscountCode exists for a given key
. Returns a 200 OK
status if the DiscountCode exists or a 404 Not Found
otherwise.
view_discount_codes:{projectKey}
region String | Region in which the Project is hosted. |
projectKey String |
|
key String |
|
curl --head https://api.{region}.commercetools.com/{projectKey}/discount-codes/key={key} -i \--header "Authorization: Bearer ${BEARER_TOKEN}"
Check if DiscountCode exists by Query Predicate
Checks if a DiscountCode exists for a given Query Predicate. Returns a 200 OK
status if any DiscountCodes match the Query Predicate, or a 404 Not Found
otherwise.
view_discount_codes:{projectKey}
region String | Region in which the Project is hosted. |
projectKey String |
|
where | The parameter can be passed multiple times. |
curl --head https://api.{region}.commercetools.com/{projectKey}/discount-codes -i \--header "Authorization: Bearer ${BEARER_TOKEN}"
Create DiscountCode
Creating a Discount Code produces the DiscountCodeCreated Message.
Deprecated OAuth 2.0 Scope: manage_orders:{projectKey}
manage_discount_codes:{projectKey}
region String | Region in which the Project is hosted. |
projectKey String |
|
expand | The parameter can be passed multiple times. |
application/json
application/json
curl https://api.{region}.commercetools.com/{projectKey}/discount-codes -i \--header "Authorization: Bearer ${BEARER_TOKEN}" \--header 'Content-Type: application/json' \--data-binary @- << DATA{"code" : "SAVE10","name" : {"en" : "Save10"},"cartDiscounts" : [ {"typeId" : "cart-discount","id" : "fdbaf4ea-fbc9-4fea-bac4-1d7e6c1995b3"} ],"isActive" : true,"cartPredicate" : "1=1"}DATA
{"id": "3b3327a4-06c2-4129-8d87-83d5ce53e038","version": 2,"code": "SAVE10","name": {"en": "Save10"},"cartDiscounts": [{"typeId": "cart-discount","id": "fdbaf4ea-fbc9-4fea-bac4-1d7e6c1995b3"}],"isActive": true,"cartPredicate": "1=1","references": [],"groups": [],"createdAt": "2015-09-15T09:02:29.323Z","lastModifiedAt": "2015-09-15T09:04:06.910Z"}
Update DiscountCode
Update DiscountCode by ID
Deprecated OAuth 2.0 Scope: manage_orders:{projectKey}
manage_discount_codes:{projectKey}
region String | Region in which the Project is hosted. |
projectKey String |
|
id String |
|
expand | The parameter can be passed multiple times. |
application/json
version Int | Expected version of the DiscountCode on which the changes should be applied. If the expected version does not match the actual version, a ConcurrentModification error will be returned. |
actions Array of DiscountCodeUpdateAction | Update actions to be performed on the DiscountCode. |
application/json
curl https://api.{region}.commercetools.com/{projectKey}/discount-codes/{id} -i \--header "Authorization: Bearer ${BEARER_TOKEN}" \--header 'Content-Type: application/json' \--data-binary @- << DATA{"version" : 1,"actions" : [ {"action" : "setName","name" : {"en" : "New Name"}} ]}DATA
{"id": "3b3327a4-06c2-4129-8d87-83d5ce53e038","version": 2,"code": "SAVE10","name": {"en": "Save10"},"cartDiscounts": [{"typeId": "cart-discount","id": "fdbaf4ea-fbc9-4fea-bac4-1d7e6c1995b3"}],"isActive": true,"cartPredicate": "1=1","references": [],"groups": [],"createdAt": "2015-09-15T09:02:29.323Z","lastModifiedAt": "2015-09-15T09:04:06.910Z"}
Update DiscountCode by Key
Deprecated OAuth 2.0 Scope: manage_orders:{projectKey}
manage_discount_codes:{projectKey}
region String | Region in which the Project is hosted. |
projectKey String |
|
key String |
|
expand | The parameter can be passed multiple times. |
application/json
version Int | Expected version of the DiscountCode on which the changes should be applied. If the expected version does not match the actual version, a ConcurrentModification error will be returned. |
actions Array of DiscountCodeUpdateAction | Update actions to be performed on the DiscountCode. |
application/json
curl https://api.{region}.commercetools.com/{projectKey}/discount-codes/key={key} -i \--header "Authorization: Bearer ${BEARER_TOKEN}" \--header 'Content-Type: application/json' \--data-binary @- << DATA{"version" : 1,"actions" : [ {"action" : "setName","name" : {"en" : "New Name"}} ]}DATA
{"id": "3b3327a4-06c2-4129-8d87-83d5ce53e038","version": 2,"code": "SAVE10","name": {"en": "Save10"},"cartDiscounts": [{"typeId": "cart-discount","id": "fdbaf4ea-fbc9-4fea-bac4-1d7e6c1995b3"}],"isActive": true,"cartPredicate": "1=1","references": [],"groups": [],"createdAt": "2015-09-15T09:02:29.323Z","lastModifiedAt": "2015-09-15T09:04:06.910Z"}
Update actions
Set Key
This action generates a DiscountCodeKeySet Message.
action String | "setKey" |
key String | Unique value to set. If empty, any existing value will be removed. MinLength:2 MaxLength: 256 Pattern: ^[A-Za-z0-9_-]+$ |
{"action": "setKey","key": "new-key"}
Set Name
action String | "setName" |
name | Value to set. If empty, any existing value will be removed. |
{"action": "setName","name": {"en": "New Name EN","de": "New Name DE"}}
Set Description
action String | "setDescription" |
description | Value to set. If empty, any existing value will be removed. |
{"action": "setDescription","description": {"en": "New Description EN","de": "New Description DE"}}
Set Cart Predicate
action String | "setCartPredicate" |
cartPredicate String | Value to set. If empty, any existing value will be removed. |
{"action": "setCartPredicate","cartPredicate": "lineItemCount(sku = \"mySKU\") > 1"}
Set Max Applications
action String | "setMaxApplications" |
maxApplications Int | Value to set. If empty, any existing value will be removed and the DiscountCode can be applied any number of times. |
{"action": "setMaxApplications","maxApplications": 100}
Set Max Applications Per Customer
action String | "setMaxApplicationsPerCustomer" |
maxApplicationsPerCustomer Int | Value to set. If empty, any existing value will be removed and the DiscountCode can be applied any number of times. |
{"action": "setMaxApplicationsPerCustomer","maxApplicationsPerCustomer": 10}
Set Custom Type
action String | "setCustomType" |
type | Defines the Type that extends the DiscountCode with Custom Fields. If absent, any existing Type and Custom Fields are removed from the DiscountCode. |
fields | Sets the Custom Fields fields for the DiscountCode. |
{"action": "setCustomType","type": {"id": "{{type-id}}","typeId": "type"},"fields": {"exampleStringField": "TextString"}}
Set CustomField
action String | "setCustomField" |
name String | Name of the Custom Field. |
value | If |
{"action": "setCustomField","name": "exampleStringField","value": "TextString"}
Change CartDiscounts
action String | "changeCartDiscounts" |
cartDiscounts Array of CartDiscountResourceIdentifier | New value to set. MinItems:1 MaxItems: 10 |
{"action": "changeCartDiscounts","cartDiscounts": [{"typeId": "cart-discount","id": "{{cartDiscountId}}"}]}
Change Groups
action String | "changeGroups" |
groups Array of String | New value to set. An empty array removes the DiscountCode from all groups. |
{"action": "changeGroups","groups": ["groupString"]}
Change IsActive
action String | "changeIsActive" |
isActive Boolean | New value to set. Set to |
{"action": "changeIsActive","isActive": false}
Set Valid From
action String | "setValidFrom" |
validFrom | Value to set that must be earlier than |
{"action": "setValidFrom","validFrom": "2018-10-12T14:00:00.000Z"}
Set Valid Until
action String | "setValidUntil" |
validUntil | Value to set that must be later than |
{"action": "setValidUntil","validUntil": "2018-10-12T14:00:00.000Z"}
Set Valid From and Until
action String | "setValidFromAndUntil" |
validFrom | Value to set that must be earlier than |
validUntil | Value to set that must be later than |
{"action": "setValidFromAndUntil","validFrom": "2018-10-12T14:00:00.000Z","validUntil": "2018-10-12T14:05:00.000Z"}
Delete DiscountCode
The API does not check if a CartDiscount, Cart, or Order exists that has a reference to the DiscountCode before deleting it.
Delete DiscountCode by ID
Deleting a Discount Code produces the DiscountCodeDeleted Message.
Deprecated OAuth 2.0 Scope: manage_orders:{projectKey}
manage_discount_codes:{projectKey}
region String | Region in which the Project is hosted. |
projectKey String |
|
id String |
|
version Int | Last seen version of the resource. |
expand | The parameter can be passed multiple times. |
dataErasure Boolean | To erase all related personal data in compliance with GDPR, set to Default: false |
application/json
curl -X DELETE https://api.{region}.commercetools.com/{projectKey}/discount-codes/{id}?version={version} -i \--header "Authorization: Bearer ${BEARER_TOKEN}"
{"id": "3b3327a4-06c2-4129-8d87-83d5ce53e038","version": 2,"code": "SAVE10","name": {"en": "Save10"},"cartDiscounts": [{"typeId": "cart-discount","id": "fdbaf4ea-fbc9-4fea-bac4-1d7e6c1995b3"}],"isActive": true,"cartPredicate": "1=1","references": [],"groups": [],"createdAt": "2015-09-15T09:02:29.323Z","lastModifiedAt": "2015-09-15T09:04:06.910Z"}
Delete DiscountCode by Key
Deleting a Discount Code produces the DiscountCodeDeleted Message.
Deprecated OAuth 2.0 Scope: manage_orders:{projectKey}
manage_discount_codes:{projectKey}
region String | Region in which the Project is hosted. |
projectKey String |
|
key String |
|
version Int | Last seen version of the resource. |
expand | The parameter can be passed multiple times. |
dataErasure Boolean | To erase all related personal data in compliance with GDPR, set to Default: false |
application/json
curl -X DELETE https://api.{region}.commercetools.com/{projectKey}/discount-codes/key={key}?version={version} -i \--header "Authorization: Bearer ${BEARER_TOKEN}"
{"id": "3b3327a4-06c2-4129-8d87-83d5ce53e038","version": 2,"code": "SAVE10","name": {"en": "Save10"},"cartDiscounts": [{"typeId": "cart-discount","id": "fdbaf4ea-fbc9-4fea-bac4-1d7e6c1995b3"}],"isActive": true,"cartPredicate": "1=1","references": [],"groups": [],"createdAt": "2015-09-15T09:02:29.323Z","lastModifiedAt": "2015-09-15T09:04:06.910Z"}