Better support for shipping method providers (single method, multiple prices / options)

[taxilian]

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

There are many shipping providers (e.g. shipstation, shippo, stamps.com, etc) which provide APIs which return an undetermined number of shipping methods with prices; currently in vendure a single Shipping Method can only return a single price, a single option.

Describe the solution you'd like
There should be some method for a "ShippingMethod" to return multiple options and some way when selecting shipping to set not only which ShippingMethod but which of the options it provided to use.

On discord (https://discord.com/channels/1100672177260478564/1200213503139655750/1200340563724083290) the suggestion was proposed to allow a shipping calculator to return multiple prices in an attempt to make it a non-breaking change.

Describe alternatives you've considered

Two options I've thought about:

1. Shipping plugin provides custom APIs for getting shipping methods, adds custom fields to the order for which is selected. The ShippingCalculator then looks at those fields to decide if it's going to be used.

2. The shipping calculator return the available shipping options as metadata; again custom fields can be used to set which method to use but if not provided it can return some arbitrary (or arbitrarily chosen?) value.

Both are a bit hacky, I feel like 2 is hackier than 1 =]

Additional context

Here is an abbreviated example of what the Shipstation APIs might return. (not exact, but it's what my custom API returns after getting all available carriers and services)

[
    {
        name: 'Stamps.com',
        code: 'stamps_com',
        nickname: 'USPS / Stamps',
        shippingProviderId: 54321,
        primary: true,
        services: [
            {
                serviceName: 'USPS First Class Mail - Package',
                serviceCode: 'usps_first_class_mail',
                shipmentCost: 3.79,
                otherCost: 0,
            },
            {
                serviceName: 'USPS Priority Mail - Package',
                serviceCode: 'usps_priority_mail',
                shipmentCost: 6.64,
                otherCost: 0,
            },
        ],
    },
    {
        name: 'UPS by ShipStation',
        code: 'ups_walleted',
        nickname: 'UPS',
        shippingProviderId: 12345,
        primary: true,
        services: [
            {
                serviceName: 'UPS Next Day Air®',
                serviceCode: 'ups_next_day_air',
                shipmentCost: 17.76,
                otherCost: 0,
            },
            {
                serviceName: 'UPS® Ground',
                serviceCode: 'ups_ground',
                shipmentCost: 6.76,
                otherCost: 0,
            },
        ],
    },
]

[jacobfrantz1]

A somewhat related issue is error handling in shipping calculators. If an api call fails, it either has to throw which fails the entire getEligibleShippingMethods query, or return a fallback price; neither of which are great.

[brunoslalmeida]

Hi @michaelbromley ,

I'm diving into this feature request and looking forward to coding it up. Given its importance for my e-commerce platform, I wanted to double-check before starting my experiments. Are there any specific areas or functions I should be particularly careful not to modify?

[brunoslalmeida]

@michaelbromley i've added the code here github it would be awesome to get some insights from you before moving forward.

[brunoslalmeida]

[michaelbromley]

Hi @brunoslalmeida I just took a look through your fork.

I think the overall direction looks good. I have some feedback on the API changes:

export const TEST_SHIPPING_METHOD = gql`
    query TestShippingMethod($input: TestShippingMethodInput!) {
        testShippingMethod(input: $input) {
            eligible
            quote {
                price
                priceWithTax
                metadata
            }
            list {
                eligible
                quote {
                    price
                    priceWithTax
                    metadata
                }
            }
        }
    }
`;

• In the list array, the eligible property is redundant as far as I understand? It is based on the eligibility checker which would will be either true or false and will apply to all computed price quotes.

I would prefer this:

    query TestShippingMethod($input: TestShippingMethodInput!) {
        testShippingMethod(input: $input) {
            eligible
            quote {
                price
                priceWithTax
                metadata
            }
            quotes {
                price
                priceWithTax
                metadata
            }
        }
    }

and we can deprecate the quote field for removal in a future version, and internally we just always use the quotes array.

[brunoslalmeida]

Yes, it is redundant it was already in plans to remove it. I was also struggling to find a name, quotes seams like a good name. I will fix it and continue.

[brunoslalmeida]

Hey @michaelbromley just finished your feedback changes (i was struggling with time) and will get the pace back this week. Thanks for your support.

[brunoslalmeida]

Hi @michaelbromley,

I have a question.

As far as I'm studying, the entry point for shipping selection at shop-api is the mutation setOrderShippingMethod. This mutation only receives a list of ShippingMethod IDs. However, knowing just the ID isn't enough to select the inner choice. I'm struggling to think of a solution that maintains backward compatibility.

My only current option is to create a new optional argument that receives an array with the same size as the first one containing IDs to identify the inner ID. If no information is sent by the front-end, then the first item of each method should be selected. To achieve this, an optional ID needs to be added to ShippingCalculationResult.

For admin-api the entry-point is setDraftOrderShippingMethod. A new optional arg can be added and in case of null use first. This is easier.

What are your thoughts on this? Am i missing something important ?

[brunoslalmeida]

I am also testing with remix, and the front-end is considering the same item (probably due to the same method id). Is this a retro-compatibility problem? Or if at the end a new version of the front end gets generated is not a problem ?

[michaelbromley]

Hi,

regarding the setOrderShippingMethod mutation, a non-breaking change could be to:

1. make the shippingMethodId input nullable (remove the !)
2. create a new input which takes an array of objects, whose shape you can decide based on the data you need.

Once we make changes to the API, we can update the storefront implementations as needed.