Guides

Quotes

B2B sales quotes: a buyer requests pricing, a rep builds and issues a revisioned proposal, and acceptance converts directly into a Throttle order with card, Net-N, or deposit + balance payment terms.

Status

Quotes are fully live — request → build → link → accept → pay
Build and issue quotes from the dashboard (Quotes in the app sidebar) or the API, and buyers view their quote at https://checkout.usethrottle.dev/q/{shareToken} — toggle optional lines, comment, request changes, decline, or accept. Accepting materializes a checkout session and converting it into a Throttle order happens automatically once payment succeeds. Lifecycle emails, expiry reminders + auto-expiration, a downloadable PDF, deposit-and-balance terms, and hosted RFQ intake forms are all live. Sales quotes are unrelated to shipping/tax quote tokens.

Core concepts

  • Quote — the negotiation record. Carries a Q-{seq} number, customer linkage, an optional buyer-supplied reference number (buyerReference), and one share token that will be the buyer's permanent link.
  • Revision — an immutable commercial snapshot. Exactly one working revision is editable at a time; issuing freezes it (issued) and supersedes the previous offer. Line items support optional upsells and per-line quantity locks (qtyEditable).
  • Payment terms — pay_in_full, net_terms (Net-1..365), or deposit_balance (deposit due at acceptance, the balance becomes a receivable). Deposit amounts are computed and frozen at issue time.
  • Lifecycle — draft → requested → under_review → proposed → accepted → converted, with revision_requested, declined, expired (re-issuable), and archived branches. Transitions are service-enforced. A buyer declines an issued quote from the link; a merchant declines a request it will not price with PATCH /api/v1/quotes/{id} { status: 'declined', declinedReason }, which emails the buyer the reason. An accepted quote the buyer has not paid can be reopened back to proposed.

Create and issue a quote

Requires an API key with the quotes:write scope (dashboard roles map to application:quotes:* permissions). Prices are integers in minor units.

Create a draft quote
curl -X POST https://api.usethrottle.dev/api/v1/quotes \
  -H "X-API-Key: sk_test_..." \
  -H "Content-Type: application/json" \
  -d '{
    "customerEmail": "buyer@example.com",
    "buyerReference": "PO-1042",
    "items": [
      { "name": "Widget (bulk)", "unitPrice": 1500, "quantity": 200 },
      { "name": "Install service", "unitPrice": 50000, "quantity": 1, "type": "service", "optional": true }
    ],
    "paymentTerms": { "mode": "net_terms", "netN": 30 },
    "expiresAt": "2026-08-15T00:00:00Z"
  }'
Issue it
# Freeze the working revision and propose it to the buyer.
curl -X POST https://api.usethrottle.dev/api/v1/quotes/{quoteId}/issue \
  -H "X-API-Key: sk_test_..." \
  -H "Content-Type: application/json" -d '{}'
# The response includes quote.shareToken — the buyer link is
# https://checkout.usethrottle.dev/q/{shareToken} (hosted page ships with the
# public-link release).

Editing after issue is explicit: POST /api/v1/quotes/{id}/revisions clones the issued revision into a new working revision; PATCH /api/v1/quotes/{id}/revisions/{revId} edits it; issuing again supersedes the prior offer at the same buyer link.

Request a quote from a cart

Cart → RFQ
# Turn an existing cart into a quote request without re-keying anything.
# The cart itself is unchanged.
curl -X POST https://api.usethrottle.dev/api/v1/carts/{cartId}/request-quote \
  -H "X-API-Key: sk_test_..." \
  -H "Content-Type: application/json" \
  -d '{ "buyerReference": "PO-1042", "note": "Need delivery by end of month" }'

Add to Quote on your storefront

For buyers who want to browse and collect several products before asking, @usethrottle/quotes ships a quote cart: a persisted list the buyer builds while moving around your site, submitted as one request. It needs no API key — the qrf_ form token is the authority, so it is safe in the browser.

Throttle stores no product catalog, so lines come from your own product data, the same way the shopping cart works. Quantities merge when the same SKU is added twice, and the cart survives page navigation.

Quote cart
import { useQuoteCart, useQuoteRequestForm } from '@usethrottle/quotes';

// An Add to Quote button on a product page. Throttle holds no catalog, so the
// line comes from your own product data — exactly like the shopping cart.
function AddToQuote({ product }) {
  const { add, count } = useQuoteCart();
  return (
    <button onClick={() => add({
      name: product.title,
      sku: product.sku,
      referenceId: product.id,
      quantity: 1,
    })}>
      Add to quote ({count})
    </button>
  );
}

