Developer Changelog

2026-08-23 — company on customers

• Customers carry a first-class company. POST /api/v1/customers and PATCH /api/v1/customers/:id accept it, and every customer response returns it (null when unset). Send null or an empty string to clear it. Existing records were backfilled from metadata.companyName and the default address's company, so a value you already stored there is preserved.
• Orders and subscriptions expose the buyer's company. The embedded customer object on order and subscription responses now includes company alongside the name and email.

2026-08-07 — Stripe Connect via OAuth

• Connecting Stripe no longer requires installing a Stripe App. A merchant can authorize Throttle through a standard Connect OAuth flow instead, with no keys pasted anywhere. The existing install-link path still works.

2026-08-03 — Production API keys read sk_live_

• Keys minted for a production environment now carry sk_live_ / pk_live_. They previously read sk_production_ / pk_production_. Keys minted before this date remain valid indefinitely — nothing in the auth path parses the environment segment, so both prefixes authenticate. Non-production environments continue to use their own slug, e.g. sk_test_ or sk_uat_.
• live, live-*, and production-* are reserved environment slugs. Creating a custom environment with one of these names is rejected, so a sandbox environment can never mint a key that looks live.

2026-08-02 — Hosted MCP server and OAuth 2.1

• Throttle is now an OAuth 2.1 authorization server. PKCE and dynamic client registration, advertised at /.well-known/oauth-authorization-server and /.well-known/oauth-protected-resource, with /oauth/authorize and /oauth/token. Consent is per application.
• A hosted remote MCP endpoint at /mcp speaking Streamable HTTP, so an MCP client can reach Throttle without running anything locally.
• @usethrottle/mcp 0.2.0 adds quote and money write tools, each idempotent and gated behind --allow-writes / --allow-live-writes. See MCP server.
• The authorization-code TTL was raised from 60 seconds to 10 minutes on 2026-08-09, since a human completing a consent screen routinely takes longer than a minute.

2026-07-28 — MCP server and /whoami

• @usethrottle/mcp 0.1.0 — a read-only Model Context Protocol server over stdio, with tools scope-filtered against the grants on your API key.
• New: GET /api/v1/whoami resolves the calling credential to its workspace, application, and environment.

2026-07-27 — Webhook payloads carry customer identity

• Every subscription.* payload now includes a customer object. Payloads previously carried only customerId, a Throttle UUID that means nothing in your system, so identifying the buyer cost a GET /customers/{id} per event.
• Flat payment.* payloads that carry an orderId gain customer, customerId, and subscriptionId.
• The customer object carries email, firstName, lastName, phone, and both external identifiers — externalId and externalCustomerId — because they are not the same field. It is attached at delivery and is absent when the customer row cannot be resolved, so treat it as nullable.
• Webhook coverage lastEmittedAt is now ISO 8601.

2026-07-19 — Money-correctness: returns, order edits, cancel, currency

Returns & exchanges

• Return refunds now reflect what the buyer actually paid. The refund for a returned line is its subtotal plus tax, minus discounts (including a proportional share of order-level code discounts), prorated exactly across partial-quantity returns. Previously refunds used bare unitPrice × quantity, under-refunding tax and over-refunding discounted items.

Orders

• PATCH /orders/:id/line-items now recalculates tax. When tax is configured for the application, edited orders re-quote tax for the resulting item set (added items no longer land with taxAmount: 0) and the captured delta charge/refund includes the tax movement.
• POST /orders/:id/cancel now settles payments. Open authorizations are always voided; pass refundCapturedPayments: true to also refund captured money. The response reports a paymentActions array.

Carts

• Cart currency is validated against the application. POST /carts rejects a currency that differs from the application's configured per-environment currency (422 currency_mismatch); omitting currency now inherits the application currency instead of silently defaulting to USD.
• Legacy deprecated discount types fail validation. Surviving free_shipping / buy_x_get_y rows (retired types) now fail checkout validation loudly instead of applying with a silent $0 effect while consuming a usage slot.

