Basket Shippings API¶

Feature name: basket

Api name: basketShippingsApi

API used to perform actions related to shippings in a basket like getting the shipping details, adding maps for pickup points or setting the details of shippings.

classDiagram
direction LR
    class select["select$"]
    class selectSelectedShipping["selectSelectedShipping$"]
    class selectAvailableShippingCountries["selectAvailableShippingCountries$"]
    class selectSelectedShippingCountry["selectSelectedShippingCountry$"]
    class selectPaymentCostForActiveShippingByPaymentId["selectPaymentCostForActiveShippingByPaymentId$"]
    class selectIsEveryAvailablePaymentFree["selectIsEveryAvailablePaymentFree$"]
    class selectSectionValidation["selectSectionValidation$"]

    BasketShippingsAPI --> get
    BasketShippingsAPI --> select
    BasketShippingsAPI --> setShipping
    BasketShippingsAPI --> setPickupPoint
    BasketShippingsAPI --> getSelectedShipping
    BasketShippingsAPI --> selectSelectedShipping
    BasketShippingsAPI --> getAvailableShippingCountries
    BasketShippingsAPI --> selectAvailableShippingCountries
    BasketShippingsAPI --> getSelectedShippingCountry
    BasketShippingsAPI --> selectSelectedShippingCountry
    BasketShippingsAPI --> setCountry
    BasketShippingsAPI --> getPaymentCostForActiveShippingByPaymentId
    BasketShippingsAPI --> selectPaymentCostForActiveShippingByPaymentId
    BasketShippingsAPI --> isEveryAvailablePaymentFree
    BasketShippingsAPI --> selectIsEveryAvailablePaymentFree
    BasketShippingsAPI --> getSectionValidation
    BasketShippingsAPI --> selectSectionValidation
    BasketShippingsAPI --> addMap
    BasketShippingsAPI --> showPickupPointMap
    BasketShippingsAPI --> shouldDisplayRemainingBasketValueForFreeShippingMessage
    BasketShippingsAPI --> addShippingInfo
    BasketShippingsAPI --> getShippingInfo

    class BasketAddressesAPI {
        get() BasketShipping[]
        select$() Observable~BasketShipping[]~
        setShipping(shipping: BasketShipping) void
        setPickupPoint(shipping: BasketShipping, point: PickupPoint) void
        getSelectedShipping() BasketShipping|undefined
        selectSelectedShipping$() Observable~BasketShipping|undefined~
        getAvailableShippingCountries() Country[]
        selectAvailableShippingCountries$() Observable~Country[]~
        getSelectedShippingCountry() ShippingCountry|undefined
        selectSelectedShippingCountry$() Observable~ShippingCountry|undefined~
        setCountry(countryId: number) Promise~void~
        getPaymentCostForActiveShippingByPaymentId(paymentId: number) FullPrice|undefined
        selectPaymentCostForActiveShippingByPaymentId$(paymentId: number) Observable~FullPrice|undefined~
        isEveryAvailablePaymentFree() boolean
        selectIsEveryAvailablePaymentFree$() Observable~boolean~
        getSectionValidation() TSectionValidation
        selectSectionValidation$() Observable~TSectionValidation~
        addMap(shipping: BasketShipping, mapStrategy: PickupPointMapStrategy) void
        showPickupPointMap(shipping: BasketShipping) Promise~void~
        shouldDisplayRemainingBasketValueForFreeShippingMessage(shipping: BasketShipping) boolean
        addShippingInfo(shipping: BasketShipping, template: HTMLTemplateElement|string) void
        getShippingInfo(shipping: BasketShipping) HTMLTemplateElement|undefined
    }

    link get "../methods/get/"
    link select "../methods/select/"
    link setShipping "../methods/set-shipping/"
    link setPickupPoint "../methods/set-pickup-point/"
    link getSelectedShipping "../methods/get-selected-shipping/"
    link selectSelectedShipping "../methods/select-selected-shipping/"
    link getAvailableShippingCountries "../methods/get-available-shipping-countries/"
    link selectAvailableShippingCountries "../methods/select-available-shipping-countries/"
    link getSelectedShippingCountry "../methods/get-selected-shipping-country/"
    link selectSelectedShippingCountry "../methods/select-selected-shipping-country/"
    link setCountry "../methods/set-country/"
    link getPaymentCostForActiveShippingByPaymentId "../methods/get-payment-cost-for-active-shipping-by-payment-id/"
    link selectPaymentCostForActiveShippingByPaymentId "../methods/select-payment-cost-for-active-shipping-by-payment-id/"
    link isEveryAvailablePaymentFree "../methods/is-every-available-payment-free/"
    link selectIsEveryAvailablePaymentFree "../methods/select-is-every-available-payment-free/"
    link getSectionValidation "../methods/get-section-validation/"
    link selectSectionValidation "../methods/select-section-validation/"
    link addMap "../methods/add-map/"
    link showPickupPointMap "../methods/show-pickup-point-map/"
    link shouldDisplayRemainingBasketValueForFreeShippingMessage "../methods/should-display-remaining-basket-value-for-free-shipping-message/"
    link addShippingInfo "../methods/add-shipping-info/"
    link getShippingInfo "../methods/get-shipping-info/"

