Cart and checkout

import { createCatalogClient } from '@usethrottle/catalog';

const catalog = createCatalogClient({
  publishableKey: 'pc_pk_your_browser_key',
});

// SKUs and quantities only: the catalog prices every line itself.
const cart = await catalog.carts.create({
  items: [
    { sku: 'BRK-PAD-01', quantity: 2 },
    { sku: 'BRK-FLUID-1L', quantity: 1 },
  ],
  currency: 'USD',
  // Optional. Each one is an https URL on a website listed in
  // Checkout settings › Allowed return websites.
  returnUrl: 'https://shop.example.com/order-complete', // after payment
  cancelUrl: 'https://shop.example.com/cart', // the checkout's cancel link
  storefrontUrl: 'https://shop.example.com/shop', // "Continue shopping"
});

// Present only when you sent a URL. false: Throttle did not store them, so
// the shopper ends on Throttle's own completion page. The cart still works.
if (cart.returnUrlApplied === false) {
  console.warn('Return URLs were not applied to this cart.');
}

console.log(cart.cart.subtotalMinor, cart.cart.currency, cart.expiresAt);

// Throttle's hosted cart page.
location.assign(cart.cartUrl);

import { createCatalogClient } from '@usethrottle/catalog';

const catalog = createCatalogClient({
  publishableKey: 'pc_pk_your_browser_key',
});

const { sessionId } = await catalog.carts.create({
  items: [{ sku: 'BRK-PAD-01', quantity: 1 }],
});

// Throttle's cart-session routes. The session id is the only credential:
// no catalog key and no customer token go with these calls.
const session = catalog.carts.session(sessionId);

const added = await session.add({ sku: 'BRK-FLUID-1L', quantity: 2 });
const line = added.cart.lineItems?.find((item) => item.referenceId === 'BRK-FLUID-1L');
if (line) await session.update(line.id, 3);

const { cart } = await session.get();
console.log(cart.lineItems, cart.subtotal, cart.currency);

// Throttle prices every line again at the hand-off. checkout() answers the
// checkout URL and never navigates. keepOpen keeps the cart alive for a
// shopper who cancels.
const { checkoutUrl } = await session.checkout({
  returnUrl: 'https://shop.example.com/order-complete',
  cancelUrl: 'https://shop.example.com/cart',
  keepOpen: true,
});
location.assign(checkoutUrl);

'use client';
import { useCart } from '@usethrottle/catalog/react';

// Inside a <CatalogProvider> with cartUrls. Every useCart under one provider
// shares one cart, and its changes run one at a time, in order.
export function AddToCart({ sku }: { sku: string }) {
  const { add, pending } = useCart();
  // The first add creates the cart; later adds go to Throttle's cart session.
  return (
    <button disabled={pending} onClick={() => void add(sku, 1).catch(() => {})}>
      Add to cart
    </button>
  );
}

export function CartPage() {
  const { cart, cartUrl, status, error, pending, update, remove, checkout, switchCurrency } =
    useCart({ currency: 'USD' });

  if (status === 'loading') return <p>Loading your cart…</p>;
  if (cart === null) return <p>Your cart is empty.</p>;

  const goToCheckout = async () => {
    // Uses the provider's cartUrls. It answers the URL and never navigates.
    const { checkoutUrl } = await checkout();
    location.assign(checkoutUrl);
  };

  return (
    <section aria-busy={pending}>
      {error?.code === 'cart_prices_changed' ? (
        <p>Some prices changed. Check your cart, then check out again.</p>
      ) : null}
      <ul>
        {cart.lineItems?.map((line) => (
          <li key={line.id}>
            {line.name} × {line.quantity}
            <button onClick={() => void update(line.id, line.quantity + 1).catch(() => {})}>
              +
            </button>
            <button onClick={() => void remove(line.id).catch(() => {})}>Remove</button>
          </li>
        ))}
      </ul>
      <p>
        {cart.unitCount} items, {cart.subtotal} {cart.currency} (minor units)
      </p>
      {/* A new cart with the same lines, priced in EUR (BC4). */}
      <button onClick={() => void switchCurrency('EUR').catch(() => {})}>Pay in EUR</button>
      <button disabled={pending} onClick={() => void goToCheckout().catch(() => {})}>
        Checkout
      </button>
      {/* Or Throttle's hosted cart page, which has its own checkout button. */}
      {cartUrl ? <a href={cartUrl}>Open the hosted cart</a> : null}
    </section>
  );
}

