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.

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

Quote tokens start with pk_ and let a storefront request read-only estimates without exposing a secret key.

Soft-deletes and deactivates a pk_ token so storefront quote requests using it stop working.

Use from the browser or your backend for read-only estimates. It validates the pk_ quote token, application id, expiry, and allowed origin.

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.

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

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

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.

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

Filter by Throttle customer id, your external customer id, or status. Proxy this through your backend for buyer-facing portals.

Use for buyer portal detail pages, support tooling, and access-gating checks.

Updates plan reference, display name, interval, amount, or metadata. Changes apply according to the subscription lifecycle rules documented in the guide.

Moves an active subscription into paused state from your backend proxy.

Moves a paused subscription back into an active billing state.

Use from buyer portals and support tooling. For buyer-facing use, authorize ownership in your backend before calling Throttle.

Pre-flight trial fraud protection by checking whether a payment method fingerprint has already used a trial for this merchant.

Use when your app stores only its own user id. Throttle resolves the canonical customer row for subscription lists, direct subscription creates, and payment-method reads.

Use on subscription confirmation pages and buyer portals when you need to show the vaulted card summary used for renewals.

Keeps the vaulted payment method on file but prevents renewals from charging it until it is resumed.