CheckoutSession Type

The CheckoutSession is the core type of the SDK: the platform-agnostic view of the shopper’s cart, customer, shipping, payment and totals that useCheckoutSession returns and that every action of useCheckoutAction updates. This page lists every field of the session and of the types it contains. All of them are importable from @ollie-shop/sdk, for example import type { CheckoutSession, CartItem } from '@ollie-shop/sdk'.

Let your agent build it. The Ollie Shop skill ships with projects created by npx create-ollie-shop and knows this interface, including which fields can be absent and need a defensive read.

Prompt

Read the selected delivery address from the session and show it in a component.

Don’t have the skill yet? Install it.

Two conventions apply everywhere below:

Amounts are in minor units (cents). Divide by 100 before formatting, or use Intl.NumberFormat with session.locale as in the examples.
Optional means the platform may not send it. Guard with ?. before reading nested data.

Structure Overview

interface CheckoutSession<E = Record<string, unknown>> {
  id: string;
  hasSaveCardOptinAccess: boolean;
  cartItems: CartItem[];
  customer?: CustomerData;
  customerPreferences?: CustomerPreferences;
  shipping?: ShippingInfo;
  payment?: PaymentInfo;
  campaign?: Campaign;
  locale: LocaleInfo;
  taxes?: TaxLine[];
  totals: Totals;
  user: User;
  readOnly: boolean;
  extensions?: E;
}

Field	Type	Description
`id`	`string`	Unique identifier for the checkout session (platform-specific or generated)
`hasSaveCardOptinAccess`	`boolean`	Whether the store lets shoppers opt in to saving their card
`cartItems`	`CartItem[]`	The items in the cart
`customer`	`CustomerData \| undefined`	The customer the order is for. May differ from `user` when an operator is assisting
`customerPreferences`	`CustomerPreferences \| undefined`	`saveData` and `locale` preferences
`shipping`	`ShippingInfo \| undefined`	Addresses, packages and quotes
`payment`	`PaymentInfo \| undefined`	Available methods, selected payments, gift cards and saved cards
`campaign`	`Campaign \| undefined`	Coupons and promotions
`locale`	`LocaleInfo`	Currency, language and country
`taxes`	`TaxLine[] \| undefined`	Breakdown of the tax lines behind `totals.tax`
`totals`	`Totals`	Totalizers
`user`	`User`	Who is operating the session
`readOnly`	`boolean`	`true` when the session can no longer be edited, for example after the shopper moved to a final payment step
`extensions`	`E \| undefined`	Custom fields added by functions or the platform. Type it with `useCheckoutSession<YourExtensions>()`

CartItem

Field	Type	Description
`id`	`string`	The SKU id
`uniqueId`	`string`	Unique id of this cart line. Use it as the React key
`index`	`number`	Position in `cartItems`. The index the item actions take
`name`	`string`	Display name
`seller`	`{ id: string; name: string } \| undefined`	The seller of record, when the platform names one
`productId`	`string \| undefined`	The product this SKU belongs to
`productRefId`, `refId`	`string \| undefined`	The merchant’s own references for the product and the SKU
`gtin`	`string \| undefined`	Barcode (EAN, UPC, ISBN)
`variant`	`string \| undefined`	Variant name (e.g., “Size Large”, “Red”)
`variantDetails`	`Record<string, string> \| undefined`	Variant attributes (e.g., `{ color: "Red" }`)
`brand`	`string \| undefined`	Brand name
`category`	`string \| undefined`	Outermost product category
`categoryTree`	`string[] \| undefined`	Full category path, outermost first
`price`	`number`	Current (sale) unit price, minor units
`originalPrice`	`number`	Original (non-sale) unit price, minor units
`quantity`	`number`	Quantity in the cart
`unitOfMeasure`	`string \| undefined`	Unit of measure (e.g., “un”, “kg”, “m”)
`unitMultiplier`	`number \| undefined`	Measured amount per quantity unit (0.3 with “kg” means 0.3 kg each). Defaults to 1
`available`	`boolean`	Whether the item can be bought right now
`unavailableReason`	`"outOfStock" \| "cannotBeDelivered" \| "sellerLimitReached" \| "other" \| undefined`	Why it is unavailable, when the platform says
`image`	`string`	Image URL
`url`	`string \| undefined`	Product page URL

CustomerData

Every field is optional.

