RFC: Pricing API improvements

[korycins]

Problem

Saleor users could have their external service responsible for managing the current prices of the product. External systems can be responsible for setting up the standard prices and discounted ones. Currently, to sync prices between Saleor and external price provider, there is a need to convert discounted prices into Sales or Promotions. This causes an additional logic required from App responsible for syncing, as the App needs to convert discountedPrice into Sale/Promotion. Additionally from Saleor side, this approach could cause a high load on the async workers responsible for re-calculating the prices on Saleor side based on the active promotions. Providing pricing API should solve the problem by reducing the number of steps that need to be done to provide a discounted price.

1. General Assumptions

The below chart quickly shows an example of steps required to simply modify the product’s discountedPrice in case of having an external price service:

sequenceDiagram
		ExternalDiscountService ->> ExternalDiscountService: Get discounted<br>price of product
		ExternalDiscountService ->> ExternalDiscountService: Calculate discount amount
    ExternalDiscountService->>+Saleor: Create promotion<br>rule for<br> single product,<br>with calculated<br>discount amount
    Saleor -->>- ExternalDiscountService: Promotion created
    Saleor ->> Saleor: Recalculate relation<br>between products<br>and promotions
    Saleor ->> Saleor: Recalculate prices<br>for discounted<br>products

As a solution, we aim to reduce the number of required steps by providing an API that would handle scenarios such as the one above. The chart below shows the same scenario as above but using the proposed API:

sequenceDiagram
		ExternalDiscountService ->> ExternalDiscountService: Get discounted<br>price of product
    ExternalDiscountService->>+Saleor: Update discounted price of product
    Saleor -->>- ExternalDiscountService: Price updated

Based on new channel settings we will determine if the promotions should be included in the channel. If not, the re-calculation will be skipped for such channels. Extended API for updating the product-variant-channel-listing will allow providing the discounted price (only when the channel setting flag is set to CUSTOM).

2. API changes

Types

enum DiscountingPriceStrategyEnum {
  """Set as default. Existing promotions on Saleor side will be used to 
  calculate a discounted price of products."""
  PROMOTION
  """Existing promotions will not have an impact on discounted price of 
  products. Discounted prices will need to be updated by external service."""
  CUSTOM
}
type PricingSettings {
	discountingPriceStrategy: DiscountingPriceStrategyEnum!
}
type Channel {
    """Requires manage_channel or manage_products permission"""
    pricingSettings: PricingSettings!
}

Mutations

input PricingSettingsInput @doc(category: "Payments") {
	discountingPriceStrategy: DiscountingPriceStrategyEnum
}

input ChannelCreateInput @doc(category: "Channels") {
    """Requires manage_channel or manage_products permission"""
	pricingSettings: PricingSettingsInput
}

input ChannelUpdateInput @doc(category: "Channels") {
    """Requires manage_channel or manage_products permission"""
	pricingSettings: PricingSettingsInput
}

input ProductVariantChannelListingAddInput @doc(category: "Products") {
  """Discounted price of the particular variant in channel. 
  Can be provided only when `channel.pricingSettings.discountingPriceStrategy` set to `CUSTOM`."""
  discountedPrice: PositiveDecimal!
}

3. Database changes

class Channel(ModelWithMetadata):
    discounting_price_strategy = models.CharField(
        max_length=128,
        choices=DiscountingPriceStrategy.CHOICES,
        default=DiscountingPriceStrategy.PROMOTION,
    )

4. UML diagrams

No response

5. To Do list

• Update docs to explain discounting-price-strategy
• migrations are zero-downtime
• add new settings to the channel
• extend the product-variant-channel-listing input to allow adding discountedPrice
  • add mandatory validation like discounted cannot be higher than normal price (also take into account the price from input)
  • providing a bigger price than discountedPrice should raise an exception
  • discountedPrice cannot be provided when the channel setting says that promotion engine is used for a channel. The proper error with proper code (probably the new one) should be raised.
• The logic responsible for price re-calculation based on promotion should skip pricing re-calculation for channels with discountingPriceStrategy set to CUSTOM
• When switching from CUSTOM to PROMOTION, the prices for products in the given channel should be marked as dirty - to recalculate the prices based on existing promotions.
• When switching from PROMOTION to CUSTOM, all products for the given channel should be marked as not dirty.
• Create a dashboard task to mark channels with CUSTOM, on promotion detail view

6. To Test

• when discountingPriceStrategy set to PROMOTION, the existing promotions are used to calculate the discountedPrice
• when discountingPriceStrategy set to CUSTOM, the existing promotions don’t have an impact on discountedPrice
• when switching from CUSTOM to PROMOTION, the existing promotions should be used to re-calculate the discounted price
• providing discountedPrice > price should not be possible
• discountedPrice can be only provided when discountingPriceStrategy is set to CUSTOM
• discountedPrice can be provided as an input for single&bulk mutations

---

Link to internal doc: https://www.notion.so/saleor/Price-lists-price-versioning-46358d97f1ff4ce98aca494364e8495f

[yellowee]

@korycins