// Anywhere else on the site, submit the accumulated lines as one request.
function SubmitQuoteRequest({ formToken }) {
  const { lines, cart, clear } = useQuoteCart();
  const { submit, submitting } = useQuoteRequestForm(formToken);
  return (
    <button
      disabled={submitting || lines.length === 0}
      onClick={async () => {
        await submit({ email: 'bea@example.com', items: cart.toRequestItems() });
        clear();
      }}
    >
      Request a quote for {lines.length} items
    </button>
  );
}

A buyer who already filled a normal cart can ask for a quote on it instead: pass cartId to POST /api/v1/quote-requests and its lines join the request. The cart is resolved inside the form's own application and environment, so an id from anywhere else is simply not found. Cart prices are recorded as the buyer's target, not as the quoted price — a cart is assembled in the browser, and this endpoint authenticates no one but the form.

Hosted request forms

For inbound RFQs without any integration, create a hosted intake form from the dashboard (Quotes → Request forms) or via POST /api/v1/quote-request-forms. The response reveals a qrf_ form token exactly once (hash-only stored — rotate to mint a new one); the buyer-facing form lives at https://checkout.usethrottle.dev/q/request/{formToken} . Submissions create-or-find the customer by email, open a requested quote (source request_form) with the buyer's free-text need as the first shared comment, and fire the same quote.requested webhook + rep notifications as every other intake path.

A request can carry line items, a written need, or both — at least one of the two. Items land on the quote's working revision unpriced, carrying the name, SKU, quantity, and per-line note the buyer supplied, so your rep prices an itemised sheet instead of transcribing prose. The hosted page renders item rows by default; set fields.lineItems: false for a prose-only form, or fields.targetPrice: true to let buyers name the price they are after.

The public form read (GET /api/v1/quote-request-forms/{token}/public) carries currency: the currency the quote will be created in, from the form or request, else the store's main currency. The hosted page shows the target-price input with that currency's symbol and decimals, and hides it when the response has no currency. It also carries tracking, the application's public analytics block (IDs and toggles, never secrets, null when it cannot be read), which the hosted page uses to load your GA4 tag and send generate_lead on submit.

Buyer amounts are an ask, never a price
targetUnitPrice is recorded against the line and shown to your rep while they price it, but it never becomes the quoted price. Everything on this endpoint arrives from a browser holding only a public form token, so treating any of it as pricing would let a buyer set what you charge.

Shipping address (optional). Set fields.shippingAddress: true to show an optional address section on the hosted form. The submission takes shippingAddress with addressLine1, addressLine2, city, stateProvince, postalCode and countryCode (ISO 3166-1 alpha-2). An all-blank address is ignored; a partly filled one without addressLine1, city and countryCode is 400 invalid_request, and retired names such as line1 are rejected with the canonical name. The address is stored on the quote as shippingAddress (your team can correct it, see “Shipping address” below) and prefilled into the checkout shipping step when the buyer accepts (they can still change it). It is added to the customer's address book only when the request created that customer — an existing customer's addresses are never changed by a public form.

Submit a request
# A quote request. Items, a written need, or both — one of the two is required.
# No API key: the qrf_ form token is the authority, so this is safe from a browser.
curl -X POST https://api.usethrottle.dev/api/v1/quote-requests \
  -H "Content-Type: application/json" \
  -d '{
    "formToken": "qrf_...",
    "email": "bea@example.com",
    "companyName": "Acme Industrial",
    "message": "Need delivery before October.",
    "items": [
      { "name": "Wide widget", "sku": "WW-40", "quantity": 400, "targetUnitPrice": 1200,
        "note": "Powder coated" },
      { "name": "Install service", "referenceId": "prod_88" }
    ],
    "formLoadedAt": 1754900000000
  }'
# Every line lands on the quote's working revision UNPRICED. targetUnitPrice is
# recorded as the buyer's ask and shown to your rep; it never sets what you quote.

Bot protection is always on: a honeypot field (trips return a success-shaped response without creating anything), a minimum-fill-time check, and per-IP rate limits. Set the form's fields.requireTurnstile flag to additionally require Cloudflare Turnstile.

Turnstile fails closed. If a form requires it and TURNSTILE_SECRET_KEY is not configured server-side, submissions are refused with 503 turnstile_not_configured rather than accepted unverified — a toggle that silently does nothing is worse than no toggle. Forms that do not require Turnstile are unaffected.

