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

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

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('FeatureSystemApi');
    await featureSystemApi.registerDynamic('basket');

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

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

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

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

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

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

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

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

    if (!basketAddressesApi || !basketOverallApi) {
        const featureSystemApi = this.getApiSync('FeatureSystemApi');
        await featureSystemApi.registerDynamic('basket');

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

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

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

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

Objects Reference

• TBasketAddressDTO
• TSectionValidation

Models reference

• Address
• BasketAction

APIs reference

• Basket Overall API
• Feature System API