useCheckoutAction

The useCheckoutAction hook enables interactions with checkout actions in a type-safe manner, automatically updating the checkout session upon successful execution. The exceptions are REQUEST, SIMULATE_SESSION and CREATE_ORDER, whose results are not a session and leave it untouched.

Let your agent build it. The Ollie Shop skill ships with projects created by npx create-ollie-shop, so your assistant already knows every action type below and the input each one expects.

Prompt

Add an add-to-cart button to my checkout component.

Don’t have the skill yet? Install it.

Action Types

The hook supports various action types including:

ADD_ITEMS - Add items to the cart
REMOVE_ITEMS - Remove items from the cart
UPDATE_COUPONS - Update coupon codes
UPDATE_CUSTOMER_DETAILS - Update customer information
UPDATE_ITEMS_QUANTITY - Update quantities of items in the cart
UPDATE_SHIPPING_PACKAGES - Update shipping packages
UPDATE_SHIPPING_ADDRESSES - Update shipping addresses
UPDATE_PAYMENT_METHODS - Update payment methods
UPDATE_GIFT_CARDS - Apply or update gift cards
UPDATE_CUSTOMER_PREFERENCES - Update customer preferences (e.g. save data, locale)
SIMULATE_SESSION - Simulate a checkout session without mutating the real one
CREATE_ORDER - Create a new order
CREATE_NEW_SESSION - Discard the current cart and start a new session
REQUEST - Make custom API requests to the backend

Parameters

actionType: ActionType - The type of checkout action to perform (e.g., ADD_ITEMS, REMOVE_ITEMS, etc.)
callback?: object - Optional configuration callbacks
- onSuccess?: (data?: CheckoutSession, input?: Input) => void - Called when the action succeeds. Receives the updated session and the input that was executed. For CREATE_ORDER, data is the created order; cast it, since the generic type is CheckoutSession. For REQUEST it is the whole { data, raw } result of your request, typed as unknown
- onError?: ({ serverError, validationErrors }) => void - Called when action fails

Keep callbacks stable. Treat onSuccess and onError as fixed for the component’s lifetime: props or state you read inside them may be the values from the first render. Read changing values through a ref, or react to the result where it is already fresh: the session from useCheckoutSession after a success, or the error return value after a failure.

const latestCoupon = useRef(coupon);
latestCoupon.current = coupon;

const { execute } = useCheckoutAction('UPDATE_COUPONS', {
  onSuccess: () => console.log('applied', latestCoupon.current), // fresh
  // onSuccess: () => console.log('applied', coupon),            // stale after the first render
});

Return Value

Returns an object with:

execute: (input: Input) => void - Function to dispatch the action with the appropriate payload
executeAsync: (input: Input) => Promise<Result | undefined> - Async version of execute. The promise settles when the request finishes and resolves with the raw action result (see Using executeAsync). It resolves, rather than rejects, on server errors
isPending: boolean - Boolean indicating if the action is currently processing
error?: object - Error information if the action failed. Check it right after a failed call; it is not reset by a later success
- serverError?: ServerError - Error returned by the server
- validationErrors?: ValidatorErrors<Input> - Input Validation errors

Actions other than CREATE_ORDER are retried on transient network errors before onError fires.

Input Parameters by Action Type

Each action type expects specific input parameters. Below are the details for each:

Navigate the tabs to see details of each action

ADD_ITEMS

type CartItemInput = {
  id: string;         // SKU id on your commerce platform (the `id` a cart item carries)
  quantity: number;   // Quantity to add
  sellerId?: string;  // Seller to add from, as in a cart item's `seller.id`. Omit for the default seller
};

// Usage
execute([{ id: "product123", quantity: 2 }]);

REMOVE_ITEMS

type RemoveItemsInput = number[];  // Array of item indexes to remove

// Usage
execute([0, 2]);  // Removes first and third items

UPDATE_COUPONS

type CouponsInput = string[];  // Array of coupon codes

// Usage
execute(["SUMMER10", "FREESHIP"]);

UPDATE_CUSTOMER_DETAILS

type CustomerDetailsInput = Partial<CustomerData>; // every field optional
// {
//   email?: string;
//   firstName?: string;
//   lastName?: string;
//   phone?: string;
//   document?: string;
//   company?: { ... };
//   addresses?: CustomerAddress[];
//   ...
// }

// Usage
execute({
  email: "customer@example.com",
  firstName: "John",
  lastName: "Doe"
});

UPDATE_ITEMS_QUANTITY

type UpdateQuantityInput = {
  index: number;    // Item index in the cart
  quantity: number; // New quantity
}[];

// Usage
execute([
  { index: 0, quantity: 3 },
  { index: 1, quantity: 1 }
]);

UPDATE_SHIPPING_PACKAGES

