= ( callback: (next: unknown, state: State) => P ) => void; export enum AgreementMode { MANUAL = 'manual', AUTO = 'auto', } . . . Agreements?: SlotProps<{ appendAgreement: SlotMethod<{ name: string; mode: AgreementMode; text?: string; translationId?: string; }>; }>; . . . ``` - The `appendAgreement` configuration is a callback function which accepts the following attributes to configure an agreement: - **`name`** The agreement identifier - **`mode`** Specifies the mode how the checkbox should appear: - 'manual': the user is required to manually check and accept the conditions to place an order - 'auto': the checkbox will appear checked by default, conditions are automatically accepted upon checkout - **`text`** Optional attribute that contains directly the text to show, and it accepts HTML with links to a specific page in EDS. In case this attribute is not provided, the `translationId` must to. Finally, if both `text` and `translationId` are provided, the `text` has more preference and its content will be shown - **`translationId`** - This attribute references the translation label that contains the checkbox text. It first looks in the placeholders/checkout.json file for this label identifier, otherwise it looks up the entry in the dictionary. This attribute must be provided if it is not. As a reminder, if both `text` and `translationId` are provided, the `text` has more preference and its content will be shown. ## Example 1: Render a custom agreement The following example renders the `TermsAndConditions` container on the checkout page, displaying a custom agreement that directly includes the label to show along with the link to the EDS page, within the element having the class `.checkout__terms-and-conditions`: ```ts // Checkout Dropin const $termsAndConditions = checkoutFragment.querySelector( '.checkout__terms-and-conditions', ); CheckoutProvider.render(TermsAndConditions, { slots: { Agreements: (ctx) => { ctx.appendAgreement(() => ({ name: 'custom', mode: 'auto', text: 'Custom terms and conditions [Terms & Conditions](/en/terms-and-conditions).', })); }, }, })($termsAndConditions), ``` ## Example 2: Render three different agreements using the translations configured in EDS The following example renders the `TermsAndConditions` container on the checkout page. The container displays three different agreements using the labels from the translations in the **`placeholders`** sheet, within the element with the class `.checkout__terms-and-conditions`: ```ts // Checkout Dropin const $termsAndConditions = checkoutFragment.querySelector( '.checkout__terms-and-conditions', ); CheckoutProvider.render(TermsAndConditions, { slots: { Agreements: (ctx) => { ctx.appendAgreement(() => ({ name: 'default', mode: 'auto', translationId: 'Checkout.TermsAndConditions.label', })); ctx.appendAgreement(() => ({ name: 'terms', mode: 'manual', translationId: 'Checkout.TermsAndConditions.terms_label', })); ctx.appendAgreement(() => ({ name: 'privacy', mode: 'auto', translationId: 'Checkout.TermsAndConditions.privacy_label', })); }, }, })($termsAndConditions), ``` ## Example 3: Render the available agreements configured in the Admin Panel The following example renders the `TermsAndConditions` container on a checkout page, displaying the available agreements configured in the Admin Panel retrieved using the `getCheckoutAgreements()` API function, in the element with the class `.checkout__terms-and-conditions`: ```ts // Checkout Dropin const $termsAndConditions = checkoutFragment.querySelector( '.checkout__terms-and-conditions', ); CheckoutProvider.render(TermsAndConditions, { slots: { Agreements: async (ctx) => { const agreements = await checkoutApi.getCheckoutAgreements(); agreements.forEach((agreement) => { ctx.appendAgreement(() => ({ name: agreement.name, mode: agreement.mode, text: agreement.text, })); }); }, }, })($termsAndConditions), ``` --- # Checkout Dictionary The **Checkout dictionary** contains all user-facing text, labels, and messages displayed by this drop-in. Customize the dictionary to: - **Localize** the drop-in for different languages and regions - **Customize** labels and messages to match your brand voice - **Override** default text without modifying source code for the drop-in Dictionaries use the **i18n (internationalization)** pattern, where each text string is identified by a unique key path. Version: 3.2.0 ## How to customize Override dictionary values during drop-in initialization. The drop-in deep-merges your custom values with the defaults. ```javascript await initialize({ langDefinitions: { en_US: { "Checkout": { "AddressValidation": { "title": "My Custom Title", "subtitle": "My Custom Title" } } } } }); ``` You only need to include the keys you want to change. For multi-language support and advanced patterns, see the [Dictionary customization guide](https://experienceleague.adobe.com/developer/commerce/storefront/dropins/all/dictionaries/). ## Default keys and values Below are the default English (`en_US`) strings provided by the **Checkout** drop-in: ```json title="en_US.json" { "Checkout": { "AddressValidation": { "title": "Verify your address", "subtitle": "To ensure accurate delivery, we suggest the changes highlighted below. Please choose which address you would like to use. If neither option is correct, edit your address.", "suggestedAddress": "Suggested Address", "originalAddress": "Original Address" }, "BillToShippingAddress": { "cartSyncError": "We were unable to save your changes. Please try again later.", "title": "Bill to shipping address" }, "EmptyCart": { "button": "Start shopping", "title": "Your cart is empty" }, "EstimateShipping": { "estimated": "Estimated Shipping", "freeShipping": "Free", "label": "Shipping", "taxToBeDetermined": "TBD", "withoutTaxes": "Excluding taxes", "withTaxes": "Including taxes" }, "LoginForm": { "account": "Already have an account?", "ariaLabel": "Email", "emailExists": { "alreadyHaveAccount": "It looks like you already have an account.", "forFasterCheckout": "for a faster checkout.", "signInButton": "Sign in" }, "floatingLabel": "Email *", "invalidEmailError": "Please enter a valid email address.", "missingEmailError": "Enter an email address.", "cartSyncError": "We were unable to save your changes. Please try again later.", "placeholder": "Enter your email address", "signIn": "Sign In", "signOut": "Sign Out", "switch": "Do you want to switch account?", "title": "Contact details" }, "MergedCartBanner": { "items": { "many": "{{count}} items from a previous session were added to your cart. Please review your new subtotal.", "one": "1 item from a previous session was added to your cart. Please review your new subtotal." } }, "OutOfStock": { "actions": { "removeOutOfStock": "Remove out of stock items", "reviewCart": "Review cart" }, "alert": "Out of stock!", "lowInventory": { "many": "Only {{count}} left!", "one": "Last item!" }, "message": "The following items are out of stock:", "title": "Your cart contains items that are out of stock" }, "PaymentMethods": { "cartSyncError": "We were unable to save your changes. Please try again later.", "emptyState": "No payment methods available", "title": "Payment" }, "PaymentOnAccount": { "referenceNumberLabel": "Custom Reference Number", "referenceNumberPlaceholder": "Enter custom reference number", "referenceNumberHint": "", "availableCreditLabel": "Available Credit", "exceedLimitWarning": "The credit limit is {{creditLimit}}. It will be exceeded by {{exceededAmount}} with this order.", "exceedLimitWarningPrefix": "The credit limit is", "exceedLimitWarningMiddle": ". It will be exceeded by", "exceedLimitWarningSuffix": "with this order.", "exceedLimitError": "Payment On Account cannot be used for this order because your order amount exceeds your credit amount." }, "PurchaseOrder": { "missingReferenceNumberError": "Reference number is required", "referenceNumberHint": "", "referenceNumberLabel": "Custom Reference Number", "referenceNumberPlaceholder": "Enter custom reference number" }, "PlaceOrder": { "button": "Place Order" }, "ServerError": { "button": "Try again", "contactSupport": "If you continue to have issues, please contact support.", "title": "We were unable to process your order", "unexpected": "An unexpected error occurred while processing your order. Please try again later.", "permissionDenied": "You do not have permission to complete checkout. Please contact your administrator for assistance." }, "Quote": { "permissionDenied": "You do not have permission to checkout with this quote.", "dataError": "We were unable to retrieve the quote data. Please try again later." }, "ShippingMethods": { "cartSyncError": "We were unable to save your changes. Please try again later.", "emptyState": "This order can't be shipped to the address provided. Please review the address details you entered and make sure they're correct.", "title": "Shipping options" }, "Summary": { "Edit": "Edit", "heading": "Your Cart ({count})" }, "Addresses": { "billToNewAddress": "Bill to new address", "shippingAddressTitle": "Shipping address", "billingAddressTitle": "Billing address" }, "TermsAndConditions": { "error": "Please accept the Terms and Conditions to continue.", "label": "I have read, understand, and accept our [Terms of Use, Terms of Sales, Privacy Policy, and Return Policy](https://www.adobe.com/legal/terms.html)." }, "title": "Checkout" } } ``` --- # Error handling Errors that occur during the checkout process must be caught and logged with clear context for quick resolution. This prevents unnecessary error propagation and provides better user experience and debugging capabilities. The checkout drop-in component must implement an error handling mechanism to improve observability and debugging capabilities. It is critical to resolve errors promptly to avoid inconsistent states and clearly inform users about what occurred. This prevents data inconsistencies between the local application and the backend, which could result in incorrect orders. ## Generic strategy Most issues arise from API call errors. The system must focus on how these errors propagate from API calls to the user interface and how they are presented to users in a friendly manner across different scenarios. Each container requires a centralized error handling system that captures errors as they occur, enabling control over error management and decision-making about subsequent actions. ## "Optimistic" UI updates with rollback pattern The system implements optimistic UI updates with a rollback mechanism. This technique improves user experience by making the application feel more responsive to user interactions. In an optimistic update, the UI behaves as though a change was successfully completed before receiving confirmation from the backend that it actually occurred. The system optimistically assumes it will eventually receive confirmation rather than an error. This approach allows for a more responsive user experience. When a user performs an action that changes the state, the system immediately sends the information to the backend and optimistically updates the user interface (UI) to reflect the change. This process is called "optimistic" because the system updates the UI with the expectation that the backend will accept the state change. If the system waited for backend confirmation before updating the UI, the delay would negatively impact the user experience. If the backend returns an error, the system performs a rollback to revert to the previous state (when possible) and displays an error message such as an inline alert. Additionally, the containers provide callback functions that merchants can use in the integration layer to display custom error messages. --- # Event handling The checkout drop-in component implements an event-driven architecture that uses the `@adobe-commerce/event-bus` package to facilitate communication between components. This event system enables containers to respond to application state changes, maintain loose coupling between components, and keep their state synchronized with the cart. ## Event system architecture The system uses a publish-subscribe pattern where containers can: 1. Subscribe to specific events using `events.on()` 2. Emit events using `events.emit()` 3. Unsubscribe using `subscription.off()` ## Events declaration The following code snippet shows the contracts that define the relationship between each event and its payload: ```js title='event-bus.d.ts' declare module '@adobe-commerce/event-bus' { interface Events { 'cart/initialized': CartModel | null; 'cart/updated': CartModel | null; 'cart/reset': void; 'cart/merged': { oldCartItems: any[] }; 'checkout/initialized': CheckoutData | null; 'checkout/updated': CheckoutData | null; 'checkout/values': ValuesModel; 'shipping/estimate': ShippingEstimate; authenticated: boolean; error: { source: string; type: string; error: Error }; } interface Cart extends CartModel {} } ``` ## Event subscription If a component wants to listen for an event fired in another component, the component must subscribe to that event. ### Subscription configuration To subscribe to an event, you must provide the following information: 1. The name of the event. 2. The event handler, which is a callback function to be executed when a new event is fired (the payload is passed as a parameter). 3. Event subscriptions can include an additional configuration parameter: - `eager: true`: The handler executes immediately if the event has been emitted previously. - `eager: false`: The handler only responds to future emissions of the event. ```js const subscription = events.on('event-name', handler, { eager: true/false }); ``` ### Events subscribed by containers The following list shows the events subscribed by the checkout drop-in component containers: #### (i) External When the event is fired by external components: - `authenticated`: Indicates that a user has authenticated. - `cart/initialized`: Indicates that a new cart has been created and initialized. - `cart/reset`: Indicates that the order has been placed and the cart is not active any more. - `cart/updated`: Indicates that the cart data has been added or updated. - `cart/merged`: Indicates that a guest cart (created during the anonymous checkout) has been merged with a customer cart (recovered from a previous checkout process). - `cart/data`: Provides cart data. - `locale`: Indicates that the locale has been changed. #### (ii) Internal When the event is fired by internal checkout drop-in components: - `checkout/initialized`: Indicates that the checkout drop-in has been initialized with cart data. - `checkout/updated`: Indicates that the checkout data has been added or updated. - `shipping/estimate`: Provides shipping estimate based on shipping method selected within a shipping address. ### Example Listen to the checkout initialization event: ```js events.on('checkout/initialized', (data) => { // Handle checkout data }); ``` ## Event emission Each component can emit an event if it wants to share information with other components or drop-ins. ### Emission configuration To emit an event, you must provide the following information: 1. The name of the event 2. The payload containing the data to be shared ```js events.emit('event-name', payload); ``` ### Events emitted by containers The following list shows the events emitted by the checkout drop-in component containers: - `checkout/initialized`: Indicates that the checkout drop-in has been initialized with cart data. - `checkout/updated`: Indicates that the checkout data has been added or updated. - `checkout/values`: Provides the local state values. - `shipping/estimate`: Provides shipping estimate based on shipping method selected within a shipping address. - `error`: Indicates that the system has received a network error type. ### Example Emit the checkout values event: ```js events.emit('checkout/values', data); ``` --- # Checkout Data & Events The **Checkout** drop-in uses the [event bus](https://experienceleague.adobe.com/developer/commerce/storefront/sdk/reference/events/) to emit and listen to events for communication between drop-ins and external integrations. Version: 3.2.0 ## Events reference {/* EVENTS_TABLE_START */} | Event | Direction | Description | |-------|-----------|-------------| | [checkout/values](#checkoutvalues-emits) | Emits | Emitted when form or configuration values change. | | [cart/data](#cartdata-listens) | Listens | Fired by Cart (`cart`) when data is available or changes. | | [cart/initialized](#cartinitialized-listens) | Listens | Fired by Cart (`cart`) when the component completes initialization. | | [cart/merged](#cartmerged-listens) | Listens | Fired by Cart (`cart`) when data is merged. | | [cart/reset](#cartreset-listens) | Listens | Fired by Cart (`cart`) when the component state is reset. | | [quote-management/quote-data](#quote-managementquote-data-listens) | Listens | Fired by Quote-management (`quote-management`) when a specific condition or state change occurs. | | [checkout/error](#checkouterror-emits-and-listens) | Emits and listens | Triggered when an error occurs. | | [checkout/initialized](#checkoutinitialized-emits-and-listens) | Emits and listens | Triggered when the component completes initialization. | | [checkout/updated](#checkoutupdated-emits-and-listens) | Emits and listens | Triggered when the component state is updated. | | [shipping/estimate](#shippingestimate-emits-and-listens) | Emits and listens | Triggered when an estimate is calculated. | | [authenticated](#authenticated-listens) | Listens | Fired by Auth (`auth`) when the user authentication state changes. | {/* EVENTS_TABLE_END */} ## Event details The following sections provide detailed information about each event, including its direction, event payload, and usage examples. ### `cart/data` (listens) Triggered when cart data is available or changes. This event provides the current cart state including items, totals, and addresses. #### Event payload ```typescript Cart | null ``` See [`Cart`](#cart) for full type definition. #### Example ```js events.on('cart/data', (payload) => { console.log('cart/data event received:', payload); // Add your custom logic here }); ``` ### `cart/initialized` (listens) Fired by Cart (`cart`) when the component completes initialization. #### Event payload ```typescript CartModel | null ``` See [`CartModel`](#cartmodel) for full type definition. #### Example ```js events.on('cart/initialized', (payload) => { console.log('cart/initialized event received:', payload); // Add your custom logic here }); ``` ### `cart/merged` (listens) Fired by Cart (`cart`) when data is merged. #### Event payload ```typescript { oldCartItems: any[] } ``` #### Example ```js events.on('cart/merged', (payload) => { console.log('cart/merged event received:', payload); // Add your custom logic here }); ``` ### `cart/reset` (listens) Fired by Cart (`cart`) when the component state is reset. #### Event payload #### Example ```js events.on('cart/reset', (payload) => { console.log('cart/reset event received:', payload); // Add your custom logic here }); ``` ### `checkout/error` (emits and listens) Triggered when an error occurs during checkout operations such as address validation, payment processing, or order placement. #### Event payload ```typescript CheckoutError ``` See [`CheckoutError`](#checkouterror) for full type definition. #### Example ```js events.on('checkout/error', (payload) => { console.log('checkout/error event received:', payload); // Add your custom logic here }); ``` ### `checkout/initialized` (emits and listens) Triggered when the checkout component completes initialization with either cart or negotiable quote data. This indicates the checkout is ready for user interaction. #### Event payload ```typescript Cart | NegotiableQuote | null ``` See [`Cart`](#cart), [`NegotiableQuote`](#negotiablequote) for full type definitions. #### Example ```js events.on('checkout/initialized', (payload) => { console.log('checkout/initialized event received:', payload); // Add your custom logic here }); ``` ### `checkout/updated` (emits and listens) Triggered when the checkout state is updated, such as when shipping methods are selected, addresses are entered, or payment methods are chosen. #### Event payload ```typescript Cart | NegotiableQuote | null ``` See [`Cart`](#cart), [`NegotiableQuote`](#negotiablequote) for full type definitions. #### Example ```js events.on('checkout/updated', (payload) => { console.log('checkout/updated event received:', payload); // Add your custom logic here }); ``` ### `checkout/values` (emits) Emitted when form or configuration values change in the checkout. This event is useful for tracking user input, validating form fields, or synchronizing state across components. #### Event payload ```typescript ValuesModel ``` See [`ValuesModel`](#valuesmodel) for full type definition. #### Example ```js events.on('checkout/values', (payload) => { console.log('checkout/values event received:', payload); // Add your custom logic here }); ``` ### `quote-management/quote-data` (listens) Fired by Quote-management (`quote-management`) when a specific condition or state change occurs. #### Event payload ```typescript { quote: NegotiableQuoteModel; permissions: { requestQuote: boolean; editQuote: boolean; deleteQuote: boolean; checkoutQuote: boolean; } } ``` See [`NegotiableQuoteModel`](#negotiablequotemodel) for full type definition. #### Example ```js events.on('quote-management/quote-data', (payload) => { console.log('quote-management/quote-data event received:', payload); // Add your custom logic here }); ``` ### `shipping/estimate` (emits and listens) Triggered when shipping cost estimates are calculated for a given address. This event provides both the address used for estimation and the resulting shipping method with its cost. #### Event payload ```typescript ShippingEstimate ``` See [`ShippingEstimate`](#shippingestimate) for full type definition. #### Example ```js events.on('shipping/estimate', (payload) => { console.log('shipping/estimate event received:', payload); // Add your custom logic here }); ``` ### `authenticated` (listens) Fired by Auth (`auth`) when the user authentication state changes. Checkout listens to this event to update the `LoginForm` display — hiding the sign-in prompt when a user is authenticated and restoring it when they sign out. #### Event payload ```typescript boolean ``` The payload is `true` if the user is authenticated, `false` otherwise. #### Example ```js events.on('authenticated', (isAuthenticated) => { console.log('authenticated event received:', isAuthenticated); // Add your custom logic here }); ``` ## Data Models The following data models are used in event payloads for this drop-in. ### Cart The `Cart` interface represents a shopping cart including items, pricing, addresses, and shipping/payment methods. Used in: [`cart/data`](#cartdata-listens), [`checkout/initialized`](#checkoutinitialized-emits-and-listens), [`checkout/updated`](#checkoutupdated-emits-and-listens). ```ts interface Cart { type: 'cart'; availablePaymentMethods?: PaymentMethod[]; billingAddress?: CartAddress; email?: string; id: string; isEmpty: boolean; isGuest: boolean; isVirtual: boolean; selectedPaymentMethod?: PaymentMethod; shippingAddresses: CartShippingAddress[]; } ``` ### CartModel Used in: [`cart/initialized`](#cartinitialized-listens). ```ts interface CartModel { id: string; totalQuantity: number; errors?: ItemError[]; items: Item[]; miniCartMaxItems: Item[]; total: { includingTax: Price; excludingTax: Price; }; discount?: Price; subtotal: { excludingTax: Price; includingTax: Price; includingDiscountOnly: Price; }; appliedTaxes: TotalPriceModifier[]; totalTax?: Price; appliedDiscounts: TotalPriceModifier[]; shipping?: Price; isVirtual?: boolean; addresses: { shipping?: { countryCode: string; zipCode?: string; regionCode?: string; }[]; }; isGuestCart?: boolean; } ``` ### CheckoutError Used in: [`checkout/error`](#checkouterror-emits-and-listens). ```ts interface CheckoutError { /** * The primary, user-friendly error message. This should be safe to display * directly in the UI. * @example "Your card was declined." */ message: string; /** * An optional, unique error code for programmatic handling. This allows the * ServerError component to show specific icons, links, or actions. * @example "payment_intent_declined" */ code?: string; } ``` ### NegotiableQuote The `NegotiableQuote` interface represents a B2B negotiable quote, which functions similarly to a cart but includes additional negotiation features like price adjustments and approval workflows. Used in: [`checkout/initialized`](#checkoutinitialized-emits-and-listens), [`checkout/updated`](#checkoutupdated-emits-and-listens). ```ts interface NegotiableQuote { type: 'quote'; availablePaymentMethods?: PaymentMethod[]; billingAddress?: Address; email?: string; isEmpty: boolean; isVirtual: boolean; name: string; selectedPaymentMethod?: PaymentMethod; shippingAddresses: ShippingAddress[]; status: NegotiableQuoteStatus; uid: string; } ``` ### NegotiableQuoteModel Used in: [`quote-management/quote-data`](#quote-managementquote-data-listens). ```ts interface NegotiableQuoteModel { uid: string; name: string; createdAt: string; salesRepName: string; expirationDate: string; updatedAt: string; status: NegotiableQuoteStatus; buyer: { firstname: string; lastname: string; }; templateName?: string; comments?: { uid: string; createdAt: string; author: { firstname: string; lastname: string; }; text: string; attachments?: { name: string; url: string; }[]; }[]; history?: NegotiableQuoteHistoryEntry[]; prices: { appliedDiscounts?: Discount[]; appliedTaxes?: Tax[]; discount?: Currency; grandTotal?: Currency; grandTotalExcludingTax?: Currency; shippingExcludingTax?: Currency; shippingIncludingTax?: Currency; subtotalExcludingTax?: Currency; subtotalIncludingTax?: Currency; subtotalWithDiscountExcludingTax?: Currency; totalTax?: Currency; }; items: NegotiableQuoteCartItem[]; shippingAddresses?: ShippingAddress[]; canCheckout: boolean; canSendForReview: boolean; } ``` ### ShippingEstimate Used in: [`shipping/estimate`](#shippingestimate-emits-and-listens). ```ts interface ShippingEstimate { address: PartialShippingAddress; availableShippingMethods?: ShippingMethod[]; shippingMethod: ShippingEstimateShippingMethod | null; success?: boolean; } ``` ### ValuesModel Used in: [`checkout/values`](#checkoutvalues-emits). ```ts interface ValuesModel { email: string; isBillToShipping: boolean | undefined; selectedPaymentMethod: PaymentMethod | null; selectedShippingMethod: ShippingMethod | null; } ``` --- # Extending the checkout drop-in component The checkout drop-in component follows the Adobe Commerce out-of-process extensibility (OOPE) pattern, which requires components to be flexible and extensible. When the checkout drop-in component lacks a specific feature, it provides mechanisms that allow developers to easily expand and customize its functionality. ## GraphQL API To extend the data payload of the drop-in, developers must use the GraphQL Extensibility API. This API allows developers to extend existing GraphQL operations to meet additional data requirements without increasing code complexity or negatively impacting performance. The API provides a flexible and efficient way to customize GraphQL fragments by integrating build-time modifications into the storefront's development pipeline. GraphQL fragments are reusable pieces of GraphQL that developers can use to extend or customize the API for a drop-in component. Drop-in components expose the list of fragments that can be extended in the `fragments.ts` file. If the drop-in component does not expose these fragments, the build process fails when you install the application because it cannot locate the fragment you want to extend. The checkout drop-in component exposes the following fragments: ```js title='fragments.ts' export { BILLING_CART_ADDRESS_FRAGMENT, SHIPPING_CART_ADDRESS_FRAGMENT, } from '@/checkout/api/graphql/CartAddressFragment.graphql'; export { CHECKOUT_DATA_FRAGMENT } from '@/checkout/api/graphql/CheckoutDataFragment.graphql'; export { CUSTOMER_FRAGMENT } from '@/checkout/api/graphql/CustomerFragment.graphql'; export { NEGOTIABLE_QUOTE_BILLING_ADDRESS_FRAGMENT, NEGOTIABLE_QUOTE_SHIPPING_ADDRESS_FRAGMENT, } from '@/checkout/api/graphql/NegotiableQuoteAddressFragment.graphql'; export { NEGOTIABLE_QUOTE_FRAGMENT } from '@/checkout/api/graphql/NegotiableQuoteFragment.graphql'; export { AVAILABLE_PAYMENT_METHOD_FRAGMENT, SELECTED_PAYMENT_METHOD_FRAGMENT, } from '@/checkout/api/graphql/PaymentMethodFragment.graphql'; export { AVAILABLE_SHIPPING_METHOD_FRAGMENT, ESTIMATE_SHIPPING_METHOD_FRAGMENT, SELECTED_SHIPPING_METHOD_FRAGMENT, } from '@/checkout/api/graphql/ShippingMethodFragment.graphql'; ``` The fragment names above match the symbols exported from `@dropins/storefront-checkout` (for example, the package `fragments` entry). The `@/checkout/...` import paths reflect the checkout drop-in source layout; in your storefront, point `build.mjs` at the same fragment names using whatever `fragments.ts` path and re-exports your scaffold provides. The `ESTIMATE_SHIPPING_METHOD_FRAGMENT` applies to the `estimateShippingMethods` mutation. Pair it with the `EstimateShippingModel` initializer model when you need to transform extended fields from the shipping estimate response. `AVAILABLE_SHIPPING_METHOD_FRAGMENT` and `SELECTED_SHIPPING_METHOD_FRAGMENT` cover cart shipping methods on the main checkout flow. ### Extend or customize a fragment To make GraphQL fragments extensible in the drop-in component, you must first update the GraphQL fragment that the drop-in uses to request the additional field. You accomplish this by modifying the `build.mjs` script located at the root of your storefront project. The `build.mjs` script automatically generates a new GraphQL query for the checkout drop-in component when you run the install command. This generated query includes the additional data that you specified in your fragment extensions. #### Example 1: Adding new information The merchant wants to extend the customer information by adding the gender and date of birth data. ```js title='build.mjs' /* eslint-disable import/no-extraneous-dependencies */ overrideGQLOperations([ { npm: '@dropins/storefront-checkout', operations: [ ` fragment CUSTOMER_FRAGMENT on Customer { gender date_of_birth } `, ], }, ]); ``` After extending the API, you must extend the models and transformers during the initialization phase if data transformation is required. You accomplish this by modifying the `/scripts/initializers/checkout.js` script. ```js title='/scripts/initializers/checkout.js' // Initialize checkout await initializeDropin(async () => { // Register the checkout component with models extensibility const models = { CustomerModel: { transformer: (data) => ({ gender: ((gender) => { switch (gender) { case 1: return "Male"; case 2: return "Female"; case 3: return "Not Specified"; default: return ""; } })(data?.gender), dateOfBirth: data?.date_of_birth, }), }, }; // Register initializers return initializers.mountImmediately(initialize, { models }); })(); ``` #### Example 2: Removing information The merchant wants to remove the selected payment method data. ```js title='build.mjs' /* eslint-disable import/no-extraneous-dependencies */ overrideGQLOperations([ { npm: '@dropins/storefront-checkout', skipFragments: ['SELECTED_PAYMENT_METHOD_FRAGMENT'], operations: [], }, ]); ``` > **Extending fragments** If the `build.mjs` script references a fragment that the drop-in component does not expose, the application build process fails. > **Extending drop-in components** See the [GraphQL Extensibility API](https://experienceleague.adobe.com/developer/commerce/storefront/sdk/reference/graphql/) and [Extending drop-in components](https://experienceleague.adobe.com/developer/commerce/storefront/dropins/all/extending/) documentation to learn more about how to extend the API for a drop-in component. --- # Checkout Functions The Checkout drop-in provides API functions that enable you to programmatically control behavior, fetch data, and integrate with Adobe Commerce backend services. Version: 3.2.0 | Function | Description | | --- | --- | | [`authenticateCustomer`](#authenticatecustomer) | API function for the drop-in. | | [`estimateShippingMethods`](#estimateshippingmethods) | Calls the `estimateShippingMethods` mutation. | | [`getCart`](#getcart) | Retrieves the current cart's checkout data from Adobe Commerce. | | [`getCheckoutAgreements`](#getcheckoutagreements) | Returns a list with the available checkout agreements. | | [`getCompanyCredit`](#getcompanycredit) | API function for the drop-in. | | [`getCustomer`](#getcustomer) | API function for the drop-in. | | [`getNegotiableQuote`](#getnegotiablequote) | Retrieves a negotiable quote for B2B customers. | | [`getStoreConfig`](#getstoreconfig) | The `storeConfig` query defines information about a store's configuration. | | [`getStoreConfigCache`](#getstoreconfigcache) | API function for the drop-in. | | [`initializeCheckout`](#initializecheckout) | API function for the drop-in. | | [`isEmailAvailable`](#isemailavailable) | Calls the `isEmailAvailable` query. | | [`resetCheckout`](#resetcheckout) | API function for the drop-in. | | [`setBillingAddress`](#setbillingaddress) | Calls the `setBillingAddressOnCart` mutation. | | [`setGuestEmailOnCart`](#setguestemailoncart) | Calls the `setGuestEmailOnCart` mutation. | | [`setPaymentMethod`](#setpaymentmethod) | Calls the `setPaymentMethodOnCart` mutation. | | [`setShippingAddress`](#setshippingaddress) | Calls the `setShippingAddressesOnCart` mutation. | | [`setShippingMethods`](#setshippingmethods) | Sets one or more shipping methods on the cart. Also exported as `setShippingMethodsOnCart`. | | [`synchronizeCheckout`](#synchronizecheckout) | API function for the drop-in. | ## authenticateCustomer ### Signature ```typescript function authenticateCustomer(authenticated = false): Promise ``` ### Parameters | Parameter | Type | Required | Description | |---|---|---|---| --- ## estimateShippingMethods The `estimateShippingMethods` function calls the https://developer.adobe.com/commerce/webapi/graphql/schema/cart/mutations/estimate-shipping-methods/ mutation. ```ts const estimateShippingMethods = async ( input?: EstimateShippingInput ): Promise ``` | Parameter | Type | Req? | Description | |---|---|---|---| | `input` | `EstimateShippingInput` | No | An object of type EstimateShippingInput, which contains a criteria object including the following fields: country_code, region_name, region_id, and zip. | ### Events Emits the [`shipping/estimate`](https://experienceleague.adobe.com/developer/commerce/storefront/dropins/checkout/events/#shippingestimate-emits-and-listens) event. ### Returns Returns an array of [`ShippingMethod`](#shippingmethod) objects or `null`. ## getCart The `getCart` function retrieves the current cart's checkout data from Adobe Commerce. It automatically uses the cart ID from internal state and calls either the `getCart` or `customerCart` `GraphQL` query depending on authentication status. The returned data includes billing address, shipping addresses, available and selected payment methods, email, total quantity, and virtual cart status—all the information needed to complete the checkout process. ```ts const getCart = async (): Promise ``` ### Events Does not emit any drop-in events. ### Returns Returns a [`Cart`](#cart) model containing complete checkout information. ## getCheckoutAgreements The `getCheckoutAgreements` function returns a list with the available checkout agreements. Each agreement has a name and the mode (manual or automatic). ```ts const getCheckoutAgreements = async (): Promise ``` ### Events Does not emit any drop-in events. ### Returns Returns an array of [`CheckoutAgreement`](#checkoutagreement) objects. ## getCompanyCredit ```ts const getCompanyCredit = async (): Promise ``` ### Events Does not emit any drop-in events. ### Returns Returns [`CompanyCredit`](#companycredit) or `null`. ## getCustomer ```ts const getCustomer = async (): Promise ``` ### Events Does not emit any drop-in events. ### Returns Returns [`Customer`](#customer) or `null`. ## getNegotiableQuote The `getNegotiableQuote` function retrieves a negotiable quote for B2B customers. The function calls the https://developer.adobe.com/commerce/webapi/graphql/schema/b2b/negotiable-quote/queries/quote/ query. ```ts const getNegotiableQuote = async ( input: GetNegotiableQuoteInput = {} ): Promise ``` | Parameter | Type | Req? | Description | |---|---|---|---| | `input` | `GetNegotiableQuoteInput` | No | Input parameters including the quote UID to retrieve. | ### Events Does not emit any drop-in events. ### Returns Returns `void`. ## getStoreConfig The `storeConfig` query defines information about a store's configuration. You can query a non-default store by changing the header in your `GraphQL` request. ```ts const getStoreConfig = async (): Promise ``` ### Events Does not emit any drop-in events. ### Returns Returns `void`. ## getStoreConfigCache ```ts const getStoreConfigCache = async (): any ``` ### Events Does not emit any drop-in events. ### Returns Returns `void`. ## initializeCheckout ### Signature ```typescript function initializeCheckout(input: InitializeInput): Promise ``` ### Parameters | Parameter | Type | Required | Description | |---|---|---|---| | `input` | `InitializeInput` | Yes | | --- ## isEmailAvailable The `isEmailAvailable` function calls the https://developer.adobe.com/commerce/webapi/graphql/schema/customer/queries/is-email-available/ query. ```ts const isEmailAvailable = async ( email: string ): Promise ``` | Parameter | Type | Req? | Description | |---|---|---|---| | `email` | `string` | Yes | A string representing the email address to check for availability. | ### Events Does not emit any drop-in events. ### Returns Returns [`EmailAvailability`](#emailavailability). ## resetCheckout ```ts const resetCheckout = async (): any ``` ### Events Emits the [`checkout/updated`](https://experienceleague.adobe.com/developer/commerce/storefront/dropins/checkout/events/#checkoutupdated-emits-and-listens) event. ### Returns Returns `void`. ## setBillingAddress The `setBillingAddress` function calls the https://developer.adobe.com/commerce/webapi/graphql/schema/cart/mutations/set-billing-address/ mutation. ```ts const setBillingAddress = async ( input: BillingAddressInputModel ): Promise ``` | Parameter | Type | Req? | Description | |---|---|---|---| | `input` | `BillingAddressInputModel` | Yes | The billing address to set on the cart, including street, city, region, country, and postal code. | ### Events Does not emit any drop-in events. ### Returns Returns `void`. ## setGuestEmailOnCart The `setGuestEmailOnCart` function calls the https://developer.adobe.com/commerce/webapi/graphql/schema/cart/mutations/set-guest-email/ mutation. ```ts const setGuestEmailOnCart = async ( email: string ): Promise ``` | Parameter | Type | Req? | Description | |---|---|---|---| | `email` | `string` | Yes | The guest customer's email address for order confirmation and communication. | ### Events Does not emit any drop-in events. ### Returns Returns `void`. ## setPaymentMethod The `setPaymentMethod` function calls the https://developer.adobe.com/commerce/webapi/graphql/schema/cart/mutations/set-payment-method/ mutation. ```ts const setPaymentMethod = async ( input: PaymentMethodInputModel ): Promise ``` | Parameter | Type | Req? | Description | |---|---|---|---| | `input` | `PaymentMethodInputModel` | Yes | The payment method code and additional payment data required by the selected payment processor. | ### Events Does not emit any drop-in events. ### Returns Returns `void`. ## setShippingAddress The `setShippingAddress` function calls the https://developer.adobe.com/commerce/webapi/graphql/schema/cart/mutations/set-shipping-address/ mutation. ```ts const setShippingAddress = async ( input: ShippingAddressInputModel ): Promise ``` | Parameter | Type | Req? | Description | |---|---|---|---| | `input` | `ShippingAddressInputModel` | Yes | The shipping address to set on the cart, including street, city, region, country, and postal code. | ### Events Does not emit any drop-in events. ### Returns Returns `void`. ## setShippingMethods The `setShippingMethods` function sets one or more shipping methods on the cart. The function calls the https://developer.adobe.com/commerce/webapi/graphql/schema/cart/mutations/set-shipping-method/ mutation. ```ts const setShippingMethods = async ( input: Array ): Promise ``` | Parameter | Type | Req? | Description | |---|---|---|---| | `input` | `Array` | Yes | An array of shipping method objects, each containing a carrier code and method code. | ### Events Does not emit any drop-in events. ### Returns Returns `void`. ## synchronizeCheckout ### Signature ```typescript function synchronizeCheckout(data: SynchronizeInput): Promise ``` ### Parameters | Parameter | Type | Required | Description | |---|---|---|---| | `data` | `SynchronizeInput` | Yes | | --- ## Data Models The following data models are used by functions in this drop-in. ### Cart The `Cart` object is returned by the following functions: [`getCart`](#getcart). ```ts interface Cart { type: 'cart'; availablePaymentMethods?: PaymentMethod[]; billingAddress?: CartAddress; email?: string; id: string; isEmpty: boolean; isGuest: boolean; isVirtual: boolean; selectedPaymentMethod?: PaymentMethod; shippingAddresses: CartShippingAddress[]; } ``` ### CheckoutAgreement The `CheckoutAgreement` object is returned by the following functions: [`getCheckoutAgreements`](#getcheckoutagreements). ```ts interface CheckoutAgreement { content: AgreementContent; id: number; mode: AgreementMode; name: string; text: string; } ``` ### CompanyCredit The `CompanyCredit` object is returned by the following functions: [`getCompanyCredit`](#getcompanycredit). ```ts type CompanyCredit = { availableCredit: Money; exceedLimit?: boolean; }; ``` ### Customer The `Customer` object is returned by the following functions: [`getCustomer`](#getcustomer). ```ts interface Customer { firstName: string; lastName: string; email: string; } ``` ### EmailAvailability The `EmailAvailability` object is returned by the following functions: [`isEmailAvailable`](#isemailavailable). ```ts type EmailAvailability = boolean; ``` ### ShippingMethod The `ShippingMethod` object is returned by the following functions: [`estimateShippingMethods`](#estimateshippingmethods). ```ts type ShippingMethod = { amount: Money; carrier: Carrier; code: string; title: string; value: string; amountExclTax?: Money; amountInclTax?: Money; }; ``` {/* This documentation is auto-generated from the drop-in source repository: REPO_URL */} --- # Checkout overview The checkout drop-in component provides a variety of fully-customizable controls to help complete a purchase. These controls include forms to introduce required information for contact details like email address, delivery and billing addresses, shipping options, and payment methods. Established customers who added items to the cart as a guest have the ability to sign in, automatically loading default addresses and contact details. ## Available resources The checkout drop-in component includes the following resources: - **[API Functions](https://experienceleague.adobe.com/developer/commerce/storefront/dropins/checkout/functions/)** - Core functions for managing checkout operations like authentication, shipping methods, and order placement - **[Utility Functions](https://experienceleague.adobe.com/developer/commerce/storefront/dropins/checkout/utilities/)** - Helper functions for DOM manipulation, form handling, data transforms, and more - **[Containers](https://experienceleague.adobe.com/developer/commerce/storefront/dropins/checkout/containers/)** - Pre-built UI components for checkout steps - **[Event Handling](https://experienceleague.adobe.com/developer/commerce/storefront/dropins/all/events/)** - Event-driven architecture for component communication ## Supported Commerce features The following table provides an overview of the Adobe Commerce features that the checkout component supports: | Feature | Status | | ---------------------------------------------------------------------------------- | ----------------------------------------- | | All product types | Supported | | Any checkout flow (BOPIS, one/two step) | Supported | | Any checkout layout | Supported | | Apply coupons to the order | Supported | | Apply gift cards to the order | Supported | | Cart rules | Supported | | Create account after checkout | Supported | | Custom customer address attributes | Supported | | Customer address selection at checkout | Supported | | Customer checkout | Supported | | Customer segments | Supported | | Default customer shipping and billing applied at checkout | Supported | | Extensibility for payment providers | Supported | | Guest checkout | Supported | | Log in during checkout | Supported | | Low product stock alert | Supported | | Out of stock/insufficient quantity products | Supported | | Taxes: Fixed | Roadmap| | Taxes: Sales, VAT | Supported | | Terms and conditions consent | Supported | | Zero subtotal checkout | Supported | | Multi-step checkout | Supported | --- # Checkout initialization The **Checkout initializer** configures the checkout flow, payment processing, shipping options, and order placement. Use initialization to customize checkout behavior, integrate payment providers, and transform checkout data models to match your storefront requirements. Version: 3.2.0 ## Configuration options The following table describes the configuration options available for the **Checkout** initializer: | Parameter | Type | Req? | Description | |---|---|---|---| | `langDefinitions` | [`LangDefinitions`](#langdefinitions) | No | Language definitions for internationalization (i18n). Override dictionary keys for localization or branding. | | `models` | [`Record`](#models) | No | Custom data models for type transformations. Extend or modify default models with custom fields and transformers. | | `defaults` | [`defaults`](#defaults) | No | Configures default checkout behaviors including whether billing address defaults to shipping address and which shipping method is pre-selected. | | `shipping` | [`shipping`](#shipping) | No | Configures shipping method filtering to control which shipping options are available to customers during checkout. | | `features` | [`features`](#features) | No | Enables or disables checkout features including B2B quote functionality and custom login routing. | ## Default configuration The initializer runs with these defaults when no configuration is provided: ```javascript title="scripts/initializers/checkout.js" // All configuration options are optional await initializers.mountImmediately(initialize, { langDefinitions: {}, // Uses built-in English strings models: {}, // Uses default data models // Drop-in-specific defaults: // defaults: undefined // See configuration options below // shipping: undefined // See configuration options below // features: undefined // See configuration options below }); ``` ## Language definitions Override dictionary keys for localization or branding. The `langDefinitions` object maps locale keys to custom strings that override default text for the drop-in. ```javascript title="scripts/initializers/checkout.js" const customStrings = { 'AddToCart': 'Add to Bag', 'Checkout': 'Complete Purchase', 'Price': 'Cost', }; const langDefinitions = { default: customStrings, }; await initializers.mountImmediately(initialize, { langDefinitions }); ``` > For complete dictionary customization including all available keys and multi-language support, see the [Checkout Dictionary](https://experienceleague.adobe.com/developer/commerce/storefront/dropins/checkout/dictionary/) page. ## Customizing data models Extend or transform data models by providing custom transformer functions. Use the `models` option to add custom fields or modify existing data structures returned from the backend. ### Available models The following models can be customized through the `models` configuration option: | Model | Description | |---|---| | [`CartModel`](#cartmodel) | Transforms cart data during checkout including items, pricing, shipping, billing, and payment information. Use this to add custom fields specific to the checkout flow. | | [`CustomerModel`](#customermodel) | Transforms `CustomerModel` data from `GraphQL`. | The following example shows how to customize the `CartModel` model for the **Checkout** drop-in: ```javascript title="scripts/initializers/checkout.js" const models = { CartModel: { transformer: (data) => ({ // Add custom fields from backend data customField: data?.custom_field, promotionBadge: data?.promotion?.label, // Transform existing fields displayPrice: data?.price?.value ? `${data.price.value}` : 'N/A', }), }, }; await initializers.mountImmediately(initialize, { models }); ``` ## Drop-in configuration The **Checkout initializer** configures the checkout flow, payment processing, shipping options, and order placement. Use initialization to customize checkout behavior, integrate payment providers, and transform checkout data models to match your storefront requirements. ```javascript title="scripts/initializers/checkout.js" await initializers.mountImmediately(initialize, { defaults: {}, shipping: {}, features: {}, langDefinitions: {}, models: {}, }); ``` > Refer to the [Configuration options](#configuration-options) table for detailed descriptions of each option. ## Configuration types The following TypeScript definitions show the structure of each configuration object: ### defaults Configures default checkout behaviors including whether billing address defaults to shipping address and which shipping method is pre-selected. ```typescript defaults?: { isBillToShipping?: boolean; selectedShippingMethod?: Selector; } ``` ### shipping Configures shipping method filtering to control which shipping options are available to customers during checkout. ```typescript shipping?: { filterOptions?: Filter; } ``` ### features Enables or disables checkout features including B2B quote functionality and custom login routing. ```typescript features?: { b2b?: { quotes?: boolean; routeLogin?: () => string | void; }; } ``` ### langDefinitions Maps locale identifiers to dictionaries of key-value pairs. The `default` locale is used as the fallback when no specific locale matches. Each dictionary key corresponds to a text string used in the drop-in UI. ```typescript langDefinitions?: { [locale: string]: { [key: string]: string; }; }; ``` ### models Maps model names to transformer functions. Each transformer receives data from GraphQL and returns a modified or extended version. Use the `Model` type from `@dropins/tools` to create type-safe transformers. ```typescript models?: { [modelName: string]: Model; }; ``` ## Model definitions The following TypeScript definitions show the structure of each customizable model: ### CartModel ```typescript export interface CartAddress extends Address {} ``` ### CustomerModel ```typescript export interface Customer { firstName: string; lastName: string; email: string; } ``` --- # Checkout Quick Start The Checkout drop-in component provides a customizable UI for the checkout process. The checkout component is designed to be integrated into your storefront and provides a seamless checkout experience for customers. Version: 3.2.0 ## Prerequisites Since the checkout component relies on containers from several other drop-in components, you must install and configure those components before you can use the checkout component. The https://github.com/hlxsites/aem-boilerplate-commerce includes all of the necessary drop-in components and configurations to help you get started quickly, so Adobe recommends relying on the boilerplate instead of installing, configuring, and integrating the drop-in components individually. ## Admin configuration Before you can use the checkout component on your storefront, you must enable and configure https://experienceleague.adobe.com/en/docs/commerce-admin/stores-sales/payments/payments and https://experienceleague.adobe.com/en/docs/commerce-admin/stores-sales/point-of-purchase/checkout/checkout-process in the Adobe Commerce Admin. :::note The checkout [overview](https://experienceleague.adobe.com/developer/commerce/storefront/dropins/checkout/) provides a summary of supported Adobe Commerce features. ::: ## Quick example The Checkout drop-in is included in the https://github.com/hlxsites/aem-boilerplate-commerce. This example shows the basic pattern: ```js // 1. Import initializer (handles all setup) // 2. Import the container you need // 3. Import the provider // 4. Render in your block export default async function decorate(block) { await provider.render(AddressValidation, { // Configuration options - see Containers page })(block); } ``` **New to drop-ins?** See the [Using drop-ins](https://experienceleague.adobe.com/developer/commerce/storefront/dropins/all/quick-start/) guide for complete step-by-step instructions. ## Quick reference **Import paths:** - Initializer: `import '../../scripts/initializers/checkout.js'` - Containers: `import ContainerName from '@dropins/storefront-checkout/containers/ContainerName.js'` - Provider: `import { render } from '@dropins/storefront-checkout/render.js'` **Package:** `@dropins/storefront-checkout` **Version:** 3.2.0 (verify compatibility with your Commerce instance) **Example container:** `AddressValidation` ## Learn more - [Containers](https://experienceleague.adobe.com/developer/commerce/storefront/dropins/checkout/containers/) - Available UI components and configuration options - [Initialization](https://experienceleague.adobe.com/developer/commerce/storefront/dropins/checkout/initialization/) - Customize initializer settings and data models - [Functions](https://experienceleague.adobe.com/developer/commerce/storefront/dropins/checkout/functions/) - Control drop-in behavior programmatically - [Events](https://experienceleague.adobe.com/developer/commerce/storefront/dropins/checkout/events/) - Listen to and respond to drop-in state changes - [Slots](https://experienceleague.adobe.com/developer/commerce/storefront/dropins/checkout/slots/) - Extend containers with custom content --- # Checkout Slots The Checkout drop-in exposes slots for customizing specific UI sections. Use slots to replace or extend container components. For default properties available to all slots, see [Extending drop-in components](https://experienceleague.adobe.com/developer/commerce/storefront/dropins/all/extending/). Version: 3.2.0 | Container | Slots | |-----------|-------| | [`LoginForm`](#loginform-slots) | `Heading`, `Preferences` | | [`PaymentMethods`](#paymentmethods-slots) | None | | [`PlaceOrder`](#placeorder-slots) | `Content` | | [`ShippingMethods`](#shippingmethods-slots) | `ShippingMethodItem` | | [`TermsAndConditions`](#termsandconditions-slots) | `Agreements` | ## LoginForm slots The slots for the `LoginForm` container allow you to customize its appearance and behavior. ```typescript interface LoginFormProps { slots?: { Heading?: SlotProps<{ authenticated: boolean; }>; Preferences?: SlotProps<{ email: string; isEmailValid: boolean; isAuthenticated: boolean; }>; }; } ``` ### Heading slot The Heading slot allows you to customize the heading section of the `LoginForm` container. #### Example ```js await provider.render(LoginForm, { slots: { Heading: (ctx) => { // Your custom implementation const element = document.createElement('div'); element.innerText = 'Custom Heading'; ctx.appendChild(element); } } })(block); ``` ### Preferences slot The Preferences slot allows you to add custom marketing preference fields within the login form. This slot enables merchants to add their own consent options (such as newsletter subscriptions, SMS updates, or promotional offers) based on their specific business needs and compliance requirements. The slot receives a context with the following properties: - `email` - The current email address entered by the user - `isEmailValid` - A boolean indicating whether the email address is valid - `isAuthenticated` - A boolean indicating whether the user is authenticated #### Example ```js await provider.render(LoginForm, { slots: { Preferences: (ctx) => { if (!ctx.isEmailValid || ctx.isAuthenticated) return; const element = document.createElement('div'); element.innerHTML = ` Subscribe to our newsletter `; ctx.appendChild(element); } } })(block); ``` ## PaymentMethods slots The slots for the `PaymentMethods` container allow you to customize its appearance and behavior. ```typescript interface PaymentMethodsProps { slots?: { Methods?: PaymentMethodHandlers; }; } ``` ## PlaceOrder slots The slots for the `PlaceOrder` container allow you to customize its appearance and behavior. ```typescript interface PlaceOrderProps { slots?: { Content?: SlotProps; }; } ``` ### Content slot The Content slot allows you to customize the content section of the `PlaceOrder` container. #### Example ```js await provider.render(PlaceOrder, { slots: { Content: (ctx) => { // Your custom implementation const element = document.createElement('div'); element.innerText = 'Custom Content'; ctx.appendChild(element); } } })(block); ``` ## ShippingMethods slots The slots for the `ShippingMethods` container allow you to fully replace the default shipping method UI with a custom implementation. ```typescript interface ShippingMethodsProps { slots?: { ShippingMethodItem?: SlotProps<{ method: ShippingMethod; isSelected: boolean; onSelect: () => void; }>; }; } ``` ### ShippingMethodItem slot The ShippingMethodItem slot allows you to replace the default RadioButton or ToggleButton UI for each shipping method with a completely custom element. Use `ctx.replaceWith()` to provide your own UI and `ctx.onRender()` to update it when the context changes. The slot receives a `ShippingMethodItemContext` with the following properties: - `method` - The shipping method data (`ShippingMethod` model with carrier, amount, title, and so on.) - `isSelected` - Whether this method is currently selected - `onSelect` - Callback that selects this shipping method and triggers the API call to set it on the cart The internal presentation component that renders the list also accepts a `busy` flag (see the checkout drop-in `ShippingMethods` UI props) when the flow is waiting on pending checkout updates or a shipping estimate. That state is not part of `ShippingMethodItemContext`. #### Example ```js function buildShippingMethodCard(ctx) { const { method, isSelected } = ctx; const price = method.amount.value === 0 ? 'FREE' : `$${method.amount.value.toFixed(2)}`; const card = document.createElement('label'); card.className = `custom-shipping-card ${isSelected ? 'custom-shipping-card--selected' : ''}`; card.innerHTML = ` ${method.carrier.title} ${method.title} ${price} `; card.querySelector('input').addEventListener('change', () => { ctx.onSelect(); }); return card; } await provider.render(ShippingMethods, { slots: { ShippingMethodItem: (ctx) => { const card = buildShippingMethodCard(ctx); ctx.replaceWith(card); ctx.onRender((updatedCtx) => { card.className = `custom-shipping-card ${updatedCtx.isSelected ? 'custom-shipping-card--selected' : ''}`; card.querySelector('input').checked = updatedCtx.isSelected; }); }, }, })(block); ``` ## TermsAndConditions slots The slots for the `TermsAndConditions` container allow you to customize its appearance and behavior. ```typescript interface TermsAndConditionsProps { slots?: { Agreements?: SlotProps<{ appendAgreement: SlotMethod<{ name: string; mode: AgreementMode; translationId?: string; text?: string; }>; }>; }; } ``` ### Agreements slot The Agreements slot allows you to customize the agreements section of the `TermsAndConditions` container. #### Example ```js await provider.render(TermsAndConditions, { slots: { Agreements: (ctx) => { // Your custom implementation const element = document.createElement('div'); element.innerText = 'Custom Agreements'; ctx.appendChild(element); } } })(block); ``` --- # Checkout styles Customize the Checkout drop-in using CSS classes and design tokens. This page covers the Checkout-specific container classes and customization examples. For comprehensive information about design tokens, responsive breakpoints, and styling best practices, see [Styling Drop-In Components](https://experienceleague.adobe.com/developer/commerce/storefront/dropins/all/styling/). Version: 3.2.0 ## Customization example Add this to https://github.com/hlxsites/aem-boilerplate-commerce/blob/main/blocks/commerce-checkout/commerce-checkout.css to customize the Checkout drop-in. For a complete list of available design tokens (colors, spacing, typography, and more), see the [Design tokens reference](https://experienceleague.adobe.com/developer/commerce/storefront/dropins/all/styling/#design-tokens-reference). ```css title="styles/styles.css" del={2-2} ins={3-3} .checkout-out-of-stock__title { color: var(--color-neutral-900); color: var(--color-brand-900); } ``` ## Container classes The Checkout drop-in uses BEM-style class naming. Use the browser DevTools to inspect elements and find specific class names. ```css /* AddressValidation */ .checkout-address-validation {} .checkout-address-validation__option {} .checkout-address-validation__option-title {} .checkout-address-validation__options {} .checkout-address-validation__options--busy {} .checkout-address-validation__subtitle {} .checkout-address-validation__title {} /* BillToShippingAddress */ .checkout-bill-to-shipping-address {} .checkout-bill-to-shipping-address__error {} /* EstimateShipping */ .cart-order-summary__shipping {} .checkout-estimate-shipping {} .checkout-estimate-shipping__caption {} .checkout-estimate-shipping__label {} .checkout-estimate-shipping__label--bold {} .checkout-estimate-shipping__label--muted {} .checkout-estimate-shipping__price {} .checkout-estimate-shipping__price--bold {} .checkout-estimate-shipping__price--muted {} .dropin-skeleton {} /* LoginForm */ .checkout-login-form__content {} .checkout-login-form__customer-details {} .checkout-login-form__customer-email {} .checkout-login-form__customer-name {} .checkout-login-form__heading {} .checkout-login-form__heading-label {} .checkout-login-form__link {} .checkout-login-form__sign-in {} .checkout-login-form__sign-out {} .checkout-login-form__title {} .dropin-field__hint {} /* OutOfStock */ .checkout-out-of-stock {} .checkout-out-of-stock__action {} .checkout-out-of-stock__actions {} .checkout-out-of-stock__item {} .checkout-out-of-stock__items {} .checkout-out-of-stock__message {} .checkout-out-of-stock__title {} .dropin-card {} .dropin-card__content {} /* PaymentMethods */ .checkout-payment-methods--full-width {} .checkout-payment-methods__content {} .checkout-payment-methods__error {} .checkout-payment-methods__methods {} .checkout-payment-methods__spinner {} .checkout-payment-methods__title {} .checkout-payment-methods__wrapper {} .checkout-payment-methods__wrapper--busy {} .checkout__content {} /* PaymentOnAccount */ .checkout-payment-on-account {} .checkout-payment-on-account__credit {} .checkout-payment-on-account__credit-amount {} .checkout-payment-on-account__credit-label {} .checkout-payment-on-account__exceed-message {} .checkout-payment-on-account__form {} .dropin-field {} /* PlaceOrder */ .checkout-place-order {} .checkout-place-order__button {} /* PurchaseOrder */ .checkout-purchase-order {} .checkout-purchase-order__form {} .dropin-field {} /* ServerError */ .checkout-server-error {} .checkout-server-error__icon {} .error-icon {} /* ShippingMethods */ .checkout-shipping-methods__content {} .checkout-shipping-methods__error {} .checkout-shipping-methods__method {} .checkout-shipping-methods__options--busy {} .checkout-shipping-methods__options--toggleButton {} .checkout-shipping-methods__spinner {} .checkout-shipping-methods__title {} .dropin-price {} .dropin-radio-button__label {} .dropin-toggle-button__content {} /* TermsAndConditions */ .checkout-terms-and-conditions {} .checkout-terms-and-conditions__error {} /* MergedCartBanner */ .checkout__banner {} ``` --- # Add a payment method The Checkout drop-in component provides extensibility features for integrating third-party payment providers. Use slots to customize the list of payment methods shown during the checkout process. > **Supported payment providers** The Checkout drop-in supports Adyen payment methods (including Bancontact) and payment extensions in addition to the Braintree example below. See the [release notes](https://experienceleague.adobe.com/developer/commerce/storefront/releases/) for the latest supported providers. ## Step-by-step This tutorial walks you through integrating Braintree as a payment provider with the Commerce boilerplate template. While we use Braintree as an example, you can adapt these same steps for other payment providers. ### 1. Prerequisites For this tutorial, you must configure the Braintree extension on your Adobe Commerce backend before integrating it with the Commerce boilerplate template. The Braintree extension is bundled with Adobe Commerce and can be https://experienceleague.adobe.com/en/docs/commerce-admin/stores-sales/payments/braintree in the Admin. If you choose to integrate with a different payment provider, consider the following: - The provider must be supported by Adobe Commerce. - The provider likely offers an extension that you must install and configure on your Adobe Commerce backend. ### 2. Add the Braintree client SDK To integrate the Braintree payment provider with the Commerce boilerplate template, you must add the Braintree client SDK to your project. ### HTML element Use the following `script` tag to add the Braintree client SDK to an HTML file. ```html ``` ### Import declaration Use the following `import` declaration to add the Braintree client SDK directly to the `commerce-checkout.js` block file. ```js import 'https://js.braintreegateway.com/web/dropin/1.43.0/js/dropin.min.js'; ``` ### 3. Define a custom handler 1. Create a `braintreeInstance` variable to manage the Braintree drop-in instance. ```js let braintreeInstance; ``` 1. Update the [`PaymentMethods`](https://experienceleague.adobe.com/developer/commerce/storefront/dropins/checkout/containers/payment-methods/) container to include a custom handler for the Braintree payment method. Set `autoSync` to `false` to prevent automatic calls to the [`setPaymentMethod`](https://experienceleague.adobe.com/developer/commerce/storefront/dropins/checkout/functions/#setpaymentmethod) function when the payment method changes. ```js CheckoutProvider.render(PaymentMethods, { slots: { Methods: { braintree: { autoSync: false, render: async (ctx) => { const container = document.createElement('div'); window.braintree.dropin.create({ authorization: 'sandbox_cstz6tw9_sbj9bzvx2ngq77n4', container, }, (err, dropinInstance) => { if (err) { console.error(err); } braintreeInstance = dropinInstance; }); ctx.replaceHTML(container); }, }, }, }, })($paymentMethods), ``` ### 4. Handle the payment method Implement the Braintree payment logic within the `handlePlaceOrder` handler of the [`PlaceOrder`](https://experienceleague.adobe.com/developer/commerce/storefront/dropins/checkout/containers/place-order/) container. This involves processing the payment using the Braintree https://developer.paypal.com/braintree/docs/guides/payment-method-nonces. ```js CheckoutProvider.render(PlaceOrder, { handlePlaceOrder: async ({ cartId, code }) => { await displayOverlaySpinner(); try { switch (code) { case 'braintree': { braintreeInstance.requestPaymentMethod(async (err, payload) => { if (err) { removeOverlaySpinner(); console.error(err); return; } await checkoutApi.setPaymentMethod({ code: 'braintree', braintree: { is_active_payment_token_enabler: false, payment_method_nonce: payload.nonce, }, }); await orderApi.placeOrder(cartId); }); break; } default: { // Place order await orderApi.placeOrder(cartId); } } } catch (error) { console.error(error); throw error; } finally { await removeOverlaySpinner(); } }, })($placeOrder), ``` ## Example See https://github.com/hlxsites/aem-boilerplate-commerce/tree/demos/blocks/commerce-checkout-braintree in the `demos` branch of the boilerplate repository for complete JS and CSS code for the Braintree payment method checkout flow. --- # Integrate with a third-party address verification API You might want to enhance the shopper experience by streamlining the process of populating and verifying the shipping address, thereby reducing the risk of user error. You can achieve this by implementing a third-party address lookup and autocomplete APIs, such as those provided by https://mapsplatform.google.com/maps-products/#places-section. This tutorial describes how to override any field in a checkout address form and extend it to integrate with this service. The implementation supports backend-configurable validation and full form submission integration. Upon successful completion of this tutorial, a form similar to the following will be displayed:  *Autocomplete shipping address* ## Step-by-step The following steps describe how to integrate the Google Address Validation API with the Commerce boilerplate template using the provided address autocomplete implementation. ### 1. Prerequisites For this tutorial, you must have a valid Google API key. https://developers.google.com/maps/documentation/javascript/get-api-key describes the process to obtain and set up this key. ### 2. Download and configure the address autocomplete implementation 1. **Download the implementation:** Copy the `address-autocomplete.js` file from `/public/samples/address-autocomplete.js` in this documentation repository to your project directory. 2. **Replace the API key placeholder:** Open the `address-autocomplete.js` file and replace `ADD-YOUR-GOOGLE-API-KEY-HERE` with your actual Google API key: ```javascript const CONFIG = { googleApiKey: 'YOUR_ACTUAL_GOOGLE_API_KEY', // ... rest of configuration }; ``` ### 3. Import and initialize the autocomplete service In your `commerce-checkout.js` file, make the following changes to enable address autocomplete: 1. **Import the autocomplete service:** ```javascript import { initializeAutocompleteWhenReady } from './address-autocomplete.js'; ``` 2. **Initialize the autocomplete in the `initializeCheckout` function:** ```javascript const initializeCheckout = async () => { // ... existing checkout initialization code ... // Initialize address autocomplete for shipping form const shippingContainer = document.querySelector('[data-commerce-checkout-shipping]'); if (shippingContainer) { initializeAutocompleteWhenReady(shippingContainer, 'input[name="street"]'); } // ... rest of initialization code ... }; ``` The `initializeAutocompleteWhenReady` function automatically: - Waits for the address form to be rendered - Attaches autocomplete functionality to the street input field - Handles form field population when an address is selected - Manages Google Maps API loading and initialization ## Example The complete address autocomplete implementation is available in `/public/samples/address-autocomplete.js`. This implementation includes: - **AddressAutocompleteService class**: Handles Google Places API integration - **initializeAutocompleteWhenReady function**: Utility function for easy integration - **Automatic form field population**: Populates street, city, country, and postal code fields - **Keyboard navigation**: Arrow keys, Enter, and Escape support - **Error handling**: Graceful fallback when Google Maps API is unavailable For additional customization options and advanced usage, see the implementation comments in the sample file. --- # Buy online, pickup in store Buy online, pickup in store (BOPIS) is a popular fulfillment option that allows customers to purchase items online and pick them up in-store. The Commerce boilerplate template does not include a BOPIS checkout flow by default, but you can easily implement one using Adobe's drop-in components. ## Step-by-step The following steps describe how to modify the https://github.com/hlxsites/aem-boilerplate-commerce/blob/main/blocks/commerce-checkout/commerce-checkout.js block file in the boilerplate template to allow users to choose between delivery and in-store pickup during the checkout process. ### 1. Prerequisites Before you start, you must configure https://experienceleague.adobe.com/en/docs/commerce-admin/stores-sales/delivery/basic-methods/shipping-in-store-delivery options in the Adobe Commerce Admin to define pickup locations. The [`fetchPickupLocations`](#fetch-pickup-locations) function retrieves the list of available pickup locations using a GraphQL query. ### 2. Update content fragment 1. To create a new section for the delivery options, additional DOM elements are required. You can add these elements by modifying the content fragment. ```html

Delivery Method