# Changelog

What's shipped in the API and these docs, most recent first. Non-breaking additions ship continuously; breaking changes are announced ahead of time through [Firmly](/contact) — none ships without notice.

## Recent changes

- **September 22, 2026 — 3-D Secure payment challenges documented; merchant-access guides restored behind sign-in.** [Complete Order](/api-reference/payment/complete-order-v2) and [Place Order](/api-reference/payment/place-order-v2) can return `409 payment_challenge_required` when the issuer requires card verification — not a failure, but a step the shopper completes before you call [Resume After Challenge](/api-reference/payment/complete-order-v2-resume). `openapi.json` carries the envelope on every route that emits it, so generated clients no longer treat a challenge as a dead end. Available to App IDs opted in via `supports_payment_challenge`; others keep the previous `422 PaymentChallengeRequired`. Separately, the merchant allow-listing and payment-provider guides are published again under [For Merchants](/for-merchants/), behind the same sign-in they had before — [contact Firmly](/contact) for access. [Search Products](/api-reference/discovery/search) is the canonical discovery search endpoint.
- **September 15, 2026 — PayPal Express Checkout documented, express checkout grouped by provider.** PayPal's three-call sequence now has reference pages — [Start](/api-reference/payment/express-checkout/paypal/start), [Authorize](/api-reference/payment/express-checkout/paypal/authorize) and [Complete Order](/api-reference/payment/express-checkout/paypal/complete-order) — verified against the API. Express checkout is now grouped per provider, so the Klarna and Google Pay pages moved to `/express-checkout/klarna/…` and `/express-checkout/google-pay/…`; the previous URLs redirect. Each provider page carries the availability check and host note for its gateway; the endpoint pages stay self-contained. Note for PayPal integrators: a declined PayPal payment returns `422 CreditCardDeclined` despite the name — see [Complete Order](/api-reference/payment/express-checkout/paypal/complete-order#error-responses).
- **September 2, 2026 — Merchant fees itemized on the cart.** Cart responses now carry an optional `fees` array plus a `fee_total`, so merchant-imposed charges (recycle, regulatory, environmental) are itemized with their own descriptions instead of being folded into `tax`. Both fields are optional and absent when a cart has no fees, and `total` is unchanged. See [Get Cart](/api-reference/cart-management/get-cart), the [ShoppingCartV2 schema](/resources/schemas/shopping-cart), and [Common types → Fee](/resources/schemas/common-types#fee).
- **August 21, 2026 — Reference accuracy pass.** Corrected the documented shapes for [place-order / complete-order](/api-reference/standard-flow/place-order) (the response carries `submitted_at` alongside `platform_order_number`), [Get Product from URL](/api-reference/catalog/get-product-from-url) (full product detail, and it can return `412 ProductNotSupported`), [Discovery search](/api-reference/discovery/search) (paginate with `cursor`; `query` is optional when you send `filters`), [Add Line Item](/api-reference/cart-management/add-line-item) (`flush_cart`/`fast_mode` are the strings `"true"`/`"false"`, and unknown query parameters are rejected), and [Set Fulfillment Type](/api-reference/shipment-configuration/set-fulfillment-type) (`fulfillment_type` enum plus `location_id`). Cart responses now document the `session` object and the `tax` / `tax_total` pairing. Example identifiers are UUIDs throughout, matching what the API returns, and every example card is the documented sandbox card.
- **August 19, 2026 — Clearer Standard vs Advanced.** Both checkout flows now have a runnable, end-to-end guide — the [Standard Checkout Guide](/cookbook/standard-checkout-guide) (`/api/v1`) and the [Advanced Checkout Guide](/cookbook/advanced-checkout-guide) (`/api/v2`) — plus a chooser on the [For Destinations](/for-destinations/) and [For Merchants](/for-merchants/) pages, and a [which-is-my-store heuristic](/for-merchants/supported-platforms#standard-vs-advanced) for merchants. The [API Explorer](/api-explorer/) is now grouped by flow: **Shared setup**, **Standard (v1)**, **Advanced (v2)**.
- **August 18, 2026 — Standard (v1) checkout documented end-to-end.** New [Standard flow reference](/api-reference/standard-flow/) (catalog, cart, checkout, order) and the runnable Standard Checkout Guide, verified against the sandbox. The Advanced (v2) endpoint set — cart, shipments, orders, sessions, and ZIP-coverage — is now complete in the reference and the Explorer.

## How updates are communicated

- **Breaking changes** are announced ahead of time through [Firmly](/contact); no breaking change ships without notice.
- **Non-breaking additions** (new endpoints, optional fields, new guides) ship continuously.
- **Internal refactors** that don't change the public contract are not announced.

## Versioning

- Two flows share the same auth and catalog: **Standard** (`/api/v1`) — single-merchant, one-shipment checkout, right for most integrations — and **Advanced** (`/api/v2`) — split shipments, add-ons, delivery scheduling, and coverage. See [Choose your checkout flow](/for-destinations/) for how to pick.
- Endpoint-level detail is in the [API Reference](/api-reference/) and the live [API Explorer](/api-explorer/).

---

## Related

- [API Reference](/api-reference/)
- [API Explorer](/api-explorer/)
- [Contact](/contact)