The buyer link

To host this experience on your own storefront instead of Throttle's page, see @usethrottle/quotes — buyer components, hooks, and an optional same-origin proxy.

Every quote gets one branded, tokenized link — revisions land at the same URL, and the link keeps working (read-only) after the quote is ordered. Buyers reach it at https://checkout.usethrottle.dev/q/{shareToken} — no account, no API key. The page shows the itemized offer with live recompute for optional lines, the revision history, a comment thread, and Request changes / Decline actions. Branding (logo, accent color, display name) comes from the application's environment settings, matching hosted checkout.

That host is configurable. Set checkoutLinkBaseUrl on the application and Throttle builds the buyer link against your domain instead — https://yourstore.com/q/{shareToken} — so you can serve the quote page yourself with @usethrottle/quotes. Leave it unset for Throttle-hosted. The same setting governs abandoned-cart recovery links.

  • GET /api/v1/quote-links/{shareToken} — the buyer-shaped read. Draft and archived quotes 404 (their link isn't active yet); internal notes, the working revision, and internal comments are never returned. customerEmail is the address the quote was sent to (null when none), the same one the quote PDF prints; a hosted page uses it to prefill the accept form.
  • POST …/view, …/comments, …/request-revision, …/decline — all public (no scope), rate-limited per IP and per token, and authenticated purely by possessing the token.
  • Rotate a leaked link with POST /api/v1/quotes/{id}/rotate-link — the old token 404s immediately.

Subscription lines

A quote line may carry recurring, with the same fields and rules as a cart subscription line. Its unitPrice is the per-period price per seat. The buyer page, the PDF and the emails split the totals into Due at acceptance (a free-trial line counts 0) and Recurring after.

POST /api/v1/quotes
{
  "customerEmail": "buyer@example.com",
  "items": [
    { "name": "Onboarding", "unitPrice": 90000, "quantity": 1, "type": "service" },
    { "name": "Team plan", "unitPrice": 4900, "quantity": 5,
      "recurring": { "plan": "team_monthly", "interval": "monthly" } },
    { "name": "Priority support", "unitPrice": 1500, "quantity": 1, "optional": true,
      "recurring": { "plan": "support_monthly", "interval": "monthly", "trialDays": 30 } }
  ],
  "paymentTerms": { "mode": "pay_in_full" }
}
// Due at acceptance: 90000 + 5 × 4900 (the trial line counts 0)
// Recurring after:   Team plan 24500 / month; Priority support 1500 / month after 30 days
  • A subscription line may be optional or quantity-editable. Quantity is seats, and an unticked optional line creates no subscription.
  • A quote line can also carry recurring.schedule, a custom installment schedule whose payments differ in amount and gap (same rules as on a cart line; unitPrice must equal schedule[0].amount). See Installment Plans. Quotes with a recurring line are card, pay-in-full only. The public link, GET /api/v1/quote-links/{shareToken}, returns the line's recurring.schedule rows too, and the buyer page lists every payment with its estimated date.
  • Subscription lines are allowed only on pay-in-full quotes, at most 10 per quote, both checked when the quote is issued.
  • A free-trial line cannot carry taxAmount or discountAmount ( 400 invalid_line_item).
  • A subscription line's unitPrice is what each renewal charges, including after a free trial, so it must be above 0 ( 400 invalid_line_item on create and on a revision edit). A one-time line may still be 0.
  • Paying the accepted quote creates one subscription per accepted line, in the same single capture as the rest of the quote, and quote.converted lists them in subscriptionIds. The subscriptions belong to the customer with the email of the buyer who accepted.

Catalog lines

When the Product Catalog extension is installed and active for the application and environment, quote lines can come from it. In the dashboard, type a name or SKU into a line's name field and pick a product. Through the API, send a line with only its sku. Either way the line is filled the same way and carries a catalog link. Without the extension, quotes work exactly as before.

SKU-only lines

A line with no name is SKU-only and must carry sku. Throttle looks the SKU up in the catalog and fills the name, description, image and price. The price is in the quote's currency, and it is the customer's price-group price when the quote's customer belongs to an enabled customer group. Throttle names the group in the signed lookup (customerGroup, only to installations holding customer_groups:read or :write); quotes are staff paths, so no buyer identity proof is needed. sku and referenceId are set to the SKU, and metadata.catalogLink records where the line came from. SKU-only lines work on POST /api/v1/quotes and PATCH /api/v1/quotes/{id}/revisions/{revId}, and can sit next to ordinary lines in the same request. A line with a name behaves exactly as it always has.

A quote with SKU-only lines
curl -X POST https://api.usethrottle.dev/api/v1/quotes \
  -H "X-API-Key: sk_test_..." \
  -H "Content-Type: application/json" \
  -d '{
    "customerId": "{customerId}",
    "currency": "USD",
    "items": [
      { "sku": "QCQ-COFFEE-1KG-FL", "quantity": 10 },
      { "sku": "QCQ-KETTLE", "quantity": 2, "unitPrice": 5900 },
      { "sku": "QCQ-COFFEE-1KG-FL", "recurring": { "interval": "monthly" } },
      { "name": "Barista training", "unitPrice": 25000, "type": "service" }
    ]
  }'