type ShippingPackageInput = {
  id: string | null;  // Quote id (`ShippingQuote.id`) to put the items on, or null to leave them unrouted
  items: number[];    // Array of cart item indexes
  addressId?: string; // Optional shipping address ID
  selectedTimeSlotId?: string; // Optional time slot ID for delivery
  type?: "delivery" | "pickup" | "digital"; // Optional, defaults to the quote's type
};

// Usage
execute([
  { 
    id: "standard-delivery", 
    items: [0, 1, 2],
    addressId: "home-address" 
  }
]);

// A package with `id: null` still has to be sent: that is how a platform
// clears a selection. Leaving an item out of the update means "leave it where it is".

UPDATE_SHIPPING_ADDRESSES

// Every field is optional: send what changed and the platform merges it.
type ShippingAddressInput = {
  id?: string;              // Saved address id, when updating one the customer already has
  type?: "home" | "billing" | "work" | "pick_up" | "search" | "other";
  postalCode?: string;
  country?: string;         // 3-letter code, e.g. "USA", "BRA"
  street?: string;
  number?: string;
  complement?: string;
  reference?: string;
  neighborhood?: string;
  city?: string;
  stateOrProvince?: string;
  geoCoordinates?: number[]; // [longitude, latitude]
  receiverName?: string;
};

// Usage
execute([
  {
    postalCode: "10001",
    country: "USA",
    street: "Main St",
    number: "123",
    city: "New York",
    stateOrProvince: "NY"
  }
]);

UPDATE_PAYMENT_METHODS

type PaymentMethodInput = {
  methodId: string;      // Payment method ID
  referenceValue: number; // Amount this payment covers, in the session's minor units (cents)
  installments?: number;  // Optional installments count
  accountId?: string;     // Optional saved card / account id for this method
};

// Usage
execute([
  {
    methodId: "credit-card",
    referenceValue: 9999,
    installments: 3
  }
]);

UPDATE_GIFT_CARDS

type GiftCardInput = {
  code?: string | null;    // Redemption code. null or omitted when targeting a special card by id
  provider?: string;
  id?: string;             // Platform id of an existing card (special cards have no code)
  value?: number;          // Amount to apply, in minor units. Omit to let the platform decide
  isSpecialCard?: boolean; // Marks a loyalty / cashback card that is attached automatically
};

// Usage: redeem a code
execute([{ code: "GIFT-1234" }]);

// Usage: apply part of a loyalty balance
execute([{ id: "loyalty-1", value: 1500, isSpecialCard: true }]);

UPDATE_CUSTOMER_PREFERENCES

type CustomerPreferencesInput = {
  saveData?: boolean; // Remember the customer's data for the next purchase
  locale?: string;    // e.g. "en-US"
};

// Usage
execute({ saveData: true });

SIMULATE_SESSION

Runs a checkout simulation and resolves with the resulting session without touching the real one. The input is a partial session: cartItems is required, shipping and payment are optional.

type SimulateCheckoutSessionInput = {
  cartItems: { id: string; quantity: number; sellerId?: string }[];
  shipping?: { packages: { id: string; items: number[] }[] /* ...other shipping fields */ };
  payment?: { selectedPayments: { methodId: string; referenceValue: number }[] };
  // ...any other CheckoutSession field, all optional
};

// Usage
execute({ cartItems: [{ id: "product123", quantity: 1 }] });

Read the result in onSuccess; the session in useCheckoutSession does not change.

CREATE_ORDER

type CreateOrderInput = {
  isGuest?: boolean;       // Whether to create a guest order
  captchaToken?: string;   // Optional captcha token for validation
  saveCardOptin?: boolean; // Whether the shopper agreed to save the card
  tags?: string[];         // Optional tags attached to the order
};

// Usage
execute({
  isGuest: true
});

Dispatching CREATE_ORDER here creates the order on the platform but does not submit the payment. The templates’ place-order button runs both steps; use it, or gate it with useNavigation, instead of recreating the flow in a custom component.

CREATE_NEW_SESSION

Discards the current cart and starts a fresh session. It takes no meaningful input.

// Usage
execute(undefined);

REQUEST

Makes custom API requests to the backend. Unlike other actions, this action does not automatically update the checkout session.

type RequestActionInput = {
  url: string;                      // The API endpoint URL
  method?: string;                  // HTTP method (GET, POST, etc.). Defaults to GET
  headers?: Record<string, string>; // Optional custom headers
  body?: string;                    // Optional request body (for POST/PUT requests)
  revalidate?: boolean;             // If true, revalidates the checkout session after request
};

// Usage - GET request
execute({
  url: "https://example.com/api/custom-endpoint"
});

