--- schema_version: "1" id: 5863a9f1118654bd17f49d7b0d62746bff3574d9b6fdb55d957b9544af6ac0fa title: Checkout collection: developer version: current locale: en-us portal_url: https://docs.salesforce.com/developer/current/en-us/commerce-cloud/salesforce-commerce/guides/d2c-commerce/b2b-comm-headless-checkout.md canonical_url: https://developer.salesforce.com/docs/commerce/salesforce-commerce/guide/b2b-comm-headless-checkout.html source_site: developer.salesforce.com content_type: documentation content_hash: ea94d0772badd9b4ba192931e991e4488198f6f892d010121fe2f5a70ac24c23 products: - B2B Commerce Developer Guide - Salesforce APIs --- # Checkout ### Overview The Checkout page implements a four-step single-page checkout flow: - Address - Delivery Method - Payment - Review Each checkout step advances only after the corresponding server-side API operation completes successfully. An order summary remains visible throughout the checkout flow to provide buyers with continuous visibility into pricing, quantities, shipping, and totals. When saved buyer addresses are available, the checkout experience displays them as selectable options by default. If no saved addresses exist, the page falls back to a manual address entry form. This flow demonstrates how a headless storefront can render checkout experiences, including address selection, delivery methods, payment processing, and order submission, using B2B Commerce Checkout APIs. Detailed flow diagrams for each checkout step are provided after this end-to-end flow. ![Checkout APIs Flow](https://developer.salesforce.com/media/d2c-commerce/b2b-headless-section-figure-image-18-1.png '{"class": "image-lg", "title": "Checkout APIs Flow"}') ### B2B Commerce APIs Used in the Flow | Operation | HTTP Method | Endpoint | | -------------------- | ----------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | Get active checkout | GET | [`/commerce/webstores/{webstoreId}/checkouts/active`](https://developer.salesforce.com/docs/atlas.en-us.chatterapi.meta/chatterapi/connect_resources_commerce_webstore_checkouts.htm) | | Start checkout | PUT | [`/commerce/webstores/{webstoreId}/checkouts`](https://developer.salesforce.com/docs/atlas.en-us.chatterapi.meta/chatterapi/connect_resources_commerce_webstore_checkouts_start_checkout.htm) | | List saved addresses | GET | [`/commerce/webstores/{webstoreId}/accounts/current/addresses`](https://developer.salesforce.com/docs/atlas.en-us.chatterapi.meta/chatterapi/connect_resources_commerce_webstore_accounts_addresses.htm) | | Save new address | POST | [`/commerce/webstores/{webstoreId}/accounts/current/addresses`](https://developer.salesforce.com/docs/atlas.en-us.chatterapi.meta/chatterapi/connect_resources_commerce_webstore_accounts_addresses.htm) | | Set shipping address | PATCH | [`/commerce/webstores/{webstoreId}/checkouts/active`](https://developer.salesforce.com/docs/atlas.en-us.chatterapi.meta/chatterapi/connect_resources_commerce_webstore_checkouts.htm) | | Pick delivery method | PATCH | [`/commerce/webstores/{webstoreId}/checkouts/active`](https://developer.salesforce.com/docs/atlas.en-us.chatterapi.meta/chatterapi/connect_resources_commerce_webstore_checkouts.htm) | | Authorize PO payment | POST | [`/commerce/webstores/{webstoreId}/checkouts/active/payments`](https://developer.salesforce.com/docs/atlas.en-us.chatterapi.meta/chatterapi/connect_resources_commerce_webstore_checkouts_payments.htm) | | Place order | POST | [`/commerce/webstores/{webstoreId}/checkouts/active/orders/actions`](https://developer.salesforce.com/docs/atlas.en-us.chatterapi.meta/chatterapi/connect_resources_commerce_webstore_checkouts_place_order_v2.htm) | ### Buyer Journey **Initialize Checkout** 1. Load the checkout experience. 2. Call the following endpoint to retrieve the active checkout: GET [`/commerce/webstores/{webstoreId}/checkouts/active`](https://developer.salesforce.com/docs/atlas.en-us.chatterapi.meta/chatterapi/connect_resources_commerce_webstore_checkouts.htm) 3. Handle a 404 Not Found response as a valid initialization path. A 404 response indicates that no active checkout exists for the current buyer session. 4. If no active checkout exists, create one by calling: PUT [`/commerce/webstores/{webstoreId}/checkouts`](https://developer.salesforce.com/docs/atlas.en-us.chatterapi.meta/chatterapi/connect_resources_commerce_webstore_checkouts_start_checkout.htm) Example request body: ```json { "cartId": "active", "deliveryAddressInput": { "shouldUseDefaultAddress": true } } ``` 5. Set `shouldUseDefaultAddress=true` to instruct the platform to: - Apply the buyer’s default shipping address - Preselect an available delivery method - Calculate shipping and totals during checkout creation This reduces additional checkout update requests later in the flow. 6. Retrieve the buyer’s saved shipping addresses by calling: GET [`/commerce/webstores/{webstoreId}/accounts/current/addresses?addressType=Shipping`](https://developer.salesforce.com/docs/atlas.en-us.chatterapi.meta/chatterapi/connect_resources_commerce_webstore_accounts_addresses.htm) 7. Retrieve cart items for the checkout summary panel by calling: GET [`/commerce/webstores/{webstoreId}/carts/current/cart-items`](https://developer.salesforce.com/docs/commerce/salesforce-commerce/references/comm-cart-ref?meta=getCartItemCollection) 8. Use the responses to render: - Checkout summary - Shipping address selection - Delivery methods - Cart side panel - Order totals **Select a Saved Shipping Address** This flow demonstrates how a headless storefront can orchestrate address selection and shipping address management during checkout using B2B Commerce Checkout APIs. ![Checkout Address Selection Flow](https://developer.salesforce.com/media/d2c-commerce/b2b-headless-section-figure-image-19-2.png '{"class": "image-lg", "title": "Checkout Address Selection Flow"}') 1. Select a shipping address from the saved-address list. 2. Call the following endpoint to apply the address to the active checkout: PATCH [`/commerce/webstores/{webstoreId}/checkouts/active`](https://developer.salesforce.com/docs/atlas.en-us.chatterapi.meta/chatterapi/connect_resources_commerce_webstore_checkouts.htm) Example request body: ```json { "deliveryAddress": { "street": "1 Market St", "city": "San Francisco", "region": "CA", "postalCode": "94105", "country": "US" } } ``` 3. Use the `deliveryAddress` field in the request body. The legacy `shippingAddress` field isn't supported by this endpoint. 4. Use the updated checkout response to refresh checkout totals and delivery information. 5. Advance the checkout flow to the delivery step. **Add and Apply a New Shipping Address** 1. Enter a new shipping address in the checkout address form. 2. Save the address to the buyer account by calling: POST [`/commerce/webstores/{webstoreId}/accounts/current/addresses`](https://developer.salesforce.com/docs/atlas.en-us.chatterapi.meta/chatterapi/connect_resources_commerce_webstore_accounts_addresses.htm) 3. Allow the platform to validate and normalize the address before applying it to the checkout. 4. After the address is saved successfully, apply the address to the active checkout by calling: PATCH [`/commerce/webstores/{webstoreId}/checkouts/active`](https://developer.salesforce.com/docs/atlas.en-us.chatterapi.meta/chatterapi/connect_resources_commerce_webstore_checkouts.htm) Example request body: ```json { "deliveryAddress": { "street": "1 Market St", "city": "San Francisco", "region": "CA", "postalCode": "94105", "country": "US" } } ``` 5. Save the address before applying it to the checkout to reduce downstream validation failures during checkout updates. 6. Use the updated checkout response to refresh delivery methods and totals. 7. Advance the checkout flow to the delivery step. **Select a Delivery Method** This flow demonstrates how a headless storefront can orchestrate delivery method selection during checkout using B2B Commerce Checkout APIs. ![Checkout Delivery Method Flow](https://developer.salesforce.com/media/d2c-commerce/b2b-headless-b2b-commerce-headless-flow-orchestration-checkout-b2b-commerce-apis-used-in-the-flow-20-1.png '{"class": "image-lg", "title": "Checkout Delivery Method Flow"}') 1. Select a delivery method from the list of available shipping options. 2. Use the delivery methods returned in the checkout response. No additional request is required to retrieve delivery methods. 3. Call the following endpoint to apply the selected delivery method: PATCH [`/commerce/webstores/{webstoreId}/checkouts/active`](https://developer.salesforce.com/docs/atlas.en-us.chatterapi.meta/chatterapi/connect_resources_commerce_webstore_checkouts.htm) Example request body: ```json { "deliveryMethodId": "" } ``` 4. Use the updated `CheckoutState` response to refresh shipping totals and order summary information. 5. Advance the checkout flow to the payment step. **Authorize a Purchase Order Payment** 1. Enter a purchase order number and billing address information in the payment form. 2. Call the following endpoint to authorize the payment: POST [`/commerce/webstores/{webstoreId}/checkouts/active/payments`](https://developer.salesforce.com/docs/atlas.en-us.chatterapi.meta/chatterapi/connect_resources_commerce_webstore_checkouts_payments.htm) Example request body: ```json { "paymentToken": "", "requestType": "SimplePurchaseOrder", "billingAddress": { "name": "Jane Doe", "companyName": "Acme Inc.", "street": "1 Market St", "city": "San Francisco", "region": "CA", "postalCode": "94105", "country": "US" } } ``` 3. Use a single concatenated name value for the billing address. Separate first-name and last-name fields aren't supported by this endpoint. 4. Use the payment response to update the checkout payment state. 5. Advance the checkout flow to the review step. **Place the Order** This flow demonstrates how a headless storefront can orchestrate payment processing and order submission during checkout using B2B Commerce Checkout APIs. ![Checkout Payment and Place Order Flow](https://developer.salesforce.com/media/d2c-commerce/b2b-headless-section-figure-image-19-1.png '{"class": "image-lg", "title": "Checkout Payment and Place Order Flow"}') 1. Select Place Order to submit the checkout. 2. Finalize totals, tax, and checkout calculations by calling: POST [`/commerce/webstores/{webstoreId}/checkouts/active/orders/actions`](https://developer.salesforce.com/docs/atlas.en-us.chatterapi.meta/chatterapi/connect_resources_commerce_webstore_checkouts_place_order_v2.htm) Example request body: ```json { "actions": [{ "action": "prepare" }] } ``` 3. After the prepare action succeeds, submit the order by calling the same endpoint again: POST [`/commerce/webstores/{webstoreId}/checkouts/active/orders/actions`](https://developer.salesforce.com/docs/atlas.en-us.chatterapi.meta/chatterapi/connect_resources_commerce_webstore_checkouts_place_order_v2.htm) Example request body: ```json { "actions": [{ "action": "submit", "parameters": {} }] } ``` 4. Retrieve the following values from the successful submit response: - `orderReferenceNumber` - `orderSummaryId` - `salesOrderId` 5. Refresh the cart summary after order submission because the active cart is now empty. 6. Use the order confirmation page to display order details and confirmation information. ### Extend the Flow - Replace the purchase order (PO) payment form with a tokenized card payment integration such as Stripe or another payment gateway. The request body sent to POST [`/commerce/webstores/{webstoreId}/checkouts/active/payments`](https://developer.salesforce.com/docs/atlas.en-us.chatterapi.meta/chatterapi/connect_resources_commerce_webstore_checkouts_payments.htm) supports the `paymentToken` field for tokenized payment flows. Integrate the payment gateway of your choice to generate the token, then update the `requestType` and payment payload accordingly. - Add coupon and promotion support during checkout using POST [`/commerce/webstores/{webstoreId}/checkouts/active/coupons`](https://developer.salesforce.com/docs/atlas.en-us.chatterapi.meta/chatterapi/connect_resources_commerce_webstore_coupons.htm) This enables buyers to apply promotional discounts directly within the checkout experience. - Replace the four-step checkout wizard with a fully expanded single-page or accordion-based checkout layout by reading the `currentStep` value returned from the active checkout response and rendering all checkout sections inline. ## See Also - [_B2B Commerce Developer Guide_: Cart and Checkout Features](https://developer.salesforce.com/docs/commerce/salesforce-commerce/guide/b2b-d2c-comm-cart-checkout.html) - [_B2B Commerce Developer Guide_: Get Started with B2B Commerce Checkout](https://developer.salesforce.com/docs/commerce/salesforce-commerce/guide/b2b-comm-checkout-get-started.html) - [_B2B Commerce Developer Guide_: Setup Payment Processing](https://developer.salesforce.com/docs/commerce/salesforce-commerce/guide/b2b-b2c-comm-checkout-payment-b2b-setup.html) - [_B2B Commerce Developer Guide_: B2B Commerce Checkout APIs](https://developer.salesforce.com/docs/commerce/salesforce-commerce/guide/b2b-d2c-comm-checkout-apis.html) - [_B2B Commerce Developer Guide_: B2B Commerce Checkout APIs](https://developer.salesforce.com/docs/commerce/salesforce-commerce/guide/b2b-d2c-comm-checkout-apis.html)