Promotion codes

Discounts for Cart-Backed Checkout

Throttle supports percentage and fixed amount promotion codes. The payment processor does not validate or calculate codes; Throttle computes the discounted cart total before checkout hands the final amount to payment.

1

Create a discount

Use the dashboard or API to create a percentage or fixed amount discount code.

2

Preview in your storefront

Call /api/v1/discounts/preview from your server when the buyer enters a code.

3

Apply to a cart

When checkout starts, apply the valid code to the Throttle cart before creating the checkout session.

4

Lock totals

Run shipping/tax calculation and checkout_final against the discounted cart before payment.

Supported types

Percentage off

type: "percentage", with value: 25 for 25% off.

Fixed amount off

type: "fixed_amount", with value: 500 for $5.00 off in minor units.

Removed discount types
Free shipping and buy-X-get-Y are no longer active product surfaces. Existing historical rows may remain inactive, but new code should only create percentage or fixed amount discounts.

Use the SDK

@usethrottle/discounts is a server-side, headless SDK. It does not ship a coupon input UI; your checkout owns that field.

Install
npm install @usethrottle/discounts
Preview and apply
import { DiscountsClient } from '@usethrottle/discounts';

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

const preview = await discounts.preview({
  code: 'SUMMER25',
  currency: 'USD',
  subtotal: 10000,
  customerId,
});

if (preview.valid) {
  await discounts.applyToCart('cart_123', preview.code);
}

Preview without mutation

Use preview when the buyer types a code in your order summary. It returns the discount amount and total without creating or changing a cart. Include a customer ID when you want the preview to check the customer redemption limit.

POST /discounts/preview
const res = await fetch(`${process.env.THROTTLE_API_URL}/api/v1/discounts/preview`, {
  method: 'POST',
  headers: {
    'x-api-key': process.env.THROTTLE_API_KEY!,
    'content-type': 'application/json',
  },
  body: JSON.stringify({
    code: 'SUMMER25',
    currency: 'USD',
    subtotal: 10000,
    customerId: '00000000-0000-0000-0000-000000000000',
  }),
});

const { data } = await res.json();
// data.valid, data.discountTotal, data.total, data.message

When a code has a minimum order total and the order is under it, the validate and preview responses add minimum (the code's minimum in the order's currency) and shortfall (how much more the order needs to reach it). Both are money values: { amount, currency, display }, where amount is in minor units and display is the formatted string, for example €12.50. They are absent when the order meets the minimum. A cart that applies such a code answers discount_invalid with the same minimum and shortfall in details. Format amount and currency with formatMoney from @usethrottle/money; see Showing money.

Customer limits

New discounts default to one redemption per customer. Set maxRedemptionsPerCustomer to another positive integer for repeat use, or null for unlimited customer redemptions. Usage is recorded when a discounted cart becomes an order.

One code per cart
A cart can hold one applied code. Applying a valid new code replaces the previous one; invalid replacement attempts leave the existing code unchanged.

Limit a code to customer groups

Send customerGroupIds (0 to 50 group ids) on create or update to make a code usable only by members of those groups. It needs the customer_groups:read scope (otherwise 403 insufficient_scopes); an unknown group answers 422 customer_group_not_found. Empty or absent means everyone; on update, absent keeps the groups and [] clears them. Responses carry customerGroupLimited, and customerGroupIds for callers with the scope.

  • The group check runs before every other check. A buyer who is not eligible gets the same Discount code not found answer an unknown code gets, so the code stays hidden. The staff validate and preview routes answer the same way.
  • Eligibility needs a customer on the cart, membership of an enabled named group, and proven identity. See Identity proof.
  • Eligibility is judged again on every recalculation, including at checkout. A code whose customer, group or expiry no longer qualifies is dropped silently and totals are recalculated without it.
  • A group that a discount names cannot be deleted (409 customer_group_in_use).

Exclude products from a code

Send conditions.excludedProductIds on create or update to list line identifiers a code never applies to, for example gift card SKUs. Entries match lines the same way conditions.productIds does: the line id, referenceId, sku, productId, variantId, or the same keys in line metadata, trimmed and case-insensitive.

