Discount Codes

Elevate, May 20-22-2025, Miami Beach, Florida

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​
DateTime​

Date and time (UTC) from which the DiscountCode is effective.

validUntil​
DateTime​

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​
CustomFields​

Custom Fields of the DiscountCode.

createdAt​
DateTime​

Date and time (UTC) the DiscountCode was initially created.

createdBy​BETA
CreatedBy​

IDs and references that created the DiscountCode.

lastModifiedAt​
DateTime​

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

lastModifiedBy​BETA

IDs and references that last modified the DiscountCode.

Example: json
{
  "id": "{{discount-code-id}}",
  "version": 1,
  "code": "SAVE10",
  "name": {
    "en": "Save10"
  },
  "key": "save10_code",
  "description": {
    "en": "Save 10% using this code"
  },
  "cartDiscounts": [
    {
      "typeId": "cart-discount",
      "id": "{{cart-discount-id}}"
    }
  ],
  "isActive": true,
  "maxApplications": 100,
  "maxApplicationsPerCustomer": 2,
  "cartPredicate": "customer.email = \"john.doe@example.com\" and customer.customerGroup.id = \"{{customer-group-id}}\"",
  "references": [
    {
      "typeId": "customer-group",
      "id": "{{customer-group-id}}"
    }
  ],
  "groups": [
    "new customers"
  ],
  "createdAt": "2024-11-21T08:36:25.991Z",
  "lastModifiedAt": "2024-11-21T08:36:25.991Z",
  "lastModifiedBy": {
    "clientId": "{{client-id}}",
    "isPlatformClient": false
  },
  "createdBy": {
    "clientId": "{{client-id}}",
    "isPlatformClient": false
  }
}

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​

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​
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​
DateTime​

Date and time (UTC) from which the DiscountCode is effective. Must be earlier than validUntil.

validUntil​
DateTime​

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

custom​

Custom Fields for the DiscountCode.

Example: json
{
  "key": "save10_code",
  "name": {
    "en": "Save10"
  },
  "description": {
    "en": "Save 10% using this code"
  },
  "code": "SAVE10",
  "cartDiscounts": [
    {
      "typeId": "cart-discount",
      "id": "{{cart-discount-id}}"
    }
  ],
  "cartPredicate": "customer.email = \"john.doe@example.com\" and customer.customerGroup.id = \"{{customer-group-id}}\"",
  "isActive": true,
  "maxApplications": 100,
  "maxApplicationsPerCustomer": 2,
  "groups": [
    "new customers"
  ]
}

DiscountCodePagedQueryResponse

PagedQueryResult with results containing an array of DiscountCode.

limit​
Int​

Number of results requested.

Default: 20​Minimum: 0​Maximum: 500​
offset​
Int​

Number of elements skipped.

Default: 0​Maximum: 10000​
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​
discount-code

Type of referenced resource.

obj​
DiscountCode​

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 is absent.

key​
String​

User-defined unique identifier of the referenced DiscountCode. Required if id is absent.

typeId​
discount-code

Type of referenced resource. If given, it must match the expected ReferenceTypeId of the referenced resource.

Get DiscountCode

Get DiscountCode by ID

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

Deprecated OAuth 2.0 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:
200

DiscountCode

asapplication/json
Request Example:cURL
curl --get https://api.{region}.commercetools.com/{projectKey}/discount-codes/{id} -i \
--header "Authorization: Bearer ${BEARER_TOKEN}" 
200 Response Example: DiscountCodejson
{
  "id": "{{discount-code-id}}",
  "version": 1,
  "code": "SAVE10",
  "name": {
    "en": "Save10"
  },
  "key": "save10_code",
  "description": {
    "en": "Save 10% using this code"
  },
  "cartDiscounts": [
    {
      "typeId": "cart-discount",
      "id": "{{cart-discount-id}}"
    }
  ],
  "isActive": true,
  "maxApplications": 100,
  "maxApplicationsPerCustomer": 2,
  "cartPredicate": "customer.email = \"john.doe@example.com\" and customer.customerGroup.id = \"{{customer-group-id}}\"",
  "references": [
    {
      "typeId": "customer-group",
      "id": "{{customer-group-id}}"
    }
  ],
  "groups": ["new customers"],
  "createdAt": "2024-11-21T08:36:25.991Z",
  "lastModifiedAt": "2024-11-21T08:36:25.991Z",
  "lastModifiedBy": {
    "clientId": "{{client-id}}",
    "isPlatformClient": false
  },
  "createdBy": {
    "clientId": "{{client-id}}",
    "isPlatformClient": false
  }
}

