This is documentation preview demonstrates how to use Product Search with GraphQL, a feature that is currently in early access. This preview might not be in sync with our official documentation available on https://docs.commercetools.com.

Discount Groups

Group Cart Discounts and apply the best discount from the group to a cart.

A Discount Group is a container for multiple Cart Discounts. When used, it ensures that only the Cart Discount offering the highest savings (best deal) to the Customer is applied to a Cart. Each Discount Group can include up to 100 Cart Discounts, and each Project can have up to 100 Discount Groups.

Representations

DiscountGroup

id​
String​

Unique identifier of the DiscountGroup.

version​
Int​

Current version of the DiscountGroup.

key​
String​

User-defined unique identifier of the DiscountGroup.

MinLength: 2​MaxLength: 256​Pattern: ^[A-Za-z0-9_-]+$​
name​

Name of the DiscountGroup.

description​

Description of the DiscountGroup.

sortOrder​
String​
Value between 0 and 1 that determines the order in which the CartDiscount from the DiscountGroup is applied; a CartDiscount with a higher value is prioritized.

The sort order is unique among all DiscountGroups and CartDiscounts.

createdAt​
DateTime​

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

createdBy​BETA
CreatedBy​

IDs and references that created the DiscountGroup.

lastModifiedAt​
DateTime​

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

lastModifiedBy​BETA

IDs and references that last modified the DiscountGroup.

Example: json
{
  "id": "{{discount-group-id}}",
  "version": 1,
  "key": "black-friday-sale",
  "name": {
    "en": "Black Friday Sale"
  },
  "description": {
    "en": "10% discount on all items in cart"
  },
  "sortOrder": "0.01",
  "createdAt": "2024-11-21T13:08:15.962Z",
  "lastModifiedAt": "2024-11-21T13:08:15.962Z",
  "lastModifiedBy": {
    "clientId": "{{client-id}}",
    "isPlatformClient": false
  },
  "createdBy": {
    "clientId": "{{client-id}}",
    "isPlatformClient": false
  }
}

DiscountGroupDraft

key​
String​

User-defined unique identifier for the DiscountGroup.

MinLength: 2​MaxLength: 256​Pattern: ^[A-Za-z0-9_-]+$​
name​

Name of the DiscountGroup.

description​

Description for the DiscountGroup.

sortOrder​
String​
Value between 0 and 1 that determines the order in which the CartDiscount from the DiscountGroup will be applied; a CartDiscount with a higher value will be prioritized.

The sort order must be unique among all DiscountGroups and CartDiscounts.

Example: json
{
  "key": "black-friday-sale",
  "name": {
    "en": "Black Friday Sale"
  },
  "description": {
    "en": "10% discount on all items in cart"
  },
  "sortOrder": "0.01"
}

DiscountGroupPagedQueryResponse

PagedQueryResult with results containing an array of DiscountGroup.
limit​
Int​
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 DiscountGroup​

DiscountGroups matching the query.

DiscountGroupReference

id​
String​
Unique identifier of the referenced DiscountGroup.
typeId​
discount-group

Type of referenced resource.

obj​
Contains the representation of the expanded DiscountGroup. Only present in responses to requests with Reference Expansion for DiscountGroups.

DiscountGroupResourceIdentifier

ResourceIdentifier to a DiscountGroup. Either id or key is required. If both are set, an InvalidJsonInput error is returned.
id​
String​
Unique identifier of the referenced DiscountGroup. Required if key is absent.
key​
String​
User-defined unique identifier of the referenced DiscountGroup. Required if id is absent.
typeId​
discount-group
Type of referenced resource. If given, it must match the expected ReferenceTypeId of the referenced resource.

Get DiscountGroup

Get DiscountGroup by ID

GET
https://api.{region}.commercetools.com/{projectKey}/discount-groups/{id}
Retrieves a DiscountGroup with the provided id.
OAuth 2.0 Scopes:
view_cart_discounts:{projectKey}
Path parameters:
region
​
String
​
Region in which the Project is hosted.
projectKey
​
String
​
key of the Project.
id
​
String
​
id of the DiscountGroup.
Query parameters:
expand
​​
The parameter can be passed multiple times.
Response:
200

DiscountGroup

asapplication/json
Request Example:cURL
curl --get https://api.{region}.commercetools.com/{projectKey}/discount-groups/{id} -i \
--header "Authorization: Bearer ${BEARER_TOKEN}" 
200 Response Example: DiscountGroupjson
{
  "id": "{{discount-group-id}}",
  "version": 1,
  "key": "black-friday-sale",
  "name": {
    "en": "Black Friday Sale"
  },
  "description": {
    "en": "10% discount on all items in cart"
  },
  "sortOrder": "0.01",
  "createdAt": "2024-11-21T13:08:15.962Z",
  "lastModifiedAt": "2024-11-21T13:08:15.962Z",
  "lastModifiedBy": {
    "clientId": "{{client-id}}",
    "isPlatformClient": false
  },
  "createdBy": {
    "clientId": "{{client-id}}",
    "isPlatformClient": false
  }
}

