Cart API docs and package types are incorrect

Extensions
1

As I interact more and more with the POS UI Extensions, I’ve been noticing some inconsistencies in how it works versus what is documented and specially with the new testing package and mocks, trying to replicate real world POS becomes hard given the types are not what we expect.

A few examples I’ve found:

Both of these properties are said to return undefined for custom sales items, but in the latest version of the POS, running 2026-07 extensions, on iOS and iPadOS, the values returned are number NaN.

Another example:

Always a positive integer. also not a true statement, if you addLineItem(variantId, 1) and then addLineItem(variantId, -1) (assuming starting from a clear cart), this value will be 0.

On the same topic,addLineItem(variantId, -X)is also an undocumented behavior many apps rely on.

There is quite a bit of undocumented behavior that can either be very helpful (the addLineItem trick is for sure the largest one), or sometimes cause bugs (e.g: Custom Sales are added with a default lineItem property by Shopify which if you are not aware of, you might end-up overwriting or clashing during bulk operations).

I can give some more examples if desired, but overall, I’d like to see some sort of improvement to the Cart API documentation and types, and a more complete reference, with best practices guidance for it as it’s such a vital part of POS UI Extensions.

2

Hey @dsnvs :waving_hand: thanks for flagging this and sharing these specific examples.

I’m digging into this further. I’ll follow up here once I have more information to share.

4

@Wes-Dev-Shopify Thanks!

While at it, maybe also check: [BUG] LineItem.discount[].amount returns fixed amount for discount with percentage type

5

Thanks for your patience while I dug into this @dsnvs.

I see what you mean with both of these examples here and we’re looking into making adjustments to our docs. I’ll follow up in this thread when I have more to share.

Regarding overall improvements to the documentation any types, a more complete reference and best practices guidance, that’s great feedback and I’ll make sure it’s heard. I understand where you’re coming from.

In the meantime, if you have any specific suggestions, or other examples of undocumented behaviour you’ve noticed, we would love to hear it!

Lastly, regarding the [BUG] LineItem.discount[].amount returns fixed amount for discount with percentage type thread you referenced, we’re looking into that as well and we’ll follow up in the thread as soon as we have more info.

I hope this helps and thanks again for bringing these examples to our attention!