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 getApiSync method.

useStorefront(async (storefront) => {
    const basketShippingsApi = storefront.getApiSync('basketShippingsApi');
});

This API is not automatically initialized. Unless you initialize it by hand, you won't be able to fetch the API. To do it you can use the registerDynamic method from the Feature System API. Here is an example on how to do it:

useStorefront(async (storefront) => {
    const featureSystemApi = this.getApiSync(FEATURE_SYSTEM_API_NAME);
    await featureSystemApi.registerDynamic('basket');

    const basketAddressesApi = storefront.getApiSync('basketShippingsApi');
});

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 (storefront) => {
    let basketShippingsApi = storefront.getApiSync('basketShippingsApi');

    if (!basketShippingsApi) {
        const featureSystemApi = this.getApiSync(FEATURE_SYSTEM_API_NAME);
        await featureSystemApi.registerDynamic('basket');

        basketShippingsApi = storefront.getApiSync('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 (storefront) => {
    let basketShippingsApi = storefront.getApiSync('basketShippingsApi');

    if (!basketShippingsApi) {
        const featureSystemApi = this.getApiSync(FEATURE_SYSTEM_API_NAME);
        await featureSystemApi.registerDynamic('basket');

        basketShippingsApi = storefront.getApiSync('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 (storefront) => {
    let basketShippingsApi = storefront.getApiSync('basketShippingsApi');

    if (!basketShippingsApi) {
        const featureSystemApi = this.getApiSync(FEATURE_SYSTEM_API_NAME);
        await featureSystemApi.registerDynamic('basket');

        basketShippingsApi = storefront.getApiSync('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 (storefront) => {
    let basketShippingsApi = storefront.getApiSync('basketShippingsApi');

    if (!basketShippingsApi) {
        const featureSystemApi = this.getApiSync(FEATURE_SYSTEM_API_NAME);
        await featureSystemApi.registerDynamic('basket');

        basketShippingsApi = storefront.getApiSync('basketShippingsApi');
    }

    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 (storefront) => {
    let basketShippingsApi = storefront.getApiSync('basketShippingsApi');

    if (!basketShippingsApi) {
        const featureSystemApi = this.getApiSync(FEATURE_SYSTEM_API_NAME);
        await featureSystemApi.registerDynamic('basket');

        basketShippingsApi = storefront.getApiSync('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 (storefront) => {
    let basketShippingsApi = storefront.getApiSync('basketShippingsApi');

    if (!basketShippingsApi) {
        const featureSystemApi = this.getApiSync(FEATURE_SYSTEM_API_NAME);
        await featureSystemApi.registerDynamic('basket');

        basketShippingsApi = storefront.getApiSync('basketShippingsApi');
    }

    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 (storefront) => {
    window.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