React Hooks API Reference

These hooks give your components access to live checkout data and the ability to modify the checkout experience. All hooks are TypeScript-ready with full type definitions, and are imported from @ollie-shop/sdk.

Quick Reference

useCheckoutSession

Read the parsed checkout session (cart items, customer, totals, locale) and validate it

useCheckoutAction

Mutate the checkout: add/remove items, update quantities, coupons, addresses, payments

useStoreInfo

Store metadata, theme tokens, props/settings, and injected components

useMessages

Add, remove, and clear notification messages

usePendingActions

Track in-flight checkout actions to drive loading states

useCheckoutOrder

Access the finalized order after checkout completes

Custom components must import only from @ollie-shop/sdk. It is externalized at build time; importing from internal packages (e.g. @ollie-shop/react) bundles them into your component and is not supported.

useCheckoutSession

The primary hook for reading checkout data. To change the cart, use useCheckoutAction — the session hook is read-only and does not expose mutation functions. It returns { session, rawSession, updateSession, sessionValidity, ... }. The parsed, platform-agnostic data lives on session.

📊 Cart Data
👤 Customer Data
🛠️ Modifying the Cart

Access cart contents and totals

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

function CartDisplay() {
  const { session } = useCheckoutSession();
  const { cartItems, totals, locale } = session;

  const format = (cents: number) =>
    new Intl.NumberFormat(locale.language, {
      style: 'currency',
      currency: locale.currency,
    }).format(cents / 100);

  return (
    <div>
      <h3>Cart Summary</h3>
      <p>Items: {cartItems.length}</p>
      <p>Subtotal: {format(totals.items)}</p>
      <p>Shipping: {format(totals.shipping ?? 0)}</p>
      <p>Total: {format(totals.total)}</p>

      {cartItems.map((item) => (
        <div key={item.uniqueId}>
          {item.name} — Qty: {item.quantity} — {format(item.price)}
        </div>
      ))}
    </div>
  );
}

session.totals (all amounts in minor units / cents):

Property	Type	Description
`items`	`number`	Total cost of items in the cart
`shipping?`	`number`	Total shipping cost
`tax?`	`number`	Total tax amount
`discounts?`	`number`	Total discount amount
`giftCard?`	`number`	Total gift card amount
`interest?`	`number`	Total interest (e.g. from installments)
`total`	`number`	Grand total for the checkout

session.cartItems[]:

Property	Type	Description
`id`	`string`	Item identifier (e.g. SKU code)
`sellerId?`	`string`	Marketplace seller/vendor identifier
`name`	`string`	Display name
`variant?`	`string`	Variant name (e.g. “Size Large”)
`brand?`	`string`	Brand name
`category?`	`string`	Primary product category
`price`	`number`	Current (sale) price in cents
`originalPrice`	`number`	Original (non-sale) price in cents
`quantity`	`number`	Quantity of this item
`available`	`boolean`	Whether the item is in stock
`index`	`number`	Position index in the cart
`image`	`string`	Image URL
`uniqueId`	`string`	Unique id of the cart line
`url?`	`string`	URL to the product details
`variantDetails?`	`Record<string, string>`	Variant info (color, size…)

Access customer informationsession.customer is optional — guard for undefined. To tell whether the operator is a guest, use session.user.isGuest.

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

function CustomerInfo() {
  const { session } = useCheckoutSession();
  const { customer, user } = session;

  if (user.isGuest) {
    return (
      <div>
        <h3>Welcome, Guest!</h3>
        <button>Sign in for faster checkout</button>
      </div>
    );
  }

  return (
    <div>
      <h3>Welcome back, {customer?.firstName}!</h3>
      {customer?.email && <p>Email: {customer.email}</p>}
    </div>
  );
}

session.customer (CustomerData, optional):

Property	Type	Description
`id?`	`string`	Platform identifier for the customer
`email?`	`string`	Email address
`firstName?`	`string`	First name
`lastName?`	`string`	Last name
`document?`	`string`	Document / tax ID (e.g. CPF)
`phone?`	`string`	Phone number
`addresses?`	`CustomerAddress[]`	Saved addresses

session.user (User, who operates the session):

Property	Type	Description
`id?`	`string`	User id (shopper or operator)
`role`	`"user" \| "operator"`	Whether a customer or an operator
`isGuest`	`boolean`	Whether the user is not logged in

