Checkout functions

This topic provides the details and instructions you need to use the functions provided by the checkout drop-in component.

authenticateCustomer

The authenticateCustomer function manages the authentication state of a customer, either by fetching customer data using the getCustomer function when authenticated or resetting the customer data when not authenticated.

export const authenticateCustomer: () => Promise<void>

Returns

The function does not return any value explicitly; it performs side effects by fetching data and logging errors.

Usage

See the following example for usage details:

import { authenticateCustomer } from '@/checkout/api/authenticateCustomer';

async function authenticate() {
  try {
    await authenticateCustomer();
    console.log('Customer authenticated successfully.');
  } catch (error) {
    console.error('Error authenticating customer:', error);
  }
}

estimateShippingMethods

The estimateShippingMethods function fetches and displays available shipping methods based on a customer’s address information. It can take a combination of fields as criteria: country, region, region identifier, and postal code.

It uses a utility function to call an estimateShippingMethods mutation.

estimateShippingMethods({ criteria: ShippingEstimationCriteria });

Parameter	Type	Req?	Description
criteria	object	Yes	An object of type ShippingEstimationCriteria, which includes the following fields: country_code, region_name, region_id, and zip.

Returns

Returns a promise that resolves to an array of ShippingMethod objects (or undefined if no shipping methods are available) fetched from the API.

type ShippingMethod = {
  amount: Price;
  carrier: Carrier;
  code: Code;
  title: Title;
  value: string;
  amountExclTax?: Price;
  amountInclTax?: Price;
};

Usage

See the following example for usage details:

import { estimateShippingMethods } from '@/checkout/api/estimateShippingMethods';

// By country code and region name
const input = {
  criteria: {
    country_code: 'US',
    region_name: 'FL',
  },
};
const estimateShippingMethods = estimateShippingMethods(input);

// By country code and region ID
const input = {
  criteria: {
    country_code: 'US',
    region_id: 18,
  },
};
const estimateShippingMethods = estimateShippingMethods(input);

// By country code and postal code
const input = {
  criteria: {
    country_code: 'US',
    zip: '80000',
  },
};
const estimateShippingMethods = estimateShippingMethods(input);

// By country code, region and postal code
const input = {
  criteria: {
    country_code: 'US',
    region_name: 'FL',
    zip: '80000',
  },
};
const estimateShippingMethods = estimateShippingMethods(input);

// By country code, region, region id and postal code
// This scenario is specific for those regions which have more than a region ID
// associated (i.e. Armed Forces region 'AE' with some regions IDs); if the region has
// just a region ID,
const input = {
  criteria: {
    country_code: 'US',
    region_name: 'FL',
    region_id: 18,
    zip: '80000',
  },
};
const estimateShippingMethods = estimateShippingMethods(input);

getCart

The getCart function fetches the cart details for either a guest user or an authenticated customer.

export const getCart: () => Promise<any>

Returns

Returns a promise that resolves to the transformed cart data fetched from the API.

transformCart

Usage

See the following example for usage details:

import { getCart } from '@/checkout/api/getCart';

async function fetchCartData() {
  try {
    const cartData = await getCart();
    console.log('Cart Data:', cartData);
  } catch (error) {
    console.error('Error fetching cart data:', error);
  }
}

// Call the function to fetch and log the cart data
fetchCartData();

getCheckoutData

The getCheckoutData function fetches and prepares the necessary data for the checkout process. It uses the getCart and getCustomer functions to fetch the cart and customer data.

export const getCheckoutData: () => Promise<void>

Returns

The function does not return any value explicitly; it performs side effects by fetching data and logging errors.

Usage

See the following example for usage details:

import { getCheckoutData } from '@/checkout/api/getCheckoutData';

async function fetchAndPrepareCheckoutData() {
  try {
    await getCheckoutData();
    console.log('Checkout data fetched and prepared successfully.');
  } catch (error) {
    console.error('Error fetching checkout data:', error);
  }
}

// Call the function to fetch and prepare the checkout data
fetchAndPrepareCheckoutData();

getCustomer

The getCustomer function fetches customer details for an authenticated user using the customer query.

export const getCustomer: () => Promise<Customer | null | undefined>

Returns

The function returns a promise that resolves to the transformed customer data fetched from the API or undefined if the user is not authenticated.

The Customer object is returned:

type Customer = {
  firstName: string;
  lastName: string;
  email: string;
  addresses: CustomerAddress[];
  defaultBillingAddress?: CustomerAddress;
  defaultShippingAddress?: CustomerAddress;
};