# items[0] to items[2] have no name, so the Product Catalog fills them, priced
# in USD for this customer (here a customer in no price group). The unitPrice
# on items[1] overrides the catalog price. items[3] is an ordinary line.
The first line, as stored
{
  "sku": "QCQ-COFFEE-1KG-FL",
  "referenceId": "QCQ-COFFEE-1KG-FL",
  "name": "House Coffee — 1kg, Filter",
  "description": "Medium roast house blend, roasted weekly.",
  "unitPrice": 4800,
  "quantity": 10,
  "priceSource": "catalog",
  "position": 0,
  "metadata": {
    "catalogLink": {
      "installationId": "{installationId}",
      "productHandle": "qcq-coffee",
      "sku": "QCQ-COFFEE-1KG-FL",
      "priceMinor": 4800,
      "currency": "USD",
      "customerId": "{customerId}",
      "minQuantity": null,
      "maxQuantity": null
    }
  }
}

The recurring line from the same request (items[2]) is stored with "recurring": { "plan": "QCQ-COFFEE-1KG-FL:monthly", "interval": "monthly" }.

  • A SKU-only line may also send quantity, unitPrice, description, optional, qtyEditable, position, recurring, imageUrl and metadata (merged with what the catalog fills). type, referenceId, taxAmount, discountAmount and priceSource are refused on it with 400 validation_error.
  • A unitPrice you send wins over the catalog price. The line is stored with priceSource: "override", unless the price you send equals the catalog price, in which case it is stored as catalog. It also lets a SKU with no price in the quote's currency through.
  • For a catalog-linked line (one carrying metadata.catalogLink), Throttle sets priceSource itself and ignores the value you send: catalog when the price equals the linked catalog price, otherwise override. A catalogLink that is malformed, or whose sku is not the line's sku, is 400 invalid_line_item.
  • The product's catalog tax code is copied into metadata.taxCategory only when the application shows the line Tax code field (app-based tax with an active Avalara connection), and only when you did not send a taxCategory yourself.
  • Out-of-stock products and minimum or maximum quantities do not block a quote line; the same SKU may appear on several lines.

Generated plan IDs

On a catalog-linked line, recurring.plan is optional. When you leave it out, Throttle names the plan <sku>:<cadence>, the same ID the dashboard generates. A plan you send is kept as typed. Every other recurring line still needs a plan (400 validation_error naming items[i].recurring.plan).

  • The cadence uses its canonical name: interval: "monthly" gives QCQ-COFFEE-1KG-FL:monthly, and every 2 weeks (intervalUnit: "week", intervalCount: 2) gives :biweekly; likewise every 1 month gives :monthly, every 3 months :quarterly, every 12 months :yearly.
  • A cadence with no canonical name keeps its count and unit: every 5 weeks gives :every-5-week.
  • A custom installment schedule gives :schedule-<payments>, for example :schedule-3.

Missing prices

In the dashboard, a product with no price in the quote's currency can still be picked. The line is saved with unitPrice: 0 and metadata.priceMissing: true, and shows “Needs a price”. Typing a price clears the flag. Issuing a quote that still has such a line is refused with 422 quote_price_missing, and error.details.lines lists each one as { position, name }, where position is the line's stored, 0-based position. Through the API, a SKU-only line without a price answers price_missing_for_currency instead (below) unless you send unitPrice.

Changing the currency

