Pricing and discounts APIs overview

Ask about this Page
Copy for AI
View as Markdown

How to work with the APIs for product pricing and discounts.

This page describes rules that apply across the pricing and discounts APIs. For what Prices and Discounts are and how they behave, see the Pricing and discounts overview.

APIs in this topic

ResourcePurposeReference
Standalone PricesStore your product prices as standalone resources, especially with a large number of prices.Standalone Prices
Product DiscountsReduce certain Product Prices.Product Discounts
Cart DiscountsChange the Prices of different elements within a Cart.Cart Discounts
Discount CodesGive specific Cart Discounts to eligible Customers.Discount Codes
Discount GroupsGroup Cart Discounts and apply the best discount from the group to a Cart.Discount Groups

Data model

  • For Embedded Prices, the discounted value is stored in the Price discounted field.
  • For Standalone Prices, the discounted value is stored in the StandalonePrice and StagedStandalonePrice discounted fields.

Working with the APIs

Price modes

The Product priceMode determines the type of Price used for a Product Variant. If the priceMode is not set, as a default, Product Variants use Embedded Prices.
  • For existing Products using Embedded Prices, use the Set PriceMode update action to change the price mode.
  • For new Products, create a Product with priceMode as Standalone.

Embedded Prices

Embedded Prices are stored within a ProductVariant, and are associated to it through its prices field.
Embedded Prices are managed and queried using the Products API. You can add Prices when creating a Product, or manage Prices of an existing Product using the Add Price, Set Prices, Change Price, or Remove Price update actions.

Standalone Prices

Standalone Prices are managed and queried using the Standalone Prices API, independent from your Products, thus contributing to better query performance.

External Prices

Since external prices are not part of the product catalog, they are not available on the Product Search API as well as the Product Projection Search API for filtering, faceting, or sorting products by price.
You can set an external price for the Line Item when creating or updating a Cart using the following actions: Add LineItem, Remove LineItem, Change LineItem Quantity, Set LineItem Price, or Set LineItem TotalPrice.
If the LineItem's priceMode is ExternalPrice, set the externalPrice value. The totalPrice of the LineItem is automatically calculated by multiplying the externalPrice by the quantity.
If the LineItem's priceMode is ExternalTotal, set the externalTotalPrice value (unit price multiplied by the quantity). The totalPrice of the LineItem is set from the value defined in externalTotalPrice.

Your code should be able to find the correct prices to display on your storefront and set the Line Item price when it's added to a Cart.

Tiered pricing

When the PriceTier minimumQuantity is reached, the Price tier is applied for the entire quantity of a Product Variant added as Line Item to a Cart.

Price selection in API responses

Both types of price selection add the additional price field to the ProductVariant and LineItem respectively in API responses. The price field is not populated for ShoppingListLineItem because price selection is not supported in the Shopping List context.
The returned ProductVariant price field—added in API responses—contains the Price that matches most of the Price-selection parameters.
The price is shown only when the timestamp of the request is within validFrom and validUntil range of Embedded Price or StandalonePrice.
  • Line Item price selection: When you create a Cart or add a LineItem to a Cart, the price is determined by the Carts API based on the following parameters:
    • Cart currency: maps to value.currencyCode of Price or StandalonePrice
    • Cart customerGroup: maps to customerGroup of Price or StandalonePrice
    • LineItemDraft distributionChannel: maps to channel of Price or StandalonePrice
    • Cart country: maps to country of Price or StandalonePrice
    • Customer customerGroupAssignments: maps to customerGroup of Price or StandalonePrice. For more information, see Fallback logic for multiple Customer Groups.
    • Business Unit customerGroupAssignments: maps to customerGroup of Price or StandalonePrice. For more information, see Fallback logic for multiple Customer Groups.
      Both businessUnit.customerGroupAssignments and cart.businessUnit fields must be defined (non-null) for B2B-specific prices to apply on the cart; otherwise, the platform selects B2C-specific prices.
      • If the Business Unit customerGroupAssignments field is an empty list ([]), the base price applies as no Customer Group-specific prices are available.
      • If the Business Unit customerGroupAssignments field is not set, the Cart customerGroup and Customer customerGroupAssignments fields are used (as a fallback) to determine eligible Customer Groups, provided the Cart has a customerId. If no customerId is set, the base price applies.