2026-07-04 — Embedded checkout: webhooks, receipts, prefill & retry fixes

Webhooks

• payment.captured and payment.vaulted now deliver for embedded checkout. These events (and all webhooks from proxy/embed sessions, including order.created) were silently dropped because the emit omitted application context. They now reach every subscribed endpoint with the correct signature.

Emails

• customer.payment_receipt now sends for embedded checkout captures. The synchronous embed capture path previously bypassed the internal event bus, so no receipt email fired for card/one-time or subscription checkouts.

Checkout

• Buyer prefill now reaches the checkout UI. Passing a customer on session create now pre-fills the buyer's name and address in the hosted/embedded form (the prefill was being stripped from the public session response).
• Failed payments are retryable. If a capture fails, returning to the same checkout session now retries cleanly instead of erroring; a duplicate submit returns the existing order without double-charging.

2026-07-04 — Abandoned-cart recovery works end to end

Checkout

• Recovery links can now complete a purchase. Creating a checkout session against an abandoned cart now reopens it (status → open), so a buyer who returns via a cart.abandoned recovery link can finish checkout on that same cart. Previously the cart was frozen and completion dead-ended with cart … is in 'abandoned' status.

Webhooks & email

• Guest carts get recovery emails. The abandoned-cart sweep now sends the customer.cart_abandoned recovery email to carts that captured only a customerEmail (no full customer record), not just carts linked to a customer.
• Configure the recovery link. The recovery URL in the cart.abandoned webhook payload and the recovery email is built from your per-app cartRecoveryUrlTemplate (must contain {cartId}) — set it in the dashboard under Abandoned carts, or via PUT /api/v1/embed-config. Without it, recovery is webhook-only with a null URL.

2026-07-04 — Subscription checkout, typed request bodies, cart lifecycle

API & SDK

• Checkout session request bodies are now documented. POST /api/v1/checkout/sessions and POST /api/v1/checkout/sessions/{id}/complete now publish their requestBody in the OpenAPI spec. @usethrottle/[email protected] regenerates postApiV1CheckoutSessions / postApiV1CheckoutSessionsComplete with a typed body parameter — no more raw-fetch workaround for creating or completing a session. Request/response validation is unchanged.

Checkout

• Plan-based & free-trial subscription checkouts can use an empty cart. When a checkout session carries a recurring block and its cart has no line items, Throttle now synthesizes a single subscription line item from the plan at completion (amount due today for an immediate charge, or $0 for a free trial), so the order converts cleanly. Previously an empty cart failed with cart_empty (“Cart cannot be converted to an order without line items”). recurring.create: 'auto' governs subscription creation after payment; it does not add cart items itself.

Webhooks

• Checkout-session expiry reaches the cart. A checkout session now stamps its expiry window onto the parent cart, and when a session expires the cart is released — its status moves to abandoned and cart.abandoned fires (with the standard recovery payload). Previously the cart stayed open with no event.

2026-07-04 — Actionable unavailableReason on payment methods

API

• GET /api/v1/checkout-sessions/{id}/payment-methods unavailableReason. When methods is empty because a payment provider is connected but can’t currently render (for example, not yet configured for the checkout’s environment), the response now includes an optional unavailableReason: { code, message }. Surface message to the buyer instead of a blank “no payment methods” state. The field is additive and only present on the empty path. The list itself now also reflects exactly what the embed will render, so the “available” view and the embed no longer diverge.

2026-06-21 — Cart email capture + richer cart.abandoned payload

API

• Cart customerEmail. POST /api/v1/carts and PATCH /api/v1/carts/{id} accept an optional customerEmail — lightweight email capture without a full customer record. The cart response now also returns customerEmail and the stored shippingAddress / billingAddress.

Webhooks

• Enriched cart.abandoned. The payload now includes shippingAddress and billingAddress (as stored on the cart, or null), and customer now represents a guest captured via the cart’s customerEmail as { id: null, email, firstName: null } — so anonymous carts with a captured email are recoverable. All fields remain additive.

