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
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
workingrevision is editable at a time; issuing freezes it (issued) and supersedes the previous offer. Line items supportoptionalupsells and per-line quantity locks (qtyEditable). - Payment terms —
pay_in_full,net_terms(Net-1..365), ordeposit_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, withrevision_requested,declined,expired(re-issuable), andarchivedbranches. Transitions are service-enforced. A buyer declines an issued quote from the link; a merchant declines a request it will not price withPATCH /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 toproposed.
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.
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"
}' # 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
# 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.
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.
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.
# 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.customerEmailis 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.
{
"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;unitPricemust equalschedule[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'srecurring.schedulerows 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
taxAmountordiscountAmount(400 invalid_line_item). -
A subscription line's
unitPriceis what each renewal charges, including after a free trial, so it must be above 0 (400 invalid_line_itemon 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.convertedlists them insubscriptionIds. 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.
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. {
"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,imageUrlandmetadata(merged with what the catalog fills).type,referenceId,taxAmount,discountAmountandpriceSourceare refused on it with400 validation_error. -
A
unitPriceyou send wins over the catalog price. The line is stored withpriceSource: "override", unless the price you send equals the catalog price, in which case it is stored ascatalog. It also lets a SKU with no price in the quote's currency through. -
For a catalog-linked line (one carrying
metadata.catalogLink), Throttle setspriceSourceitself and ignores the value you send:catalogwhen the price equals the linked catalog price, otherwiseoverride. AcatalogLinkthat is malformed, or whoseskuis not the line'ssku, is400 invalid_line_item. -
The product's catalog tax code is copied into
metadata.taxCategoryonly when the application shows the line Tax code field (app-based tax with an active Avalara connection), and only when you did not send ataxCategoryyourself. - 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"givesQCQ-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
schedulegives: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.
# 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/statusanswers{ 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=¤cy=&customerId=&limit=searches active variants by exact SKU, SKU fragment or text (q2–100 characters,limit1–20, default 8). It answers{ rows, installationId }, or{ rows: [], available: false }when the catalog is not available. Each row carries the price forcurrencyandcustomerId(priceMinor: nullwhen there is none),priceKind,taxCode,stockStatusand the quantity limits. -
POST /api/v1/quote-catalog/lineswith{ 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 answers422 catalog_not_available.
curl "https://api.usethrottle.dev/api/v1/quote-catalog/search?q=coffee¤cy=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.
# 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). # 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.
# 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_receivedadmin.quote_requestedQuote issued customer.quote_proposed— Comment added customer.quote_comment_addedadmin.quote_comment_addedRevision requested — admin.quote_revision_requestedAccepted customer.quote_acceptedadmin.quote_acceptedDeclined — admin.quote_declinedExpiring — a warning, before the date customer.quote_expiring(24h)admin.quote_expiring(48h)Expired — terminal, when it lapses customer.quote_expiredadmin.quote_expiredNote 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 → expiredonceexpiresAtpasses (emittingquote.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}/pdfresponds with a 302 to a short-lived signed download URL (filenameQ-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 includesorderIdandsubscriptionIds([]when the quote had no subscription lines). -
quote.expired— the expiry job flipped a proposed quote past itsexpiresAtto expired. Re-issue a new revision to reactivate the same link.