PATCH /api/v1/quotes/{id} accepts currency (stored uppercased) until the quote's first revision is issued. After that it answers 409 quote_currency_locked, because the buyer has seen prices in the old currency: create a new quote instead. The currency must be one of the store's enabled currencies, else 422 currency_not_enabled (422 currency_not_supported for an unknown code, 422 currency_not_available_in_production where production does not accept it). Sending the current currency changes nothing. Changing it through the API does not re-price existing lines, catalog-linked ones included (the dashboard offers to re-price them; the API does not). A create without currency takes the store's main currency.

Changing the currency flags every typed amount (each item's price, the flat shipping amount and the deposit) for review, because the number was typed for the old currency. The flags are metadata.amountReview: { fromCurrency } on an item and { fromCurrency, fields, fieldFrom } on the revision. POST /api/v1/quotes/{id}/issue answers 422 quote_amounts_need_review with details.pending (each entry { kind: 'item', position, name }, { kind: 'shippingFlatAmount' } or { kind: 'depositAmount' }) until each is confirmed: an item by being sent again without the flag, the flat shipping amount by a save that carries shippingFlatAmount, the deposit by a save that carries paymentTerms. A client that rebuilds the items without their metadata therefore clears the item flags.

Shipping address

PATCH /api/v1/quotes/{id} accepts shippingAddress with the same fields as the request form (addressLine1, addressLine2, city, stateProvince, postalCode, countryCode). It replaces the whole address; null or an all-blank address clears it, and a partly filled one without addressLine1, city and countryCode is 400 invalid_request. Use it to add an address to a quote that came in without one, or to correct the buyer's. It is prefilled into checkout when the buyer accepts and the quote asks for a shipping address. It is not copied to the customer's address book.

Buyer view

Each item in the buyer link responses (GET /api/v1/quote-links/{shareToken} and the other quote-links answers) carries linkedSku: the SKU of a catalog-linked line, or null on any other line. The hosted quote page and the PDF print SKU <sku> under a linked line's name. Other lines look as they always have. Each item also carries referenceId (or null): the line reference the hosted page reports to GA4 as item_id, so it matches the server purchase.

Catalog line errors

A request with SKU-only lines either fills every one of them or writes nothing. When lines cannot be filled, the answer is one 422 whose error.code is the first failing line's code, and error.details.lines lists every failing line as { index, sku, code, message }, where index is the line's index in your items array.

Two lines that cannot be filled
# An EUR quote whose items[1] and items[2] cannot be filled. Nothing is written.
HTTP/1.1 422 Unprocessable Entity

{
  "error": {
    "code": "sku_not_found",
    "message": "items[1]: no catalog product has SKU QCQ-NOPE.",
    "details": {
      "lines": [
        { "index": 1, "sku": "QCQ-NOPE", "code": "sku_not_found",
          "message": "items[1]: no catalog product has SKU QCQ-NOPE." },
        { "index": 2, "sku": "QCQ-MUG", "code": "price_missing_for_currency",
          "message": "items[2]: QCQ-MUG has no price in EUR. Send unitPrice for this line." }
      ]
    }
  },
  "meta": { "requestId": "req_..." }
}
code status when
catalog_not_available 422 A SKU-only line was sent, but the Product Catalog is not installed and active in this environment. Send the line with its name and unitPrice instead.
sku_not_found 422 No active catalog variant has that SKU. Draft and archived products count as not found.
price_missing_for_currency 422 The variant has no price in the quote's currency, and the line sent no unitPrice.
currency_not_enabled 422 The quote's currency is not one of the environment's currencies (on a SKU-only fill, or a currency change). currency_not_supported and currency_not_available_in_production are also 422.
quote_amounts_need_review 422 POST /quotes/{id}/issue while an amount typed in another currency is unconfirmed. details.pending lists them.
catalog_unavailable 503 The Product Catalog did not answer. Nothing was written: retry, or send the lines with their name and unitPrice.
validation_error 400 A line with neither name nor sku; a SKU-only line with a field it may not send; a recurring line that is not catalog-linked and has no plan. When one line has several problems, do not rely on the order in which they are listed.
invalid_line_item 400 A malformed metadata.catalogLink, or one naming another SKU; metadata.priceMissing: true with a unitPrice other than 0, or on a recurring.schedule line.
quote_price_missing 422 Raised at issue: a line is still flagged as needing a price (above), or a line the buyer requested (metadata.requestedByBuyer) still has a unitPrice of 0. details.lines names each one.
quote_currency_locked 409 A currency change after the first revision was issued.

Quote catalog routes

The dashboard's line search uses three routes, also open to API keys. Each needs quotes:write (dashboard users need application:quotes:write), works in the caller's own application and environment, answers Cache-Control: no-store, and reports the time spent calling the catalog as Server-Timing: catalog;dur=<ms>. On search and lines, currency must be one of the environment's currencies (422 currency_not_enabled), customerId, when sent, must be a customer of the same environment (404 not_found), and a catalog that does not answer is 503 catalog_unavailable. Status takes no parameters and never calls the catalog.

  • GET /api/v1/quote-catalog/status answers { available }: whether the Product Catalog is installed and active here. It reads Throttle's own records and makes no catalog call.
  • GET /api/v1/quote-catalog/search?q=&currency=&customerId=&limit= searches active variants by exact SKU, SKU fragment or text (q 2–100 characters, limit 1–20, default 8). It answers { rows, installationId }, or { rows: [], available: false } when the catalog is not available. Each row carries the price for currency and customerId (priceMinor: null when there is none), priceKind, taxCode, stockStatus and the quantity limits.
  • POST /api/v1/quote-catalog/lines with { skus, currency, customerId? } (1–200 SKUs) answers { lines, installationId }: one entry per requested SKU, in request order, duplicates included, each { sku, ok: true, row } or { sku, ok: false, code: "NOT_FOUND" }. Without the catalog it answers 422 catalog_not_available.
Search the catalog
curl "https://api.usethrottle.dev/api/v1/quote-catalog/search?q=coffee&currency=USD&limit=1" \
  -H "X-API-Key: sk_test_..."

{
  "data": {
    "installationId": "{installationId}",
    "rows": [
      {
        "sku": "QCQ-COFFEE-1KG-FL",
        "variantId": "{variantId}",
        "productHandle": "qcq-coffee",
        "productTitle": "House Coffee",
        "name": "House Coffee — 1kg, Filter",
        "optionValues": ["1kg", "Filter"],
        "description": "Medium roast house blend, roasted weekly.",
        "imageUrl": null,
        "priceMinor": 4800,
        "currency": "USD",
        "priceKind": "list",
        "taxCode": "PF050101",
        "stockStatus": "in_stock",
        "minQuantity": null,
        "maxQuantity": null
      }
    ]
  }
}
# Without an installed, active Product Catalog: { "data": { "rows": [], "available": false } }

installationId is the catalog installation that answered. It is what a line's metadata.catalogLink.installationId holds when you build a linked line yourself. Products and their tax codes get into the catalog through the Catalog Push API or the catalog dashboard.

Accept a quote

Acceptance materializes the accepted revision into a cart and creates a checkout session — the buyer is redirected to checkoutUrl to pay by card or Net-N, whichever the quote's payment terms allow. Optional lines can be deselected and quantity-editable lines resized at acceptance time via itemSelections; locked lines and non-optional lines reject any attempt to change them ( invalid_item_selection). Re-accepting the same revision is idempotent — it returns the existing checkout session instead of creating a second one; accepting after the current revision has been superseded returns 409 revision_superseded.

Buyer accepts via the hosted link
# The buyer accepts straight from the hosted link — no account, no API key.
curl -X POST https://api.usethrottle.dev/api/v1/quote-links/{shareToken}/accept \
  -H "Content-Type: application/json" \
  -d '{
    "revisionId": "{the currently issued revision id}",
    "acceptedByName": "Bea Buyer",
    "acceptedByEmail": "bea@example.com",
    "itemSelections": [
      { "itemId": "{optional line id}", "selected": false }
    ]
  }'