1. What exactly triggers the update of prices? Would it be initiated by Saleor or by the external service? Can it be triggered manually on both sides?
2. When switching discountingPriceStrategy from CUSTOM to PROMOTION would the existing discounted prices be overwritten by the calculated promotion prices?
3. Would it be possible to get conflicting prices between the external service and existing promotions when transitioning from CUSTOM to PROMOTION? How would we handle it?
4. When skipping recalculations for channels with CUSTOM strategy would this apply to all price changes, or only those initiated through the new API?
5. How would manual price changes or updates be handled in CUSTOM channels?
6. How discountingPriceStrategy interacts with tax calculations?
7. How changing channel discountingPriceStrategy would affect existing orders and checkouts?
8. How discountingPriceStrategy would affect products which are available in both CUSTOM and PROMOTION channels?
9. What should happen if multiple requests attempt to update the same product's discounted price simultaneously?
10. Would the API support multiple currencies?
11. In case of failures or errors during the price update process, would there be any fallback mechanism?
12. What about the backwards compatibility?
13. How will the pricing API support multiple tenants each with their own external pricing system?

[fowczarek]

In my opionion one missing part is some kind of indicator on PromotionListView and PromotionVirew marking promotions assigned to the channel with CUSTOM as a discount strategy.

The idea behind this change is to minimalize support issues when someone creates a promotion for the channel with a CUSTOM discount strategy and raises the issue that the promotion not working.

[korycins]

Yes, you're right. It would be good to have such info on promotion view. I've added point to todo list, to create the task for that.
For now, we will use data from rules.channels, to get the info about current pricing strategy. If there will be a need, we will extend the PromotionRule type to provide this data separately.

[korycins]

@yellowee

What exactly triggers the update of prices? Would it be initiated by Saleor or by the external service? Can it be triggered manually on both sides?

It depends. For CUSTOM, your external service is responsible for updating the discountedPrice on Saleor side. For PROMOTION, the update system is already implemented. It is done in the background by async tasks scheduled by celery beat. In that case, any change in promotion, sale, product, category, etc will mark a product as dirty - which means, that we need to re-calculate the prices.

When switching discountingPriceStrategy from CUSTOM to PROMOTION would the existing discounted prices be overwritten by the calculated promotion prices?

Yeap, it is already covered by a point in to-do list: When switching from CUSTOM to PROMOTION, the prices for products in the given channel should be marked as dirty - to recalculate the prices based on existing promotions.

Would it be possible to get conflicting prices between the external service and existing promotions when transitioning from CUSTOM to PROMOTION? How would we handle it?

No, it will not be possible. The mutation input will be blocked when using PROMOTION. It is already added to to-do list discountedPrice cannot be provided when the channel setting says that promotion engine is used for a channel. The proper error with the proper code (probably the new one) should be raised.

When skipping recalculations for channels with CUSTOM strategy would this apply to all price changes, or only those initiated through the new API?

When setting the CUSTOM, we will skip the logic responsible for updating the discountedPrice of the product/variant for this channel. Your external system will be responsible for updating the prices.

How would manual price changes or updates be handled in CUSTOM channels?

CUSTOM is related only to discountedPrice. This field is not available on API yet, so there is no way of modifying the discountedPrice without adding new Promotion. The rest of the fields price, costPrice will work in the same way, as it is not related to these changes.

How discountingPriceStrategy interacts with tax calculations?

it won't interact. It is the way of calculating the discountedPrice. The usage of this field will be the same as it is now.

How changing channel discountingPriceStrategy would affect existing orders and checkouts?

When re-calculating the expired prices, the variant's discountedPrice will be used. It will work in the same way as previously. discountingPriceStrategy defines the way of updating discountedPrice field. The usage in all cases will be the same as previously.

How discountingPriceStrategy would affect products that are available in both CUSTOM and PROMOTION channels?

Products for channel with PROMOTION will have a discountedPrice calculated based on existing promotions. For channels with CUSTOM, discountedPrice will not be updated by Saleor, only by external service.

What should happen if multiple requests attempt to update the same product's discounted price simultaneously?

The value from the latest request will be saved as discountedPrice.

Would the API support multiple currencies?

The new field will work in the same way as it is working for price field. We don't allow you to provide currency, as currency is already set on the assigned channel.

In case of failures or errors during the price update process, would there be any fallback mechanism?

We don't have any fallbacks for failing mutations. If mutation fails for some reason, this needs to be handled by an external service.

What about the backwards compatibility?

By default, it works as previously. To change the behavior, you need to change the strategy to CUSTOM. PROMOTION is set as default. Mentioned in Types section.

How will the pricing API support multiple tenants each with their own external pricing system?

I don't know if I understand the correlation here. We provide an API that would allow you to control the discountedPrice. This allows you to control discounted prices by your external system. If you have multiple price providers, then you will probably need to build a proxy app, or handle the case in a different way.

[yellowee]

Thank you for your extensive explanation, it clarifies all my doubts!

--> QA approved.

[timuric]

@korycins would vouchers work on channels with CUSTOM mode?

[korycins]

Yes, it will not have an impact on vouchers logic.

[timuric]

I see a few problematic scenarios:

• External source has only some products as an override. This means that we create the opposite problem, where discounts need to be converted to static lists. We get the same problem but the other way around.
• Transient state. It is only possible to batch all changes at once when you from PROMOTION to CUSTOM mode. Let's say after the Black Friday event there is a new list of prices for Cyber Monday, the only way to batch updates is to set the mode from CUSTOM to PROMOTION, update all the prices, and set back to CUSTOM. For use cases when prices are only managed externally there will be no mechanism for applying changes all at once, which is problematic for campaign management.

[timuric]

Perhaps CUSTOM can be called MANUAL as both modes are somehow custom

[timuric]

Or perhaps more explicit would be WITHOUT_PROMOTIONS