type CustomerAddress = {
  id: string;
  firstName: string;
  lastName: string;
  company?: string;
  street: string[];
  city: string;
  postCode?: string;
  vatId?: string;
  telephone?: string;
  region?: Region;
  country: Country;
  customAttributes: CustomAttribute[];
};

Usage

See the following example for usage details:

import { getCustomer } from '@/checkout/api/getCustomer';

async function fetchAndLogCustomer() {
  try {
    const customer = await getCustomer();
    if (customer) {
      console.log('Customer:', customer);
    } else {
      console.log('No customer data found.');
    }
  } catch (error) {
    console.error('Error fetching customer data:', error);
  }
}

// Call the function to fetch and log the customer data
fetchAndLogCustomer();

getStoreConfig

The getStoreConfig function fetches information about a store’s configuration settings using the storeConfig query.

You can query a non-default store by changing the header in your GraphQL request.

export const getStoreConfig: () => Promise<StoreConfig>

Returns

The function returns a promise that resolves to the transformed store configuration data fetched from the API.

If the API call fails, it returns the default store configuration settings (STORE_CONFIG_DEFAULTS).

transformStoreConfig

Usage

See the following example for usage details:

import { getStoreConfig } from '@/checkout/api/getStoreConfig';

async function fetchAndLogStoreConfig() {
  try {
    const storeConfig = await getStoreConfig();
    console.log('Store Config:', storeConfig);
  } catch (error) {
    console.error('Error fetching store config:', error);
  }
}

// Call the function to fetch and log the store configuration
fetchAndLogStoreConfig();

initializeCheckout

The initializeCheckout function initializes the checkout process by fetching necessary configuration and data from various Adobe Commerce GraphQL APIs using the following functions:

fetchAddressFormFields
getCountries
getStoreConfig

export const initializeCheckout: () => Promise<[StoreConfig, any, any]>

Returns

The function returns a promise that resolves to an array containing the results of the three API calls.

Promise.all([getStoreConfig(), getCountries(), fetchAddressFormFields()]);

Usage

See the following example for usage details:

import {
  fetchAddressFormFields,
  getCountries,
  getStoreConfig,
} from '@/checkout/api';

initializeCheckout();

isEmailAvailable

The isEmailAvailable function checks whether the specified email has already been used to create a customer account using the isEmailAvailable query.

A value of true indicates that the email address is available and the customer can use the email address to create an account. As of Adobe commerce 2.4.7, the default value is true.

export const isEmailAvailable: (email: string) => Promise<EmailAvailability>

Parameter	Type	Req?	Description
email	string	Yes	A string representing the email address to check for availability.

Returns

A promise that resolves to an EmailAvailability object indicating whether the email is available.

type EmailAvailability = boolean;

Usage

See the following example for usage details:

import { isEmailAvailable } from '@/checkout/api/isEmailAvailable';

isEmailAvailable('test@example.com');

placeOrder

The placeOrder function handles the process of placing an order in the checkout system using the placeOrder mutation.

It publishes the place-order Adobe Commerce Event within the order and shoppingCart contexts to the Adobe Client Data Layer (ACDL).

export const placeOrder: () => Promise<Order>

Returns

The transformed order data fetched from the API.

transformOrder

Usage

See the following example for usage details:

import { placeOrder } from '@/checkout/api/placeOrder';

placeOrder('IeTUiU0oCXjm0uRqGCOuhQ2AuQatogjG');

redirect

The redirect function redirects the user to a specific URL. It takes a single parameter (url) of type string, which represents the URL to redirect to.

export const redirect: (url: string) => void

Usage

See the following example for usage details:

import { redirect } from '@/checkout/api/redirect';

redirect('https://example.com');

resetCheckout

The resetCheckout function resets the checkout process to its initial state by clearing the cart data.

export const resetCheckout: () => void

Usage

See the following example for usage details:

import { state } from '@/checkout/lib/state';
import { cartSignal } from '@/checkout/signals';

resetCheckout();

resetCustomer

The resetCustomer function clears the current customer information and resets the customer state to its inital value in the checkout process.

export const resetCustomer: () => void

Usage

See the following example for usage details:

import { state } from '@/checkout/lib/state';
import { customerSignal } from '@/checkout/signals';

resetCustomer();

setBillingAddress