# Response: { "data": { "quote": {...}, "checkoutUrl": "https://checkout.usethrottle.dev/s/..." } }
# Redirect the buyer to checkoutUrl to complete payment (card or Net-N,
# depending on the quote's payment terms).
Rep records a phone/email acceptance
# A rep records a phone/email acceptance on the merchant's behalf.
curl -X POST https://api.usethrottle.dev/api/v1/quotes/{quoteId}/accept \
  -H "X-API-Key: sk_test_..." \
  -H "Content-Type: application/json" \
  -d '{
    "revisionId": "{the currently issued revision id}",
    "acceptedByName": "Bea Buyer",
    "acceptedByEmail": "bea@example.com",
    "reason": "Verbal agreement over the phone"
  }'

Deposit + balance (deposit_balance terms): the buyer pays the deposit by card at acceptance — the checkout shows “Due today” as the deposit, frozen at issue time — and completion automatically creates a second net30 payment for the balance at Net- balanceNetN terms, issues the balance invoice, and drops it into Receivables aging. The order carries two payment rows (deposit captured, balance authorized) and its paymentStatus stays partially_paid until the balance is captured — record the balance payment with POST /api/v1/orders/{id}/capture when it settles. Item selections that would shrink the total to at or below the frozen deposit are rejected.

Shipping at checkout

