Skip to content

Basket

To make working with the shopping basket easier, we have split its functions into several smaller APIs. Each API is built to handle one specific part of the process, from adding an item to the cart to completing a purchase.

This structure makes it simpler for you to connect your code. Instead of learning one large, complex API, you can use a specific API for each task. For example, you'll use one API to manage cart items, another to apply discount codes, and a different one for shipping details.

This setup helps you build new features and fix problems more quickly because everything is easier to find. In this section, we will explain each Basket API so you can easily add the functions your store needs.

Basket APIs Explained

Here is a breakdown of each specific API and what it helps you do.

Basket Products API

Api name: basketProductsApi

This is the main API for managing the items in the cart. You can use it to get a list of all products currently in the basket, see the total number of items, and find out their combined price.

Basket Addresses API

Api name: basketAddressesApi

This API lets you manage all customer address information. You can use it to get the current shipping or billing address, update its details, or check that the information is valid.

Basket Shippings API

Api name: basketShippingsApi

This API is for managing delivery options. You can get a list of available shipping methods, set the one the customer chooses, or add maps for in-store pickup locations.

Basket Payments API

Api name: basketPaymentsApi

This API handles everything related to payments. It lets you get a list of available payment options, save the customer's chosen method, and confirm that the payment section is filled out correctly.

Basket Promotions API

Api name: basketPromotionsApi

Use this API to manage discounts and special offers. It lets you add or remove coupon codes from the basket and get information about any promotions that are currently active.

Basket Taxes API

Api name: basketTaxesApi

This API is used for all tax-related information. You can get a list of taxes that apply to the items in the basket and see their total calculated amount.

Basket Additional Fields API

Api name: basketAdditionalFieldsApi

If your basket uses custom fields (like for gift messages or special requests), this API lets you manage them. You can get a list of the available fields, update their values, and validate the information inside them.

Basket Overall API

Api name: basketOverallApi

This API manages the final summary and overall actions for the basket. Use it for things like adding a comment to the order, clearing the entire cart, or getting a final summary of costs and delivery details before checkout.

Retrieving Basket APIs

Basket APIs are not automatically initialized hence they need to be manually registered in order to retrieve them. There are two methods of doing so:

First one (recommended) is using the basket.initialized event from Event Bus to ensure the basket feature has been registered.

useStorefront(async ({ eventBus, getApi }) => {
    // listen to basket.initialized event
    eventBus.on('basket.initialized', async () => {
        // retrieve the api of choice
        const basketExampleApi = await getApi('basketApiName');
    });
});

The second method is manually checking if the API has been retrieved. If it didn't, we manually register the basket feature using the registerDynamic method from Feature System API.

useStorefront(async (storefront) => {
    // trying to retrieve the api of choice
    let basketExampleApi = await getApi('basketApiName');

    if (!basketExampleApi) {
        // if it didn't retrieve, manually registering the basket feature
        const featureSystemApi = storefront.getApiSync('FeatureSystemApi');
        await featureSystemApi.registerDynamic('basket');

        // then retrieving the api again
        basketExampleApi = await getApi('basketApiName');
    }
});

NOTE: It's better to use the first method whenever you can as it is far simpler.

APIs reference

Below is a complete reference of all Basket APIs and their methods. Click on each API to expand and see its available methods.

Basket Products API
Basket Addresses API
Basket Shippings API
Basket Payments API
Basket Promotions API
Basket Taxes API
  • get - Gets a list of taxes associated with current basket
  • select$ - Selects a list of taxes associated with current basket
  • getSum - Gets a list of tax prices associated with current basket
  • selectSum$ - Selects a list of tax prices associated with current basket
Basket Additional Fields API
  • get - Gets additional fields in a basket
  • select$ - Selects current additional fields in a basket
  • change - Changes current value of a given additional field
  • upload - Uploads a file into the additional field with file input
  • getSectionValidation - Validates the additional fields section
  • selectSectionValidation$ - Selects validation of additional fields section
Basket Overall API
Basket Updater API
Basket Loyalty API