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.

Representations

DiscountCode

id
String

Unique identifier of the DiscountCode.

version
Int

Current version of the DiscountCode.

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

Reference to CartDiscounts that can be applied to the Cart once the DiscountCode is applied.

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.

createdByBETA

Present on resources created after 1 February 2019 except for events not tracked.

lastModifiedAt

Date and time (UTC) the DiscountCode was last updated.

lastModifiedByBETA

Present on resources created after 1 February 2019 except for events not tracked.

DiscountCodeDraft

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

Specify what CartDiscounts the API applies when you add the DiscountCode to the Cart.

MinItems: 1MaxItems: 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.

maxApplicationsPerCustomer
Int

Number of times the DiscountCode can be applied per Customer.

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.

validUntil

Date and time (UTC) until which the DiscountCode is effective. Must be later than validFrom.

custom

Custom Fields for the DiscountCode.

DiscountCodePagedQueryResponse

PagedQueryResult with results containing an array of DiscountCode.

limit
Int
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 withTotal=false. When the results are filtered with a Query Predicate, total is subject to a limit.

results
Array of DiscountCode

DiscountCodes matching the query.

DiscountCodeReference

id
String

Unique identifier of the referenced DiscountCode.

typeId
String
"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

id
String

Unique identifier of the referenced DiscountCode. Either id or key is required.

key
String

User-defined unique identifier of the referenced DiscountCode. Either id or key is required.

typeId
String
"discount-code"

References a DiscountCode.

Get DiscountCode

GET
https://api.{region}.commercetools.com/{projectKey}/discount-codes/{id}

Deprecated scope: view_orders:{projectKey}

OAuth 2.0 Scopes:
view_discount_codes:{projectKey}
Path parameters:
region
String

Region in which the Project is hosted.

projectKey
String

key of the Project.

id
String

id of the DiscountCode.

Query parameters:
expand
The parameter can be passed multiple times.
Response:
Request Example:cURL
curl --get https://api.{region}.commercetools.com/{projectKey}/discount-codes/{id} -i \
--header 'Authorization: Bearer ${BEARER_TOKEN}'
Clipboard icon
200 Response Example: DiscountCodejson
{
"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"
}
Clipboard icon

Query DiscountCodes

GET
https://api.{region}.commercetools.com/{projectKey}/discount-codes

Deprecated scope: view_orders:{projectKey}

OAuth 2.0 Scopes:
view_discount_codes:{projectKey}
Path parameters:
region
String

Region in which the Project is hosted.

projectKey
String

key of the Project.

Query parameters:
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
offset
Int

Number of elements skipped.

withTotal
Boolean

Controls the calculation of the total number of query results. Set to false to improve query performance when the total is not needed.

Request Example:cURL
curl --get https://api.{region}.commercetools.com/{projectKey}/discount-codes -i \
--header 'Authorization: Bearer ${BEARER_TOKEN}'
Clipboard icon
200 Response Example: DiscountCodePagedQueryResponsejson
{
"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"
} ]
}
Clipboard icon

Create DiscountCode

POST
https://api.{region}.commercetools.com/{projectKey}/discount-codes

Deprecated scope: manage_orders:{projectKey}

OAuth 2.0 Scopes:
manage_discount_codes:{projectKey}
Path parameters:
region
String

Region in which the Project is hosted.

projectKey
String

key of the Project.

Query parameters:
expand
The parameter can be passed multiple times.
Request Body:DiscountCodeDraftasapplication/json
Response:
201DiscountCodeasapplication/json
Request Example:cURL
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
Clipboard icon
201 Response Example: DiscountCodejson
{
"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"
}
Clipboard icon

Update DiscountCode

POST
https://api.{region}.commercetools.com/{projectKey}/discount-codes/{id}

Deprecated scope: manage_orders:{projectKey}

OAuth 2.0 Scopes:
manage_discount_codes:{projectKey}
Path parameters:
region
String

Region in which the Project is hosted.

projectKey
String

key of the Project.

id
String

id of the DiscountCode.

Query parameters:
expand
The parameter can be passed multiple times.
Request Body:
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 is returned.

actions

Update actions to be performed on the DiscountCode.

Response:
200DiscountCodeasapplication/json
Request Example:cURL
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
Clipboard icon
200 Response Example: DiscountCodejson
{
"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"
}
Clipboard icon

Update actions

Set Name

action
String
"setName"
name

Value to set. If empty, any existing value will be removed.

Example: json
{
"action" : "setName",
"name" : {
"en" : "New Name EN",
"de" : "New Name DE"
}
}
Clipboard icon

Set Description