A percentage code that skips gift cards
curl -X POST https://api.usethrottle.dev/api/v1/discounts \
  -H "X-API-Key: sk_live_xxx" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "20% off, not gift cards",
    "code": "SPRING20",
    "type": "percentage",
    "value": 20,
    "conditions": { "excludedProductIds": ["GIFT-25", "GIFT-50"] }
  }'
  • An exclusion wins. A line listed in both productIds and excludedProductIds gets no discount. A code with exclusions and no productIds applies to every other line.
  • A percentage code takes its percentage of the remaining lines only; a fixed-amount code is capped at their total. If every line is excluded, the code computes to 0.
  • Up to 500 strings of up to 200 characters. Blank and duplicate entries are dropped; anything else is 400 validation_error naming the field. On update, an empty array removes the list. Like every conditions write, the object you send replaces the stored one, so send the other keys you want to keep.
  • The order's metadata.discountScope records the exclusions with the product scope, so a line added to the order later is judged by the rule it was placed under.
  • Exclusions are identifiers, not products. In the dashboard, picking a Product Catalog product adds the SKUs of its variants; a variant added to the product later is not excluded until you add it.

List and search codes

GET /api/v1/discounts uses cursor pagination and accepts q, type, isActive, code, and sort filters. Use meta.pagination.cursor for the next page until hasMore is false.

Cart and order records

Applied coupons are visible on cart reads and are preserved on the order snapshot. A cart response includes appliedDiscount with the code, discount ID, type, amount, currency, validity, and snapshot hash. When the cart becomes an order, the order stores discountId, discountCode, and metadata.appliedDiscount.

Calculated tax is charged on the price after the code: a cart-wide code lowers every line's taxable amount in proportion, and a code limited to certain products lowers only those lines. Native tax, the Avalara quote and the filed Avalara document agree, and the stateless quote nets its discountsTotal the same way. A tax rule set to tax before discounts still taxes the full price. An order with a discount carries metadata.taxDiscountBasis: "net_of_cart_code"; editing its line items re-taxes it the same way. Orders placed before this behaviour shipped have no such key and keep the tax basis they were placed on when edited. The key is managed by Throttle, so do not set or remove it yourself.

The lines a code applied to are recorded on the order when it is placed, as metadata.discountScope (the code, its type and value, its product scope and excluded products, and the order line ids it reduced). Editing the order's line items and the filed Avalara document read that record, not the discount as it is now: narrowing, widening, re-pricing or deleting a code after an order was placed does not change that order's tax. A line added by an edit shares the code when the recorded product scope covers it. Orders placed before this record existed read the live discount, as before. Throttle manages this key too: a value you send is ignored.

Redemption timing
Global and per-customer usage counts are recorded when the discounted cart is converted to an order. Preview does not mutate usage. Apply validates customer limits when the cart has a customer ID.

Payment flow

Throttle applies discounts before payment. The payment processor receives the final amount to authorize or capture; it does not receive a coupon code to validate.

sequenceDiagram
  participant B as Browser
  participant M as Merchant Backend
  participant T as Throttle API
  participant C as Checkout Iframe
  B->>M: buyer enters SUMMER25
  M->>T: POST /api/v1/discounts/preview
  T-->>M: valid + discountTotal + total
  M-->>B: show adjusted order summary
  B->>M: buyer starts checkout
  M->>T: POST /api/v1/carts/{id}/apply-discount
  M->>T: POST /api/v1/checkout/sessions
  M-->>B: sessionId
  B->>C: render checkout
  C->>T: complete payment with discounted total
Discount preview, cart apply, and checkout handoff.

Metadata

Discounts accept arbitrary JSON metadata for campaign IDs, channels, attribution, or merchant notes. Metadata is stored with the discount and returned by the REST API, GraphQL API, and SDK.

Discount metadata
await discounts.create({
  code: 'SUMMER25',
  name: 'Summer 25% off',
  type: 'percentage',
  value: 25,
  maxRedemptionsPerCustomer: 1,
  metadata: {
    campaign: 'summer-2026',
    channel: 'email',
  },
});

