Checkout Guide

The checkout flow moves a customer from browsing to a submitted P21 order. The augur packages handle cart state, pricing, shipping, address validation, payment processing, and order submission — your app wires them together.

Flow Overview

Add to Cart → Cart Page → Checkout → Order Submitted → Confirmation

Cart — Items are added and managed via a Zustand store. Quantities, pricing, and line items stay in sync with the commerce microservice.
Shipping — Customer enters a shipping address (validated via SmartyStreets), then selects a shipping method with live rate quotes.
Billing & Payment — Customer provides billing details and pays by credit card (hosted payment iframe) or invoice (for approved accounts).
Order Submission — The complete order (lines, addresses, shipping, payment) is submitted to P21 through the commerce service.
Confirmation — Customer sees order details on a thank-you page.

Cart Management

Initialization

The useCartInitializationBase hook from augur-hooks manages cart lifecycle. It finds or creates a cart header in the commerce service and loads existing lines into a Zustand store.

import { useCartInitializationBase } from "@simpleapps-com/augur-hooks";

useCartInitializationBase({
  userId,
  cartToken,           // UUID for anonymous users (stored in a cookie)
  cartHdrLookup,       // Server action → commerceActions.cartHdrLookup()
  getCartLines,        // Server action → commerceActions.getCartLines()
});

Once initialized, cart state is available anywhere via hooks:

import { useCartHdrUid, useCartLines } from "@simpleapps-com/augur-hooks";

const cartHdrUid = useCartHdrUid();
const cartLines = useCartLines();

Cart Actions

The useCartActionsBase hook provides add, update, remove, and clear operations:

import { useCartActionsBase } from "@simpleapps-com/augur-hooks";

const { addToCart, updateQuantity, removeFromCart, clearCart } =
  useCartActionsBase({
    addToCartAction,        // Server action → commerce API
    updateCartLinesAction,  // Server action → commerce API
    deleteCartAction,       // Server action → commerceActions.deleteCartItems()
    onSuccess: () => toast("Cart updated"),
    onError: (err) => toast.error(err.message),
  });

A common pattern is debouncing quantity updates — update the UI immediately and delay the API call by 500ms so rapid changes don't flood the server.

Cart Pricing

Use useCartPricing from your site hooks to get prices with actual cart quantities, ensuring accurate quantity-based price breaks:

const { prices, getUnitPrice } = useCartPricing();

// In a cart line component
const unitPrice = getUnitPrice(item.itemId);

This is the single source of truth for prices across the cart and checkout pages.

Shipping

Address Validation

The SmartyStreets service validates and corrects shipping addresses:

const result = await smartyStreetsActions.validateAddress(address1, postalCode, state);
// Returns corrected address fields (city, state, zip+4)

A typical pattern is validating on blur or after a short debounce, then showing a correction modal if the validated address differs from what the customer entered.

Shipping Rates

Fetch live rates from the shipping service based on the destination and cart contents:

const rates = await shippingActions.getShippingRates({
  fromAddress,      // Your warehouse address
  toAddress,        // Customer's validated shipping address
  weight,           // Total cart weight
  serviceCodes,     // Carrier service codes to quote
});

Your app determines which carriers to offer and any free-shipping thresholds based on your business rules.

Billing & Payment

Payment Methods

The payments service supports hosted credit card processing via a secure iframe. The flow:

Setup — Call paymentsActions.transactionSetup() to get a session ID and iframe URL
Capture — Render the hosted iframe where the customer enters card details (card data never touches your server)
Verify — Call paymentsActions.validatePayment() to confirm the card was captured
Query — Call paymentsActions.accountQuery() to get a payment token for order submission

For invoice/terms customers, billing is just an address and PO number — no payment processing needed.

Order Submission

Once all steps are complete, submit the order:

const result = await commerceActions.checkoutOrder(cartHdrUid, {
  header: {
    carrier_id,
    customer_id,
    contact_id,
    ship_to_name,
    ship_to_address1,
    ship_to_city,
    ship_to_state,
    ship_to_postal_code,
    customer_po_number,
    shipping_estimate,
    // ... additional header fields
  },
  lines: orderCartLines,    // Array of { inv_mast_uid, item_id, qty, uom, unitPrice }
  payments: paymentData,    // Credit card token or invoice details
  notes: { note: customerNotes },
});

On success, clear the cart and redirect to a confirmation page. The commerce service handles creating the order in P21.

Server Actions

All checkout operations go through createSiteActions from augur-server:

import { createSiteActions } from "@simpleapps-com/augur-server";

const actions = createSiteActions(api, { /* config */ });

actions.commerce    // Cart CRUD, order submission
actions.shipping    // Rate quotes
actions.payments    // Credit card processing
actions.smartyStreets // Address validation
actions.pricing     // Cart line pricing

Client Hooks

augur-hooks provides the client-side state layer:

Hook	Purpose
`useCartInitializationBase`	Find/create cart, load lines into store
`useCartActionsBase`	Add, update, remove, clear cart items
`useCartHdrUid`	Read cart header UID from store
`useCartLines`	Read cart lines from store
`useCartPricing`	Prices for current cart with quantity breaks

Typical Architecture

Client (React)                    Server (Next.js)                 Augur Services
─────────────────                 ────────────────                 ──────────────
Zustand cart store  ──actions──►  Server actions    ──SDK calls──► Commerce API
useCartPricing      ──actions──►  pricingActions    ──SDK calls──► Pricing API
ShippingForm        ──actions──►  shippingActions   ──SDK calls──► Shipping API
AddressForm         ──actions──►  smartyStreets     ──SDK calls──► SmartyStreets API
PaymentIframe       ──actions──►  paymentsActions   ──SDK calls──► Payments API
ProcessOrder        ──actions──►  checkoutOrder     ──SDK calls──► Commerce API → P21

Checkout

On this page