Field	Type	Description
`id`	`string`	The customer’s id on the platform
`email`	`string`	Email address
`firstName`, `lastName`	`string`	Name
`document`	`string`	Document or tax id (e.g., CPF in Brazil)
`phone`	`string`	Phone number
`addresses`	`CustomerAddress[]`	Saved addresses
`company`	`CustomerCompany`	Set when buying as a company: `name`, `document` (e.g., CNPJ), `phone`, `tradeName`, `stateRegistration`, all optional

CustomerPreferences: saveData?: boolean (remember the customer’s data) and locale?: string (e.g., "en-US").

Addresses

Address

The base shape, used for billing addresses as BillingAddress.

Field	Type	Description
`id`	`string \| undefined`	Set for saved addresses
`type`	`"home" \| "billing" \| "work" \| "pick_up" \| "search" \| "other" \| undefined`	`"search"` marks an address found through the address search, not yet saved
`street`, `number`, `complement`, `reference`, `neighborhood`, `city`, `stateOrProvince`	`string \| undefined`	Address lines
`country`	`string`	Country code (e.g., “USA”, “BRA”)
`postalCode`	`string`	Postal or zip code
`geoCoordinates`	`number[] \| undefined`	`[longitude, latitude]`

ShippingAddress

Address plus receiverName?: string.

CustomerAddress

Address plus:

Field	Type	Description
`selected`	`boolean`	Whether this is the selected address
`receiverName`	`string \| undefined`	Who receives deliveries there
`editable`	`boolean \| undefined`	`true` when the address was created in this session and can be edited without logging in

ShippingInfo

Field	Type	Description
`addresses`	`ShippingAddress[]`	Addresses available for selection
`packages`	`ShippingPackage[]`	The packages the cart is split into, with the quote each one sits on
`availableQuotes`	`ShippingQuote[]`	The shipping options the shopper can pick
`availableCountries`	`string[]`	Country codes the store ships to

ShippingPackage

Field	Type	Description
`id`	`string`	Package id, which is also the id of the quote it was placed on
`items`	`number[]`	Indexes of the cart items in this package
`carrier`	`string`	Carrier (e.g., “FedEx”, “Correios”)
`method`	`string`	Carrier method (e.g., “Standard”, “Express”)
`vendor`	`string \| undefined`	Vendor of the package
`estimatedDeliveryTime`	`EstimatedDeliveryTime \| undefined`	Estimate as a duration
`estimatedDeliveryDate`	`string \| undefined`	Estimate as an ISO 8601 date. Prefer it when present
`price`	`number`	Shipping price, minor units
`addressId`	`string`	The address this package ships to
`type`	`"delivery" \| "pick_up" \| "digital"`	How it is fulfilled. `"digital"` is used for gift cards and other items with no physical delivery
`storeName`	`string \| undefined`	Store name, for pickup packages
`timeSlot`	`TimeSlot \| undefined`	The delivery or pickup window chosen

EstimatedDeliveryTime: { value: number; unit }, where unit is a singular or plural time unit ("day", "days", "hour", "week", …) or "businessDays". TimeSlot: { id: string; price: number; originalPrice: number; startDate: string; endDate: string }, dates in ISO 8601.

ShippingQuote

A union of three shapes, narrowed by type:

`type`	Extra fields
`"delivery"`	none
`"pick_up"`	`pickUpInfo`
`"digital"`	none. Never shown as a choice; it exists so every package has a matching quote

Fields shared by all three:

Field	Type	Description
`id`	`string`	Quote id. Pass it as `id` in `UPDATE_SHIPPING_PACKAGES`
`carrier`	`string`	Carrier
`name`	`string`	Method name (e.g., “Standard”, “Express”)
`vendor`	`string`	Vendor
`estimatedDeliveryTime`	`EstimatedDeliveryTime`	Estimate as a duration
`estimatedDeliveryDate`	`string \| undefined`	Estimate as an ISO 8601 date
`availableItems`	`{ itemIndex: number; price: number }[]`	The cart items this quote can carry, with the price for each
`price`	`number`	Price of the quote, minor units
`timeSlots`	`TimeSlot[]`	Windows the shopper can pick, when the carrier offers them

pickUpInfo on a pickup quote:

