> ## 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.

# CheckoutSession Type

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**

```typescript theme={"system"}
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](http://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**

```typescript theme={"system"}
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**

```typescript theme={"system"}
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**

```typescript theme={"system"}
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**

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