useCheckoutSession - Ollie Shop

The useCheckoutSession hook provides access to the current checkout session data and functionality to update it. It gives you access to both the parsed, platform-agnostic checkout session data and the raw session data from the e-commerce platform.

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

Returns an object with:

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 (VTEX, Shopify, etc.) 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

Session Validation

The sessionValidity object contains the results of validating the checkout session against a ZodSchema. This schema-based validation ensures that all required data is present and formatted correctly.

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

A common use case is checking if some information is complete before redirecting the user to the next step

export const function PageShipping {
  const { sessionValidity } = useCheckoutSession();

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

  // Component rendering...
  return (
    <form onSubmit={() => {}}>
        <button type="submit">
            Next to {missingAddressFields ? 'address' : 'payment'}
        </button>
    </form>
  )
}

This pattern lets you detect missing required fields and direct users to the appropriate step in your checkout flow to provide that information.

Example

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

function CartSummary() {
  const { session } = useCheckoutSession();

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

Notes

Use type parameters with useCheckoutSession<YourExtensions>() when you have custom properties in your checkout session

​Import

​Usage

​Return Value

​Session Validation

​Understanding sessionValidity

​Validating Address Information

​Example

​Notes