Field	Type	Description
`name`	`string`	Name of the pickup point
`address`	`ShippingAddress`	Its address
`pickupPointId`	`string \| undefined`	Its id in the platform’s pickup directory
`distance`	`number \| undefined`	Straight-line distance in kilometres
`businessHours`	`{ dayOfWeek: number; opensAt: string; closesAt: string }[] \| undefined`	Opening hours, one entry per day it opens. `dayOfWeek` 0 is Sunday; times are `HH:mm:ss` local

PaymentInfo

Field	Type	Description
`availableMethods`	`PaymentMethod[]`	Every payment method the store offers
`selectedPayments`	`SelectedPayment[]`	The payment(s) chosen. Some checkouts allow more than one
`giftCards`	`GiftCard[] \| undefined`	Gift cards applied
`savedCards`	`SavedCard[]`	Cards the shopper saved
`total`	`number`	Amount the payments must cover, minor units

PaymentMethod

Field	Type	Description
`id`	`string`	Method id. Pass it as `methodId` in `UPDATE_PAYMENT_METHODS`
`type`	`PaymentMethodType`	`"credit_card"`, `"debit_card"`, `"pix"`, `"boleto"`, `"paypal"`, `"google_pay"`, `"apple_pay"`, `"gift_card"`, and the other method types the SDK knows
`name`	`string`	Display name (e.g., “Visa”, “PayPal”)
`installments`	`PaymentInstallment[] \| undefined`	Installment plans computed on the order total
`installmentsByValue`	`{ value: number; installments: PaymentInstallment[] }[] \| undefined`	Installment plans per amount, for split payments
`config`	`Record<string, unknown> \| undefined`	Extra configuration the method needs

PaymentInstallment: { number: number; amount: number; total: number; interestRate?: number }, amounts in minor units.

SelectedPayment

Field	Type	Description
`id`	`string`	Payment id
`methodId`	`string`	The chosen method (`PaymentMethod.id`)
`referenceValue`	`number`	Base amount for this payment, minor units
`total`	`number`	Amount paid with it, minor units
`installments`	`number \| undefined`	Installments chosen
`savedCardId`	`string \| null`	The saved card used, if any

GiftCard

Field	Type	Description
`id`	`string`	Gift card id
`provider`	`string`	Provider
`code`	`string \| null`	Redemption code. `null` for special cards (loyalty, cashback) attached automatically
`value`	`number \| undefined`	Amount applied to this order
`balance`	`number \| undefined`	Total balance, when the provider reports it
`isInUse`	`boolean \| undefined`	Whether it is applied
`isSpecialCard`	`boolean \| undefined`	`true` for cards attached automatically rather than redeemed by code

SavedCard

Field	Type	Description
`id`	`string`	Card id
`brandId`, `brandName`	`string`	The card brand (e.g., “Visa”)
`cardNumber`	`string`	Masked number (e.g., “************1111”)
`bin`	`string`	First digits of the card
`addresses`	`{ id: string }[]`	Billing addresses linked to the card
`isExpired`	`boolean`	Whether the card is expired

Campaign

Field	Type	Description
`coupons`	`string[] \| undefined`	Coupon codes the shopper applied
`promotions`	`Promotion[] \| undefined`	Promotions in effect

Promotion: id: string, name?: string, discountValue?: number (minor units), code?: string (the coupon that triggered it), trigger: "coupon" | "automatic", applied: boolean.

Totals

Field	Type	Description
`items`	`number`	Items subtotal
`shipping`	`number \| undefined`	Shipping
`tax`	`number \| undefined`	Tax
`discounts`	`number \| undefined`	Discounts
`giftCard`	`number \| undefined`	Gift cards applied
`interest`	`number \| undefined`	Interest from installments
`change`	`number \| undefined`	Change
`custom`	`{ id: string; label: string; value: number }[] \| undefined`	Extra totalizer lines from the platform. Display only
`total`	`number`	Grand total: items + shipping + tax + interest - discounts

TaxLine: { name: string; value: number }.

LocaleInfo

Field	Type	Description
`currency`	`string`	ISO 4217 code (e.g., “USD”, “BRL”)
`language`	`string`	Language code (e.g., “en”, “pt-BR”)
`country`	`string`	ISO 3166-1 alpha-3 code (e.g., “USA”, “BRA”)

User

Field	Type	Description
`id`	`string \| undefined`	The shopper’s user id, or the operator’s id
`role`	`"user" \| "operator"`	`"operator"` when a third party (support, telesales) is driving the checkout
`isGuest`	`boolean`	`true` when nobody is logged in

