Basket Addresses API

Feature name: basket

Api name: basketAddressesApi

---

API used to perform actions related to addresses in a basket like getting the addresses, changing their values or validating them.

classDiagram
direction LR
    class selectShippingAddress["selectShippingAddress$"]
    class selectBillingAddress["selectBillingAddress$"]
    class selectIsBillingAddressEqualShippingAddress["selectIsBillingAddressEqualShippingAddress$"]
    class selectIsDifferentShippingAddressRequired["selectIsDifferentShippingAddressRequired$"]
    class selectSectionValidation["selectSectionValidation$"]

    BasketAddressesAPI --> getShippingAddress
    BasketAddressesAPI --> selectShippingAddress
    BasketAddressesAPI --> getBillingAddress
    BasketAddressesAPI --> selectBillingAddress
    BasketAddressesAPI --> setShippingAddress
    BasketAddressesAPI --> setBillingAddress
    BasketAddressesAPI --> isBillingAddressEqualShippingAddress
    BasketAddressesAPI --> selectIsBillingAddressEqualShippingAddress
    BasketAddressesAPI --> isDifferentShippingAddressRequired
    BasketAddressesAPI --> selectIsDifferentShippingAddressRequired
    BasketAddressesAPI --> setBillingAddressAsShippingAddress
    BasketAddressesAPI --> getSectionValidation
    BasketAddressesAPI --> selectSectionValidation

    class BasketAddressesAPI {
        getShippingAddress() Address|null
        selectShippingAddress$() Observable~Address|null~
        getBillingAddress() Address|null
        selectBillingAddress$() Observable~Address|null~
        setShippingAddress(action: BasketAction, address: TBasketAddressDTO) Promise<Record<string,string[]>|undefined>
        setBillingAddress(action: BasketAction, address: TBasketAddressDTO) Promise<Record<string,string[]>|undefined>
        isBillingAddressEqualShippingAddress() boolean
        selectIsBillingAddressEqualShippingAddress$() Observable~boolean~
        isDifferentShippingAddressRequired() boolean
        selectIsDifferentShippingAddressRequired$() Observable~boolean~
        setBillingAddressAsShippingAddress() Promise~void~
        getSectionValidation() TSectionValidation
        selectSectionValidation$() Observable~TSectionValidation~
    }

    link getShippingAddress "../methods/get-shipping-address/"
    link selectShippingAddress "../methods/select-shipping-address/"
    link setShippingAddress "../methods/set-shipping-address/"
    link getBillingAddress "../methods/get-billing-address/"
    link selectBillingAddress "../methods/select-billing-address/"
    link setBillingAddress "../methods/set-billing-address/"
    link isBillingAddressEqualShippingAddress "../methods/is-billing-address-equal-shipping-address/"
    link selectIsBillingAddressEqualShippingAddress "../methods/select-is-billing-address-equal-shipping-address/"
    link isDifferentShippingAddressRequired "../methods/is-different-shipping-address-required/"
    link selectIsDifferentShippingAddressRequired "../methods/select-is-different-shipping-address-required/"
    link setBillingAddressAsShippingAddress "../methods/set-billing-address-as-shipping-address/"
    link getSectionValidation "../methods/get-section-validation/"
    link selectSectionValidation "../methods/select-section-validation/"

Get API

To get the Basket Addresses API use its name basketAddressesApi with the getApi method.

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

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

• getShippingAddress - get a shipping address in a basket
• selectShippingAddress$ - select current shipping address in a basket
• setShippingAddress - change a current value of a shipping address
• getBillingAddress - get a billing address in a basket
• selectBillingAddress$ - select current billing address in a basket
• setBillingAddress - change a current value of a billing address
• isBillingAddressEqualShippingAddress - check if the billing address is equal to the shipping address
• selectIsBillingAddressEqualShippingAddress$ - select a value representing whether the billing address is equal to the shipping address or not
• isDifferentShippingAddressRequired - check whether a different shipping address is required
• selectIsDifferentShippingAddressRequired$ - select a value representing whether a different shipping address is required or not
• setBillingAddressAsShippingAddress - change a current value of a billing address to the value of a shipping address
• getSectionValidation - validate a basket section where addresses are present
• selectSectionValidation$ - select a validation of a basket section where addresses are present

Event Bus events

This API listens to the following events with the Event Bus:

• basket.basketUpdated

Example

In this example we make a basketAddressesApi call to get shipping address in the basket.

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

        const shippingAddress = basketAddressesApi.getShippingAddress();
    });
});

Example

In this example we make a basketAddressesApi call to get a current billing address in the basket.

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

        const billingAddress$ = basketAddressesApi.selectBillingAddress$();

        billingAddress$.subscribe((currentBillingAddress) => {
            // do something with the address
        });
    });
});

Example

In this example we make a basketAddressesApi call to check if a different shipping address is required (when shipping to a different address).

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

        const isDifferentShippingAddressRequired = basketAddressesApi.isDifferentShippingAddressRequired();

        if (isDifferentShippingAddressRequired) {
            // do something if a different shipping address is required
        }
        else {
            // do something if a different shipping address is not required
        }
    });
});

Example

In this example we make a basketAddressesApi call to set a new value of a shipping address. We also use a getActions method from Basket Overall API to get the action for changing the shipping address.

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

        const changeShippingAddressAction = basketOverallApi.getActions().changeShippingAddress;

        await basketAddressesApi.setShippingAddress(changeShippingAddressAction, {
            isCompany: false,
            companyName: '',
            firstName: 'John',
            lastName: 'Snow',
            personalIdNumber: '',
            taxId: '',
            countryId: 'US',
            city: 'My City',
            postalCode: '12-345',
            street: 'example street 8',
            street2: '',
            phone: '123456789',
            state: '',
            useAsBillingAddress: false,
            createUserAccount: false
        });
    });
});

Example

In this example we make a basketAddressesApi call to validate the basket section with addresses.

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

        const validation = basketAddressesApi.getSectionValidation();
    });
});

Objects Reference

• TBasketAddressDTO
• TSectionValidation

Models reference

• Address
• BasketAction

APIs reference

• Basket Overall API
• Feature System API