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.
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
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 itemsnumberTotal cost of items in the cart shipping?numberTotal shipping cost tax?numberTotal tax amount discounts?numberTotal discount amount giftCard?numberTotal gift card amount interest?numberTotal interest (e.g. from installments) totalnumberGrand total for the checkout
session.cartItems[]:Property Type Description idstringItem identifier (e.g. SKU code) sellerId?stringMarketplace seller/vendor identifier namestringDisplay name variant?stringVariant name (e.g. “Size Large”) brand?stringBrand name category?stringPrimary product category pricenumberCurrent (sale) price in cents originalPricenumberOriginal (non-sale) price in cents quantitynumberQuantity of this item availablebooleanWhether the item is in stock indexnumberPosition index in the cart imagestringImage URL uniqueIdstringUnique id of the cart line url?stringURL to the product details variantDetails?Record<string, string>Variant info (color, size…)
Access customer information session.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?stringPlatform identifier for the customer email?stringEmail address firstName?stringFirst name lastName?stringLast name document?stringDocument / tax ID (e.g. CPF) phone?stringPhone number addresses?CustomerAddress[]Saved addresses
session.user (User, who operates the session):Property Type Description id?stringUser id (shopper or operator) role"user" | "operator"Whether a customer or an operator isGuestbooleanWhether 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_ITEMSnumber[] (item indexes)Remove items UPDATE_ITEMS_QUANTITY{ index; quantity }[]Update quantities UPDATE_COUPONSstring[] (coupon codes)Apply/remove coupons
See useCheckoutAction 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 platformstringE-commerce platform (e.g. “vtex”) platformStoreIdstringStore id on the platform storeId?stringOllie store id logo?stringStore logo URL versionId?stringActive store version id correlationId?stringRequest correlation id template?TemplateTypeActive template theme?Record<string, string>Flat design tokens props?objectVersion 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 > ); }