Get DiscountCode by Key

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

Deprecated OAuth 2.0 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.

key
​
String
​

key of the DiscountCode.

Query parameters:
expand
​​
The parameter can be passed multiple times.
Response:
200

DiscountCode

asapplication/json
Request Example:cURL
curl --get https://api.{region}.commercetools.com/{projectKey}/discount-codes/key={key} -i \
--header "Authorization: Bearer ${BEARER_TOKEN}" 
200 Response Example: DiscountCodejson
{
  "id": "{{discount-code-id}}",
  "version": 1,
  "code": "SAVE10",
  "name": {
    "en": "Save10"
  },
  "key": "save10_code",
  "description": {
    "en": "Save 10% using this code"
  },
  "cartDiscounts": [
    {
      "typeId": "cart-discount",
      "id": "{{cart-discount-id}}"
    }
  ],
  "isActive": true,
  "maxApplications": 100,
  "maxApplicationsPerCustomer": 2,
  "cartPredicate": "customer.email = \"john.doe@example.com\" and customer.customerGroup.id = \"{{customer-group-id}}\"",
  "references": [
    {
      "typeId": "customer-group",
      "id": "{{customer-group-id}}"
    }
  ],
  "groups": ["new customers"],
  "createdAt": "2024-11-21T08:36:25.991Z",
  "lastModifiedAt": "2024-11-21T08:36:25.991Z",
  "lastModifiedBy": {
    "clientId": "{{client-id}}",
    "isPlatformClient": false
  },
  "createdBy": {
    "clientId": "{{client-id}}",
    "isPlatformClient": false
  }
}

Query DiscountCodes

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

Deprecated OAuth 2.0 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.
sort
​​
The parameter can be passed multiple times.
expand
​​
The parameter can be passed multiple times.
limit
​
Int
​

Number of results requested.

Default: 20​
offset
​
Int
​

Number of elements skipped.

Default: 0​
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.

Default: true​
var.<varName>
​
String
​

Predicate parameter values.

The parameter can be passed multiple times.
Response:
200

DiscountCodePagedQueryResponse

asapplication/json
Request Example:cURL
curl --get https://api.{region}.commercetools.com/{projectKey}/discount-codes -i \
--header "Authorization: Bearer ${BEARER_TOKEN}" 
200 Response Example: DiscountCodePagedQueryResponsejson
{
  "limit": 20,
  "offset": 0,
  "count": 1,
  "total": 1,
  "results": [
    {
      "id": "{{discount-code-id}}",
      "version": 1,
      "code": "SAVE10",
      "name": {
        "en": "Save10"
      },
      "key": "save10_code",
      "description": {
        "en": "Save 10% using this code"
      },
      "cartDiscounts": [
        {
          "typeId": "cart-discount",
          "id": "{{cart-discount-id}}"
        }
      ],
      "isActive": true,
      "maxApplications": 100,
      "maxApplicationsPerCustomer": 2,
      "cartPredicate": "customer.email = \"john.doe@example.com\" and customer.customerGroup.id = \"{{customer-group-id}}\"",
      "references": [
        {
          "typeId": "customer-group",
          "id": "{{customer-group-id}}"
        }
      ],
      "groups": ["new customers"],
      "createdAt": "2024-11-21T08:36:25.991Z",
      "lastModifiedAt": "2024-11-21T08:36:25.991Z",
      "lastModifiedBy": {
        "clientId": "{{client-id}}",
        "isPlatformClient": false
      },
      "createdBy": {
        "clientId": "{{client-id}}",
        "isPlatformClient": false
      }
    }
  ]
}

Check if DiscountCode exists

Check if DiscountCode exists by ID

HEAD
https://api.{region}.commercetools.com/{projectKey}/discount-codes/{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.

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.

Response:
200
Request Example:cURL
curl --head https://api.{region}.commercetools.com/{projectKey}/discount-codes/{id} -i \
--header "Authorization: Bearer ${BEARER_TOKEN}" 

Check if DiscountCode exists by Key

HEAD
https://api.{region}.commercetools.com/{projectKey}/discount-codes/key={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.

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.

key
​
String
​

key of the DiscountCode.

Response:
200
Request Example:cURL
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

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

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.

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

Create DiscountCode

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

Creating a Discount Code produces the DiscountCodeCreated Message.

Deprecated OAuth 2.0 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:
201

DiscountCode

