@usethrottle/cart

Typed Node.js REST client for the Throttle Cart API.

Install

npm install @usethrottle/cart

Quickstart

End-to-end: create a cart, build it out, and convert it to an order.

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

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

// 1. Create a cart
const cart = await client.carts.create({
  storeId: 'store_abc',
  currency: 'USD',
  netN: 45,
});

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

// 3. Select a shipping method
await client.shipping.select(cart.id, {
  methodId: 'fedex_ground',
  displayName: 'FedEx Ground',
  rateAmount: 599,
});

// 4. Apply a discount code
await client.discounts.apply(cart.id, 'SAVE10');

// 5. Set tax lines
await client.taxLines.set(cart.id, [
  { lineItemId: '...', jurisdictionCode: 'US-NY', taxType: 'sales', rate: 0.04, amount: 400 },
]);

// 6. Checkout → Order
const order = await client.carts.checkout(cart.id, { paymentMethod: 'card' });
console.log(order.id, order.status);

applicationId is accepted as an alias for storeId when your integration already uses the newer application naming.

All monetary values are integers in the smallest currency unit (cents for USD).

Net-N invoice terms

Cart-level invoice terms are optional. Pass netN on cart create or update to set the cart override, or null to clear it. The final invoice term is resolved when the buyer completes checkout with Invoice Terms:

customer.netN ?? cart.netN ?? DEFAULT_NET_N

allowedMethods only controls which payment methods can appear in checkout; it does not change the Net-N day count. For hosted/embed checkout, create a cart with netN and then create a checkout session for that cart.

Shipping and tax

Use the secret-key client on your backend to calculate and persist cart totals with Throttle's native engine:

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

const locked = await client.shippingTax.calculateCart(cart.id, {
  kind: 'checkout_final',
  selectedShippingMethodId: estimate.shipping.selectedMethod?.id,
});

External stores can also request read-only storefront quotes with a publishable pk_ quote token. Create one from the dashboard Shipping & Tax page or with POST /api/v1/shipping-tax/quote-tokens.

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

const quotes = new StorefrontQuoteClient({
  applicationId: 'application_uuid',
  quoteToken: 'pk_publishable_quote_token',
});

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' },
  },
});

For provider-owned totals, set the store to byo mode on the shipping or tax axis (or both) and push the final snapshot through /api/v1/shipping-tax/external-snapshots. Throttle accepts external pushes when at least one axis is in byo mode:

await client.shippingTax.pushExternalSnapshot({
  storeId: 'store_uuid',
  cartId: cart.id,
  currency: 'USD',
  totals: {
    subtotal: 12900,
    discountTotal: 0,
    shippingTotal: 600,
    taxTotal: 1215,
    total: 14715,
  },
});

Subscriptions

Pass type: 'subscription' and a recurring block on the line item:

await client.items.add(cart.id, {
  type: 'subscription',
  name: 'Pro Plan',
  unitPrice: 1900,
  quantity: 1,
  recurring: { interval: 'month', count: null }, // count: null = until cancelled
});

Then call client.carts.checkout as normal. Set count to a number to cap the billing cycles.

Events

Every mutation appends an immutable event to the cart's event log. Fetch it with:

const events = await client.events.list(cart.id);
// [{ eventType: 'cart.created', sequence: 1, ... }, ...]

// Poll only new events since the last sequence you saw
const newEvents = await client.events.list(cart.id, { sinceSequence: 5, limit: 50 });

For real-time delivery, subscribe to Throttle's outbound webhooks from your merchant dashboard. Webhooks are signed with HMAC-SHA256 and fire from Throttle's servers to your backend over HTTPS.

Errors

All non-2xx responses throw ThrottleApiError. Inspect code for the machine-readable reason and statusCode for the HTTP status:

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

try {
  await client.discounts.apply(cart.id, 'EXPIRED');
} catch (e) {
  if (e instanceof ThrottleApiError && e.code === 'discount_invalid') {
    // surface a user-friendly message
  }
  if (e instanceof ThrottleApiError) {
    console.error(e.statusCode, e.code, e.message);
  }
}

Client options

| Option | Default | Description | | ----------- | ----------------------------- | ----------------------------------------------------------- | | apiKey | — | Required. Your Throttle secret key (sk_…). | | baseUrl | https://api.usethrottle.dev | Optional override for a dedicated Throttle API environment. | | timeoutMs | 30000 | Per-request abort timeout in ms. | | fetch | globalThis.fetch | Custom fetch implementation (e.g. node-fetch). |

See also

• Checkout SDK: @usethrottle/checkout-sdk
• React embed components: @usethrottle/checkout-react