Cart changes go through useCheckoutAction, not useCheckoutSession.

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

function CartActions() {
  const { execute: addItems } = useCheckoutAction('ADD_ITEMS');
  const { execute: removeItems } = useCheckoutAction('REMOVE_ITEMS');
  const { execute: updateQuantity } = useCheckoutAction('UPDATE_ITEMS_QUANTITY');
  const { execute: updateCoupons } = useCheckoutAction('UPDATE_COUPONS');

  return (
    <div>
      <button onClick={() => addItems([{ id: 'upsell-123', quantity: 1 }])}>
        Add Extended Warranty
      </button>
      <button onClick={() => removeItems([0])}>Remove first item</button>
      <button onClick={() => updateQuantity([{ index: 0, quantity: 3 }])}>
        Set first item qty to 3
      </button>
      <button onClick={() => updateCoupons(['SAVE10'])}>Apply SAVE10</button>
    </div>
  );
}

Action	Input	Description
`ADD_ITEMS`	`{ id; quantity; sellerId? }[]`	Add items to the cart
`REMOVE_ITEMS`	`number[]` (item indexes)	Remove items
`UPDATE_ITEMS_QUANTITY`	`{ index; quantity }[]`	Update quantities
`UPDATE_COUPONS`	`string[]` (coupon codes)	Apply/remove coupons

See useCheckoutAction for the full list of actions and inputs.

useStoreInfo

Access store metadata, theme tokens, and configuration.

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

function ThemedComponent() {
  const { platformStoreId, logo, theme, props } = useStoreInfo();

  // `theme` is a flat Record<string, string> of design tokens
  // (CSS-variable-style keys), not a nested object.
  return (
    <div
      style={{
        backgroundColor: theme?.['--color-primary'],
        color: theme?.['--color-text'],
      }}
    >
      <h2>{platformStoreId}</h2>
      {logo && <img src={logo} alt="Store logo" />}

      {props?.flags?.showCouponCodeInputOpened && (
        <input placeholder="Enter coupon code" />
      )}
    </div>
  );
}

Returned properties (Omit<StoreInfo, "messages">):

Property	Type	Description
`platform`	`string`	E-commerce platform (e.g. “vtex”)
`platformStoreId`	`string`	Store id on the platform
`storeId?`	`string`	Ollie store id
`logo?`	`string`	Store logo URL
`versionId?`	`string`	Active store version id
`correlationId?`	`string`	Request correlation id
`template?`	`TemplateType`	Active template
`theme?`	`Record<string, string>`	Flat design tokens
`props?`	`object`	Version props and feature flags
`settings?`	`Record<string, unknown>`	Store settings
`components?`	`CustomComponent[]`	Custom components injected into this store

Combining Hooks

import {
  useCheckoutSession,
  useCheckoutAction,
  usePendingActions,
  useStoreInfo,
} from '@ollie-shop/sdk';

function CheckoutSummary() {
  const { session } = useCheckoutSession();
  const { platformStoreId } = useStoreInfo();
  const { hasPendingActions } = usePendingActions();
  const { execute: removeItems } = useCheckoutAction('REMOVE_ITEMS');

  const { cartItems, totals, locale, user } = session;
  const format = (cents: number) =>
    new Intl.NumberFormat(locale.language, {
      style: 'currency',
      currency: locale.currency,
    }).format(cents / 100);

  return (
    <div style={{ opacity: hasPendingActions ? 0.5 : 1 }}>
      <h2>Order Summary — {platformStoreId}</h2>
      <p>{user.isGuest ? 'Guest order' : 'Signed-in order'}</p>

      {cartItems.map((item) => (
        <div key={item.uniqueId}>
          <span>{item.name} — {format(item.price)}</span>
          <button onClick={() => removeItems([item.index])}>Remove</button>
        </div>
      ))}

      <p><strong>Total: {format(totals.total)}</strong></p>
    </div>
  );
}

Use usePendingActions to disable buttons or show skeletons while a useCheckoutAction call is in flight — the pending list is updated automatically by the action hook.

​Quick Reference

useCheckoutSession

useCheckoutAction

useStoreInfo

useMessages

usePendingActions

useCheckoutOrder

​useCheckoutSession

​useStoreInfo

​Combining Hooks

Quick Reference

useCheckoutSession

useStoreInfo

Combining Hooks