Build Cart State That Checkout Can Trust

npm install @usethrottle/cart

// PREREQUISITES (Step 0 in /developers/quickstart):
//   1. Sign in to the dashboard. A default Application is auto-created for you.
//      Copy its UUID (App settings -> Identifiers) into THROTTLE_APPLICATION_ID.
//   2. In Embed Config, add your storefront origin (e.g. http://localhost:3000)
//      to allowedOrigins. The PaymentEmbed will render "Embed not authorized" until you do.
//   3. Generate a server-side secret key (for example sk_uat_* or sk_live_*)
//      from API Keys and put it in THROTTLE_API_KEY.
import { CartClient } from '@usethrottle/cart';

const client = new CartClient({
  apiKey: process.env.THROTTLE_API_KEY!,
});

const cart = await client.carts.create({
  applicationId: process.env.THROTTLE_APPLICATION_ID!, // uuid from Step 0.1
  currency: 'USD',
});

await client.items.add(cart.id, {
  type: 'product',
  name: 'Premium Widget',
  unitPrice: 2999, // minor units (cents)
  quantity: 2,
});

await client.discounts.apply(cart.id, 'SAVE10');

// Pass the address inline to set the destination AND get rates in one call
// (it is persisted to the cart) — no separate carts.update needed.
const quote = await client.shippingTax.calculateCart(cart.id, {
  kind: 'cart_estimate',
  shippingAddress: { countryCode: 'US', postalCode: '94107', stateProvince: 'CA' },
});

// /carts/{id}/checkout creates a DRAFT ORDER from the cart. It does NOT
// create a checkout session by itself. To render the payment embed, mint
// a checkout session afterwards (see /developers/embedded-checkout).
const order = await client.carts.checkout(cart.id, {
  paymentMethod: 'card',
});

import { StorefrontQuoteClient } from '@usethrottle/cart';

const quotes = new StorefrontQuoteClient({
  applicationId: 'e7efb0a6-892e-46b2-97ab-296bb04c5b29',
  quoteToken: 'pk_publishable_quote_token',
  origin: 'https://shop.example.com',
});

const estimate = await quotes.quote({
  currency: 'USD',
  items: [
    {
      id: 'sku_123',
      quantity: 1,
      subtotalAmount: 12900,
      requiresShipping: true,
      taxCategory: 'standard',
    },
  ],
  addresses: {
    shipping: {
      countryCode: 'US',
      stateProvince: 'CA',
      postalCode: '90001',
    },
  },
});

// Selecting a shipping method is ONE call. The response is the full cart with
// shipping, tax, and total already recomputed — no separate calculate-before or
// recalculate-after, and no need to keep your own copy of the totals.
const cart = await client.shipping.select(cartId, {
  methodId: 'standard',
  displayName: 'Standard (3-5 days)',
  rateAmount: 799,
});
cart.selectedShipping; // { methodId, displayName, rateAmount, currency, ... }
cart.shippingTotal;    // 799
cart.taxTotal;         // recomputed
cart.total;            // recomputed
// GET /carts/{id} returns the same authoritative shape any time you need it:
const fresh = await client.carts.get(cartId);
fresh.selectedShipping; // bind your UI directly to this — it never drifts.

// One canonical address shape (CartAddress). Required: addressLine1, city,
// countryCode (ISO-3166-1 alpha-2). Validated at write time.
await client.carts.update(cartId, {
  shippingAddress: {
    firstName: 'Ada',
    addressLine1: '1 Market St',
    addressLine2: 'Suite 400',
    city: 'San Francisco',
    stateProvince: 'CA',
    postalCode: '94105',
    countryCode: 'US',
  },
});
// ❌ line1 / state / country / zip are rejected with a did-you-mean hint —
//    they are NOT silently stored.