SDK

• @usethrottle/cart: CreateCartInput / UpdateCartInput / Cart gain customerEmail. @usethrottle/webhook-types: CartAbandonedData gains the address fields and a nullable customer id.

2026-06-20 — useThrottleCheckout hook

SDK

• @usethrottle/checkout-react. New useThrottleCheckout hook that orchestrates a storefront checkout over a cart session: totals and selectedMethod bound to the cart, one-call selectMethod, a status state machine, automatic stale-cart recovery (rebuild + retry on cart_not_open), and createSession returning the checkoutSessionId for <PaymentEmbed>. See Cart sessions.

2026-06-20 — allowedMethods on payment-only embeds

API

• Fail-loud. POST /api/v1/checkout-sessions/embed-token (payment-only) now rejects allowedMethods with 400 allowed_methods_unsupported instead of accepting and silently ignoring it. A payment-only embed renders the methods configured on your payment connection; the embed token has no method-restriction field. allowedMethods continues to filter the full hosted checkout (the /payment-methods catalog + payment tiles) — that flow is unchanged.

SDK

• @usethrottle/checkout-sdk. createEmbedToken no longer accepts allowedMethods (it never applied to the payment-only embed). createSession still accepts it for the full checkout.

Docs

• Documented the precedence between session allowedMethods and payment connection configuration. See Embedded Checkout.

2026-06-20 — Cancel a checkout session

API

• DELETE /api/v1/checkout/sessions/{id} now cancels an in-flight session (previously a no-op). It is idempotent, marks the session cancelled, and re-opens an associated cart still in checkout status (never a terminal converted cart). A completed session returns 422 already_completed; an unknown session returns 404.

SDK

• @usethrottle/checkout-sdk. New checkout.cancelSession(sessionId) method.

Docs

• Clarified the session→cart lifecycle: creating a session does not move the cart out of open; the cart only becomes converted when the order is created at session completion. See Embedded Checkout.

2026-06-20 — Canonical cart address + typed cart errors

API

• Canonical cart address. PATCH /api/v1/carts/{id} now validates shippingAddress / billingAddress at write time against one canonical shape (CartAddress: required addressLine1, city, countryCode). Non-canonical keys (line1, state, country, zip) are now rejected with a validation_error naming the camelCase replacement, instead of being stored verbatim and failing later at checkout with address_required.

SDK

• @usethrottle/cart. Exports the canonical CartAddress type (used by carts.update and the cart response) and two typed lifecycle errors — CartNotOpenError (409 cart_not_open) and CartNotFoundError (404). Both extend ThrottleApiError, so existing checks keep working. See Errors.

Docs

• Clarified that selecting a shipping method is a single atomic call returning the full recomputed cart, and that the cart (not a client-side copy) is the source of truth for the selected method and totals. See Cart API.

2026-06-20 — Abandoned-carts read APIs

API

• New endpoints. GET /api/v1/abandoned-carts (cursor-paginated; each row carries customer, total, itemCount, abandonedAt, and recoveryStatus) and GET /api/v1/abandoned-carts/summary (abandonedCount, abandonedValue, recoveryEmailsSent over a trailing window). Both require the carts:read scope. Available in @usethrottle/api-client. See API reference.

2026-06-20 — Richer cart.abandoned webhook payload

Webhooks

• Enriched payload. The cart.abandoned outbound event now carries the full recovery context in data: customer ( id, email, firstName; or null for anonymous carts), lineItems, currency, totals ( subtotal, taxTotal, shippingTotal, discountTotal, total), itemCount, and a recoveryUrl. This lets ESP integrations (e.g. Klaviyo) drive a recovery flow from the single webhook with no follow-up API call. See Webhooks.
• Backward compatible. The change is purely additive — only cartId and sequence are guaranteed, so existing consumers are unaffected. The envelope version stays "1".
• Typed. @usethrottle/webhook-types now types the enriched CartAbandonedData (new fields are optional). recoveryUrl is populated from the app's cartRecoveryUrlTemplate when set, otherwise null.

