Validate a cart snapshot

cartSnapshot contains merchant-defined JSON. sessions.retrieve() returns it as a JsonObject. Use sessions.retrieveTyped() when you want runtime validation and a typed cart property.

Define a cart schema

The server SDK accepts a Zod-style schema with a parse method or a plain validator function. The SDK does not require a validation library.

This schema matches the cart created in the Stripe setup guide:

type CheckoutCart = {
  currency: string;
  lineItems: Array<{
    amountMinor: number;
    name: string;
    offerId: string;
    quantity: number;
  }>;
};

const checkoutCartSchema = {
  parse(value: unknown): CheckoutCart {
    if (typeof value !== "object" || value === null) {
      throw new Error("Cart must be an object.");
    }

    const cart = value as { currency?: unknown; lineItems?: unknown };
    if (
      typeof cart.currency !== "string" ||
      !Array.isArray(cart.lineItems) ||
      cart.lineItems.some(
        (item) =>
          typeof item !== "object" ||
          item === null ||
          typeof item.name !== "string" ||
          typeof item.offerId !== "string" ||
          !Number.isInteger(item.amountMinor) ||
          item.amountMinor < 0 ||
          !Number.isInteger(item.quantity) ||
          item.quantity < 1,
      )
    ) {
      throw new Error("Cart does not match the checkout cart shape.");
    }

    return cart as CheckoutCart;
  },
};

Retrieve a typed cart

Pass the schema to sessions.retrieveTyped() in place of sessions.retrieve():

const session = await proxy.sessions.retrieveTyped(
  proxySessionId,
  checkoutCartSchema,
);

session.cart.currency;
session.cart.lineItems;

The result contains the normal merchant session fields plus cart, typed as CheckoutCart.

If validation fails, the SDK throws ProxyCheckoutValidationError with code: "cart_invalid" and field: "cart_snapshot". The error’s cause contains the schema or validator error.