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.

Note: When you create, update, or remove a discount, 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.
  • createdAt - DateTime
  • lastModifiedAt - DateTime
  • 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
  • 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 Money
    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 by ID

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

Query ProductDiscounts

Endpoint: /{projectKey}/product-discounts
Method: GET
OAuth2 Scopes: view_products:{projectKey}
Response Representation: PagedQueryResult with the results array of ProductDiscount
Query Parameters:

Create a ProductDiscount

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

Update ProductDiscount

Endpoint: /{projectKey}/product-discounts/{id}
Method: POST
OAuth2 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 Actions

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

  • action - String - "setDescription"
  • description - LocalizedString - Optional

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

Endpoint: /{projectKey}/product-discounts/{id}
Method: DELETE
OAuth2 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
OAuth2 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: