CheckoutSession Type

​

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

​

cartItems

• 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

• 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

• 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

• selected: Whether this address is currently selected
• receiverName: Optional name of person receiving deliveries

​

shipping

• 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

• receiverName: Optional name of person receiving the package

​

Shipping Packages

• 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

• 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

• 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

• 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

• 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

• 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

• 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

• name: Name or code of the tax (e.g., “VAT”, “State Tax”)
• value: Amount of this tax in minor units

​

totals

• 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

• 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

​

extensions

​

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>
  );
}

​

Related 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