Skip to main content
The CheckoutSession is the core interface representing a checkout session in the Ollie Shop ecosystem. It contains all the necessary data to render and process a typical checkout flow, including cart items, customer information, shipping details, payment methods, and totals.

​
Structure Overview

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

​
Properties

​
id

Type: string
Description: A unique identifier for the checkout session. This is a platform-specific ID.

​
cartItems

Type: CartItem[]
Description: An array of items in the user’s cart. Each item contains pricing information, availability, and other product information. Each cart item includes:
  • id: Unique identifier for the cart item (e.g., SKU code)
  • sellerId: (Optional) Identifier for the marketplace seller providing the item
  • name: Display name of the item
  • price: Current (sale) price in minor units (e.g., cents)
  • originalPrice: Original (non-sale) price in minor units
  • quantity: Number of this item in the cart
  • available: Whether the item is in stock
  • index: Position index in the cart
  • image: URL for the item’s image
  • url: (Optional) URL to the product details
  • variantDetails: (Optional) Object containing variant information (e.g., color, size)

​
customer

Type: CustomerData (optional)
Description: Information about the customer for order fulfillment, which may include:
  • id: Platform’s unique identifier for the customer
  • email: Customer’s email address
  • firstName: Customer’s first name
  • lastName: Customer’s last name
  • document: Customer’s document or tax ID (e.g., CPF in Brazil)
  • phone: Customer’s phone number
  • addresses: List of customer’s addresses

​
Address

Type: Base address interface
Description: The core address structure used across the checkout system:
  • id: Optional unique identifier for saved addresses
  • type: Optional address type (“home”, “billing”, “work”, “pick_up”, “other”)
  • street: Optional street name
  • number: Optional street number
  • complement: Optional address complement/apartment number
  • reference: Optional delivery reference
  • neighborhood: Optional neighborhood or district
  • city: Optional city name
  • country: Required country code (e.g., “USA”, “BRA”)
  • stateOrProvince: Optional state or province
  • postalCode: Required postal code

​
CustomerAddress

Type: CustomerAddress extends Address
Description: Addresses associated with a customer account, with additional fields:
  • selected: Whether this address is currently selected
  • receiverName: Optional name of person receiving deliveries

​
shipping

Type: ShippingInfo (optional)
Description: Comprehensive shipping information including:
  • addresses: List of shipping addresses available for selection
  • packages: List of shipping packages the user has selected
  • availableQuotes: List of shipping options available for user selection
  • availableCountries: List of country codes available for shipping

​
ShippingAddress

Type: ShippingAddress extends Address
Description: Used specifically for shipping destinations, with additional field:
  • receiverName: Optional name of person receiving the package

​
Shipping Packages

Each ShippingPackage
contains:
  • id: Unique identifier for the shipping package
  • items: List of cart item indexes included in this package
  • carrier: Name of the shipping carrier (e.g., “FedEx”, “UPS”)
  • method: Carrier’s shipping method (e.g., “Standard”, “Express”)
  • estimatedDeliveryTime: Object containing:
    • value: Numerical value of the estimated delivery time
    • unit: Unit of time (e.g., “day”, “hour”, “week”) as Intl.RelativeTimeFormatUnit
  • price: Cost of shipping this package in minor units
  • addressId: ID of the shipping address for this package
  • type: Type of shipping: “delivery” or “pick_up”
  • storeName: Optional name of store for pickup packages
  • timeSlot: Optional time slot selection with:
    • id: Unique identifier for the time slot
    • originalPrice: Original price for this time slot
    • price: Current price for this time slot
    • startDate: Start date and time in ISO 8601 format
    • endDate: End date and time in ISO 8601 format

​
Shipping Quotes

Each ShippingQuote (as either DeliveryQuote or PickUpQuote) contains:
  • id: Unique identifier for the shipping quote
  • carrier: Name of the shipping carrier
  • name: Display name of the shipping method
  • estimatedDeliveryTime: Object containing:
    • value: Numerical value of the estimated delivery time
    • unit: Unit of time (e.g., “day”, “hour”, “week”) as Intl.RelativeTimeFormatUnit
  • availableItems: List of cart item indexes this quote applies to
  • price: Cost of this shipping option in minor units
  • timeSlots: Array of available delivery/pickup time slots, each containing:
    • id: Unique identifier for the time slot
    • originalPrice: Original price for this time slot
    • price: Current price for this time slot
    • startDate: Start date and time in ISO 8601 format
    • endDate: End date and time in ISO 8601 format
  • type: Either “delivery” or “pick_up”
  • For pickup quotes: additional pickUpInfo containing:
    • name: Name of the pickup location/store
    • address: Full address object containing all standard address fields

