API Surface by Integration Task

Use this for payment-only provider proxy mode when your application owns cart, shipping, and order summary UI. The response returns a Throttle session id plus hosted and embedded URLs.

curl -X POST https://api.usethrottle.dev/api/v1/checkout-sessions/embed-token \
  -H "x-api-key: $THROTTLE_API_KEY" \
  -H "content-type: application/json" \
  -d '{
    "amount": 2599,
    "currency": "USD",
    "country": "US",
    "externalCartId": "cart_123"
  }'

Use this when Throttle owns or can reference the cart that should become an order. This is the preferred session creation path for native carts, subscriptions, collect flags, and full checkout.

curl -X POST https://api.usethrottle.dev/api/v1/checkout/sessions \
  -H "x-api-key: $THROTTLE_API_KEY" \
  -H "content-type: application/json" \
  -d '{
    "applicationId": "00000000-0000-0000-0000-000000000000",
    "cartId": "11111111-1111-1111-1111-111111111111",
    "returnUrl": "https://shop.example.com/thank-you",
    "cancelUrl": "https://shop.example.com/cart",
    "allowedMethods": ["card", "net30"],
    "paymentTerms": { "netN": 45 },
    "collect": { "shippingAddress": true, "billingAddress": true }
  }'

The hosted checkout app calls this without a merchant API key so buyers can load or reload a checkout after the original embed JWT expires.

The iframe uses this to decide which payment method tiles to show. The server checks connector eligibility and then applies the session allowedMethods filter.

Called by the hosted iframe after the buyer submits payment. The session id scopes the operation; your backend should listen for webhooks rather than calling this directly.

Start here when Throttle should own cart state before checkout. Create the cart from your backend, then add items and calculate totals before converting it to an order.

Read the current cart, including totals, line items, selected shipping, tax lines, and applied discount state.

Patch the customer id, addresses, notes, or metadata on an open native cart.

Use this for products, services, tickets, donations, custom items, and subscription line items before checkout.

Patch quantity, price, tax, discount, or metadata for an existing cart line item.

Deletes a line item from an open native cart.

Persist the buyer-selected shipping option before final checkout. Use the id returned from shipping/tax calculation when possible.

Use when the buyer changes address, shipping is no longer required, or the selected method is no longer available.

Use this when you bring your own tax calculation and need to persist the final line-level tax breakdown on a native cart.

Remove persisted tax lines when the cart address changes, the tax mode changes, or you need to recompute taxes from scratch.

Validates a code and writes the active applied discount snapshot onto the cart. A cart can have one active code; applying a new valid code replaces the old one.

Clears the applied discount snapshot and returns the cart without an active promotion code.

Call after items, discount, shipping, and final tax calculation are ready. This creates the order that payment and fulfillment workflows use.

Use cart events for polling/debugging cart mutations. For real-time delivery, subscribe to outbound webhooks.

Carts that the sweep flagged abandoned, newest first. Cursor-paginated. A cart becomes abandoned after the per-app idle threshold (see embed-config `cartAbandonmentThresholdMinutes`) or once it passes its expiry.

Headline counts for the abandoned-carts dashboard over a trailing window.

Use when your application is in bring-your-own shipping or tax mode and an upstream provider owns the final totals.

Creates a percentage or fixed amount discount code for later preview and cart application.

Use for promotion management screens, campaign reconciliation, or validating which codes exist before checkout.

Patch campaign metadata, active windows, usage limits, or the display name for an existing discount.

Removes a discount from future use. Existing orders keep their historical discount snapshot.

Call while the buyer types a code in your storefront. Preview returns the computed discount and final total without changing cart or usage counts.

Use setup tooling or advanced dashboards to show the active shipping/tax modes and catalog for an application.

Reports whether the application is calculating tax through a connected provider, from the published shipping/tax config and the active provider connection for the request’s environment. Fails closed: with no published config or no active connection every flag is false and taxMode is off. Requires the shipping_tax:read scope.

Use during setup to audit active quote tokens. Raw token values are not returned after creation.

Quote tokens start with qt_ (tokens minted before this change start with pk_ and remain valid indefinitely) and let a storefront request read-only estimates without exposing a secret key.

Soft-deletes and deactivates a qt_ (or legacy pk_) token so storefront quote requests using it stop working.

Use from the browser or your backend for read-only estimates. Accepts either a quoteToken (qt_, or legacy pk_) validated against application id, expiry, and allowed origin, or an X-API-Key (sk_/pk_) carrying shipping_quotes:write — in which case applicationId and environmentId must match the key.

Use this from your backend when a Throttle cart exists. Persist checkout_final totals before cart checkout so payment receives locked totals. Pass shippingAddress/billingAddress inline to set the destination and calculate in one request — they are persisted to the cart before calculation, so a separate PATCH /carts/{id} is not required. Unknown fields are rejected with a 400 validation_error.

Add, update (quantity/unitPrice), or remove line items and recompute the order total. On a captured order the total delta is settled automatically: an increase charges the customer’s stored card for the difference; a decrease refunds it (capped at the captured amount). Draft/pending orders edit freely with no money movement. Terminal orders (cancelled/refunded/voided) reject.

Use for order history, reconciliation, and merchant-side operations dashboards.

Use for order detail pages, reconciliation, fulfillment handoff, and support tooling.

Moves an order to any status in the lifecycle vocabulary, in either direction. Unlike the automatic transitions the engine applies, this accepts any target — a merchant correcting a mis-shipped order needs to move it back. Side effects already applied (captured payments, sent emails, shipped fulfillments) are never rewound; the status label changes, the history records who changed it and why.