'use client';
import { useEffect, useRef } from 'react';
import { useAuth } from '@usethrottle/auth/react';
import { useCart } from '@usethrottle/catalog/react';

// Inside both providers. When a signed-out shopper with a cart signs in,
// attach the cart to their account: Throttle moves the lines of their older
// open cart into this one (the resolved cart wins) and prices every line for
// them. A session restored on page load is not a sign-in and claims nothing.
export function ClaimCartOnSignIn() {
  const { status, account } = useAuth();
  const { cart, refresh } = useCart();
  const cartId = cart?.cartId ?? null;
  const previous = useRef(status);

  useEffect(() => {
    const was = previous.current;
    previous.current = status;
    if (was !== 'unauthenticated' || status !== 'authenticated') return;
    if (cartId === null) return;
    void account
      .claimCart(cartId)
      .then(() => refresh()) // show the merged lines at the shopper's prices
      .catch(() => undefined); // a failed claim never blocks the sign-in
  }, [status, cartId, account, refresh]);

  return null;
}

import {
  CartLineError,
  createCatalogClient,
  isCatalogError,
  type CartLineProblem,
} from '@usethrottle/catalog';

const catalog = createCatalogClient({
  publishableKey: 'pc_pk_your_browser_key',
});

declare function showLineProblem(problem: CartLineProblem): void;

try {
  const cart = await catalog.carts.create({
    items: [{ sku: 'BRK-PAD-01', quantity: 12 }],
    returnUrl: 'https://shop.example.com/order-complete',
  });
  location.assign(cart.cartUrl);
} catch (error) {
  if (error instanceof CartLineError) {
    // CART_ITEMS_INVALID: one entry per refused line, with its own code.
    // QUANTITY_UNAVAILABLE carries maxQuantity, which can be 0.
    for (const problem of error.lines) showLineProblem(problem);
  } else if (isCatalogError(error) && error.code === 'RETURN_URL_NOT_ALLOWED') {
    // One issue per refused field: returnUrl, cancelUrl or storefrontUrl.
    console.error(error.issues.map((issue) => issue.path));
  } else if (isCatalogError(error) && error.retryable) {
    // CART_UNAVAILABLE, STOREFRONT_UNAVAILABLE or a 429: try again later.
    console.warn(`Try again in ${error.retryAfterSeconds ?? 10} s`);
  } else {
    // CART_CURRENCY_*, CHECKOUT_NOT_CONFIGURED, EXTENSION_UPGRADE_REQUIRED,
    // CART_REJECTED: the store needs fixing; nothing the shopper can do.
    throw error;
  }
}

import {
  CartLineError,
  createCatalogClient,
  isCatalogError,
  type ThrottleCart,
} from '@usethrottle/catalog';

const catalog = createCatalogClient({
  publishableKey: 'pc_pk_your_browser_key',
});

declare const sessionId: string;
declare function showCart(cart: ThrottleCart): void;
declare function startNewCart(): Promise<void>;

const session = catalog.carts.session(sessionId);

try {
  const { checkoutUrl } = await session.checkout({
    returnUrl: 'https://shop.example.com/order-complete',
    cancelUrl: 'https://shop.example.com/cart',
    keepOpen: true,
  });
  location.assign(checkoutUrl);
} catch (error) {
  if (error instanceof CartLineError) {
    // quantity_unavailable or line_not_purchasable: lines[] says which.
    console.error(error.lines);
  } else if (isCatalogError(error) && error.code === 'cart_prices_changed') {
    // Throttle repriced the cart. Show the new prices; the next checkout
    // goes through when nothing changed again.
    const { cart } = (error.details ?? {}) as { cart?: ThrottleCart };
    if (cart) showCart(cart);
  } else if (isCatalogError(error) && error.code === 'cart_session_expired') {
    // The session ended. details.storefrontUrl is passed on unchecked: never
    // render it as a link or navigate to it without your own check.
    await startNewCart();
  } else {
    throw error;
  }
}