Allow store add shipping method to cart API route to specify multiple shipping options

[NicolasGorga]

Currently (v2.9.0) the /store/carts/[id]/shipping-methods route only allows a single shipping method to be added to the cart, both on the query validator StoreAddCartShippingMethods passed to validateAndTransformQuery, as well as in the object passed as input for the addShippingMethodToCartWorkflow.

A cart naturally can have more than one shipping method, for example when items coming from different StockLocations with different ShippingOptions are purchased from the same cart. The addShippingMethodToCartWorkflow allows for this, but internally, calls the removeShippingMethodFromCartStep for all the currently set shipping methods for the cart. If you are updating the cart shipping methods by interacting with this API core route, then you are effectively only being able to have one shipping method linked to a cart at any given moment.

I propose aligning the core API route to the signature of the addShippingMethodToCartWorkflow, allowing an array of shipping option ids, along with their data fields, to be passed to the endpoint and send this as is to the workflow. This will allow us to add multiple shipping options to a cart from the API core route in charge of this.

I could take on this, just would like the team input on this. Below my plan and observations:

• Update StoreAddCartShippingMethods validator to look like this:

export const StoreAddCartShippingMethods = z.array(
    z.object({
        option_id: z.string(),
        data: z.record(z.unknown()).optional(),
      })
  .strict()
).min(1, { message: "At least one shipping method is required" })

• Inside the route.ts file, udpate the call to the workflow like so

await addShippingMethodToCartWorkflow(req.scope).run({
    input: {
      options: payload.map(method => ({
           id: method.option_id,
           data: method.data
       })),
      cart_id: req.params.id,
    },
  })

• Update sdk.store.cart.addShippingMethod, so the second argument reflects this change

• This is a BREAKING CHANGE but i guess it is necessary if we don't want to cause confusion as to what should be passed in the body of the API route. I say this as i guesss to make it backward compatible then we could specify wither this new schema or the previous and handle how the input to the workflow should be constructed depending on which one it is.

• Doc changes: The endpoint reference should be updated https://docs.medusajs.com/api/store#carts_postcartsidshippingmethods, i think i read once it was auto generated from comments in the route file? I am not so sure about this, but i don't see any in the current source code, so clarification here would be super.

• Guide changes: Guides like this should also be changed: https://docs.medusajs.com/resources/storefront-development/checkout/shipping, specifically, the code snippets that interact with sdk.store.cart.addShippingMethod

Let me know what you think team!

[olivermrbl]

Thanks for sharing @NicolasGorga. And appreciate the level of detail.

This is a good and perfectly valid suggestion. That said, I’m hesitant to introduce a breaking change to the existing API and workflow for this use case. It's relatively uncommon compared to adding a single method, and I believe we can find a way to support this through alternative approaches.

Possible options could be:

• Create a new workflow that can be used in a custom API endpoint (I think I prefer this)
• Create a new workflow and adjust the existing route to accept either one or multiple shipping methods
• Create a new workflow and introduce a separate core API endpoint, e.g. /store/carts/:id/shipping-methods/[batch | bulk | ... ]

This way, we can support the scenario without introducing a breaking change. I'd be happy to flesh these approaches out in detail with you, if we choose to go down this path.

Curious to hear what you think.

[NicolasGorga]

Hey @olivermrbl,

Regarding creating a new workflow, I would like to understand why not use the existent one? Since from looking at its implementation it was conceived and supports adding multiple shipping options to the cart. At first i was also hesitant about current its logic of clearing the currently set shipping options, but i am now starting to think it is good, since you mainly interact with this from the checkout point of view, so it is safe to assume at all times you have the list of shipping options the user selected and thus, whatever you send should be the current snapshot of the user selection.

IMO this should be part of the core API route layer. While it is true that it is less common than a single shipping method, almost all markletplace implementations that don't have a central WH that receives the items of an order from multiple sellers, unifying the shipping, will need this. I also see this for a current client for example that has a mix of items he owns, plus dropshipped ones that ship straight from China and an order can have a mix of these products.

So and taking into account your worry about the breaking change, i would say these are the two options:

• Your third suggestion about the new core endpoint, but not using a new workflow, since the existent addShippingMethodToCartWorkflow already has everything we need (please correct me if i'm wrong)

OR

• Change the current endpoint validator, making it backwards compatible (to avoid the breaking change) and allowing the current schema, plus the array one. I feel more inclined to this (in the ideal i would change it to the array, as one item represents single shipping methods and more this multiple scenario), since nothing changes in terms of the logic, just the input shape. Intention (single or multiple shipping method flow) is derived and expressed from the elements in the array.

I just feel adding a separate endpoint just for changing the input schema, is making the flow harder to understand. Specially for those going into the source code and seeing the exact same workflow gets called. WYT?

Eager to collab on this!

[NicolasGorga]

Hello any updates?

[olivermrbl]

Regarding creating a new workflow, I would like to understand why not use the existent one? Since from looking at its implementation it was conceived and supports adding multiple shipping options to the cart. At first i was also hesitant about current its logic of clearing the currently set shipping options, but i am now starting to think it is good, since you mainly interact with this from the checkout point of view, so it is safe to assume at all times you have the list of shipping options the user selected and thus, whatever you send should be the current snapshot of the user selection.

You are right. On second thought, the workflow can be used to add multiple options in its current state.

However, I am still hesitant to tweak the existing API endpoint since we cannot really avoid making a breaking change (which I would like to avoid) or making the input type messy.

One of Medusa's strengths is that you have a framework available to add custom API endpoints for specific use cases, such as marketplaces, so if this use case is needed, it is pretty easily achievable.

In addition to this, I haven't seen any actual requests for this up until now, so it seems like a premature optimization at this point. Perhaps we can pick up this discussion again if we see a rise in demand for adding multiple shipping options. Let me know what you think?

[NicolasGorga]

I see your point, i'll watch out for any requests or conversation around this functionality and get back to you here if i see a rise in its demand. Cheers!