A quote with shippingMode flat charges exactly shippingFlatAmount, and free charges nothing, whatever the store's own shipping setup says: the checkout does not offer other methods or re-price it. Tax is still calculated at checkout, on that shipping too where shipping is taxable. With checkout_calculated (and none) the checkout prices shipping from the store's setup, as for any cart.

Tax on a quote

A line's taxAmount is an estimate. The buyer's quote page and PDF label it Estimated tax, and the checkout recalculates the final tax with the store's tax provider from the address the buyer confirms. The dashboard quote builder fills it in from POST /api/v1/shipping-tax/quotes against the quote's ship-to. A quote whose lines carry no tax shows Calculated at checkout instead.

Which addresses the checkout asks for

Acceptance also decides which address steps the hosted checkout shows. By default Throttle derives them from the accepted lines: the shipping step appears when something on the quote actually ships (any line whose delivery method is a shipment or an in-person handover) or when the quote prices shipping at all (shippingMode other than none), or when the quote has a shippingAddress and a line's delivery is unknown (type: "custom", which is what request-form lines are), so the address is prefilled; the billing step is always on — a quote is a B2B document, and the payer's address is what the receipt, the invoice and any tax treatment are written against. A services-only or digital quote therefore no longer dead-ends its buyer at a shipping form. Deselecting an optional line at acceptance is taken into account — if the only shippable line is dropped, so is the shipping step.

Set collect on a working revision to override either flag. It is accepted on POST /api/v1/quotes and PATCH /api/v1/quotes/{id}/revisions/{revId}, is carried forward when a revision is cloned, and applies to the resumed checkout a buyer returns to after the session TTL as well.

Ask for neither address
# Override what the checkout asks for. Either flag may be omitted (leave it
# as it is) or sent as null (hand it back to the derived default).
curl -X PATCH https://api.usethrottle.dev/api/v1/quotes/{quoteId}/revisions/{revisionId} \
  -H "X-API-Key: sk_test_..." \
  -H "Content-Type: application/json" \
  -d '{ "collect": { "shippingAddress": false, "billingAddress": false } }'
# The same field is accepted on POST /api/v1/quotes.

Each revision in the quote detail payload reports both the stored override and the result: collectShipping / collectBilling are the raw columns (null = derive), collect is what the checkout will actually ask for, and collectDefault is what the derivation alone would produce — useful for labelling an “Auto” option in your own UI.

Payment terms are enforced, not advisory

A checkout session created from an accepted quote pins allowedMethods to what the terms permit, and completion rejects any other method with 422 payment_method_not_allowed. A pay_in_full quote cannot be settled as a Net-N receivable.

Negotiated Net-N also outranks the customer's standing default. If a quote is issued and accepted at Net-60, the invoice is Net-60 even when customers.net_n says otherwise: a signed term for one deal beats an account-level habit. The resolved value is snapshotted on payments.net_n with net_n_source = 'cart_override'.

Errors

code status when
revision_superseded 409 A newer revision was issued. The response details.currentRevisionId names the live one so the page can refresh itself.
quote_expired 410 The accepted revision is past its expiry.
invalid_item_selection 400 Locked-line quantity change, non-optional line deselected, unknown item id, or a deposit quote whose selection fell to or below the deposit.
accept_in_progress 409 A concurrent acceptance is materializing the cart and session. Retry shortly — one quote only ever produces one checkout.
payment_method_not_allowed 422 Completion attempted with a method the quote's terms exclude. details lists what the session accepts.
net_terms_not_configured 409 Raised at issue time: the application has no active Invoice Terms connector, so Net-N or deposit terms could never be invoiced. Connect Invoice Terms or switch the quote to pay in full.
too_many_subscriptions 422 Raised at issue: more than 10 subscription lines.
recurring_terms_unsupported 422 Raised at issue: subscription lines on a net-terms or deposit quote.
recurring_source_conflict 422 Raised at issue: the quote has subscription lines and also a legacy plan line (metadata.subscriptionLineItem: true). Remove one of the two. A quote made from a cart leaves the legacy plan line out when the cart also has subscription lines.

