useCheckoutSession

Build a custom totalizer from the session totals.

​

Import

import { useCheckoutSession } from '@ollie-shop/sdk';

​

Usage

const { session, rawSession, updateSession, sessionValidity } = useCheckoutSession();

// Access session data
console.log(session.cartItems);

// Update session data
updateSession(newSession, newRawSession);

// Check if the session is valid
if (sessionValidity?.valid) {
  // Session is valid
} else {
  // Handle validation errors
  console.error(sessionValidity?.errors);
}

​

Return Value

• session: CheckoutSession<Extensions> - The parsed, platform-agnostic checkout session conforming to your custom schema
• rawSession: unknown - The original session data from the e-commerce platform (for example the VTEX orderForm) in raw/unparsed form
• updateSession: (session: CheckoutSession<Extensions>, rawSession: unknown) => void - Function to update both the parsed and raw session data
• sessionValidity?: ValidationSuccess | ValidationFailure - Results from the last validation check of the session data
• sessionValidate: (session, options?: { ignorePayment?: boolean }) => ValidationSuccess | ValidationFailure - Validate any session object on demand, optionally skipping the payment rules
• revalidate: () => void - Fetch the session again from the platform and update the context
• revalidateAsync: () => Promise<...> - Same as revalidate, but returns a promise that settles when the fetch finishes
• isFallback: boolean - true while the session is served from the last known copy; call revalidate to refresh
• fallbackError?: string - The message that explains the fallback state
• clearFallback: () => void - Clear the fallback state, for example after a successful revalidate

​

Session Validation

if (sessionValidity?.valid) {
  // Session is valid - all required fields are present and correctly formatted
} else {
  // Session is invalid - access validation errors
  const errors = sessionValidity?.errors;
}

​

Understanding sessionValidity

• sessionValidity uses a ZodSchema to validate the structure and content of your checkout session
• It helps identify missing or invalid information in customer details, shipping addresses, payment methods, etc.
• This validation is crucial for determining whether a user can proceed to checkout or needs to provide more information

​

Validating Address Information

import { useCheckoutSession } from '@ollie-shop/sdk';

export default function NextStepButton() {
  const { sessionValidity } = useCheckoutSession();

  // Extract address validation errors if they exist
  const missingAddressFields =
    sessionValidity && "errors" in sessionValidity
      ? sessionValidity.errors?.shipping?.addresses
      : undefined;

  return (
    <button type="button">
      Next to {missingAddressFields ? 'address' : 'payment'}
    </button>
  );
}

​

Example

import { useCheckoutSession } from '@ollie-shop/sdk';

function CartSummary() {
  const { session } = useCheckoutSession();
  const { currency, language } = session.locale;

  // Totals are in minor units (cents), so divide by 100 before formatting
  const format = (amount: number) =>
    new Intl.NumberFormat(language, { style: 'currency', currency }).format(amount / 100);

  return (
    <div>
      <h2>Cart Summary</h2>
      <p>Total Items: {session.cartItems.length}</p>
      <p>Subtotal: {format(session.totals.items)}</p>
      {(session.totals.discounts ?? 0) > 0 && (
        <p>Discounts: -{format(session.totals.discounts ?? 0)}</p>
      )}
      <p>Shipping: {format(session.totals.shipping ?? 0)}</p>
      <p><strong>Total: {format(session.totals.total)}</strong></p>
    </div>
  );
}

​

Notes

• Use type parameters with useCheckoutSession<YourExtensions>() when you have custom properties in your checkout session
• All amounts in session.totals and on cart items are in the currency’s minor units (cents). Format them with session.locale as in the example
• To change the cart, use useCheckoutAction. updateSession replaces the context with a session you already have; it does not call the platform