Product Discounts

If multiple active Product Discounts match a Price, then the ProductDiscount sortOrder determines which one applies.
Product Discounts are managed and queried using the Product Discounts API.
To use external discounts, set the ProductDiscountDraft value to external.

Cart Discounts

Cart Discounts can be used to discount different elements of a Cart, some of which include:

Gift Line Items are ignored by MultiBuyLineItemsTarget and CartDiscountPatternTarget discounts.
Cart Discounts can be defined globally for a Project, or be specific to one or more Stores in a Project. In the latter case, the Discount is only applied to Carts that belong to one of the Stores referenced in the CartDiscount stores array. If the array is empty or unspecified, the Discount applies (globally) to all Carts.
You can avoid applying further Cart Discounts to the Cart by setting the stackingMode to StopAfterThisDiscount on the CartDiscount that must be applied last.
The stacking mode does not control free shipping as defined via freeAbove on a ShippingRate. To avoid unwanted scenarios, we highly recommend not using Cart Discounts on shipping target and freeAbove together.
Cart Discounts are managed and queried using the Cart Discounts API.
Cart Discounts are recalculated every time a Discount Code, LineItem, or CustomLineItem is added or removed from a Cart, or when an Order is created from a Cart.

Discount Codes

Discount Codes are managed and queried using the Discount Codes API.

Discount Groups

You can only group Cart Discounts if they are not specific to a Store and they target Line Items (that is, CartDiscounts with target as lineItems, customLineItems, multiBuyLineItems, multiBuyCustomLineItems, or pattern).
To remove a Cart Discount from a Discount Group, use the Set DiscountGroup action and set the sort order for the Cart Discount again.
Discounts Groups are managed and queried using the Discount Groups API.

Direct Discounts

Direct Discounts are always active and valid, use the default StackingMode Stacking, and do not have a sorting order. They apply in the order listed in the directDiscounts array of the Cart or Order.
For all three discount types to coexist, directDiscountsIgnoreCartDiscounts must be false on the Cart.
To avoid losing a negotiated reduction, participateInBestDealSelection must be set to false on the DirectDiscountDraft.
To update or add Direct Discounts to an Order, use the Set DirectDiscounts update action.

Discount combination mode

In the BestDeal DiscountCombinationMode, Product Discounts and Cart Discounts can both be present on the same Cart, but only one discount type applies per Line Item.
The discount combination mode for a Cart and for an Order is indicated in the discountTypeCombination field.

Eventual consistency

When you create, update, or delete a Product Discount, the Prices are updated in an eventually consistent manner. Both Embedded Prices and StandalonePrices associated to a ProductVariant are updated, regardless of the Product's priceMode value.

The time to update can vary—between a fraction of a second to several hours—depending on the following factors:

  • The number of Products and their size
  • The number of Products affected by Discount predicates
  • The number of Prices to be updated

Limits

With Embedded Prices, you can store up to 100 Prices for each Product Variant. For more flexibility with pricing your products with higher limits, see Standalone Prices.

When using Embedded Prices, keep the JSON document size in mind. A Product and all its Prices are stored in a single JSON document. As Price count and Product Type complexity grow, you may approach the document size limit.

A maximum number of 50 000 Standalone Prices can be specified per ProductVariant. This is a soft limit that can be increased per Project after a performance impact review. See Limit increase guidance.
Product Discounts are subject to a limit in a Project.
Cart Discounts are subject to a limit in a Project.
A DiscountCode can apply up to 10 CartDiscounts.
Discount Groups are subject to a limit in a Project.
Discount Codes are subject to a limit in a Project.