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.items);

// 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.items.length}</p>
      <p>Subtotal: ${session.totals.items}</p>
      {session.totals.discounts > 0 && (
        <p>Discounts: -${session.totals.discounts}</p>
      )}
      <p>Shipping: ${session.totals.shipping}</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