Native carts

Build Cart State That Checkout Can Trust

Use @usethrottle/cart when Throttle owns the cart, totals, and checkout handoff for your store.

Create the cart

Start with storeId and currency. Keep cart operations on your backend.

Add commerce state

Add items, apply discounts, select shipping, and calculate tax before checkout.

Lock totals for checkout

Run checkout_final calculation when the buyer commits to shipping and payment.

Convert to order

Call checkout to create the order and continue payment through Throttle.

End-to-end cart flow

The cart client wraps the native cart endpoints and throws ThrottleApiError for non-2xx responses.

Install

npm install @usethrottle/cart

Cart quickstart

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

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

const cart = await client.carts.create({
  storeId: 'store_123',
  currency: 'USD',
});

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

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

const quote = await client.shippingTax.calculateCart(cart.id, {
  kind: 'cart_estimate',
});

const order = await client.carts.checkout(cart.id, {
  paymentMethod: 'card',
});

Shipping and tax

Use cart calculation from your backend when a cart already exists in Throttle. Use storefront quote tokens for read-only estimates before checkout.

Storefront quote

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

const quotes = new StorefrontQuoteClient({
  storeId: 'store_123',
  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',
    },
  },
});

Quote tokens are publishable

Quote tokens start with pk_ and are scoped by store and allowed origin. They can estimate totals, but they cannot mutate carts or create orders.

Native cart endpoints

Create

POST /api/v1/carts

Add item

POST /api/v1/carts/{id}/items

Apply discount

POST /api/v1/carts/{id}/apply-discount

Select shipping

POST /api/v1/carts/{id}/shipping

Set tax lines

PUT /api/v1/carts/{id}/tax-lines

Checkout

POST /api/v1/carts/{id}/checkout