Get API¶

To get the Basket Shippings API use its name basketShippingsApi with the getApi method.

useStorefront(async ({ eventBus, getApi }) => {
    eventBus.on('basket.initialized', async () => {
        const basketShippingsApi = await getApi('basketShippingsApi');
    });
});

This API is not automatically initialized. Unless you initialize it by hand or use a proper event like in the example above, you won't be able to fetch the API. Read more in the Retrieving basket APIs section

Methods¶

get - Retrieve all basket shipping options.
select - Select basket shipping options.
setShipping - Set the shipping option for the basket.
setPickupPoint - Set the pickup point for the basket shipping.
getSelectedShipping - Retrieve the currently selected shipping option.
selectSelectedShipping - Observe changes to the selected shipping option.
getAvailableShippingCountries - Retrieve the list of available shipping countries.
selectAvailableShippingCountries - Observe the available shipping countries.
getSelectedShippingCountry - Retrieve the currently selected shipping country.
selectSelectedShippingCountry - Observe changes to the selected shipping country.
setCountry - Set the shipping country by its ID.
getPaymentCostForActiveShippingByPaymentId - Get the payment cost for the active shipping method by payment ID.
selectPaymentCostForActiveShippingByPaymentId - Observe the payment cost for the active shipping method by payment ID.
isEveryAvailablePaymentFree - Check if every available payment option is free.
selectIsEveryAvailablePaymentFree - Observe whether every available payment option is free.
getSectionValidation - Validate the shipping section of the basket.
selectSectionValidation - Observe the validation state of the shipping section.
addMap - Add a map for the shipping option using a specified map strategy.
showPickupPointMap - Display the pickup point map for the shipping option.
shouldDisplayRemainingBasketValueForFreeShippingMessage - Determine if the message about the free shipping for the remaining basket should display based on the shipping option.
addShippingInfo - Add shipping information to the given shipping option.
getShippingInfo - Retrieve the shipping information from the basket.

Event Bus events¶

The methods of this API dispatch the following events with the Event Bus:

Example¶

In this example we make a basketShippingsApi call to retrieve the list of available shipping countries.

useStorefront(async ({ eventBus, getApi }) => {
    eventBus.on('basket.initialized', async () => {
        const basketShippingsApi = await getApi('basketShippingsApi');

        const availableShippingCountries = basketShippingsApi.getAvailableShippingCountries();
    });
});

Example¶

In this example we make a basketShippingsApi call to check if every available payment option is free.