const discount = await discounts.get('disc_xxx');
// discount.metadata.campaign === 'summer-2026'

Apply to checkout

Cart application is the authoritative step. Apply the code to a native Throttle cart before you create or render the checkout session.

Cart mutation
// Server-side only. Never expose your sk_ key in the browser.
import { createDiscountsClient } from '@usethrottle/discounts';

const discounts = createDiscountsClient({
  apiKey: process.env.THROTTLE_API_KEY!,
});

await discounts.applyToCart(cartId, 'SUMMER25');

// Remove the active code:
await discounts.removeFromCart(cartId);
Storefront pattern
// Storefront checkout pattern
// 1. Buyer enters code in your order summary.
// 2. Your server previews it without mutating a cart.
const preview = await discounts.preview({ code, currency: 'USD', subtotal, customerId });

// 3. If valid, include the code when your server creates the Throttle cart.
const cart = await cartClient.carts.create({ applicationId, currency: 'USD' });
await Promise.all(items.map((item) => cartClient.items.add(cart.id, item)));
await discounts.applyToCart(cart.id, preview.code);

// 4. Create the checkout session using the discounted cart id.
await checkout.createSession({ applicationId, cartId: cart.id, returnUrl, cancelUrl });

Pre-applying at session create

POST /api/v1/checkout/sessions accepts a top-level discountCode: string field. When provided, Throttle validates the code synchronously against the session's cart and applies it before returning. The response cart total reflects the discount.

Pre-apply at session create
curl -X POST https://api.usethrottle.dev/api/v1/checkout/sessions \
  -H "X-API-Key: sk_live_xxx" \
  -H "Content-Type: application/json" \
  -d '{
    "applicationId": "e7efb0a6-892e-46b2-97ab-296bb04c5b29",
    "externalCartId": "cart_abc",
    "amount": 2999,
    "currency": "USD",
    "discountCode": "FRIEND10"
  }'
Validation is synchronous
An invalid or expired code returns 422 discount_invalid. The session is not created. Your storefront should call /api/v1/discounts/preview first if you want to surface the error inline, then retry the session create with the validated code (or omit it). The preview endpoint computes the discounted total without mutating any cart or session.

Discounts in more than one currency

A discount carries its amounts per currency in amounts, keyed by currency code, in minor units. value is the fixed amount (fixed-amount codes only) and minOrder is the minimum order total.

A fixed-amount code in USD and EUR
curl -X POST https://api.usethrottle.dev/api/v1/discounts \
  -H "X-API-Key: sk_live_xxx" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Welcome 9",
    "code": "WELCOME9",
    "type": "fixed_amount",
    "amounts": {
      "USD": { "value": 1000, "minOrder": 5000 },
      "EUR": { "value": 900,  "minOrder": 4500 }
    }
  }'
  • No entry means not offered. Throttle never converts. A code with no entry for the order's currency answers 422 discount_currency_unsupported ("This code can't be used for orders in GBP.") on every cart kind, and validate returns it as code.
  • Percentage codes with no minimum anywhere keep amounts: {} and work in every currency. A minimum in one currency makes the other currencies need an entry.
  • Legacy writes mean the main currency. value and conditions.minOrder without amounts set the main-currency entry. When both are sent they must agree. A write whose amounts lacks the main currency answers 400 with the path amounts.<MAIN> (or amounts.<MAIN>.minOrder, conditions.minOrder). The minimum applies to fixed-amount codes too.
  • POST /api/v1/discounts/validate and /preview take an optional currency; it defaults to the store's main currency.

Current boundaries

  • Promotion codes work on cart-backed checkout totals.
  • Discounts are order-level cart reductions, not item-level discounts.
  • Only one coupon can be attached to a cart; this is enforced by the API and database.
  • External/provider-owned carts must apply discounts upstream in the provider.
  • Recurring subscription discounts are not part of this v1 surface.
  • Keep secret API keys on your backend; browsers should call your server.
Related guides
Continue with Cart API for native carts and Embedded Checkout for the iframe handoff.