Reopen an accepted quote

POST /api/v1/quotes/{id}/reopen (scope quotes:write, empty body) takes back an accepted quote the buyer has not paid, for example when checkout can't find a shipping option or the terms need to change. It cancels the quote's checkout session, retires the cart made at acceptance, and returns the quote to proposed with the acceptance cleared. Start a new revision, edit it and issue it on the same buyer link; the buyer accepts again on a new checkout.

The acceptance is kept on the quote's timeline as a reopened event. Reopening sends no email and no webhook; issuing the new revision sends the usual ones. The response is the quote.

code status when
quote_not_reopenable 409 The quote is not accepted.
checkout_in_progress 409 The buyer is paying right now. Try again once the payment settles.
checkout_completed 409 The buyer has paid; the quote is converting to an order.

Emails, expiry, and PDF

  • Lifecycle emails — sent automatically, branded with the application's logo/color and from-address (same sender resolution as order emails). All templates are editable from the dashboard email-template editor.
    Moment Buyer Merchant team
    Quote request submitted customer.quote_request_received admin.quote_requested
    Quote issued customer.quote_proposed —
    Comment added customer.quote_comment_added admin.quote_comment_added
    Revision requested — admin.quote_revision_requested
    Accepted customer.quote_accepted admin.quote_accepted
    Declined — admin.quote_declined
    Expiring — a warning, before the date customer.quote_expiring (24h) admin.quote_expiring (48h)
    Expired — terminal, when it lapses customer.quote_expired admin.quote_expired

    Note the two expiry pairs: expiring warns ahead of the date so a rep can chase, expired reports the lapse. The names are one letter apart and are easy to confuse.

  • Who receives the merchant-team email — every merchant-team row in the table above, plus the expiry warnings below. By default that is every active workspace owner, workspace admin, and member granted this application. To send it somewhere else instead — a shared sales@ alias, or one rep — set the recipients per application and environment:
    Quote notification recipients
    # Read the current recipients
    curl https://api.usethrottle.dev/api/v1/applications/$APPLICATION_ID/quote-settings \
      -H "X-API-Key: $THROTTLE_SECRET_KEY"
    
    # Route quote email to a shared alias instead of the whole team
    curl -X PATCH https://api.usethrottle.dev/api/v1/applications/$APPLICATION_ID/quote-settings \
      -H "X-API-Key: $THROTTLE_SECRET_KEY" \
      -H "Content-Type: application/json" \
      -d '{"notificationEmails":["sales@yourcompany.com"]}'

    Up to 10 addresses; an address does not have to be a team member. A configured list replaces the default audience rather than adding to it, so include your own address if you still want the mail. An empty list restores the default. In-app notifications are unaffected — they always go to team members, since an alias has no dashboard account. Settings are per environment: your sandbox can route somewhere else entirely.

  • Active expiry — an hourly job warns the rep 48h before an unaccepted quote expires, warns the buyer at 24h, and flips proposed → expired once expiresAt passes (emitting quote.expired). Each reminder fires once per issued revision — re-issuing re-arms them. A buyer revisiting an expired link notifies the rep in-app (a high-intent re-engagement signal).
  • PDF — GET /api/v1/quote-links/{shareToken}/pdf responds with a 302 to a short-lived signed download URL (filename Q-1042-rev2.pdf). Rendered lazily from the frozen issued revision — never live pricing — and cached per revision; acceptance re-renders it with the acceptance stamp. The hosted page links to it.

Webhooks

Requires quotes:read. Payloads carry the quote plus the current revision; internal notes and internal comments are never included.

  • quote.requested — an RFQ is submitted (dashboard, API, or cart).
  • quote.proposed — a revision is issued to the buyer.
  • quote.viewed — the buyer opens the link. Throttled to one delivery per revision per 6 hours.
  • quote.comment_added — a shared comment from either party (internal comments never fire this).
  • quote.revision_requested — the buyer asks for changes instead of accepting.
  • quote.declined — the buyer declines, with an optional reason.
  • quote.accepted — the buyer accepts (or a rep records a phone/email acceptance) and checkout begins.
  • quote.converted — the accepted quote completes checkout and its order now exists. Payload includes orderId and subscriptionIds ([] when the quote had no subscription lines).
  • quote.expired — the expiry job flipped a proposed quote past its expiresAt to expired. Re-issue a new revision to reactivate the same link.