The Checkout page implements a four-step single-page checkout flow:
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.
| Operation | HTTP Method | Endpoint |
|---|---|---|
| Get active checkout | GET | /commerce/webstores/{webstoreId}/checkouts/active |
| Start checkout | PUT | /commerce/webstores/{webstoreId}/checkouts |
| List saved addresses | GET | /commerce/webstores/{webstoreId}/accounts/current/addresses |
| Save new address | POST | /commerce/webstores/{webstoreId}/accounts/current/addresses |
| Set shipping address | PATCH | /commerce/webstores/{webstoreId}/checkouts/active |
| Pick delivery method | PATCH | /commerce/webstores/{webstoreId}/checkouts/active |
| Authorize PO payment | POST | /commerce/webstores/{webstoreId}/checkouts/active/payments |
| Place order | POST | /commerce/webstores/{webstoreId}/checkouts/active/orders/actions |
Initialize Checkout
Load the checkout experience.
Call the following endpoint to retrieve the active checkout:
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.
If no active checkout exists, create one by calling:
PUT /commerce/webstores/{webstoreId}/checkouts
Example request body:
1{
2 "cartId": "active",
3 "deliveryAddressInput": {
4 "shouldUseDefaultAddress": true
5 }
6}Set shouldUseDefaultAddress=true to instruct the platform to:
This reduces additional checkout update requests later in the flow.
Retrieve the buyer’s saved shipping addresses by calling:
GET /commerce/webstores/{webstoreId}/accounts/current/addresses?addressType=Shipping
Retrieve cart items for the checkout summary panel by calling:
GET /commerce/webstores/{webstoreId}/carts/current/cart-items
Use the responses to render:
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.
Select a shipping address from the saved-address list.
Call the following endpoint to apply the address to the active checkout:
PATCH /commerce/webstores/{webstoreId}/checkouts/active
Example request body:
1{
2 "deliveryAddress": {
3 "street": "1 Market St",
4 "city": "San Francisco",
5 "region": "CA",
6 "postalCode": "94105",
7 "country": "US"
8 }
9}Use the deliveryAddress field in the request body. The legacy shippingAddress field isn’t supported by this endpoint.
Use the updated checkout response to refresh checkout totals and delivery information.
Advance the checkout flow to the delivery step.
Add and Apply a New Shipping Address
Enter a new shipping address in the checkout address form.
Save the address to the buyer account by calling:
POST /commerce/webstores/{webstoreId}/accounts/current/addresses
Allow the platform to validate and normalize the address before applying it to the checkout.
After the address is saved successfully, apply the address to the active checkout by calling:
PATCH /commerce/webstores/{webstoreId}/checkouts/active
Example request body:
1{
2 "deliveryAddress": {
3 "street": "1 Market St",
4 "city": "San Francisco",
5 "region": "CA",
6 "postalCode": "94105",
7 "country": "US"
8 }
9}Save the address before applying it to the checkout to reduce downstream validation failures during checkout updates.
Use the updated checkout response to refresh delivery methods and totals.
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.
Select a delivery method from the list of available shipping options.
Use the delivery methods returned in the checkout response. No additional request is required to retrieve delivery methods.
Call the following endpoint to apply the selected delivery method:
PATCH /commerce/webstores/{webstoreId}/checkouts/active
Example request body:
1{
2 "deliveryMethodId": "<delivery-method-id>"
3}Use the updated CheckoutState response to refresh shipping totals and order summary information.
Advance the checkout flow to the payment step.
Authorize a Purchase Order Payment
Enter a purchase order number and billing address information in the payment form.
Call the following endpoint to authorize the payment:
POST /commerce/webstores/{webstoreId}/checkouts/active/payments
Example request body:
1{
2 "paymentToken": "<po-number>",
3 "requestType": "SimplePurchaseOrder",
4 "billingAddress": {
5 "name": "Jane Doe",
6 "companyName": "Acme Inc.",
7 "street": "1 Market St",
8 "city": "San Francisco",
9 "region": "CA",
10 "postalCode": "94105",
11 "country": "US"
12 }
13}Use a single concatenated name value for the billing address. Separate first-name and last-name fields aren’t supported by this endpoint.
Use the payment response to update the checkout payment state.
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.
Select Place Order to submit the checkout.
Finalize totals, tax, and checkout calculations by calling:
POST /commerce/webstores/{webstoreId}/checkouts/active/orders/actions
Example request body:
1{
2 "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
Example request body:
1{
2 "actions": [{ "action": "submit", "parameters": {} }]
3}Retrieve the following values from the successful submit response:
orderReferenceNumberorderSummaryIdsalesOrderIdRefresh the cart summary after order submission because the active cart is now empty.
Use the order confirmation page to display order details and confirmation information.
/commerce/webstores/{webstoreId}/checkouts/active/payments 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./commerce/webstores/{webstoreId}/checkouts/active/coupons This enables buyers to apply promotional discounts directly within the checkout experience.currentStep value returned from the active checkout response and rendering all checkout sections inline.
j