action
String
"setDescription"
description

Value to set. If empty, any existing value will be removed.

Example: json
{
"action" : "setDescription",
"description" : {
"en" : "New Description EN",
"de" : "New Description DE"
}
}
Clipboard icon

Set Cart Predicate

action
String
"setCartPredicate"
cartPredicate
String

Value to set. If empty, any existing value will be removed.

Example: json
{
"action" : "setCartPredicate",
"cartPredicate" : "lineItemCount(sku = \"mySKU\") > 1"
}
Clipboard icon

Set Max Applications

action
String
"setMaxApplications"
maxApplications
Int

Value to set. If empty, any existing value will be removed.

Example: json
{
"action" : "setMaxApplications",
"maxApplications" : 100
}
Clipboard icon

Set Max Applications Per Customer

action
String
"setMaxApplicationsPerCustomer"
maxApplicationsPerCustomer
Int

Value to set. If empty, any existing value will be removed.

Example: json
{
"action" : "setMaxApplicationsPerCustomer",
"maxApplicationsPerCustomer" : 10
}
Clipboard icon

Set Custom Type

action
String
"setCustomType"

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.

Example: json
{
"action" : "setCustomType",
"type" : {
"id" : "{{type-id}}",
"typeId" : "type"
},
"fields" : {
"exampleStringTypeField" : "TextString"
}
}
Clipboard icon

Set CustomField

action
String
"setCustomField"
name
String

Name of the Custom Field.

value

If value is absent or null, this field will be removed if it exists. Removing a field that does not exist returns an InvalidOperation error. If value is provided, it is set for the field defined by name.

Example: json
{
"action" : "setCustomField",
"name" : "ExampleStringTypeField",
"value" : "TextString"
}
Clipboard icon

Change CartDiscounts

action
String
"changeCartDiscounts"
cartDiscounts

New value to set.

MinItems: 1MaxItems: 10
Example: json
{
"action" : "changeCartDiscounts",
"cartDiscounts" : [ {
"typeId" : "cart-discount",
"id" : "{{cartDiscountId}}"
} ]
}
Clipboard icon

Change Groups

action
String
"changeGroups"
groups
Array of String

New value to set. An empty array removes the DiscountCode from all groups.

Example: json
{
"action" : "changeGroups",
"groups" : [ "groupString" ]
}
Clipboard icon

Change IsActive

action
String
"changeIsActive"
isActive
Boolean

New value to set. Set to true to activate the DiscountCode for all matching Discounts.

Example: json
{
"action" : "changeIsActive",
"isActive" : false
}
Clipboard icon

Set Valid From

action
String
"setValidFrom"
validFrom

Value to set that must be earlier than validUntil. If empty, any existing value will be removed.

Example: json
{
"action" : "setValidFrom",
"validFrom" : "2018-10-12T14:00:00.000Z"
}
Clipboard icon

Set Valid Until

action
String
"setValidUntil"
validUntil

Value to set that must be later than validFrom. If empty, any existing value will be removed.

Example: json
{
"action" : "setValidUntil",
"validFrom" : "2018-10-12T14:00:00.000Z"
}
Clipboard icon

Set Valid From and Until

action
String
"setValidFromAndUntil"
validFrom

Value to set that must be earlier than validUntil. If empty, any existing value will be removed.

validUntil

Value to set that must be later than validFrom. If empty, any existing value will be removed.

Example: json
{
"action" : "setValidFromAndUntil",
"validFrom" : "2018-10-12T14:00:00.000Z",
"validUntil" : "2018-10-12T14:05:00.000Z"
}
Clipboard icon

Delete DiscountCode

Warning icon

The API does not check if a CartDiscount, Cart, or Order exists that has a reference to the DiscountCode before deleting it.

DELETE
https://api.{region}.commercetools.com/{projectKey}/discount-codes/{id}

Deprecated scope: manage_orders:{projectKey}

OAuth 2.0 Scopes:
manage_discount_codes:{projectKey}
Path parameters:
region
String

Region in which the Project is hosted.

projectKey
String

key of the Project.

id
String

id of the DiscountCode.

Query parameters:
version
Int

Last seen version of the resource.

expand
The parameter can be passed multiple times.
dataErasure
Boolean

Defaults to false. Set to true if you want to erase all related personal data in compliance with GDPR.

Response:
Request Example:cURL
curl -X DELETE https://api.{region}.commercetools.com/{projectKey}/discount-codes/{id}?version={version} -i \
--header 'Authorization: Bearer ${BEARER_TOKEN}'
Clipboard icon
200 Response Example: DiscountCodejson
{
"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"
}
Clipboard icon