Discount Applications exposes line level discounts on the Order API

[Ryan]

Hi!

If you missed it at Unite this year, we've exposed line level discount information on the Order API with a new readable property: discount_applications.  Take a look at the updated Order API reference for all of the details.  This feature will enable more accurate accounting when discounts are involved in orders.

We look forward to seeing what features this enables, as always please leave questions and comments in the thread below.

Shopify Apps Team

[HunkyBill]

Quick Question:

item.price is static as the variant price. Always has been. Always will be. 

item.price less the total of the item's discount_allocations amounts will be the subtotal for the item used for the purpose of taxes?

So if an item is subject to VAT, to know the true item price, we have to do the following:

add up all the discount_allocation amounts. Subtract that from the line item price. Now remove VAT and we would know the price of the item without taxes. 

Correct? In other words, we can do the math now to ensure when dealing with taxes and discounts, we know the whole story for line item pricing now?

[Félix]

add up all the discount_allocation amounts. Subtract that from the line item price. Now remove VAT and we would know the price of the item without taxes. 

Yes!

If the tax is included in the line item price, this is how you proceed to know the amount paid by the customer without taxes for the line item. 

(quantity * price) - sum of discount allocations - VAT

If the tax is not included, you simply substract the sum of discount_allocations amounts from the line item total price.

(quantity * price) - sum of discount allocations

Correct? In other words, we can do the math now to ensure when dealing with taxes and discounts, we know the whole story for line item pricing now?

Correct!

[HunkyBill]

Ahhh you do bring up an interesting point. Always ensure the line item price is multiplied by quantity as the subtotal there, since the discount allocations amounts will be applied not per line item, but per total quantity purchased of that line item. 

In other words, we do not have to worry that a discount was applied  to just **one** or **two** of a quantity of three purchased of a line item, we can safely assume that whatever the total of the discount allocations amounts to, that amount applies to the total quantity purchased. 

[Félix]

In other words, we do not have to worry that a discount was applied on just one or two of a quantity of three purchased of a line item, we can safely assume that whatever the total of the discount allocations amounts is, it applies to the total quantity purchased. 

Yes! In the case of BOGO discounts (e.g. buy 1 get 1 for free) which can apply on a specific quantity, we split the line items to apply the discount on the desired quantity.

[HunkyBill]

With Shops that use Avalara tax reporting, you have a line item called pre_tax_price which is calculated to ensure discounts are correctly applied to the retail price. 

Can we assume that this can now be ignored since Shopify reports discounting per line item? 

Again, in the name of cleaning up cruft, attributes like this will either be problematic or not depending on their value to the ecosystem. 

[Félix]

Can we assume that this can now be ignored since Shopify reports discounting per line item? 

Yes it can be ignored and we are planning on deprecating it. The same goes for the applied_discount attribute and applied_discounts on line items.

Again, in the name of cleaning up cruft, attributes like this will either be problematic or not depending on their value to the ecosystem. 

I could not agree more 🙂

[Bharath]

HI All, 

Can we apply this line level discounts via API? if yes, how can we do that?

[Ryan]

No, this is read only. Apply discounts the same way as before using PriceRule + Discount code APIs.

[ClementG]

Hi there,

I just wanted to say that we are very happy with this change.

This allows us to compute much more accurate discounts, in particular when a price rule applies only to specific line items.

Thank you!

Clement

[ClementG]

Hi again,

We came across something quite confusing.

It's really not clear how the discount applications relate to the lineitem.total_discount and order.total_discounts properties.

When testing discounts, we see that when using the online store, POS or draft orders, the discount allocation is allocated to line items but lineitem.total_discount always remains 0.

However, we came across an order generated by an app, where the discount amount was in both the discount allocation as well as the lineitem.total_discount. This cause our report to double count to the discount.

Is there a difference between those two scenarios? Is lineitem.total_discount deprecated?

If so, are orders that were placed before the discounts allocations release being changed to change to add the discount allocations property to them?

[Félix]

Hi Clement!

order.total_discount will always contain the sum of all discounts so it is safe to use it.

line_item.total_discount will indeed be eventually deprecated as it represents discounts "showing on the line item". In other words, it's a presentation concern baked in the API as all discounts are actually allocated on the line items / shipping lines. This means it's indeed possible to have line_item.total_discount equal to 0, even if order.total_discount is not zero, as you mentioned.

Discount applications and their allocations include all discounts, not matter how they are presented (on the order or the line item). The discount application itself describes the discount calculation intention and type, so it's up to the client to decide how to present discounts given this information, if need be.

Also the API is backward compatible as we, more or less, always stored discounts this way internally, so all orders created before the discount allocations were introduced also expose those attributes.

Let me know if this helps!

[ClementG]

Thanks Felix for the speedy response.

So if I understand correctly, for reporting purposes line_item.total_discount is totally useless right?

We can always use line_item.discount_allocations, instead, even on very old orders?

Also, I wanted to confirm that the following equation is always true:

order.total_discounts = sum of discount allocations of all line items and shipping lines

Correct?

In other words, the entire discount amount is always 100% allocated to line items and/or shipping lines. Which means that there is no need for us to ever manually allocate the order-level discount to line items (pro-rata) as it is already done by Shopify.

Sorry to drill in but I want to make sure I got this correctly.

[Félix]

For reporting purposes line_item.total_discount is totally useless right?

Yes, this is correct.

We can always use line_item.discount_allocations, instead, even on very old orders?

Yes, this is also correct.

Also, I wanted to confirm that the following equation is always true:

order.total_discounts = sum of discount allocations of all line items and shipping lines

Correct?

You got it right!

In other words, the entire discount amount is always 100% allocated to line items and/or shipping lines. Which means that there is no need for us to ever manually allocate the order-level discount to line items (pro-rata) as it is already done by Shopify.

Exactly, you get the exact allocation done by Shopify in the backend. 

Let me know if there is anything else!

[ClementG]

Sweet, that's what I wanted to hear!

Thanks!

[ClementG]

Hi Felix,

We have come accross an order for which the equation does not hold.

It's an order with two discount applications, but only one of the two is allocated.

We are concerned about this because this could mean our reporting is wrong.

Are you able to investigate what happened here?

The order in question is https://nitrocharts-testing.myshopify.com/admin/orders/387291185212

[Félix]

Hi Clement!

I will investigate further as it seems there is a problem with the data itself with this order, the discount across all line items was not allocated properly. The API returns the truth, which is concerning a bit.

I'll get back to you when I have more information.

Thanks for letting me know about this.

[ClementG]

Ok.

We are almost ready to deploy our changes to incorporate discount allocations but we will wait until we hear back from you on this one.

If it's a freak order it may be ok but if it's a more widespread issue then we might hold off for now.

[Félix]

I understand. I am under the impression it's an outlier, but I'll have to confirm. I'll investigate this tomorrow morning as it is late a bit here (EDT) and I'll let you know.

[ClementG]

Sure, thanks for the quick replies!