Checkout Page

A checkout page collects customer details, shipping, payment, terms acceptance, and order submission. Build it with one checkout scope and keep the order summary read-only.

Minimum Structure

CheckoutProvider
  CheckoutForm
    BillingAddressForm
    ShippingAddressForm
    ShippingMethodSelector
    PaymentMethodSelector
    TermsCheckbox
    CheckoutNotices
    PlaceOrderButton
  OrderSummary
    Product rows
    Totals rows

Checkout shell

<OmeWooCheckoutProvider>
{#slot default}
  <OmeWooCheckoutForm>
    {#slot default}
      <OmeWooBillingAddressForm />
      <OmeWooShippingAddressForm />
      <OmeWooShippingMethodSelector />
      <OmeWooPaymentMethodSelector />
      <OmeWooTermsCheckbox />
      <OmeWooCheckoutNotices />
      <OmeWooPlaceOrderButton />
    {/slot}
  </OmeWooCheckoutForm>

  <OmeWooOrderSummary />
{/slot}
</OmeWooCheckoutProvider>

Step 1: Put Checkout On The Woo Checkout Page

The OME checkout must live on the configured Woo checkout page. Authors should use a dedicated Woo checkout page or template that contains an OmeWooCheckoutProvider or OmeWooCheckoutForm shell, not a generic page mixed with the native Woo checkout block.

When the configured checkout page contains an OME checkout shell, Etch disables Woo's empty-PHP-cart redirect for that page request. That lets a cart created with Store API Cart-Token and Nonce session headers survive hard navigation to checkout: the server renders the checkout shell, then the browser runtime restores cart and checkout state through Store API requests.

Classic checkout pages and non-checkout pages keep Woo's native empty-cart redirect. Order-pay and order-received endpoints also keep Woo's native routing behavior.

Step 2: Add Provider And Form

CheckoutProvider creates the checkout scope. CheckoutForm owns the submit event and the final Store API checkout request.

Put address forms, selectors, terms, notices, and place-order controls inside CheckoutForm. OrderSummary can sit inside the provider but does not need to be inside the form.

Step 3: Add Address Forms

BillingAddressForm and ShippingAddressForm share address form props and markup generation. They render fields from the checkout field schema, not from hard-coded field lists in the docs.

The checkout runtime handles:

• required billing fields,
• email validation,
• country and state selectors,
• state field visibility when the selected country has no state options,
• the shipping-address toggle and its embedded field group,
• local blocking before Store API submit when known-invalid fields are present.

Step 4: Add Shipping And Payment Selectors

ShippingMethodSelector and PaymentMethodSelector use the shared UIChoice mode logic. Both support select and button-radio presentation. In checkout, selected values are written into checkout state before the form is submitted.

Shipping method options come from package-aware Store API rates. Payment options come from enabled supported Woo payment methods.

Step 5: Add Terms, Notices, And Submit

TermsCheckbox blocks submit when it is required and unchecked. CheckoutNotices renders checkout-scoped error messages. PlaceOrderButton triggers the parent CheckoutForm.

The form sets data-ome-state during validation, pending submit, success, and error states so authors can style the visible state without replacing the native Woo order lifecycle.

Step 6: Add An Order Summary

OrderSummary is read-only. It renders current cart products and totals inside checkout, but it does not submit or mutate checkout data. Use the default propped mode for a quick summary, or atom modes when you want to author product rows and totals yourself.

Mode	Use it when
propped	You want the component to render its own summary structure.
product_atoms	You want to author product rows but keep totals managed by the summary.
full_atoms	You want to author product rows and totals with cart item and total atoms.

This reuse keeps cart and checkout total display aligned with the same normalized cart data.

Step 7: Keep Woo's Checkout Lifecycle

Checkout submission goes through Woo Store API checkout. Woo's native checkout hooks still run through that path, including order update and payment processing hooks.

That means Etch components can be authored visually while Woo plugins that rely on native checkout hooks still see the checkout lifecycle.

Next References

• Checkout Shell explains provider, form, notices, and place-order props.
• Checkout Address Forms explains billing and shipping fields.
• Shipping Selector and Payment Selector explain selector modes.
• Order Summary explains summary modes.
• Checkout Fields and Validation explains Woo field schema and validation behavior.
• Woo Template Integration Contract explains assigned checkout pages and route ownership.