asapplication/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 
{
  "key" : "save10_code",
  "name" : {
    "en" : "Save10"
  },
  "description" : {
    "en" : "Save 10% using this code"
  },
  "code" : "SAVE10",
  "cartDiscounts" : [ {
    "typeId" : "cart-discount",
    "id" : "{{cart-discount-id}}"
  } ],
  "cartPredicate" : "customer.email = "john.doe@example.com" and customer.customerGroup.id = "{{customer-group-id}}"",
  "isActive" : true,
  "maxApplications" : 100,
  "maxApplicationsPerCustomer" : 2,
  "groups" : [ "new customers" ]
}
DATA
201 Response Example: DiscountCodejson
{
  "id": "{{discount-code-id}}",
  "version": 1,
  "code": "SAVE10",
  "name": {
    "en": "Save10"
  },
  "key": "save10_code",
  "description": {
    "en": "Save 10% using this code"
  },
  "cartDiscounts": [
    {
      "typeId": "cart-discount",
      "id": "{{cart-discount-id}}"
    }
  ],
  "isActive": true,
  "maxApplications": 100,
  "maxApplicationsPerCustomer": 2,
  "cartPredicate": "customer.email = \"john.doe@example.com\" and customer.customerGroup.id = \"{{customer-group-id}}\"",
  "references": [
    {
      "typeId": "customer-group",
      "id": "{{customer-group-id}}"
    }
  ],
  "groups": ["new customers"],
  "createdAt": "2024-11-21T08:36:25.991Z",
  "lastModifiedAt": "2024-11-21T08:36:25.991Z",
  "lastModifiedBy": {
    "clientId": "{{client-id}}",
    "isPlatformClient": false
  },
  "createdBy": {
    "clientId": "{{client-id}}",
    "isPlatformClient": false
  }
}

Update DiscountCode

Update DiscountCode by ID

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

Deprecated OAuth 2.0 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:DiscountCodeUpdateasapplication/json
Response:
200

DiscountCode

asapplication/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" : "setMaxApplicationsPerCustomer",
    "maxApplicationsPerCustomer" : 5
  } ]
}
DATA
200 Response Example: DiscountCodejson
{
  "id": "{{discount-code-id}}",
  "version": 2,
  "code": "SAVE10",
  "name": {
    "en": "Save10"
  },
  "key": "save10_code",
  "description": {
    "en": "Save 10% using this code"
  },
  "cartDiscounts": [
    {
      "typeId": "cart-discount",
      "id": "{{cart-discount-id}}"
    }
  ],
  "isActive": true,
  "maxApplications": 100,
  "maxApplicationsPerCustomer": 5,
  "cartPredicate": "customer.email = \"john.doe@example.com\" and customer.customerGroup.id = \"{{customer-group-id}}\"",
  "references": [
    {
      "typeId": "customer-group",
      "id": "{{customer-group-id}}"
    }
  ],
  "groups": ["new customers"],
  "createdAt": "2024-11-21T08:36:25.991Z",
  "lastModifiedAt": "2024-12-21T08:36:25.991Z",
  "lastModifiedBy": {
    "clientId": "{{client-id}}",
    "isPlatformClient": false
  },
  "createdBy": {
    "clientId": "{{client-id}}",
    "isPlatformClient": false
  }
}

Update DiscountCode by Key

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

Deprecated OAuth 2.0 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.

key
​
String
​

key of the DiscountCode.

Query parameters:
expand
​​
The parameter can be passed multiple times.
Request Body:DiscountCodeUpdateasapplication/json
Response:
200

DiscountCode

asapplication/json
Request Example:cURL
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" : "setMaxApplicationsPerCustomer",
    "maxApplicationsPerCustomer" : 5
  } ]
}
DATA
200 Response Example: DiscountCodejson
{
  "id": "{{discount-code-id}}",
  "version": 2,
  "code": "SAVE10",
  "name": {
    "en": "Save10"
  },
  "key": "save10_code",
  "description": {
    "en": "Save 10% using this code"
  },
  "cartDiscounts": [
    {
      "typeId": "cart-discount",
      "id": "{{cart-discount-id}}"
    }
  ],
  "isActive": true,
  "maxApplications": 100,
  "maxApplicationsPerCustomer": 5,
  "cartPredicate": "customer.email = \"john.doe@example.com\" and customer.customerGroup.id = \"{{customer-group-id}}\"",
  "references": [
    {
      "typeId": "customer-group",
      "id": "{{customer-group-id}}"
    }
  ],
  "groups": ["new customers"],
  "createdAt": "2024-11-21T08:36:25.991Z",
  "lastModifiedAt": "2024-12-21T08:36:25.991Z",
  "lastModifiedBy": {
    "clientId": "{{client-id}}",
    "isPlatformClient": false
  },
  "createdBy": {
    "clientId": "{{client-id}}",
    "isPlatformClient": false
  }
}

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_-]+$​
Example: json
{
  "action": "setKey",
  "key": "new-key"
}

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",
    "de": "Neuer Name"
  }
}

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",
    "de": "Neue Beschreibung"
  }
}

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"
}

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.