Get DiscountGroup by Key

GET
https://api.{region}.commercetools.com/{projectKey}/discount-groups/key={key}
Retrieves a DiscountGroup with the provided key.
OAuth 2.0 Scopes:
view_cart_discounts:{projectKey}
Path parameters:
region
​
String
​
Region in which the Project is hosted.
projectKey
​
String
​
key of the Project.
key
​
String
​
key of the DiscountGroup.
Query parameters:
expand
​​
The parameter can be passed multiple times.
Response:
200

DiscountGroup

asapplication/json
Request Example:cURL
curl --get https://api.{region}.commercetools.com/{projectKey}/discount-groups/key={key} -i \
--header "Authorization: Bearer ${BEARER_TOKEN}" 
200 Response Example: DiscountGroupjson
{
  "id": "{{discount-group-id}}",
  "version": 1,
  "key": "black-friday-sale",
  "name": {
    "en": "Black Friday Sale"
  },
  "description": {
    "en": "10% discount on all items in cart"
  },
  "sortOrder": "0.01",
  "createdAt": "2024-11-21T13:08:15.962Z",
  "lastModifiedAt": "2024-11-21T13:08:15.962Z",
  "lastModifiedBy": {
    "clientId": "{{client-id}}",
    "isPlatformClient": false
  },
  "createdBy": {
    "clientId": "{{client-id}}",
    "isPlatformClient": false
  }
}

Query DiscountGroups

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

Retrieves all DiscountGroups in the Project.