The setBillingAddress function sets the billing address for a specific cart using the setBillingAddressOnCart Adobe Commerce GraphQL mutation.

setBillingAddress({input: BillingAddressInput})

It takes an input parameter where BillingAddressInput is an interface that contains the specific properties for the billing address:

interface BillingAddressInput {
  address?: AddressInput;
  customer_address_id?: number;
  same_as_shipping?: boolean;
  use_for_shipping?: boolean;
}

Returns

The function returns a promise that resolves to the transformed cart data fetched from the API.

transformCart

Usage

To set the billing address as the same as the shipping address:

import { setBillingAddress } from '@/checkout/api/setBillingAddress';

setBillingAddress({
  input: {
    same_as_shipping: true,
  }
});

To set a specific billing address:

import { setBillingAddress } from '@/checkout/api/setBillingAddress';

setBillingAddress({
  input: {
    address: {
      firstname: 'John',
      lastname: 'Doe',
      street: ['123 Main St', 'Apt 1'],
      city: 'New York',
      postcode: '10001',
      country_code: 'US',
      telephone: '555-555-5555',
    },
    same_as_shipping: false,
  }
});

setGuestEmailOnCart

The setGuestEmailOnCart function sets the email address for a guest user on the cart using the setGuestEmailOnCart mutation.

export const setGuestEmailOnCart: (email: string) => Promise<any>

Parameter	Type	Req?	Description
email	string	Yes	A string representing the guest email to be set on the cart.

Returns

The function returns a promise that resolves to the transformed cart data fetched from the API.

transformCart

Usage

See the following example for usage details:

import { setGuestEmailOnCart } from '@/checkout/api/setGuestEmailOnCart';

setGuestEmailOnCart('test@example.com');

setPaymentMethod

The setPaymentMethod function sets the provided payment method for the current cart using the setPaymentMethodOnCart mutation.

It takes the following parameter: paymentMethod.

export const setPaymentMethod: (paymentMethod: string) => Promise<any>

Parameter	Type	Req?	Description
paymentMethod	string	Yes	A string representing the payment method to be set on the cart.

Returns

The function returns a promise that resolves to the transformed cart data fetched from the API.

transformCart

Usage

See the following example for usage details:

import { setPaymentMethod } from '@/checkout/api/setPaymentMethod';

setPaymentMethod('payment-method-code');

setShippingAddress

The setShippingAddress function sets the shipping address for a specific cart using the setShippingAddressesOnCart mutation.

setShippingAddress({ input: SetShippingAddressesOnCartInput });

Parameter	Type	Req?	Description
address	AddressInput	Yes	An object containing the shipping address details.

Returns

The function returns a promise that resolves to the transformed cart data fetched from the API.

transformCart

Usage

See the following example for usage details:

import { setShippingAddress } from '@/checkout/api/setShippingAddress';

setShippingAddress({
  address: {
    city: 'San Francisco',
    country_code: 'US',
    firstname: 'John',
    lastname: 'Doe',
    postcode: '94103',
    region: {
      region_code: 'CA',
      region: 'California',
    },
    street: ['1234 Main Street'],
    telephone: '555-555-5555',
  },
});

setShippingMethodsOnCart

The setShippingMethodsOnCart function sets the shipping methods for a specific cart using the setShippingMethodsOnCart mutation.

setShippingMethodsOnCart({ input: setShippingMethodsOnCartInput });

Parameter	Type	Req?	Description
shippingMethods	ShippingMethodsOnCart	Yes	An array of shipping methods of type ShippingMethodsOnCart.

Returns

The function returns a promise that resolves to the transformed cart data fetched from the API.

transformCart

Usage

See the following example for usage details:

import { setShippingMethodsOnCart } from '@/checkout/api/setShippingMethods';

setShippingMethodsOnCart([
  {
    carrier_code: 'flatrate',
    method_code: 'flatrate',
  },
]);

synchronizeCheckout

The synchronizeCheckout function synchronizes the checkout state with the current cart information. It ensures that the checkout process is properly initialized, reset, or updated based on the cart data. It uses the getCart function to fetch the necessary cart details.

export const synchronizeCheckout: () => void

Returns

The function does not return any value explicitly; it performs side effects by fetching data and logging errors.

Usage

See the following example for usage details:

import { synchronizeCheckout } from '@/checkout/api/synchronizeCheckout';

synchronizeCheckout('IeTUiU0oCXjm0uRqGCOuhQ2AuQatogjG');