[go: up one dir, main page]

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.

MinLength2MaxLength256Pattern^[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.

isActive
Boolean

A DiscountGroup must be active for its CartDiscounts to be considered during discount application.

Defaulttrue
createdAt

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

createdByBETA

IDs and references that created the DiscountGroup.

lastModifiedAt

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

lastModifiedByBETA

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",
  "isActive": true,
  "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.

MinLength2MaxLength256Pattern^[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.

isActive
Boolean

A DiscountGroup must be active for its CartDiscounts to be considered during discount application.

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

DiscountGroupPagedQueryResponse

PagedQueryResult with results containing an array of DiscountGroup.
limit
Int
Default20Minimum0Maximum500
offset
Int
Number of elements skipped.
Default0Maximum10000
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

as
application/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",
  "isActive": true,
  "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

as
application/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",
  "isActive": true,
  "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

as
application/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",
      "isActive": true,
      "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 status if a DiscountGroup exists, or a 404 status otherwise.
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 status if a DiscountGroup exists, or a 404 status otherwise.
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 status if any DiscountGroups match the query predicate, or a 404 status otherwise.
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.
If the limit for active Discount Groups has been reached, a MaxDiscountGroupsReached 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.
Query parameters:
expand
The parameter can be passed multiple times.
Request Body:DiscountGroupDraftasapplication/json
Response:
201

DiscountGroup

as
application/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",
  "isActive" : true
}
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",
  "isActive": true,
  "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

Update actions to be performed on the DiscountGroup.

Response:
200

DiscountGroup

as
application/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": 2,
  "key": "black-friday-sale",
  "name": {
    "en": "Black Friday Sale"
  },
  "description": {
    "en": "10% discount on all items in cart"
  },
  "sortOrder": "0.01",
  "isActive": false,
  "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

Update actions to be performed on the DiscountGroup.

Response:
200

DiscountGroup

as
application/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": 2,
  "key": "black-friday-sale",
  "name": {
    "en": "Black Friday Sale"
  },
  "description": {
    "en": "10% discount on all items in cart"
  },
  "sortOrder": "0.01",
  "isActive": false,
  "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.

MinLength2MaxLength256Pattern^[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"
}

Set IsActive

This action generates the DiscountGroupIsActiveSet Message.
If the limit for active Discount Groups has been reached, a MaxDiscountGroupsReached error is returned.
action
String
"setIsActive"
isActive
Boolean

New value to set.

A DiscountGroup must be active for its CartDiscounts to be considered during discount application.

Example: json
{
  "action": "setIsActive",
  "isActive": false
}

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

as
application/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",
  "isActive": true,
  "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

as
application/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",
  "isActive": true,
  "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
  }
}