23 June 2025
Composable Commerce
HTTP API
Announcement
Pricing and DiscountsLimitsMessages/SubscriptionsGraphQL
You can now ensure customers always receive the best available deal when multiple Cart Discounts (targeting line items) are active. With the new Discount Groups API, now in public beta, you can group Cart Discounts and automatically apply only the most beneficial discount from the group to the customer's cart.

Changes:

  • [API] Added Messages for Discount Groups.
  • [API] Added the discountGroup field to CartDiscount and CartDiscountDraft types in Cart Discounts API.
  • [API] Changed the sortOrder field of CartDiscountDraft type to optional.
  • [API] Added the Set DiscountGroup update action to Cart Discounts API.
  • [API] Added the ApplicationStoppedByGroupBestDeal enum to the DiscountCodeState type in Carts API.
  • [GraphQL API] Added the following types to the GraphQL schema: DiscountGroup, DiscountGroupDraft, DiscountGroupLimitWithCurrent, DiscountGroupLimitsProjection, DiscountGroupQueryResult, DiscountGroupUpdateAction, SetCartDiscountDiscountGroup, SetDiscountGroupKey, SetDiscountGroupName, SetDiscountGroupDescription SetDiscountGroupSortOrder, DiscountGroupCreated, DiscountGroupDeleted, DiscountGroupKeySet, DiscountGroupSortOrderSet.
  • [GraphQL API] Added the following fields to the Query type: discountGroup and discountGroups.
  • [GraphQL API] Added the following fields to the Mutation type: createDiscountGroup, updateDiscountGroup, deleteDiscountGroup.
  • [GraphQL API] Added the discountGroup and discountGroupRef fields to the CartDiscount type.
  • [GraphQL API] Added the discountGroup input field to CartDiscountDraft type.
  • [GraphQL API] Changed the CartDiscountDraft.sortOrder input field type from String! to String.
  • [GraphQL API] Added the setDiscountGroup input field to CartDiscountUpdateAction type.
  • [GraphQL API] Added the ApplicationStoppedByGroupBestDeal enum to DiscountCodeState type.
  • [GraphQL API] Added the discountGroups field to the ProjectCustomLimitsProjection type.

The following changes were introduced in terms of GraphQL SDL:

extend type Query {
"BETA: This feature can be subject to change and should be used carefully in production. https://docs.commercetools.com/api/contract#public-beta"
  discountGroup(
    "Queries with specified ID"
    id: String,

    "Queries with specified key"
    key: String): DiscountGroup

"BETA: This feature can be subject to change and should be used carefully in production. https://docs.commercetools.com/api/contract#public-beta"
    discountGroups(where: String, sort: [String!], limit: Int, offset: Int): DiscountGroupQueryResult!
}

extend type CartDiscount {
  "BETA: This feature can be subject to change and should be used carefully in production. https://docs.commercetools.com/api/contract#public-beta"
  discountGroup: DiscountGroup
  discountGroupRef: Reference
}

extend type Mutation {
  "BETA: This feature can be subject to change and should be used carefully in production. https://docs.commercetools.com/api/contract#public-beta"
  createDiscountGroup(
    "BETA: This feature can be subject to change and should be used carefully in production. https://docs.commercetools.com/api/contract#public-beta"
    draft: DiscountGroupDraft!): DiscountGroup

  "BETA: This feature can be subject to change and should be used carefully in production. https://docs.commercetools.com/api/contract#public-beta"
  deleteDiscountGroup(version: Long!,

    "Queries with specified ID"
    id: String,

    "Queries with specified key"
    key: String): DiscountGroup

"BETA: This feature can be subject to change and should be used carefully in production. https://docs.commercetools.com/api/contract#public-beta"
  updateDiscountGroup(version: Long!,

    "BETA: This feature can be subject to change and should be used carefully in production. https://docs.commercetools.com/api/contract#public-beta"
    actions: [DiscountGroupUpdateAction!]!,

    "Queries with specified ID"
    id: String,

    "Queries with specified key"
    key: String): DiscountGroup
}

extend input CartDiscountDraft {
  sortOrder: String
  "BETA: This feature can be subject to change and should be used carefully in production. https://docs.commercetools.com/api/contract#public-beta"
  discountGroup: ResourceIdentifierInput
}

extend input CartDiscountUpdateAction {
  setDiscountGroup: SetCartDiscountDiscountGroup
}

"BETA: This feature can be subject to change and should be used carefully in production. https://docs.commercetools.com/api/contract#public-beta"
type DiscountGroup implements Versioned {
id: String!
version: Long!
key: String!
sortOrder: String!
name(
"String is defined for different locales. This argument specifies the desired locale."
locale: Locale,

    "List of languages the client is able to understand, and which locale variant is preferred."
    acceptLanguage: [Locale!]): String
nameAllLocales: [LocalizedString!]
description(
"String is defined for different locales. This argument specifies the desired locale."
locale: Locale,

    "List of languages the client is able to understand, and which locale variant is preferred."
    acceptLanguage: [Locale!]): String
descriptionAllLocales: [LocalizedString!]
createdAt: DateTime!
lastModifiedAt: DateTime!
createdBy: Initiator
lastModifiedBy: Initiator
}

type DiscountGroupCreated implements MessagePayload {
  discountGroup: DiscountGroup!
  type: String!
}

type DiscountGroupDeleted implements MessagePayload {
  discountGroupId: String!
  type: String!
}

type DiscountGroupKeySet implements MessagePayload {
  key: String!
  discountGroupId: String!
  oldKey: String
  type: String!
}

type DiscountGroupSortOrderSet implements MessagePayload {
  sortOrder: String!
  discountGroupId: String!
  oldSortOrder: String
  type: String!
}

"BETA: This feature can be subject to change and should be used carefully in production. https://docs.commercetools.com/api/contract#public-beta"
input DiscountGroupDraft {
key: String!
sortOrder: String!
name: [LocalizedStringItemInputType!]
description: [LocalizedStringItemInputType!]
}

type DiscountGroupLimitWithCurrent implements LimitWithCurrent {
limit: Long
current: Long!
}

type DiscountGroupLimitsProjection {
totalActive: DiscountGroupLimitWithCurrent!
}

type DiscountGroupQueryResult {
offset: Int!
count: Int!
total: Long!
exists: Boolean!
results: [DiscountGroup!]!
}

"BETA: This feature can be subject to change and should be used carefully in production. https://docs.commercetools.com/api/contract#public-beta"
input DiscountGroupUpdateAction {
setKey: SetDiscountGroupKey
setSortOrder: SetDiscountGroupSortOrder
setName: SetDiscountGroupName
setDescription: SetDiscountGroupDescription
}

input SetCartDiscountDiscountGroup {
discountGroup: ResourceIdentifierInput
sortOrder: String
}
"BETA: This feature can be subject to change and should be used carefully in production. https://docs.commercetools.com/api/contract#public-beta"
input SetDiscountGroupDescription {
description: [LocalizedStringItemInputType!]
}

"BETA: This feature can be subject to change and should be used carefully in production. https://docs.commercetools.com/api/contract#public-beta"
input SetDiscountGroupKey {
key: String!
}

"BETA: This feature can be subject to change and should be used carefully in production. https://docs.commercetools.com/api/contract#public-beta"
input SetDiscountGroupName {
name: [LocalizedStringItemInputType!]
}

"BETA: This feature can be subject to change and should be used carefully in production. https://docs.commercetools.com/api/contract#public-beta"
input SetDiscountGroupSortOrder {
sortOrder: String!
}