OAuth 2.0 Scopes:
view_cart_discounts:{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
​
Default: 20​
Minimum: 0​
Maximum: 500​
offset
​
Int
​
Number of elements skipped.
Default: 0​
Maximum: 10000​
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
​
The parameter can be passed multiple times.
Response:
200

DiscountGroupPagedQueryResponse

asapplication/json
Request Example:cURL
curl --get https://api.{region}.commercetools.com/{projectKey}/discount-groups -i \
--header "Authorization: Bearer ${BEARER_TOKEN}" 
200 Response Example: DiscountGroupPagedQueryResponsejson
{
  "limit": 20,
  "offset": 0,
  "count": 1,
  "total": 1,
  "results": [
    {
      "id": "{{discount-group-id}}",
      "version": 1,
      "key": "black-friday-sale",
      "name": {
        "en": "Black Friday Sale"
      },
      "description": {
        "en": "10% discount on all items in cart"
      },
      "sortOrder": "0.01",
      "createdAt": "2024-11-21T13:08:15.962Z",
      "lastModifiedAt": "2024-11-21T13:08:15.962Z",
      "lastModifiedBy": {
        "clientId": "{{client-id}}",
        "isPlatformClient": false
      },
      "createdBy": {
        "clientId": "{{client-id}}",
        "isPlatformClient": false
      }
    }
  ]
}

Check if DiscountGroup exists

Check if DiscountGroup exists by ID

HEAD
https://api.{region}.commercetools.com/{projectKey}/discount-groups/{id}
Checks if a DiscountGroup exists with the provided id. Returns a 200 OK status if a DiscountGroup exists; otherwise, returns a Not Found.
OAuth 2.0 Scopes:
view_cart_discounts:{projectKey}
Path parameters:
region
​
String
​
Region in which the Project is hosted.
projectKey
​
String
​
key of the Project.
id
​
String
​
id of the DiscountGroup.
Response:
200
Request Example:cURL
curl --head https://api.{region}.commercetools.com/{projectKey}/discount-groups/{id} -i \
--header "Authorization: Bearer ${BEARER_TOKEN}" 

Check if DiscountGroup exists by Key

HEAD
https://api.{region}.commercetools.com/{projectKey}/discount-groups/key={key}
Checks if a DiscountGroup exists with the provided key. Returns a 200 OK status if a DiscountGroup exists; otherwise, returns a Not Found.
OAuth 2.0 Scopes:
view_cart_discounts:{projectKey}
Path parameters:
region
​
String
​
Region in which the Project is hosted.
projectKey
​
String
​
key of the Project.
key
​
String
​
key of the DiscountGroup.
Response:
200
Request Example:cURL
curl --head https://api.{region}.commercetools.com/{projectKey}/discount-groups/key={key} -i \
--header "Authorization: Bearer ${BEARER_TOKEN}" 

Check if DiscountGroup exists by Query Predicate

HEAD
https://api.{region}.commercetools.com/{projectKey}/discount-groups
Checks if one or more DiscountGroups exist for the provided query predicate. Returns a 200 OK status if any DiscountGroups match the query predicate; otherwise, returns a Not Found.
OAuth 2.0 Scopes:
view_cart_discounts:{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-groups -i \
--header "Authorization: Bearer ${BEARER_TOKEN}" 

Create DiscountGroup

POST
https://api.{region}.commercetools.com/{projectKey}/discount-groups
Creates a DiscountGroup in the Project. This request generates the DiscountGroupCreated Message.
OAuth 2.0 Scopes:
manage_cart_discounts:{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:DiscountGroupDraftasapplication/json
Response:
201

DiscountGroup

asapplication/json
Request Example:cURL
curl https://api.{region}.commercetools.com/{projectKey}/discount-groups -i \
--header "Authorization: Bearer ${BEARER_TOKEN}" \
--header 'Content-Type: application/json' \
--data-binary @- << DATA 
{
  "key" : "black-friday-sale",
  "name" : {
    "en" : "Black Friday Sale"
  },
  "description" : {
    "en" : "10% discount on all items in cart"
  },
  "sortOrder" : "0.01"
}
DATA
201 Response Example: DiscountGroupjson
{
  "id": "{{discount-group-id}}",
  "version": 1,
  "key": "black-friday-sale",
  "name": {
    "en": "Black Friday Sale"
  },
  "description": {
    "en": "10% discount on all items in cart"
  },
  "sortOrder": "0.01",
  "createdAt": "2024-11-21T13:08:15.962Z",
  "lastModifiedAt": "2024-11-21T13:08:15.962Z",
  "lastModifiedBy": {
    "clientId": "{{client-id}}",
    "isPlatformClient": false
  },
  "createdBy": {
    "clientId": "{{client-id}}",
    "isPlatformClient": false
  }
}

Update DiscountGroup

Update DiscountGroup by ID

POST
https://api.{region}.commercetools.com/{projectKey}/discount-groups/{id}
Updates a DiscountGroup in the Project using one or more update actions.
OAuth 2.0 Scopes:
manage_cart_discounts:{projectKey}
Path parameters:
region
​
String
​
Region in which the Project is hosted.
projectKey
​
String
​
key of the Project.
id
​
String
​
id of the DiscountGroup.
Query parameters:
expand
​​
The parameter can be passed multiple times.
Request Body:
application/json
version​
Int​
Expected version of the DiscountGroup 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 DiscountGroupUpdateAction​

Update actions to be performed on the DiscountGroup.

Response:
200

DiscountGroup

asapplication/json
Request Example:cURL
curl https://api.{region}.commercetools.com/{projectKey}/discount-groups/{id} -i \
--header "Authorization: Bearer ${BEARER_TOKEN}" \
--header 'Content-Type: application/json' \
--data-binary @- << DATA 
{
  "version" : 1,
  "actions" : [ {
    "action" : "setKey",
    "key" : "my-new-discount-group-key"
  } ]
}
DATA
200 Response Example: DiscountGroupjson
{
  "id": "{{discount-group-id}}",
  "version": 1,
  "key": "black-friday-sale",
  "name": {
    "en": "Black Friday Sale"
  },
  "description": {
    "en": "10% discount on all items in cart"
  },
  "sortOrder": "0.01",
  "createdAt": "2024-11-21T13:08:15.962Z",
  "lastModifiedAt": "2024-11-21T13:08:15.962Z",
  "lastModifiedBy": {
    "clientId": "{{client-id}}",
    "isPlatformClient": false
  },
  "createdBy": {
    "clientId": "{{client-id}}",
    "isPlatformClient": false
  }
}

Update DiscountGroup by Key

POST
https://api.{region}.commercetools.com/{projectKey}/discount-groups/key={key}
Updates a DiscountGroup in the Project using one or more update actions.
OAuth 2.0 Scopes:
manage_cart_discounts:{projectKey}
Path parameters:
region
​
String
​
Region in which the Project is hosted.
projectKey
​
String
​
key of the Project.
key
​
String
​
key of the DiscountGroup.
Query parameters:
expand
​​
The parameter can be passed multiple times.
Request Body:
application/json
version​
Int​
Expected version of the DiscountGroup 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 DiscountGroupUpdateAction​

Update actions to be performed on the DiscountGroup.

Response:
200

DiscountGroup

asapplication/json
Request Example:cURL
curl https://api.{region}.commercetools.com/{projectKey}/discount-groups/key={key} -i \
--header "Authorization: Bearer ${BEARER_TOKEN}" \
--header 'Content-Type: application/json' \
--data-binary @- << DATA 
{
  "version" : 1,
  "actions" : [ {
    "action" : "setKey",
    "key" : "my-new-discount-group-key"
  } ]
}
DATA
200 Response Example: DiscountGroupjson
{
  "id": "{{discount-group-id}}",
  "version": 1,
  "key": "black-friday-sale",
  "name": {
    "en": "Black Friday Sale"
  },
  "description": {
    "en": "10% discount on all items in cart"
  },
  "sortOrder": "0.01",
  "createdAt": "2024-11-21T13:08:15.962Z",
  "lastModifiedAt": "2024-11-21T13:08:15.962Z",
  "lastModifiedBy": {
    "clientId": "{{client-id}}",
    "isPlatformClient": false
  },
  "createdBy": {
    "clientId": "{{client-id}}",
    "isPlatformClient": false
  }
}

Update actions

Set Key

Setting a key generates the DiscountGroupKeySet Message.
action​
String​
"setKey"
key​
String​

New value to set.

MinLength: 2​MaxLength: 256​Pattern: ^[A-Za-z0-9_-]+$​
Example: json
{
  "action": "setKey",
  "key": "new-key"
}

Set Name

action​
String​
"setName"
name​

New 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 SortOrder

Setting the sort order generates the DiscountGroupSortOrderSet Message.
action​
String​
"setSortOrder"
sortOrder​
String​
New value to set (between 0 and 1). A CartDiscount with a higher value will be prioritized.

The sort order must be unique among all DiscountGroups and CartDiscounts.

Example: json
{
  "action": "setSortOrder",
  "sortOrder": "0.2"
}

Delete DiscountGroup

A DiscountGroup can only be deleted if it is not referenced by any CartDiscount.

Delete DiscountGroup by ID

DELETE
https://api.{region}.commercetools.com/{projectKey}/discount-groups/{id}
Deletes a DiscountGroup in the Project. This request generates the DiscountGroupDeleted Message.
If the DiscountGroup is referenced by a CartDiscount, a ReferenceExists error is returned.
OAuth 2.0 Scopes:
manage_cart_discounts:{projectKey}
Path parameters:
region
​
String
​
Region in which the Project is hosted.
projectKey
​
String
​
key of the Project.
id
​
String
​
id of the DiscountGroup.
Query parameters:
version
​
Int
​

Last seen version of the resource.

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

DiscountGroup

asapplication/json
Request Example:cURL
curl -X DELETE https://api.{region}.commercetools.com/{projectKey}/discount-groups/{id}?version={version} -i \
--header "Authorization: Bearer ${BEARER_TOKEN}"
200 Response Example: DiscountGroupjson
{
  "id": "{{discount-group-id}}",
  "version": 1,
  "key": "black-friday-sale",
  "name": {
    "en": "Black Friday Sale"
  },
  "description": {
    "en": "10% discount on all items in cart"
  },
  "sortOrder": "0.01",
  "createdAt": "2024-11-21T13:08:15.962Z",
  "lastModifiedAt": "2024-11-21T13:08:15.962Z",
  "lastModifiedBy": {
    "clientId": "{{client-id}}",
    "isPlatformClient": false
  },
  "createdBy": {
    "clientId": "{{client-id}}",
    "isPlatformClient": false
  }
}

Delete DiscountGroup by Key

DELETE
https://api.{region}.commercetools.com/{projectKey}/discount-groups/key={key}
Deletes a DiscountGroup in the Project. This request generates the DiscountGroupDeleted Message.
If the DiscountGroup is referenced by a CartDiscount, a ReferenceExists error is returned.
OAuth 2.0 Scopes:
manage_cart_discounts:{projectKey}
Path parameters:
region
​
String
​
Region in which the Project is hosted.
projectKey
​
String
​
key of the Project.
key
​
String
​
key of the DiscountGroup.
Query parameters:
version
​
Int
​

Last seen version of the resource.

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

DiscountGroup

asapplication/json
Request Example:cURL
curl -X DELETE https://api.{region}.commercetools.com/{projectKey}/discount-groups/key={key}?version={version} -i \
--header "Authorization: Bearer ${BEARER_TOKEN}"
200 Response Example: DiscountGroupjson
{
  "id": "{{discount-group-id}}",
  "version": 1,
  "key": "black-friday-sale",
  "name": {
    "en": "Black Friday Sale"
  },
  "description": {
    "en": "10% discount on all items in cart"
  },
  "sortOrder": "0.01",
  "createdAt": "2024-11-21T13:08:15.962Z",
  "lastModifiedAt": "2024-11-21T13:08:15.962Z",
  "lastModifiedBy": {
    "clientId": "{{client-id}}",
    "isPlatformClient": false
  },
  "createdBy": {
    "clientId": "{{client-id}}",
    "isPlatformClient": false
  }
}