Delivery Method

{item.list?.map((product: OrderItemModel) => (
))} ... ``` ### 2. Search for the order A guest user does not have access to the order history page. Therefore, the only way to access an order is by using the Order Search form. The search order form retrieves the order that matches the specified email address, last name, and order name, as shown below:  *Order cancellation form* The `OrderSearchForm` component is responsible for rendering the form to search for an order. It receives the following parameters: ```text [ ['Configuration', 'Description'], ['fieldsConfig', 'An array of fields to be rendered in the form.'], ['loading', 'A boolean to indicate whether the form is loading.'], [ 'inLineAlert', 'After submitting the form, an inline alert is shown with the result of the operation (success, warning, error) with its respective message.', ], [ 'onSubmit', 'A function to be called when the form is submitted and a flag to indicate if the form is valid.', ], ] ``` See the following code for an example of the implementation: ```jsx ... {inLineAlert.text ? ( } /> ) : null}
... ``` ### 3. Render and submit the cancellation form The cancellation form allows the customer to select a cancellation reason and submit the form.  *Order cancellation form* The `OrderCancel` component renders the `OrderCancelForm` container inside a modal. This modal receives two parameters: ```text [ ['Parameter', 'Description'], ['orderRef', 'Identifies the order.'], ['cancelReasons', 'Contains all the configured cancellation reasons.'], ] ``` For example: ```jsx ... } data-testid="order-cancellation-reasons-modal" > ... ``` The `OrderCancelForm` component is responsible for: - Rendering the form with multiple cancellation reasons and a submission button. - Handling the form submission. - Showing the appropriate error messages if a failure occurs after submitting the form. ```jsx ... {isErrorVisible && ( )} ... ``` ### 4. Display the confirmation notice When a logged-in customer submits the cancellation form, Commerce immediately sets the status of the order to `Canceled` and the drop-in displays a confirmation notice.  *Confirmation for logged-in users.* If the shopper is a guest user, the drop-in displays the following dialog:  *Guest user is notified that cancellation has been requested.* The order status remains `Pending` until the shopper clicks the link in an email similar to the following to confirm the cancellation. > **Confirm Your Main Website Store Order Cancellation** It seems that you'd like to cancel your order #000000001. If this is correct, please _click here_ to confirm your cancellation request. If you have questions about your order, you can email us at _support@example.com_. Once clicked, the order becomes `Canceled` and the order status page is updated accordingly. The order status page uses the `OrderStatusContent` component to render the order with all its properties and the available actions. See the following code for an example of the `OrderStatusContent` implementation below: ```jsx ...
{isReturnPage ? returnMessage : orderMessage} ... ``` After performing any action, the order status page is re-rendered, so that it reflects the new status and the available actions. The appropriate message is shown to the user, depending on the action performed. --- # Notify Me CTA When a product or selected variant is out of stock, the primary Call to Action (CTA) button on the Product Detail Page (PDP) can display **"Notify Me"** instead of **"Add to Cart"**. This applies to both simple products and configurable products with multiple options (for example, size and color). When the shopper switches to a different variant, the CTA updates dynamically based on that variant's stock status. > **Notify Me as customization** "Notify Me" is a frequently requested customization. This tutorial shows how to add it using the event bus and CTA updates. If your implementation requires backend integration (for example, an admin toggle for back-in-stock notifications), this approach keeps the logic in your block. If it becomes standard behavior in the future, it may be added to the boilerplate directly. ## Prerequisites Before following these steps, you should understand: - [Events](https://experienceleague.adobe.com/developer/commerce/storefront/dropins/product-details/events/) — `pdp/data`, `pdp/valid`, and subscription patterns - [Functions](https://experienceleague.adobe.com/developer/commerce/storefront/dropins/product-details/functions/) — `getProductConfigurationValues` for reading selected options - [Cart Events](https://experienceleague.adobe.com/developer/commerce/storefront/dropins/cart/events/) — `cart/data` for detecting when the product is already in the cart - **Add to Cart button** — Your block must include an Add to Cart button. This can be a standard HTML `` element or any other button implementation. Step 1 shows how to create one using the SDK's [Button component](https://experienceleague.adobe.com/developer/commerce/storefront/sdk/components/button/), which supports `setProps` for the CTA updates in this tutorial. If you already have an Add to Cart button, start at Step 2. This tutorial uses the basic tools exposed by the Product Details drop-in: the [event bus](https://experienceleague.adobe.com/developer/commerce/storefront/sdk/reference/events/) and a CTA element in your block. For a full implementation reference example in the Commerce boilerplate, see https://github.com/hlxsites/aem-boilerplate-commerce/pull/1116. ## Overview You'll create the Add to Cart button, subscribe to `pdp/data`, `pdp/valid`, and `cart/data`, and update the CTA in each callback based on stock status, configuration validity, and cart state. ## Implementation steps All code below runs inside your block's `decorate(block)` function. ### 1. Create the Add to Cart button Create the primary CTA button using the [Button component](https://experienceleague.adobe.com/developer/commerce/storefront/sdk/components/button/) from the SDK. The `render` call returns a Promise that resolves to the button instance—store it so you can call `setProps` on it later. If your block already has this button, skip to the next step. In the boilerplate, the element comes from the layout fragment (see [layouts](https://experienceleague.adobe.com/developer/commerce/storefront/dropins/all/layouts/) for the full structure). After creating the fragment and calling `block.replaceChildren(fragment)`, get the element and render the button. The `onClick` body is expanded in Steps 6 and 7. ```js // Inside decorate(block): product, labels, fragment already created (see layouts) const $addToCart = fragment.querySelector('.product-details__buttons__add-to-cart'); block.replaceChildren(fragment); const addToCart = await UI.render(Button, { children: labels.Global?.AddProductToCart, icon: h(Icon, { source: 'Cart' }), onClick: async () => { // Step 6: out-of-stock guard (top of handler) // Step 7: try-catch-finally with Add to Cart / Update in Cart logic }, })($addToCart); ``` ### 2. Implement a CTA update function Create a function that updates the CTA element based on stock status, update mode (item in cart), and labels. When out of stock, set the button text to **"Notify Me"**, remove the cart icon, and keep the button enabled. When in stock, show **"Add to Cart"** or **"Update in Cart"** with the cart icon based on cart context. Define this at module level (before `decorate`). It uses `h` and `Icon` from the Step 1 imports. ```js function updatePrimaryCTA(buttonInstance, { isOutOfStock, isUpdateMode, labels }) { if (!buttonInstance) return; if (isOutOfStock) { buttonInstance.setProps((prev) => ({ ...prev, children: labels.Global?.NotifyMe || 'Notify Me', icon: null, disabled: false, })); } else { const buttonText = isUpdateMode ? labels.Global?.UpdateProductInCart : labels.Global?.AddProductToCart; buttonInstance.setProps((prev) => ({ ...prev, children: buttonText, icon: h(Icon, { source: 'Cart' }), })); } } ``` > If your block uses a placeholders spreadsheet, add a `NotifyMe` entry. Otherwise the code falls back to the hardcoded string `"Notify Me"`. ### 3. Track stock and update mode state Define these state variables at the start of `decorate`. They drive the CTA update logic. ```js let isUpdateMode = false; let isOutOfStock = false; ``` ### 4. Subscribe to `pdp/data` for stock status Subscribe to `pdp/data` with `{ eager: true }` so the handler runs on initial load and whenever the product or variant changes. Read `inStock` from the payload and update the CTA accordingly. **Why:** Product data (including stock) changes when the page loads or when the shopper selects a different variant. You need to react to both. ```js events.on('pdp/data', (data) => { isOutOfStock = data?.inStock === false; updatePrimaryCTA(addToCart, { isOutOfStock, isUpdateMode, labels }); }, { eager: true }); ``` See the [`pdp/data` event reference](https://experienceleague.adobe.com/developer/commerce/storefront/dropins/product-details/events/#pdpdata-emits-and-listens) for the full event payload. ### 5. Subscribe to `pdp/valid` for configuration validity Subscribe to `pdp/valid` with `{ eager: true }`. When the product is **in stock**, disable the button if the configuration is invalid (for example, required options not selected). When **out of stock**, keep the **"Notify Me"** button enabled regardless of configuration validity. **Why:** For Add to Cart, the button should be disabled until the shopper completes required selections. For Notify Me, the button can stay enabled so the shopper can request notification even before selecting options. ```js events.on('pdp/valid', (valid) => { if (!isOutOfStock) { addToCart.setProps((prev) => ({ ...prev, disabled: !valid })); } }, { eager: true }); ``` ### 6. Handle out-of-stock clicks in the button handler Add this at the **top** of the `onClick` handler you created in Step 1. When `isOutOfStock` is `true`, run your custom notify-me logic and return early so no cart logic executes. ```js // Inside the onClick from Step 1: if (isOutOfStock) { const values = pdpApi.getProductConfigurationValues(); // Replace with your logic: open modal, call back-in-stock API, emit custom event, etc. console.log('Notify Me', { sku: product?.sku, values }); return; } // ... existing Add to Cart / Update in Cart logic (try block) ``` ### 7. Subscribe to `cart/data` for update mode Subscribe to `cart/data` with `{ eager: true }`. When the cart data changes, determine whether the current product is already in the cart. If so, set `isUpdateMode` and call `updatePrimaryCTA` so the button shows **"Update in Cart"** instead of **"Add to Cart"**. **Why:** The CTA text and behavior differ when the item is already in the cart. Cart data changes when items are added, updated, or removed. ```js events.on( 'cart/data', (data) => { // Determine if current product/variant is in cart... isUpdateMode = itemIsInCart; updatePrimaryCTA(addToCart, { isOutOfStock, isUpdateMode, labels }); }, { eager: true }, ); ``` ### 8. Reset the CTA after cart actions After an add-to-cart or update-in-cart action completes (for example, in the `finally` block of your click handler), call `updatePrimaryCTA` to restore the correct button state. ```js // Inside the onClick from Step 1, in the finally block: } finally { updatePrimaryCTA(addToCart, { isOutOfStock, isUpdateMode, labels }); addToCart.setProps((prev) => ({ ...prev, disabled: false, })); } ``` --- # Customize the layout of the AddressForm The AddressForm container provides a highly configurable and customizable layout for seamless integration. The sorting of address attributes is managed through the Adobe Commerce Admin settings, giving flexibility in how data fields are displayed. The visual layout of the form, including input widths (such as 50% or 100% to position multiple inputs on the same line), is controlled by CSS. This enables integrators to tailor the form's appearance by applying custom CSS rules. By default, the first name and last name fields in the address form are set to 50% width. The display is controlled through CSS, as the form is implemented using a grid layout:  *Default AddressForm container* To modify the layout and render these fields as full-width, create custom CSS rules at the boilerplate level and use them to override default container CSS:  *One column AddressForm container* Using this approach, you can easily customize the address form layout during the integration process, such as implementing a three-column layout to display three fields in a row. These adjustments require only basic CSS knowledge for effective customization. This approach is fully applicable to address forms in all views of the Addresses container, as it utilizes the AddressForm container internally. ### Layout Customization Example The following examples show how to adjust the https://github.com/hlxsites/aem-boilerplate-commerce/blob/main/blocks/commerce-addresses/commerce-addresses.css block CSS in a boilerplate environment to customize the address form layout. In the default layout, some fields are half width, while others take up the whole width.  *Default layout of the AddressForm container* To set all fields to half width, add the following CSS rule to the `storefront-addresses` block: ```css .commerce-addresses .account-address-form { grid-template-columns: repeat(2,1fr); } ```  *Two column layout of the AddressForm container* To set the text area and button group to 100% width while keeping the other fields at half width: ```css .commerce-addresses .account-address-form div.account-address-form__field--test_text_area, .commerce-addresses .account-address-form div.account-address-form-wrapper__buttons { grid-column: span 2; } ``` Notice that the CSS selector includes the modifier `--test_text_area`, allowing you to target a specific field by attribute code.  *Two column layout with full width text area* To create a three-column layout with a full-size text area and button area, set the grid template columns to `repeat(2,1fr)`: ```css .commerce-addresses .account-address-form { grid-template-columns: repeat(2,1fr); } .commerce-addresses .account-address-form div.dropin-field { grid-column: span 1; } .commerce-addresses .account-address-form div.account-address-form__field--test_text_area, .commerce-addresses .account-address-form div.account-address-form-wrapper__buttons { grid-column: span 3; } ```  *Three column layout with full width text area* --- # Payment Services stored methods in My Account Shoppers who save a card with Payment Services during checkout can see and remove those vaulted methods on a **My Account** page. Removal uses a confirmation step before the token is deleted—see [Remove confirmation](https://experienceleague.adobe.com/developer/commerce/storefront/dropins/user-account/containers/payment-methods/#remove-confirmation). The Commerce boilerplate does **not** include a payment-methods block out of the box. This tutorial shows how to add one yourself (for example a `commerce-payment-methods` block) that renders the User Account [PaymentMethods](https://experienceleague.adobe.com/developer/commerce/storefront/dropins/user-account/containers/payment-methods/) container. That container loads tokens with the same GraphQL `customerPaymentTokens` query used for vault data elsewhere. What was vaulted through Payment Services appears here when the shopper is signed in. This page is Payment Services–specific: it assumes vaulting is enabled for your Payment Services integration and focuses on wiring the account experience with a small custom block. ## Prerequisites - **Payment Services** is https://experienceleague.adobe.com/en/docs/commerce/payment-services/get-started/onboard and the /dropins/payment-services/installation/ meets version requirements for your storefront. - **Save / vault** is available for your payment flow (see Adobe’s https://developer.adobe.com/commerce/webapi/graphql/payment-services-extension/workflows/vaulted-card/ for how tokens are created at checkout). - Checkout (or another flow) already initializes Payment Services where shoppers vault cards. For example, the boilerplate https://github.com/hlxsites/aem-boilerplate-commerce/blob/main/blocks/commerce-checkout/commerce-checkout.js loads https://github.com/hlxsites/aem-boilerplate-commerce/blob/main/scripts/initializers/payment-services.js. - Account pages run the **account** initializer so GraphQL calls use the customer token. Import https://github.com/hlxsites/aem-boilerplate-commerce/blob/main/scripts/initializers/account.js (or your equivalent) before rendering the container. ## Add a payment methods block Create a block. The naming is up to you, but `commerce-payment-methods` is a clear convention. This block should: 1. Redirect **guests** to login (same pattern as other account blocks). 2. Initialize the **User Account** drop-in via `account.js`. 3. Render **PaymentMethods** with optional **with header** and **minified view** from the block configuration. Example `decorate` implementation: ```javascript export default async function decorate(block) { const { 'minified-view': minifiedViewConfig = 'false', 'with-header': withHeaderConfig = 'true', } = readBlockConfig(block); if (!checkIsAuthenticated()) { window.location.href = rootLink(CUSTOMER_LOGIN_PATH); } else { await accountRenderer.render(PaymentMethods, { withHeader: withHeaderConfig === 'true', minifiedView: minifiedViewConfig === 'true', })(block); } } ``` Place the block on the account page (or desired section) where the list should appear. Use the same section metadata, block registration, and readBlockConfig patterns as other commerce blocks (for example, customer info or orders). ## Block configuration (authoring) Expose authoring keys in `decorate` that map to `readBlockConfig`. For example: - `with-header` — Controls whether a section title and divider are shown for the payments area (full account pages often omit this). - **`minified-view`** — Enables a compact layout with condensed rows and a simplified empty state, ideal for dashboards alongside other widgets. Add a `_your-block-name.json` (and optional README) next to the block source so authors get defaults and labels consistent with the rest of your project. ## Limit the list to Payment Services tokens (optional) Vault tokens include a `payment_method_code`. Payment Services methods typically use codes that start with `payment_services` (for example, hosted-field variants). The PaymentMethods container accepts `filterPaymentMethodCodes`: an array of strings. A token is shown if its code equals or starts with any entry. The example decorate above doesn’t include this prop. To display only Payment Services–vaulted methods (and hide saved methods from other gateways), add it to the render call. For example: ```javascript await accountRenderer.render(PaymentMethods, { withHeader: withHeaderConfig === 'true', minifiedView: minifiedViewConfig === 'true', filterPaymentMethodCodes: ['payment_services'], })(block); ``` Adjust the prefix list if your Admin or integration uses a different payment method code pattern. ## How data reaches the UI - By default, the container calls `getCustomerPaymentTokens`, which executes the `customerPaymentTokens` query and transforms the returned vault details (JSON) into rows for the PaymentCard component. The details include Payment Services fields like brand and last four digits. - If another part of the page already has token rows on the client, you can emit **`account/customerPaymentTokens`** on the event bus so the container **shows that list** without an extra **`getCustomerPaymentTokens`** round trip (see [Events](https://experienceleague.adobe.com/developer/commerce/storefront/dropins/user-account/events/#accountcustomerpaymenttokens-listens) and [TypeScript declaration](https://experienceleague.adobe.com/developer/commerce/storefront/dropins/user-account/events/#typescript-declaration)). That is optional injection only; **Remove** still calls **`deletePaymentToken`** on the GraphQL API, not the bus. Payment Services + GraphQL alone is the usual path for My Account. ## Related documentation - [PaymentMethods container](https://experienceleague.adobe.com/developer/commerce/storefront/dropins/user-account/containers/payment-methods/) — props, GraphQL vs bus, and errors. - [User Account functions](https://experienceleague.adobe.com/developer/commerce/storefront/dropins/user-account/functions/) — **`getCustomerPaymentTokens`**, **`deletePaymentToken`**. - [Payment Services installation](https://experienceleague.adobe.com/developer/commerce/storefront/dropins/payment-services/installation/) and [initialization](https://experienceleague.adobe.com/developer/commerce/storefront/dropins/payment-services/initialization/). - Checkout: [Add payment method](https://experienceleague.adobe.com/developer/commerce/storefront/dropins/checkout/tutorials/add-payment-method/) when customizing how cards are vaulted at purchase time. > **PCI and SDK UI** Payment card entry at checkout remains within the Payment Services drop-in/SDK to maintain PCI compliance. My Account only lists and removes existing saved tokens—it does not replace the hosted card form used during checkout. --- # Validate address in My Account Use the `AddressValidation` container to present both the original and suggested addresses from your verification service, letting shoppers choose before saving. This tutorial shows how to integrate the container in the `commerce-addresses` block.  *AddressValidation displayed in a modal* ## Overview At a high level: - Call your address verification service on form submit. - If it returns a suggestion, open a modal and render `AddressValidation`. - If the shopper selects the suggestion, populate the form with the suggested data and re-submit; otherwise, retain the original form values. ## Integration in commerce-addresses block Update your `blocks/commerce-addresses/commerce-addresses.js` to: - Import `AddressValidation` - Pass `forwardFormRef`, `onAddressData`, and `onSubmit` to `Addresses` - When a suggestion exists, show a modal with `AddressValidation` and two actions: Edit Address and Save Address ```javascript // blocks/commerce-addresses/commerce-addresses.js const validateAddress = async (address) => { // Call your service with the form data // const result = await fetch(...) // return result.suggestedAddress || null // Example mocked suggestion return { city: 'Bainbridge Island', countryCode: 'US', postcode: '98110-2450', region: { regionCode: 'WA', regionId: 1 }, street: ['123 Winslow Way E'], telephone: '555-123-4567', }; }; const finalizeSubmission = (setContainerProps, formRef, updates = {}) => { setContainerProps({ onSubmit: null, ...updates }); setTimeout(() => formRef.current?.requestSubmit(), 1); }; const renderAddressValidation = async ({ originalAddress, suggestedAddress, onEdit, onSave, }) => { const container = document.createElement('div'); const addressValidation = document.createElement('div'); const actionsContainer = document.createElement('div'); const editAddressButton = document.createElement('div'); const saveAddressButton = document.createElement('div'); actionsContainer.appendChild(editAddressButton); actionsContainer.appendChild(saveAddressButton); container.appendChild(addressValidation); container.appendChild(actionsContainer); actionsContainer.classList.add('actions-container'); await showModal(container); let selectedAddress, currentSelection; provider.render(AddressValidation, { selectedAddress: 'suggested', originalAddress, suggestedAddress, handleSelectedAddress: async ({ address, selection }) => { selectedAddress = address; currentSelection = selection; }, })(addressValidation); UI.render(Button, { children: 'Edit Address', size: 'medium', variant: 'secondary', onClick: () => { if (currentSelection === 'suggested') { onEdit(selectedAddress); } removeModal(); }, })(editAddressButton); UI.render(Button, { children: 'Save Address', size: 'medium', variant: 'primary', onClick: () => { const updates = {}; if (currentSelection === 'suggested') { updates.inputsDefaultValueSet = selectedAddress; } removeModal(); onSave(updates); }, })(saveAddressButton); }; export default async function decorate(block) { const { 'minified-view': minifiedViewConfig = 'false' } = readBlockConfig(block); if (!checkIsAuthenticated()) { window.location.href = rootLink(CUSTOMER_LOGIN_PATH); return; } let originalAddress; const formRef = { current: null }; const addressesContainer = await accountRenderer.render(Addresses, { minifiedView: minifiedViewConfig === 'true', withActionsInMinifiedView: false, withActionsInFullSizeView: true, routeAddressesPage: () => rootLink(CUSTOMER_ADDRESS_PATH), forwardFormRef: formRef, onAddressData: (values) => { originalAddress = values?.data; }, onSubmit: async (event, formValid) => { if (!formValid) return; const setContainerProps = (updates) => { addressesContainer.setProps((prev) => ({ ...prev, ...updates })); }; const suggestedAddress = await validateAddress(originalAddress); if (!suggestedAddress) { finalizeSubmission(setContainerProps, formRef); return; } await renderAddressValidation({ originalAddress, suggestedAddress, onEdit: (selectedAddress) => { setContainerProps({ inputsDefaultValueSet: selectedAddress }); }, onSave: (updates) => { finalizeSubmission(setContainerProps, formRef, updates); }, }); }, })(block); } ``` ```javascript // modal-utils.js let modal; export const showModal = async (content) => { modal = await createModal([content]); modal.showModal(); }; export const removeModal = () => { if (!modal) return; modal.removeModal(); modal = null; }; ``` ### Optional styles ```css /* Minimal layout for the modal */ .modal-content { padding: 32px; } .actions-container { display: flex; gap: 16px; margin-top: 48px; justify-content: flex-end; } ``` ## Next steps - See the [`AddressValidation` container](https://experienceleague.adobe.com/developer/commerce/storefront/dropins/user-account/containers/address-validation/) container for props and behaviors. - Ensure your suggestion matches the `CustomerAddressInput` shape expected by the Addresses container.