// Usage - POST request with body
execute({
  url: "https://example.com/api/custom-endpoint",
  method: "POST",
  headers: { "Content-Type": "application/json" },
  body: JSON.stringify({ key: "value" }),
  revalidate: true
});

Use the revalidate option to refresh the session after making changes.

Example

Import

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

Usage

const { execute, executeAsync, isPending, error } = useCheckoutAction(
  actionType,
  {
    onSuccess: (data) => {
      // Handle success
    },
    onError: ({ serverError, validationErrors }) => {
      // Handle errors
    }
  }
);

// Execute the action (fire and forget)
execute({
  // Input specific to the action type
});

// Or use executeAsync to await the result
const result = await executeAsync({
  // Input specific to the action type
});

Action

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

function AddToCartButton({ productId, quantity }) {
  const { execute, isPending } = useCheckoutAction('ADD_ITEMS', {
    onSuccess: () => {
      console.log('Item added successfully');
    },
    onError: ({ serverError }) => {
      console.error('Failed to add item', serverError?.message);
    }
  });

  return (
    <button
      onClick={() => execute([{ id: productId, quantity }])}
      disabled={isPending}
    >
      {isPending ? 'Adding...' : 'Add to Cart'}
    </button>
  );
}

Using executeAsync

executeAsync is useful when you need to wait for an action before doing something else. It resolves with the raw action result, typed as unknown, so narrow it before reading it. The result is { data?: { data, raw }, serverError?, validationErrors? }, where data.data is the updated session and data.raw is the platform’s response.

import { useCheckoutAction } from '@ollie-shop/sdk';
import type { CheckoutSession, ServerError } from '@ollie-shop/sdk';

type ActionResult = {
  data?: { data: CheckoutSession; raw: unknown };
  serverError?: ServerError;
};

function AddToCartButton({ productId, quantity }: { productId: string; quantity: number }) {
  const { executeAsync, isPending } = useCheckoutAction('ADD_ITEMS');

  const handleAddToCart = async () => {
    const result = (await executeAsync([{ id: productId, quantity }])) as ActionResult | undefined;

    if (result?.serverError) {
      console.error('Failed to add item', result.serverError.message);
      return;
    }

    if (result?.data) {
      console.log('Cart now has', result.data.data.cartItems.length, 'items');
    }
  };

  return (
    <button onClick={handleAddToCart} disabled={isPending}>
      {isPending ? 'Adding...' : 'Add to Cart'}
    </button>
  );
}

The promise resolves as soon as the request finishes. The session in useCheckoutSession is updated right after, so prefer onSuccess or the session itself when you only need the new state.

Overview

Start Here

AI Coding Agents

Core Concepts

Customization

Ollie Studio

Functions

CLI Reference

Ollie SDK

Analytics & Scripts

Tools & Tips

Product updates

Action Types

Parameters

Return Value

Input Parameters by Action Type

ADD_ITEMS

REMOVE_ITEMS

UPDATE_COUPONS

UPDATE_CUSTOMER_DETAILS

UPDATE_ITEMS_QUANTITY

UPDATE_SHIPPING_PACKAGES

UPDATE_SHIPPING_ADDRESSES

UPDATE_PAYMENT_METHODS

UPDATE_GIFT_CARDS

UPDATE_CUSTOMER_PREFERENCES

SIMULATE_SESSION

CREATE_ORDER

CREATE_NEW_SESSION

REQUEST

Example

Import

Usage

Action

Using executeAsync

​Action Types

​Parameters

​Return Value

​Input Parameters by Action Type

​ADD_ITEMS

​

​REMOVE_ITEMS

​

​UPDATE_COUPONS

​

​UPDATE_CUSTOMER_DETAILS

​

​UPDATE_ITEMS_QUANTITY

​UPDATE_SHIPPING_PACKAGES

​

​UPDATE_SHIPPING_ADDRESSES

​

​UPDATE_PAYMENT_METHODS

​UPDATE_GIFT_CARDS

​UPDATE_CUSTOMER_PREFERENCES

​SIMULATE_SESSION

​CREATE_ORDER

​CREATE_NEW_SESSION

​REQUEST

​Example

​Import

​Usage

​Action

​Using executeAsync

Action Types

Parameters

Return Value

Input Parameters by Action Type

ADD_ITEMS

REMOVE_ITEMS

UPDATE_COUPONS

UPDATE_CUSTOMER_DETAILS

UPDATE_ITEMS_QUANTITY

UPDATE_SHIPPING_PACKAGES

UPDATE_SHIPPING_ADDRESSES

UPDATE_PAYMENT_METHODS

UPDATE_GIFT_CARDS

UPDATE_CUSTOMER_PREFERENCES

SIMULATE_SESSION

CREATE_ORDER

CREATE_NEW_SESSION

REQUEST

Example

Import

Usage

Action

Using executeAsync