useStorefront(async ({ eventBus, getApi }) => {
    eventBus.on('basket.initialized', async () => {
        const basketShippingsApi = await getApi('basketShippingsApi');

        const isEveryAvailablePaymentFree = basketShippingsApi.isEveryAvailablePaymentFree();

        if (isEveryAvailablePaymentFree) {
            // do something
        }
    });
});

Example¶

In this example we make a basketShippingsApi call to set the current shipping country by id.

useStorefront(async ({ eventBus, getApi }) => {
    eventBus.on('basket.initialized', async () => {
        const basketShippingsApi = await getApi('basketShippingsApi');

        await basketShippingsApi.setCountry(2);
    });
});

Example¶

In this example we make a basketShippingsApi call to set the pickup point for the basket shipping.

useStorefront(async ({ eventBus, getApi }) => {
    eventBus.on('basket.initialized', async () => {
        const basketProductsApi = await getApi('basketProductsApi');

        const currentBasketShipping = basketShippingsApi.getSelectedShipping();

        const examplePickupPoint = {
            code: 'PP001',
            isCollectOnDeliveryAvailable: true,
            supplier: 'FastShip',
            name: 'Central Pickup Point',
            description: 'Pickup point near the central park.',
            street: 'Park Street',
            houseNumber: '12A',
            city: 'Berlin',
            postalCode: '10115',
            province: null,
            countryCode: 'DE',
            latitude: '52.5200',
            longitude: '13.4050',
            openingHours: '09:00-18:00'
        };

        basketShippingsApi.setPickupPoint(currentBasketShipping, examplePickupPoint);
    });
});

Example¶

In this example we make a basketShippingsApi call to add a map for the selected shipping option.

useStorefront(async ({ eventBus, getApi }) => {
    eventBus.on('basket.initialized', async () => {
        const basketShippingsApi = await getApi('basketShippingsApi');

        class ExampleDeliveryPointMap {
            public async showMap(choosePickupPointCallback) {
                choosePickupPointCallback();
                // here goes code for map handling
            }
        }

        class ExamplePickupPointMapStrategy {
            public execute() {
                return ExampleDeliveryPointMap;
            }
        }

        const selectedShipping = basketShippingsApi.getSelectedShipping()

        const basketShippingOptions = basketShippingsApi.addMap(selectedShipping, ExamplePickupPointMapStrategy);
    });
});

Example¶

In this example we make a basketShippingsApi call to display the pickup point map for the current shipping.

useStorefront(async ({ eventBus, getApi }) => {
    eventBus.on('basket.initialized', async () => {
        const basketProductsApi = await getApi('basketProductsApi');

        const selectedShipping$ = basketShippingsApi.selectSelectedShipping$();

        selectedShipping$.subscribe(async (shippingOption) => {
            if (!shippingOption) {
                console.log('No shipping option is currently selected.');
                return;
            }

            if (shippingOption.isPickupPointDelivery) {
                await basketShippingsApi.showPickupPointMap(shippingOption);
            }
        });
    });
});

Example¶

In this example we integrate a map template inside one of the shipping methods.

To do that we add the integration module that will contain the template for a map.

map-integration

Inside the module's HTML section we insert the <template> with some id which will represent the map container

<template id="map-integration-example">
    <button class="btn btn_primary btn_s">Show a map</button>
</template>

Finally, we add the template as a shipping info for a desired shipping after the basket has been initialized. Of course the code responsible for clicking a button is not presented in this example as it may vary depending on the map.

useStorefront(async ({ eventBus, getApi }) => {
    eventBus.on('basket.initialized', async () => {
        const basketShippingsApi = await getApi('basketShippingsApi');

        // finding a desired shipping by its id
        const shipping = basketShippingsApi.get().find((shipping) => shipping.id === 2);

        basketShippingsApi.addShippingInfo(shipping, 'map-integration-example');
    });
});

Models reference¶

Objects reference¶

TSectionValidation