Usage Examples

Formatting amounts

Every amount is in minor units, so one helper built from session.locale serves every example below.

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

function useFormatCurrency() {
  const { session } = useCheckoutSession();
  const { currency, language } = session.locale;
  return (amount: number) =>
    new Intl.NumberFormat(language, { style: 'currency', currency }).format(amount / 100);
}

Checking if a session is ready for checkout

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

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

  if (!session.shipping?.addresses?.length) {
    return <p>Please add a shipping address</p>;
  }

  if (!session.payment?.selectedPayments?.length) {
    return <p>Please select a payment method</p>;
  }

  return <button type="button">Complete Purchase</button>;
}

Displaying cart totals

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

function CartSummary() {
  const { session } = useCheckoutSession();
  const { totals } = session;
  const format = useFormatCurrency();

  return (
    <div>
      <div>Items: {format(totals.items)}</div>
      {totals.shipping !== undefined && <div>Shipping: {format(totals.shipping)}</div>}
      {totals.discounts !== undefined && <div>Discounts: -{format(totals.discounts)}</div>}
      <div>Total: {format(totals.total)}</div>
    </div>
  );
}

Handling multi-package shipping

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

function ShippingPackages() {
  const { session } = useCheckoutSession();
  const packages = session.shipping?.packages ?? [];
  const format = useFormatCurrency();

  return (
    <div>
      <h2>Your Shipments</h2>
      {packages.map((pkg) => (
        <div key={pkg.id}>
          <div>Carrier: {pkg.carrier}</div>
          <div>Method: {pkg.method}</div>
          <div>Price: {format(pkg.price)}</div>
          {pkg.estimatedDeliveryDate
            ? <div>Arrives: {new Date(pkg.estimatedDeliveryDate).toLocaleDateString()}</div>
            : pkg.estimatedDeliveryTime && (
                <div>
                  Estimated delivery: {pkg.estimatedDeliveryTime.value} {pkg.estimatedDeliveryTime.unit}
                </div>
              )}
        </div>
      ))}
    </div>
  );
}

Reading the selected pickup point

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

function PickupPoint() {
  const { session } = useCheckoutSession();
  const pkg = session.shipping?.packages.find((p) => p.type === 'pick_up');
  const quote = session.shipping?.availableQuotes.find((q) => q.id === pkg?.id);

  if (!quote || quote.type !== 'pick_up') return null;

  return (
    <p>
      Pick up at {quote.pickUpInfo.name}, {quote.pickUpInfo.address.street}
    </p>
  );
}

useCheckoutSession: the hook that returns this type
useCheckoutAction: the inputs that change it
Checkout Order Types: the shape of the order placed from this session

Overview

Start Here

AI Coding Agents

Core Concepts

Customization

Ollie Studio

Functions

CLI Reference

Ollie SDK

Analytics & Scripts

Tools & Tips

Product updates

CheckoutSession Type

Structure Overview

CartItem

CustomerData

Addresses

Address

ShippingAddress

CustomerAddress

ShippingInfo

ShippingPackage

ShippingQuote

PaymentInfo

PaymentMethod

SelectedPayment

GiftCard

SavedCard

Campaign

Totals

LocaleInfo

User

Usage Examples

Formatting amounts

Checking if a session is ready for checkout

Displaying cart totals

Handling multi-package shipping

Reading the selected pickup point

​Structure Overview

​CartItem

​CustomerData

​Addresses

​Address

​ShippingAddress

​CustomerAddress

​ShippingInfo

​ShippingPackage

​ShippingQuote

​PaymentInfo

​PaymentMethod

​SelectedPayment

​GiftCard

​SavedCard

​Campaign

​Totals

​LocaleInfo

​User

​Usage Examples

​Formatting amounts

​Checking if a session is ready for checkout

​Displaying cart totals

​Handling multi-package shipping

​Reading the selected pickup point

​Related

Structure Overview

CartItem

CustomerData

Addresses

Address

ShippingAddress

CustomerAddress

ShippingInfo

ShippingPackage

ShippingQuote

PaymentInfo

PaymentMethod

SelectedPayment

GiftCard

SavedCard

Campaign

Totals

LocaleInfo

User

Usage Examples

Formatting amounts

Checking if a session is ready for checkout

Displaying cart totals

Handling multi-package shipping

Reading the selected pickup point

Related