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 });
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 nameconst input = { criteria: { country_code: 'US', region_name: 'FL', },};const estimateShippingMethods = estimateShippingMethods(input);
// By country code and region IDconst input = { criteria: { country_code: 'US', region_id: 18, },};const estimateShippingMethods = estimateShippingMethods(input);
// By country code and postal codeconst input = { criteria: { country_code: 'US', zip: '80000', },};const estimateShippingMethods = estimateShippingMethods(input);
// By country code, region and postal codeconst 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 datafetchCartData();
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 datafetchAndPrepareCheckoutData();
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 datafetchAndLogCustomer();
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 configurationfetchAndLogStoreConfig();
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>
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>
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>
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 });
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 });
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');