Embed config

• Per-app abandonment threshold. PUT /api/v1/embed-config now accepts cartAbandonmentThresholdMinutes (and GET returns it): the minutes of inactivity before an open/checkout cart is treated as abandoned by the sweep. Range 15– 129600 (90 days). Pass null to clear; when unset, the platform default of 1440 (24h) applies. The value is per application and per environment. See API reference.

2026-05-11 — Team management & per-app roles

Workspace invitations

• Two-tier role model. Workspaces now carry three roles: owner, workspace_admin, and member. Members get explicit per-application roles from admin, developer, finance, or viewer. See Team management and Permissions.
• New invitations + members endpoints. POST /api/v1/workspaces/:workspaceId/invites, .../invites/:id/resend, .../invites/:id/revoke, GET .../members, GET .../members/me, PATCH .../members/:memberId, DELETE .../members/:memberId, DELETE .../members/:memberId/applications/:applicationId.
• Strict email match on accept. POST /api/v1/invites/accept now requires the caller's Clerk verified primary email to match the invite token's email claim. Mismatch returns 403 invite/email_mismatch.
• Permission introspection. GET /api/v1/auth/permissions returns the caller's effective workspaceRole and appRole plus the full static catalog. Use it to drive UI gating.
• Auth context fields. Server-side handlers now see auth.workspaceRole, auth.appRole, and auth.workspaceMemberId on Clerk-authenticated requests. Legacy auth.role field preserved.

Emails

• Four new templates seeded by @platform/emails: system.team_invite_resent, system.team_invite_accepted, system.team_access_revoked, system.team_role_changed.

Legacy compatibility

• POST /api/v1/merchants/me/invites and its /resend, /revoke siblings continue to work — they delegate to the new team-service. Legacy clients sending { email, role: 'admin' } still receive role: 'admin' in the response envelope.

2026-05-04 — Collect flags, billing, metadata propagation

Embedded checkout

• Collect flags shipped. POST /api/v1/checkout/sessions accepts a new collect: { shippingAddress: boolean; billingAddress: boolean } object on the request body. Defaults match historical behaviour (shippingAddress: true, billingAddress: false). See Collection Flags .
• Billing address is now first-class. POST /api/v1/checkout-sessions/:id/complete accepts new billingAddress (same shape as shippingAddress) and billingSameAsShipping: boolean (default false). Required when collect.billingAddress is true on the session.
• step: 'billing' postMessage event. The unified /s flow now emits an additional throttle.step.changed event with step: 'billing' when the buyer reaches the billing form.
• field extras on address_required 422 responses. Validation errors at /complete now include a field key (e.g. "billingAddress" or "shippingAddress") so the iframe and API integrators can route the error to the right form section.
• Pay button auto-disables until collect-flagged fields are complete. Parent-set submitDisabled still composes additively — see Parent Controls .
• ?mode=payment-only deprecated. Still respected client-side for one release. New integrators should set collect: { shippingAddress: false, billingAddress: false } instead.

Discounts

• Session-create discountCode. POST /api/v1/checkout/sessions accepts a new discountCode: string field. Validated synchronously; invalid codes return 422 discount_invalid. See Discounts.

Metadata + webhooks

• Session metadata propagates to orders. User-attached metadata on a checkout session is merged into the order at conversion with precedence cart < session < {customerEmail}.
• Reserved keys are stripped server-side. recurring, customer_prefill, mode, amount, currency, and externalCartId are removed from session metadata before persistence; use top-level request fields instead.
• Session metadata caps. 50 keys / 10KB serialized. Over-size payloads return 422 metadata_too_large.
• Webhook payloads now carry user metadata. order.created, payment.captured, and subscription.created include the merged data.metadata bag. See Metadata.