Append-only audit trail, oldest first. Each row carries fromStatus, toStatus, actorType (user | system | integration), actorId, reason, and source (manual | state_machine | fulfillment | payment | migration).

Cash at the counter, a bank transfer to the merchant's own account, a cheque. The payment is created already captured, so the order advances exactly as a processor capture would — paymentStatus rolls up, fulfillment unblocks, receipts send. No processor is contacted and no card is charged. A draft order is placed by the recording, so cash against an order created through the API needs no separate checkout call. These payments are excluded from billable GMV. Requires the payment_records:write scope and the application:payments:record permission (admin or finance).

curl -X POST https://api.usethrottle.dev/api/v1/orders/ord_abc/payments/record \
  -H "X-API-Key: $THROTTLE_SECRET_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "amount": 20000, "method": "cheque", "reference": "0114", "note": "Collected at pickup" }'

A comp waives what the buyer still owes. Money already captured stays captured. Nothing is sent to a payment processor and the buyer is never charged. `compAmount` is set to the outstanding balance; `total` is NOT reduced, because the order is still a sale of that size — the comp is a credit recorded against it, and what the buyer owes is `total - compAmount`, so `paymentStatus` settles at `captured` and `displayStatus` reads "… · Comped". The amount is never accepted from the caller — only the reason is. Anything still claiming the waived balance is settled: open authorizations are voided, and unpaid Net-N invoices are voided and their buyers emailed. Requires the order_comps:write scope and the application:orders:comp permission (admin or finance).

curl -X POST https://api.usethrottle.dev/api/v1/orders/ord_abc/comp \
  -H "X-API-Key: $THROTTLE_SECRET_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "reason": "Warranty replacement" }'

The order owes what it owed again: `compAmount` returns to 0, `total` is restored, and `paymentStatus` falls back out of `captured` on its own. Side effects of the comp are NOT rewound — an authorization voided at the processor cannot be un-voided, and a voided Net-N invoice is not reissued, so collecting the restored balance means taking a fresh payment. A tax return filed for the comp is reversed by retrying it: POST /v1/tax-documents/{id}/retry. Requires the order_comps:write scope and the application:orders:comp permission.

curl -X POST https://api.usethrottle.dev/api/v1/orders/ord_abc/comp/reverse \
  -H "X-API-Key: $THROTTLE_SECRET_KEY"

Returns all payments scoped to the calling application, cursor-paginated by createdAt DESC. Filter by `method` (e.g. net30, card), `status` (repeat the param for multi-status OR logic), `order_id` (UUID — returns payments for a specific order), `due_from` / `due_to` (YYYY-MM-DD ISO dates that filter on `metadata.dueDate`), `amount_min` / `amount_max` (integer cents, inclusive bounds), `aging` (Net-N aging bucket: `0_30 | 31_60 | 61_90 | 90_plus`), `limit` (page size), and `cursor` (opaque continuation token from the previous response).

Use when you need to show payment state, processor references, refunds, or Net 30 state for a specific order.

Use when you need capture, authorization, refund, or failure transaction details for reconciliation and support tooling.

Refund a payment fully or partially. Use webhooks to update downstream order state after the refund result is recorded.

Use for buyer portals or operations tools that need to show or download a Net 30 invoice PDF.

Queues the customer.net30_invoice_issued email again. The email includes a fresh buyer-facing invoice download link.

Public buyer route used by invoice emails. Throttle validates the signed token, reloads the payment, and redirects to a short-lived S3 signed URL. Tokens are valid for the snapshotted Net-N term, clamped to 1-365 days.

Returns active and paused outbound webhook endpoints. Deleted endpoints are excluded.

Register the HTTPS URL that receives durable order, payment, cart, subscription, discount, customer, and fulfillment events.

curl -X POST https://api.usethrottle.dev/api/v1/webhook-endpoints \
  -H "x-api-key: $THROTTLE_API_KEY" \
  -H "content-type: application/json" \
  -d '{
    "url": "https://shop.example.com/api/throttle/webhook",
    "enabledEvents": ["order.created", "payment.captured", "payment.failed"]
  }'

Use this to rotate receivers, pause delivery, resume delivery, or change subscribed events.

Stops future dispatch and removes the endpoint from list responses. Create a new endpoint to subscribe again.

Use for debugging and operational audit views. This endpoint returns attempts, not the endpoint configuration itself.

Use during setup to verify URL reachability, signature validation, and handler routing without waiting for a real checkout event.

Generates a new signing secret and returns it once in the response. The previous secret stops verifying immediately, so update your receiver before (or right after) rotating. Use this to recover from a leaked secret.

Re-fires the same event payload with a fresh signature. Use after fixing a receiver bug or recovering from downtime.

Use this in setup tooling or dashboards to show which parent origins and brand values are currently configured.

Required before embedding checkout in production. The parentOrigin passed to the SDK must match an allowed origin.

Requires the applications:read scope (API key) or the application:settings dashboard permission (Clerk). Resolves the environment from the caller (X-Throttle-Environment-Id for Clerk, the key’s own environment for an API key).

Requires the applications:write scope (API key) or the application:settings dashboard permission (Clerk). Merges into the existing settings JSON — send only the fields you want to change.

Use for manual creation flows after a vaulted payment method exists. Embed-driven create:auto remains the fastest checkout path.