Documentation

Product Discounts

Product discounts reduce certain product prices.

The commercetools platform stores product discounts in the discounted field of the Product Price. This makes product discounts useful for scenarios when you want to display a discounted price before adding an item to the cart.

The maximum number of ProductDiscounts that can be active at the same time is 500.

Only one ProductDiscount can apply to a product at any given time. If more than one product discount matches a price, the sortOrder determines which one applies.

When you create, update, or remove a discount, it can take up to 15 minutes to update all the prices with the discounts. For more information, see Eventual Consistency.

Representations

ProductDiscount

  • id - String
    The unique ID of the product discount
  • version - Number
    The current version of the product discount.
  • key - String - Optional User-specific unique identifier for a product discount. Must be unique across a project.
  • createdAt - DateTime
  • createdBy - CreatedBy BETA
    Present on resources created after 2019-02-01 except for events not tracked.
  • lastModifiedAt - DateTime
  • lastModifiedBy - LastModifiedBy BETA
    Present on resources updated after 2019-02-01 except for events not tracked.
  • name - LocalizedString
  • description - LocalizedString - Optional
  • value - ProductDiscountValue
  • predicate - String
    A valid ProductDiscount Predicate.
  • sortOrder - String
    The string contains a number between 0 and 1. A discount with greater sortOrder is prioritized higher than a discount with lower sortOrder. A sortOrder must be unambiguous.
  • isActive - Boolean
    Only active discount will be applied to product prices.
  • validFrom - DateTime - Optional
    The time from which the discount should be effective. Please take Eventual Consistency into account for calculated product discount values.
  • validUntil - DateTime - Optional
    The time from which the discount should be ineffective. Please take Eventual Consistency into account for calculated undiscounted values.
  • references - Array of Reference
    The platform will generate this array from the predicate. It contains the references of all the resources that are addressed in the predicate.

ProductDiscountDraft

  • name - LocalizedString
  • key - String - Optional
    User-defined unique identifier for the ProductDiscount. Keys can only contain alphanumeric characters (a-Z, 0-9), underscores and hyphens (_, -) and be between 2 and 256 characters.
  • description - LocalizedString - Optional
  • value - ProductDiscountValue
  • predicate - String
    A valid ProductDiscount Predicate.
  • sortOrder - String
    The string must contain a decimal number between 0 and 1. A discount with greater sortOrder is prioritized higher than a discount with lower sortOrder.
  • isActive - Boolean
    If set to true the discount will be applied to product prices.
  • validFrom - DateTime - Optional
    The time from which the discount should be effective. Please take Eventual Consistency into account for calculated product discount values.
  • validUntil - DateTime - Optional
    The time from which the discount should be effective. Please take Eventual Consistency into account for calculated undiscounted values.

ProductDiscountValue

Defines discount type with the corresponding value. The type can be relative, absolute or external.

Relative

Discounts the product price by a percentage, defined by the permyriad field.

  • type - relative
  • permyriad - Number
    Per ten thousand. The fraction the price is reduced. 1000 will result in a 10% price reduction.

Absolute

Discounts the product price by a fixed amount, defined by the money field.

  • type - absolute
  • money - Array of CentPrecisionMoney
    The array contains money values in different currencies. An absolute ProductDiscount will only match a price if this array contains a value with the same currency. If it contains 10€ and 15$, for example, the matching € price will be decreased by 10€ and the matching $ price will be decreased by 15$.

External

Discounts the product price by allowing the client to explicitly set a discounted value. Use this value when setting discounts using an external service.

  • type - external

Get ProductDiscount

Get ProductDiscount by ID

Endpoint: /{projectKey}/product-discounts/{id}
Method: GET
OAuth 2.0 Scopes: view_products:{projectKey}
Response Representation: ProductDiscount

Get ProductDiscount by Key

Endpoint: /{projectKey}/product-discounts/key={key}
Method: GET
OAuth 2.0 Scopes: view_products:{projectKey}
Response Representation: ProductDiscount

Query ProductDiscounts

Endpoint: /{projectKey}/product-discounts
Method: GET
OAuth 2.0 Scopes: view_products:{projectKey}
Response Representation: PagedQueryResult with results containing an array of ProductDiscount
Query Parameters:

Create a ProductDiscount

Endpoint: /{projectKey}/product-discounts
Method: POST
OAuth 2.0 Scopes: manage_products:{projectKey}
Request Representation: ProductDiscountDraft
Response Representation: ProductDiscount

Update ProductDiscount

Update ProductDiscount by ID

Endpoint: /{projectKey}/product-discounts/{id} Method: POST
OAuth 2.0 Scopes: manage_products:{projectKey}
Response Representation: ProductDiscount
Fields:

  • version - Number - Required
    The expected version of the ProductDiscount on which the changes should be applied. If the expected version does not match the actual version, a 409 Conflict will be returned.
  • actions - Array of UpdateAction - Required
    The list of update actions to be performed on the ProductDiscount.

Update ProductDiscount by Key

Endpoint: /{projectKey}/product-discounts/key={key}
Method: POST
OAuth 2.0 Scopes: manage_products:{projectKey}
Response Representation: ProductDiscount Fields:

  • version - Number - Required
    The expected version of the ProductDiscount on which to apply the changes. If the expected version does not match the actual version, a 409 Conflict is returned.
  • actions - Array of UpdateAction - Required
    The list of update actions to perform on the ProductDiscount.

Update actions

Set Key

Sets a ProductDiscount's key field. The key must be unique across the project.

  • action - String - "setKey"
  • key - String - Optional If key is absent or null, the existing key, if any, will be removed.

Change Value

Change Predicate

Change Is Active

  • action - String - "changeIsActive"
  • isActive - Boolean

Set Valid From

  • action - String - "setValidFrom"
  • validFrom - DateTime - Optional
    The time from which the discount should be effective. Please take Eventual Consistency into account for calculated product discount values.

Set Valid Until

  • action - String - "setValidUntil"
  • validUntil - DateTime - Optional
    The time from which the discount should be ineffective. Please take Eventual Consistency into account for calculated undiscounted values.

Set Valid From and Until

  • action - String - "setValidFromAndUntil"
  • validFrom - DateTime - Optional
  • validUntil - DateTime - Optional
    The timeframe for which the discount should be effective. Please take Eventual Consistency into account for calculated undiscounted values.

Change Name

Set Description

Change Sort Order

  • action - String - "changeSortOrder"
  • sortOrder - String
    The string must contain a number between 0 and 1. A discount with greater sortOrder is prioritized higher than a discount with lower sortOrder.

Delete ProductDiscount

Delete ProductDiscount by ID

Endpoint: /{projectKey}/product-discounts/{id}
Method: DELETE
OAuth 2.0 Scopes: manage_products:{projectKey} Query Parameters:

  • version - Number - Required

Delete ProductDiscount by Key

Endpoint: /{projectKey}/product-discounts/key={key}
Method: DELETE
OAuth 2.0 Scopes: manage_products:{projectKey}
Query Parameters:

  • version - Number - Required

Get Matching ProductDiscount

This endpoint can be used to simulate which product discounts would be applied if a specified product variant had a specified price. Given product and variant ids and a price, this endpoint will return the product discount that would have been applied to that price.

Endpoint: /{projectKey}/product-discounts/matching
Method: POST
OAuth 2.0 Scopes: view_products:{projectKey}
Response Representation: ProductDiscount

Fields:

  • productId - UUID
    ID of the product
  • variantId - Integer
    ID of the variant
  • staged - Boolean
    Whether to use the staged version of this variant or the published one
  • price - Price - Required

Specific Error Codes: