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

DiscountCodeDraft

DiscountCodePagedQueryResponse

DiscountCodeReference

DiscountCodeResourceIdentifier

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` LocalizedString	Name of the DiscountCode.
`description` LocalizedString	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 LastModifiedBy	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` LocalizedString	Name of the DiscountCode.
`description` LocalizedString	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` 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` CustomFieldsDraft	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

Reference to a DiscountCode.

`id` String	Unique identifier of the referenced DiscountCode.
`typeId` ReferenceTypeId	`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` ReferenceTypeId	`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

Expansion

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

Expansion

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` QueryPredicate	The parameter can be passed multiple times.
`sort` Sort	The parameter can be passed multiple times.
`expand` Expansion	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

QueryPredicate

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

Expansion

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

Expansion

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 will be returned.
`actions` Array of DiscountCodeUpdateAction	Update actions to be performed on the DiscountCode.

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

Expansion

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 will be returned.
`actions` Array of DiscountCodeUpdateAction	Update actions to be performed on the DiscountCode.

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 Max Applications Per Customer

Set Valid From and Until

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` LocalizedString	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` LocalizedString	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` TypeResourceIdentifier	Defines the Type that extends the DiscountCode with Custom Fields. If absent, any existing Type and Custom Fields are removed from the DiscountCode.
`fields` FieldContainer	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` CustomFieldValue	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` Array of CartDiscountResourceIdentifier	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` Expansion	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` Expansion	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
  }
}

Discount Codes

Representations.css-c0cbbx{display:inline-block;}.css-c0cbbx >:disabled{pointer-events:none;}.css-ik49mw{-webkit-flex-shrink:0;-ms-flex-negative:0;flex-shrink:0;}.css-ik49mw *:not([fill='none']){fill:inherit;}.css-ik49mw,.css-ik49mw image{width:24px;height:24px;}

DiscountCode.css-c0cbbx{display:inline-block;}.css-c0cbbx >:disabled{pointer-events:none;}.css-ik49mw{-webkit-flex-shrink:0;-ms-flex-negative:0;flex-shrink:0;}.css-ik49mw *:not([fill='none']){fill:inherit;}.css-ik49mw,.css-ik49mw image{width:24px;height:24px;}

DiscountCodeDraft.css-c0cbbx{display:inline-block;}.css-c0cbbx >:disabled{pointer-events:none;}.css-ik49mw{-webkit-flex-shrink:0;-ms-flex-negative:0;flex-shrink:0;}.css-ik49mw *:not([fill='none']){fill:inherit;}.css-ik49mw,.css-ik49mw image{width:24px;height:24px;}

DiscountCodePagedQueryResponse.css-c0cbbx{display:inline-block;}.css-c0cbbx >:disabled{pointer-events:none;}.css-ik49mw{-webkit-flex-shrink:0;-ms-flex-negative:0;flex-shrink:0;}.css-ik49mw *:not([fill='none']){fill:inherit;}.css-ik49mw,.css-ik49mw image{width:24px;height:24px;}

DiscountCodeReference.css-c0cbbx{display:inline-block;}.css-c0cbbx >:disabled{pointer-events:none;}.css-ik49mw{-webkit-flex-shrink:0;-ms-flex-negative:0;flex-shrink:0;}.css-ik49mw *:not([fill='none']){fill:inherit;}.css-ik49mw,.css-ik49mw image{width:24px;height:24px;}

DiscountCodeResourceIdentifier.css-c0cbbx{display:inline-block;}.css-c0cbbx >:disabled{pointer-events:none;}.css-ik49mw{-webkit-flex-shrink:0;-ms-flex-negative:0;flex-shrink:0;}.css-ik49mw *:not([fill='none']){fill:inherit;}.css-ik49mw,.css-ik49mw image{width:24px;height:24px;}

Get DiscountCode.css-c0cbbx{display:inline-block;}.css-c0cbbx >:disabled{pointer-events:none;}.css-ik49mw{-webkit-flex-shrink:0;-ms-flex-negative:0;flex-shrink:0;}.css-ik49mw *:not([fill='none']){fill:inherit;}.css-ik49mw,.css-ik49mw image{width:24px;height:24px;}

Get DiscountCode by ID.css-c0cbbx{display:inline-block;}.css-c0cbbx >:disabled{pointer-events:none;}.css-ik49mw{-webkit-flex-shrink:0;-ms-flex-negative:0;flex-shrink:0;}.css-ik49mw *:not([fill='none']){fill:inherit;}.css-ik49mw,.css-ik49mw image{width:24px;height:24px;}

Get DiscountCode by Key.css-c0cbbx{display:inline-block;}.css-c0cbbx >:disabled{pointer-events:none;}.css-ik49mw{-webkit-flex-shrink:0;-ms-flex-negative:0;flex-shrink:0;}.css-ik49mw *:not([fill='none']){fill:inherit;}.css-ik49mw,.css-ik49mw image{width:24px;height:24px;}

Query DiscountCodes.css-c0cbbx{display:inline-block;}.css-c0cbbx >:disabled{pointer-events:none;}.css-ik49mw{-webkit-flex-shrink:0;-ms-flex-negative:0;flex-shrink:0;}.css-ik49mw *:not([fill='none']){fill:inherit;}.css-ik49mw,.css-ik49mw image{width:24px;height:24px;}

Check if DiscountCode exists.css-c0cbbx{display:inline-block;}.css-c0cbbx >:disabled{pointer-events:none;}.css-ik49mw{-webkit-flex-shrink:0;-ms-flex-negative:0;flex-shrink:0;}.css-ik49mw *:not([fill='none']){fill:inherit;}.css-ik49mw,.css-ik49mw image{width:24px;height:24px;}

Check if DiscountCode exists by ID.css-c0cbbx{display:inline-block;}.css-c0cbbx >:disabled{pointer-events:none;}.css-ik49mw{-webkit-flex-shrink:0;-ms-flex-negative:0;flex-shrink:0;}.css-ik49mw *:not([fill='none']){fill:inherit;}.css-ik49mw,.css-ik49mw image{width:24px;height:24px;}

Check if DiscountCode exists by Key.css-c0cbbx{display:inline-block;}.css-c0cbbx >:disabled{pointer-events:none;}.css-ik49mw{-webkit-flex-shrink:0;-ms-flex-negative:0;flex-shrink:0;}.css-ik49mw *:not([fill='none']){fill:inherit;}.css-ik49mw,.css-ik49mw image{width:24px;height:24px;}

Check if DiscountCode exists by Query Predicate.css-c0cbbx{display:inline-block;}.css-c0cbbx >:disabled{pointer-events:none;}.css-ik49mw{-webkit-flex-shrink:0;-ms-flex-negative:0;flex-shrink:0;}.css-ik49mw *:not([fill='none']){fill:inherit;}.css-ik49mw,.css-ik49mw image{width:24px;height:24px;}

Create DiscountCode.css-c0cbbx{display:inline-block;}.css-c0cbbx >:disabled{pointer-events:none;}.css-ik49mw{-webkit-flex-shrink:0;-ms-flex-negative:0;flex-shrink:0;}.css-ik49mw *:not([fill='none']){fill:inherit;}.css-ik49mw,.css-ik49mw image{width:24px;height:24px;}

Update DiscountCode.css-c0cbbx{display:inline-block;}.css-c0cbbx >:disabled{pointer-events:none;}.css-ik49mw{-webkit-flex-shrink:0;-ms-flex-negative:0;flex-shrink:0;}.css-ik49mw *:not([fill='none']){fill:inherit;}.css-ik49mw,.css-ik49mw image{width:24px;height:24px;}

Update DiscountCode by ID.css-c0cbbx{display:inline-block;}.css-c0cbbx >:disabled{pointer-events:none;}.css-ik49mw{-webkit-flex-shrink:0;-ms-flex-negative:0;flex-shrink:0;}.css-ik49mw *:not([fill='none']){fill:inherit;}.css-ik49mw,.css-ik49mw image{width:24px;height:24px;}

Update DiscountCode by Key.css-c0cbbx{display:inline-block;}.css-c0cbbx >:disabled{pointer-events:none;}.css-ik49mw{-webkit-flex-shrink:0;-ms-flex-negative:0;flex-shrink:0;}.css-ik49mw *:not([fill='none']){fill:inherit;}.css-ik49mw,.css-ik49mw image{width:24px;height:24px;}

Update actions.css-c0cbbx{display:inline-block;}.css-c0cbbx >:disabled{pointer-events:none;}.css-ik49mw{-webkit-flex-shrink:0;-ms-flex-negative:0;flex-shrink:0;}.css-ik49mw *:not([fill='none']){fill:inherit;}.css-ik49mw,.css-ik49mw image{width:24px;height:24px;}

Set Key.css-c0cbbx{display:inline-block;}.css-c0cbbx >:disabled{pointer-events:none;}.css-ik49mw{-webkit-flex-shrink:0;-ms-flex-negative:0;flex-shrink:0;}.css-ik49mw *:not([fill='none']){fill:inherit;}.css-ik49mw,.css-ik49mw image{width:24px;height:24px;}

Set Name.css-c0cbbx{display:inline-block;}.css-c0cbbx >:disabled{pointer-events:none;}.css-ik49mw{-webkit-flex-shrink:0;-ms-flex-negative:0;flex-shrink:0;}.css-ik49mw *:not([fill='none']){fill:inherit;}.css-ik49mw,.css-ik49mw image{width:24px;height:24px;}

Set Description.css-c0cbbx{display:inline-block;}.css-c0cbbx >:disabled{pointer-events:none;}.css-ik49mw{-webkit-flex-shrink:0;-ms-flex-negative:0;flex-shrink:0;}.css-ik49mw *:not([fill='none']){fill:inherit;}.css-ik49mw,.css-ik49mw image{width:24px;height:24px;}

Set Cart Predicate.css-c0cbbx{display:inline-block;}.css-c0cbbx >:disabled{pointer-events:none;}.css-ik49mw{-webkit-flex-shrink:0;-ms-flex-negative:0;flex-shrink:0;}.css-ik49mw *:not([fill='none']){fill:inherit;}.css-ik49mw,.css-ik49mw image{width:24px;height:24px;}

Set Max Applications.css-c0cbbx{display:inline-block;}.css-c0cbbx >:disabled{pointer-events:none;}.css-ik49mw{-webkit-flex-shrink:0;-ms-flex-negative:0;flex-shrink:0;}.css-ik49mw *:not([fill='none']){fill:inherit;}.css-ik49mw,.css-ik49mw image{width:24px;height:24px;}

Set Max Applications Per Customer.css-c0cbbx{display:inline-block;}.css-c0cbbx >:disabled{pointer-events:none;}.css-ik49mw{-webkit-flex-shrink:0;-ms-flex-negative:0;flex-shrink:0;}.css-ik49mw *:not([fill='none']){fill:inherit;}.css-ik49mw,.css-ik49mw image{width:24px;height:24px;}

Set Custom Type.css-c0cbbx{display:inline-block;}.css-c0cbbx >:disabled{pointer-events:none;}.css-ik49mw{-webkit-flex-shrink:0;-ms-flex-negative:0;flex-shrink:0;}.css-ik49mw *:not([fill='none']){fill:inherit;}.css-ik49mw,.css-ik49mw image{width:24px;height:24px;}

Set CustomField.css-c0cbbx{display:inline-block;}.css-c0cbbx >:disabled{pointer-events:none;}.css-ik49mw{-webkit-flex-shrink:0;-ms-flex-negative:0;flex-shrink:0;}.css-ik49mw *:not([fill='none']){fill:inherit;}.css-ik49mw,.css-ik49mw image{width:24px;height:24px;}

Change CartDiscounts.css-c0cbbx{display:inline-block;}.css-c0cbbx >:disabled{pointer-events:none;}.css-ik49mw{-webkit-flex-shrink:0;-ms-flex-negative:0;flex-shrink:0;}.css-ik49mw *:not([fill='none']){fill:inherit;}.css-ik49mw,.css-ik49mw image{width:24px;height:24px;}

Change Groups.css-c0cbbx{display:inline-block;}.css-c0cbbx >:disabled{pointer-events:none;}.css-ik49mw{-webkit-flex-shrink:0;-ms-flex-negative:0;flex-shrink:0;}.css-ik49mw *:not([fill='none']){fill:inherit;}.css-ik49mw,.css-ik49mw image{width:24px;height:24px;}

Change IsActive.css-c0cbbx{display:inline-block;}.css-c0cbbx >:disabled{pointer-events:none;}.css-ik49mw{-webkit-flex-shrink:0;-ms-flex-negative:0;flex-shrink:0;}.css-ik49mw *:not([fill='none']){fill:inherit;}.css-ik49mw,.css-ik49mw image{width:24px;height:24px;}

Set Valid From.css-c0cbbx{display:inline-block;}.css-c0cbbx >:disabled{pointer-events:none;}.css-ik49mw{-webkit-flex-shrink:0;-ms-flex-negative:0;flex-shrink:0;}.css-ik49mw *:not([fill='none']){fill:inherit;}.css-ik49mw,.css-ik49mw image{width:24px;height:24px;}

Set Valid Until.css-c0cbbx{display:inline-block;}.css-c0cbbx >:disabled{pointer-events:none;}.css-ik49mw{-webkit-flex-shrink:0;-ms-flex-negative:0;flex-shrink:0;}.css-ik49mw *:not([fill='none']){fill:inherit;}.css-ik49mw,.css-ik49mw image{width:24px;height:24px;}

Set Valid From and Until.css-c0cbbx{display:inline-block;}.css-c0cbbx >:disabled{pointer-events:none;}.css-ik49mw{-webkit-flex-shrink:0;-ms-flex-negative:0;flex-shrink:0;}.css-ik49mw *:not([fill='none']){fill:inherit;}.css-ik49mw,.css-ik49mw image{width:24px;height:24px;}

Delete DiscountCode.css-c0cbbx{display:inline-block;}.css-c0cbbx >:disabled{pointer-events:none;}.css-ik49mw{-webkit-flex-shrink:0;-ms-flex-negative:0;flex-shrink:0;}.css-ik49mw *:not([fill='none']){fill:inherit;}.css-ik49mw,.css-ik49mw image{width:24px;height:24px;}

Delete DiscountCode by ID.css-c0cbbx{display:inline-block;}.css-c0cbbx >:disabled{pointer-events:none;}.css-ik49mw{-webkit-flex-shrink:0;-ms-flex-negative:0;flex-shrink:0;}.css-ik49mw *:not([fill='none']){fill:inherit;}.css-ik49mw,.css-ik49mw image{width:24px;height:24px;}

Delete DiscountCode by Key.css-c0cbbx{display:inline-block;}.css-c0cbbx >:disabled{pointer-events:none;}.css-ik49mw{-webkit-flex-shrink:0;-ms-flex-negative:0;flex-shrink:0;}.css-ik49mw *:not([fill='none']){fill:inherit;}.css-ik49mw,.css-ik49mw image{width:24px;height:24px;}

Representations

DiscountCode

DiscountCodeDraft

DiscountCodePagedQueryResponse

DiscountCodeReference

DiscountCodeResourceIdentifier

Get DiscountCode

Get DiscountCode by ID

Get DiscountCode by Key

Query DiscountCodes

Check if DiscountCode exists

Check if DiscountCode exists by ID

Check if DiscountCode exists by Key

Check if DiscountCode exists by Query Predicate

Create DiscountCode

Update DiscountCode

Update DiscountCode by ID

Update DiscountCode by Key

Update actions

Set Key

Set Name

Set Description

Set Cart Predicate

Set Max Applications

Set Max Applications Per Customer

Set Custom Type

Set CustomField

Change CartDiscounts

Change Groups

Change IsActive

Set Valid From

Set Valid Until

Set Valid From and Until

Delete DiscountCode

Delete DiscountCode by ID

Delete DiscountCode by Key