Example: json
{
  "action": "setMaxApplications",
  "maxApplications": 150
}

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.

Example: json
{
  "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.

Example: json
{
  "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 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": "exampleStringField",
  "value": "TextString"
}

Change CartDiscounts

action​
String​
"changeCartDiscounts"
cartDiscounts​

New value to set.

MinItems: 1​MaxItems: 10​
Example: json
{
  "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.

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

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
}

Set Valid From

action​
String​
"setValidFrom"
validFrom​
DateTime​

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

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

Set Valid Until

action​
String​
"setValidUntil"
validUntil​
DateTime​

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

Example: json
{
  "action": "setValidUntil",
  "validUntil": "2025-11-12T14:00:00.000Z"
}

Set Valid From and Until

action​
String​
"setValidFromAndUntil"
validFrom​
DateTime​

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

validUntil​
DateTime​

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

Example: json
{
  "action": "setValidFromAndUntil",
  "validFrom": "2025-10-12T14:00:00.000Z",
  "validUntil": "2025-11-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

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

Deleting a Discount Code produces the DiscountCodeDeleted Message.

Deprecated OAuth 2.0 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
​

To erase all related personal data in compliance with GDPR, set to true.

Default: false​
Response:
200

DiscountCode

asapplication/json
Request Example:cURL
curl -X DELETE https://api.{region}.commercetools.com/{projectKey}/discount-codes/{id}?version={version} -i \
--header "Authorization: Bearer ${BEARER_TOKEN}"
200 Response Example: DiscountCodejson
{
  "id": "{{discount-code-id}}",
  "version": 1,
  "code": "SAVE10",
  "name": {
    "en": "Save10"
  },
  "key": "save10_code",
  "description": {
    "en": "Save 10% using this code"
  },
  "cartDiscounts": [
    {
      "typeId": "cart-discount",
      "id": "{{cart-discount-id}}"
    }
  ],
  "isActive": true,
  "maxApplications": 100,
  "maxApplicationsPerCustomer": 2,
  "cartPredicate": "customer.email = \"john.doe@example.com\" and customer.customerGroup.id = \"{{customer-group-id}}\"",
  "references": [
    {
      "typeId": "customer-group",
      "id": "{{customer-group-id}}"
    }
  ],
  "groups": ["new customers"],
  "createdAt": "2024-11-21T08:36:25.991Z",
  "lastModifiedAt": "2024-11-21T08:36:25.991Z",
  "lastModifiedBy": {
    "clientId": "{{client-id}}",
    "isPlatformClient": false
  },
  "createdBy": {
    "clientId": "{{client-id}}",
    "isPlatformClient": false
  }
}

Delete DiscountCode by Key

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

Deleting a Discount Code produces the DiscountCodeDeleted Message.

Deprecated OAuth 2.0 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.

key
​
String
​

key of the DiscountCode.

Query parameters:
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 true.

Default: false​
Response:
200

DiscountCode

asapplication/json
Request Example:cURL
curl -X DELETE https://api.{region}.commercetools.com/{projectKey}/discount-codes/key={key}?version={version} -i \
--header "Authorization: Bearer ${BEARER_TOKEN}"
200 Response Example: DiscountCodejson
{
  "id": "{{discount-code-id}}",
  "version": 1,
  "code": "SAVE10",
  "name": {
    "en": "Save10"
  },
  "key": "save10_code",
  "description": {
    "en": "Save 10% using this code"
  },
  "cartDiscounts": [
    {
      "typeId": "cart-discount",
      "id": "{{cart-discount-id}}"
    }
  ],
  "isActive": true,
  "maxApplications": 100,
  "maxApplicationsPerCustomer": 2,
  "cartPredicate": "customer.email = \"john.doe@example.com\" and customer.customerGroup.id = \"{{customer-group-id}}\"",
  "references": [
    {
      "typeId": "customer-group",
      "id": "{{customer-group-id}}"
    }
  ],
  "groups": ["new customers"],
  "createdAt": "2024-11-21T08:36:25.991Z",
  "lastModifiedAt": "2024-11-21T08:36:25.991Z",
  "lastModifiedBy": {
    "clientId": "{{client-id}}",
    "isPlatformClient": false
  },
  "createdBy": {
    "clientId": "{{client-id}}",
    "isPlatformClient": false
  }
}