[POS UI Extensions] Return UUID when Cart API's Line item level promises are resolved

[dsnvs]

Please list the related package(s)

retail-ui-extensions

If this related to specific APIs or components, please list them here

Cart API's Line Item Level action

Is your feature request related to a problem? Please describe.

Our apps rely on managing the line items in the cart (add a new line item, remove line item), and with the current Cart API, chained operations are cumbersome and severely increase the complexity of the code.

For example, adding new line items with properties to the cart requires us first to add the line item to the cart, then listen to cart changes to try and identify the new line item (which becomes very tricky for custom sales), so we can grab the new UUID and apply the line item property.

Maybe I am missing something here and there is a simple way to do this, but with my understanding of React Hooks (which is not that high), React Hooks' paradigm combined with the useCartSubscription() hook being limited to one subscriber at a time, doing this is a big hassle. In most scenarios, chaining the actions is not a hard task, but it makes the extension way more complex with data moving in multiple directions and a single context that has to manage the cart.

Describe the changes you are looking for

Having the addLineItem() and addCustomSale() functions reaturn the UUIDs of the line item when the promise is resolved would eliminate this problem almost entirely.

Returning the quantity would also be super helpful so we could remove a line item from the cart if quantity was zero.

Describe alternatives you’ve considered

Additional context

[kyle-villeneuve]

This is super important for us, without it it leads to a lot of very unidiomatic code.

Just to piggyback onto this... another useful improvement would be setting custom properties as a third argument in addLineItem

[kyle-villeneuve]

// setup listener before adding to cart

let called = false; // ensure the subscription is only fired once

api.cart.subscribable.subscribe(async ({ lineItems }) => {
  if (called) return;

  const lineItem = lineItems.find((li) => li.variantId === Number(variantId));

  if (lineItem) {
    called = true; // prevent subsequent calls
    
    // do stuff with added lineItem here
    // ...
    
    // set a new listener to "unsubscribe"
    api.cart.subscribable.subscribe(() => {});
  }
});
}

// add to cart, which should trigger the subscriber
await api.cart.addLineItem(Number(variantId), 1);

this is the workaround for now

[adamwooding]

+1 for this feature. @js-goupil has there been any movement on this? Thanks so much :)

[js-goupil]

@adamwooding no movement yet, but it would have to be a part of the January release. It's a popular ask, and a low hanging fruit so I'll see what I can do to get the ball rolling. My apologies for the lack of response, I've been out for a month, but I'm back now 😄

[vctrchu]

@adamwooding @dsnvs @kyle-villeneuve We have updated the addLineItem and addCustomSale to return UUIDS. It will be available for use officially in ui-extension version 2025-01 and POS 9.26 starting on 1/26/2025. Thank you for your patience.