​
payment

Type: PaymentInfo (optional)
Description: Payment details including:
  • availableMethods: All payment methods available (credit card, PayPal, etc.)
  • selectedPayments: Payment method(s) selected by the user
  • total: Total amount to be paid

​
Payment Methods

Each PaymentMethod contains:
  • id: Unique identifier for the payment method
  • type: Payment method type (e.g., “credit_card”, “debit_card”, “paypal”)
  • name: Display name of the payment method (e.g., “Visa”, “PayPal”)
  • installments: Optional array of available payment installment options, each containing:
    • number: Number of installments (e.g., 1, 3, 6)
    • amount: Amount of each installment in minor units
    • total: Total amount across all installments in minor units
    • interestRate: Optional interest rate percentage for this installment plan

​
Selected Payments

Each SelectedPayment contains:
  • methodId: ID of the chosen payment method (matching PaymentMethod.id)
  • referenceValue: Base amount for this payment, typically the sub-total
  • total: Total amount being paid with this payment method in minor units
  • installments: Optional number of installments chosen for this payment

​
campaign

Type: Campaign (optional)
Description: Marketing or merchandising campaign information:
  • coupons: Array of coupon codes applied by the user
  • promotions: Array of promotions, each containing:
    • id: Unique identifier for the promotion
    • name: Optional display name or description
    • discountValue: Optional total discount amount in minor units

​
locale

Type: LocaleInfo
Description: Regional settings for the checkout:
  • currency: ISO 4217 currency code (e.g., “USD”, “BRL”)
  • language: Language code (e.g., “en”, “pt-BR”)
  • country: Country code in ISO 3166-1 alpha-3 format (e.g., “USA”, “BRA”)

​
taxes

Type: TaxLine[] (optional)
Description: Detailed breakdown of tax lines, each containing:
  • name: Name or code of the tax (e.g., “VAT”, “State Tax”)
  • value: Amount of this tax in minor units

​
totals

Type: Totals
Description: Comprehensive breakdown of order costs:
  • items: Total cost of items in the cart
  • shipping: (Optional) Total shipping cost
  • tax: (Optional) Total tax amount
  • discounts: (Optional) Total discount amount
  • interest: (Optional) Total interest amount (e.g., from installments)
  • total: Grand total for the checkout

​
user

Type: User
Description: Information about who is operating the checkout session:
  • id: Identifier for the user (customer ID or operator ID)
  • role: Role of the user:
    • "user": The end customer themselves
    • "operator": A third party acting on behalf of the customer
  • isGuest: Whether the user is not logged in

​
readOnly

Type: boolean
Description: Indicates if the checkout session is locked from further modification. This could occur when a user was identified but not logged in.

​
extensions

Type: Extensions (generic parameter, optional)
Description: An extension point where clients can add custom fields for platform-specific or business-specific needs.

​
Usage Examples

​
Checking if a session is valid for checkout

function CanProceedToCheckout() {
  const { session } = useCheckoutSession();
  
  // Check if we have the minimum required data
  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>Complete Purchase</button>;
}

​
Displaying cart totals

function CartSummary() {
  const { session } = useCheckoutSession();
  const { totals, locale } = session;
  
  return (
    <div>
      <div>Items: {formatCurrency(totals.items, locale.currency)}</div>
      {totals.shipping !== undefined && (
        <div>Shipping: {formatCurrency(totals.shipping, locale.currency)}</div>
      )}
      {totals.discounts !== undefined && (
        <div>Discounts: -{formatCurrency(totals.discounts, locale.currency)}</div>
      )}
      <div className="total">
        Total: {formatCurrency(totals.total, locale.currency)}
      </div>
    </div>
  );
}

​
Handling multi-package shipping

function ShippingPackages() {
  const { session } = useCheckoutSession();
  const packages = session.shipping?.packages || [];
  
  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: {formatCurrency(pkg.price, session.locale.currency)}</div>
          {pkg.estimatedDeliveryTime && (
            <div>
              Estimated delivery: {pkg.estimatedDeliveryTime.value} {pkg.estimatedDeliveryTime.unit}
            </div>
          )}
        </div>
      ))}
    </div>
  );
}
The CheckoutSession interface works with several other types:
  • CartItem - Information about items in the cart
  • CustomerData - Customer details
  • ShippingInfo - Shipping details and options
  • PaymentInfo - Payment methods and selections
  • Campaign - Promotions and coupons
  • LocaleInfo - Regional settings
  • Totals - Cost breakdown
  • User - Information about session operator