Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.ollie.shop/llms.txt

Use this file to discover all available pages before exploring further.

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