# API Changelog

Every change to the Shoprocket REST API, newest first, tagged so you can scan for what affects you.

## How we describe changes

- Added New endpoint, field, or option. Safe to ignore.
- Improved Behavioural improvement that doesn't break existing requests.
- Fixed Bug fix. May change a response in edge cases.
- Deprecated Flagged for future removal. Still works for at least 6 months.
- Removed Only on a major version bump. Old version stays available for 12 months.

## 2026

16 November 2026 Added

- `POST /stores/{storeId}/imports/from-url` takes an optional `collections`: Shopify collection handles to import as categories as well as the ones the shop's pages link to. Its `found` now lists `skippedCollections` (`handle`, `name`, `products`), the collections with products that no page links to, so they can be sent back as `collections`.

16 November 2026 Added Changed

- A page section's Text paragraph (`rich-text` `body.text`), a paragraph block's `text` and a question's `answer` are now sanitised HTML (links, bold, italic, lists, paragraphs) instead of plain text, up to 10,000 characters. A value with no markup is still plain text, so render these as HTML: the public pages API always returns them safe to inject, with any stray tag escaped to text.
- New `page-body` section type (the Article) carries one `html` field of the same sanitised HTML, up to 20,000 characters. A client that does not know the type should skip it.

16 November 2026 Changed

- `branding.cartLines` (and the seller's `cartLines` store update) now has two keys, `brand` and `subtitle`; the `attributes` switch is gone. An `attributes` key sent with an update is still accepted and ignored, and reads never return it. Our own cart no longer draws attribute tags. Every cart line still carries `attributes[]`, so a headless cart can keep showing them.

- The shop chrome (`menus.chrome`) carries the logo's size and the store name switch: `logoHeight` (24-120) and `logoHeightPhone` (16-80), each the logo's height in CSS pixels or `null` for the default, and `showStoreName`, where `null` means the name shows only when the store has no logo. Draw the logo from its `widths` (its own shape), not the square `urls.thumb`.
- The announcement bar's `scheme` may be `custom`, with `background` and `foreground` as `#rrggbb`. If the text colour does not reach 4.5:1 on the background, draw black or white text instead, as the hosted shop does. A client that only knows the three named schemes should treat an unknown one as `inverse`.
- A store's `fontPairing` may now be a heading and a body chosen separately, as `<heading>+<body>` (for example `eczar+nunito-sans`), up to 120 characters. The `fontsHref` you are given already names one stylesheet for both faces.

15 November 2026 Added Changed

- Quote requests take file answers. A line's `properties` on `POST /public/{pk}/quote-requests` may now answer a product's file field with the `token` from `POST /cart/uploads`, sent with the same `X-Cart-Token`; until now file fields were not accepted on a request. The request keeps its own copy of the file, so it outlives the cart. A `cart` request takes each line's files from that cart's own lines. A token that is not this cart's upload answers `422`. In the dashboard's `GET /stores/{storeId}/contact-messages` a file answer has `type` `file` and the file's name as its `value`, and the seller downloads it from `GET /stores/{storeId}/contact-messages/{id}/lines/{line}/files/{fieldId}`. Make a quote copies it onto the draft, where it downloads like any order line's file.

- A store that is still being set up is hidden until it goes live. `GET /public/{pk}` and the hosted shop's bootstrap carry a new `comingSoon`: while it is `true`, draw nothing (or a "coming soon" note) unless the page holds the seller's preview token (`?sr_preview=`, sent back as `X-Shoprocket-Preview`). The seller's store read carries the same `comingSoon`.
- Outside a preview session such a store's `GET /public/{pk}/payment-methods` is empty with `checkoutDisabledReason` "this shop is not open yet", and `POST /public/{pk}/cart/checkout` answers 409 with the new rejection `store_not_open`. Inside one, only the test gateway is offered, so every order a store in set-up takes is a test order; a basket started before the preview is refused with the same code.
- New `GET /public/{pk}/preview-session` says whether the `X-Shoprocket-Preview` header holds a valid preview token for the store, and when it expires. `POST /stores/{storeId}/preview-session` also returns `sitePreviewUrl`, the seller's own site with the token on it, and its tokens now last 4 hours, up from 30 minutes.

15 November 2026 Added

- A product line on `POST /stores/{storeId}/orders` and `PUT /stores/{storeId}/orders/{id}` can send `properties`: answers to the product's buyer input fields, keyed by field id, exactly as `POST /public/{pk}/cart/items` takes them. They are judged against the product's own fields: an answer to a field hidden by its condition is dropped, a missing required answer is refused with `422` (on a draft too), and each answer's charge is added to `unitPrice`, which is then the price before those charges. File fields cannot be answered here. Omit `properties` and the line is priced as sent, and an edited line keeps the answers it has; sending the same answers back keeps the prices they were sold at. The answers come back on the line's `properties` as on any order.
- `GET /stores/{storeId}/products/summaries?include=variants` now carries each product's `personalizationFields` when it has any, so an order form can ask them.

15 November 2026 Changed

- `POST /public/{pk}/orders/{orderId}/pay` on an order checked out through its payment link now checks the link's "price valid until" date again, and answers `409` with `rejection: quote_unavailable` once it has passed, before any payment starts. Before, a client that checked out inside the date could start the payment after it. A payment that already started is unaffected and settles as usual; a PayPal express approval counts from when PayPal raised it. The seller can send the link again with a new date.

12 November 2026 Added

- A draft order's payment link now carries a seller-set "price valid until" date. `POST /stores/{storeId}/orders/{id}/payment-link` and `POST /stores/{storeId}/orders/{id}/payment-link/send` accept `validUntil` (a `YYYY-MM-DD` day in the store's timezone; the link pays until the end of it), `validDays` (days from today) or `keepValidUntil` (keep a date still ahead). With none of them the link gets the store's default number of days, 30 unless changed, which is what every send and copy did before. The copy route's body is optional.
- `GET` and `PUT /stores/{storeId}/quote-settings` carry `validDays`, that default. A quote cart's `quote` carries `validUntil`, the day to show the shopper as "Price valid until".

14 November 2026 Changed

- `GET /public/{pk}` no longer carries `showBranding`, and neither do the hosted order status and review pages' reads. Shoprocket no longer adds a "Powered by Shoprocket" credit anywhere a shopper looks, so there is nothing to switch. An old client that reads the field and finds it missing keeps working.
- The seller's store read loses `showBranding` and `brandingRemovable`, and the store update no longer accepts `showBranding`: a request that still sends it has the key ignored, not refused. The `white-label` feature is gone from `features[]` and from the plan catalogue.
- The v2-compatible REST API's `remove_branding` is now always `0`.

12 November 2026 Added

- Every cart line gains `brand`, `summary` and `attributes[]` (each `{ name, value, type }`): the product's brand, its short summary and its public attributes, read live from the product and in the `locale` you ask for. A `boolean` attribute's `value` is `Yes` or `No` in English, so print your own words for it. A signed line carries none of them.
- `GET /public/{pk}` gains `branding.cartLines`: which of those the store's own cart shows (`brand`, `subtitle`, `attributes`, each `true` or `false`, off when absent). The seller's store update accepts the same switches as `cartLines`.

12 November 2026 Added Changed

- A product's `personalizationFields` now read in the `locale` you ask for: each field's `label` and each choice's `label` are the store's translation when it has one. Each choice gains `value`, the option in the store's own wording: send `value` as the field's answer when adding to the cart or asking for a quote, and compare `showIf.equals` against it. Sending a choice's `label` still works in the store's own language.
- A cart, order or quote line's `properties[]` now read in the shopper's language too: `label` and a dropdown's `value` are translated, typed answers are never. Each property gains `answer`, the answer exactly as stored, to send back when asking about the same line again.
- A free-text spec in a product's `attributes[]` (`display`, `values[].value`) and a spec's `unit` now read in the `locale` you ask for.

12 November 2026 Added

- Every fulfilment on an order now carries `deliveryStatus` (`in_transit`, `attempted_delivery`, `ready_for_pickup`, `delivered` or `failure`), `deliveryStatusDetail` (the carrier's words for a failure), `deliveryStatusAt` and `deliveredAt`. They are filled from carrier tracking for shipping labels bought through Shoprocket, and stay `null` for a shipment recorded by hand. When they change, an `order.updated` webhook is sent.

12 November 2026 Changed

- On `GET /public/{pk}`, a banner's `promos.items[].text` and a pop-up's `popup.body` now read in the `locale` you ask for when the seller wrote them and the store has a translation; before, the seller's own words always came back as typed. `words` now also carries the seller's words in each other language the store sells in, beside the wording we write, so a client that switches language reads them from there.

- Shop reviews on the storefront API. `GET /public/{pk}/reviews` takes `show`: `shop` (reviews of the shop as a whole), `product` (the default, as before) or `all`, and `page` to page through them `limit` at a time. Each review adds `kind` (`shop` or `product`) and its `reply`; `productName` and `productSlug` are `null` for a shop review, and `productSlug` is `null` for a product that is no longer for sale, which still keeps its reviews. The response adds `meta` with the paging and three rating summaries (`overall`, `shop`, `products`), each with `reviewCount`, `averageRating` and `ratingDistribution`.
- `GET /public/review-requests/{token}` adds `shopReview`, the shop review the link asks for or `null`: `when` is `instead` for an order with no product left to review (custom, archived or deleted items) and `after` when the seller asks for one after the product reviews. A shop review is sent through `POST /public/review-requests/{token}/reviews` with `productId: null`, once per email. The seller API's automations read and save `shopReviewPrompt`, the switch for `after`.
- A signed cart item's `expires` is now enforced when the order is placed, not only when the item is added: `POST /public/{pk}/cart/checkout` refuses a cart holding a signed line whose `expires` has passed with rejection `signed_item_invalid` and `signedItem.reason` `signed_item_expired`. An order placed before it still pays at the signed price. `expires` may now be up to 30 days ahead (was 7); further is refused with `signed_item_expires_too_far`.
- Cart lines carry `signedExpiresAt`, when a signed line's price stops holding (null on other lines). Checkout accepts an optional `paypalOrderId`: the PayPal order the shopper approved with the express button, so a signed line whose hold ended after that approval still checks out. See [Signed cart items](https://shoprocket.io/docs/signed-items.md).

11 November 2026 Added

- `POST /stores/{storeId}/orders/shipping-options` lists the shipping rates checkout would offer an order's lines at its shipping address (your shipping zones' rates and any live carrier quotes, cheapest first), judged on the order's own prices and discount, without saving anything. `POST /stores/{storeId}/orders` takes an optional `shippingMethodName` to name the rate the order ships at, and on a draft `PUT /stores/{storeId}/orders/{id}` now accepts `delivery` of type `shipping` to rename it.
- `POST /stores/{storeId}/orders` accepts `autoTax: true` to work out the order's tax the way checkout does, from the store's tax registrations, the shipping (or billing) address, each product's tax band and whether prices include tax; with no address the store's business address is used, and `taxes` is ignored. It defaults to `false`, so an order you send tax lines for (or none) is unchanged. On `PUT /stores/{storeId}/orders/{id}`, `autoTax: true` switches an order to it and recalculates now, and an order that works out its tax recalculates on every update that changes its lines, addresses, discount or shipping; `autoTax: false` keeps its tax lines as they are.
- Order lines take an optional `taxClass` (`standard`, `reduced`, `super_reduced`, `zero`, `exempt`) for a custom line with no product. Orders, and the order in webhook payloads, now carry `autoTax`, and each line its `taxClass`.
- `POST /stores/{storeId}/orders/tax-preview` returns the tax an order would carry, with its lines and the rate each item would be taxed at, without saving anything.
- Quote requests carry a product's buyer input answers. Each line of `POST /public/{pk}/quote-requests` takes `properties`, the answers keyed by field id, judged against the product's own fields exactly as `POST /cart/items` judges them: a hidden field's answer is dropped, a missing required one answers `422`, and any charge comes from the catalogue. File fields are not accepted on a request. Two lines of one variant with different answers stay two lines. A quote request line in the dashboard's `GET /stores/{storeId}/contact-messages` gains `properties`, each answer with its `label`, `value` and `priceDelta`, and its `unitPrice` now includes the charge.

11 November 2026 Added Changed

- `GET /public/{pk}/payment-methods` takes `locale`, like the other public reads. Each method's `name` and `description` come back in that language: the seller's own words for an offline method or a gateway label when the store has a translation, and our own gateway names (such as "Pay by card & more") in every language we ship. Without `locale` they read in the store's default language.
- `GET /public/{pk}/cart/shipping-options` now also translates a rate's name when it falls back to its shipping method's name, every option's `description`, and the pickup locations and local delivery areas it lists. The cart's `shippingMethodName` follows the same rules, and a pickup reads "Pickup at" in the shopper's language. An order freezes its pickup location, local delivery area and payment instructions in the language it was placed in.

- Shop reviews: a review can be about the shop as a whole rather than one product. On the seller API's reviews,`productId` and `productName` are now `null` for a shop review, so read them as nullable. `GET /stores/{storeId}/reviews` takes `kind=shop` or `kind=product` to list one kind, and its response adds `shopRating` (`reviewCount` and `averageRating`, from approved shop reviews). A review never changes product after it is created.
- Reviews imports no longer need a product column. A row naming no product the store has imports as a shop review unless the import's options carry `assign`: data row number to a `prod_...` id, or `skip`. `POST /stores/{storeId}/imports/{id}/review-rows` lists a pending reviews import's rows that match no product (and how many do), for the mapping you pass. The reviews export writes a blank product for a shop review, which imports back as one.

- `POST /stores/{storeId}/orders` and `PUT /stores/{storeId}/orders/{id}` accept a `customerId` (`cust_...`) to save the order, draft or quote against that customer, so it shows in their order history and counts toward their totals. Without one, an order that has an `email` now links to the store's customer with that email, or adds one, instead of staying unlinked. On an update, `customerId: null` unlinks the order, and leaving it out keeps the link as it is. An unknown or deleted customer is refused with `422`.

11 November 2026 Added

- Products carry `receiptNote`: a plain-text note for the customer (up to 1,000 characters, `null` when there is none) that prints under the product's line on the order confirmation email and the invoice. The seller API's product create and update accept it, and it is translatable like the description. Each order line keeps the note as it read at purchase, so a later edit never changes an issued invoice.
- `GET /public/{pk}/filters` returns every filter for a store's products without the products: each filterable attribute and variant option with its `handle`, its values' `slug` s and counts, plus the price range (`priceMin`, `priceMax`, `currency`) and the `total` it covers. With no parameters it covers the whole catalogue, so you can build a fixed filter sidebar from one cached read. Pass `category`, `q`, `attr` and the other product-list filters to scope it. The JavaScript SDK's `products.filters()` calls it.

10 November 2026 Added Changed

- Each item of `nexusThresholds` on `GET /stores/{storeId}/tax-settings` now carries the period its threshold is measured over, `measurementWindow` (for example `rolling_12_months` for the UK or `calendar_current_or_previous` for most US states), with last calendar year's `previousRevenue`, `previousTransactions`, `previousPeriodStart` and `previousPeriodEnd`, and `dismissedReason`. The figures are now measured over each territory's own period instead of the calendar year, so `currentRevenue`, `periodStart` and `periodEnd` follow that period, and `nexusEstablished` can turn false again once a rolling period no longer passes the threshold.

10 November 2026 Added

- eWAY's card form in your own page. With `embedded: true`, `POST /public/{pk}/orders/{orderId}/pay` answers an eWAY order with an `eway_secure_fields` handoff: collect the card with eWAY Secure Fields, loaded with the `publicApiKey` from a new `eway` entry in a payment method's `sdk` (on `GET /public/{pk}/payment-methods`), then post the `secureFieldCode` to `POST /public/{pk}/orders/{orderId}/eway-pay`. When the answer carries `threeDSecure`, run eWAY's 3-D Secure SDK with its `accessCode`. Either way a code is single use, so save the fields again and post the fresh code to `POST /public/{pk}/orders/{orderId}/eway-3ds`. An account without 3-D Secure answers `chargeWithoutThreeDSecure: true` with nothing charged yet: the same fresh-code call charges once. Without `embedded`, eWAY stays the `redirect` handoff to its hosted page. eWAY's credentials gain `public_api_key`, required on a new save.

10 November 2026 Added

- Checkout refuses with `phone_required` when the store's `phoneNumberField` is `required` and the cart's delivery address (or, with no delivery, its billing address) has no `phone`. Send the shopper's phone on the address with `PATCH /public/{pk}/cart`.
- `GET /public/{pk}` carries the seller's checkout wording in every other language the store sells in:`checkout.translations` maps a language code to its `termsText`, `termsNoticeText` and `confirmationMessage`, and `paused.notices` maps a language code to the paused-shop message. A field missing from a language is not translated yet; show the untranslated value.
- Checkout refuses with `shipping_required` (`409`) when the cart has an item to deliver and no delivery option chosen: no `shippingRateId`, pickup location, local delivery area or carrier quote. Before, such an order went through with no shipping charge, to any address. Fetch `GET /public/{pk}/cart/shipping-options` for the address and set the shopper's pick with `PATCH /public/{pk}/cart`; an address with no options is one the store does not deliver to. A store with no shipping, pickup or local delivery set up at all is unchanged.

9 November 2026 Added Changed

- eWAY, a card gateway for Australian and New Zealand stores. `eway` is a new value of the gateway key (on payment settings, the storefront's payment methods and a checkout's `paymentMethod`). It takes cards in AUD and NZD, and `POST /public/{pk}/orders/{orderId}/pay` answers it with a `redirect` handoff to eWAY's hosted card page, which returns the shopper to your `returnUrl` once the payment is settled.
- Card routing with no default card gateway: when every switched-on card gateway is routed to its own currencies, a checkout in any other currency now offers no card gateway, where before it fell back to the first one.

9 November 2026 Added

- Card gateway by currency. A payment gateway gains `cardCurrencies`: the currencies a card gateway takes card payments in instead of the store's default card gateway, writable on `PUT /stores/{storeId}/payment-settings` (replaces the list; omit to keep it). A save is refused with a `422` when a currency is routed to a gateway that does not take cards, to one that cannot settle it, or to two gateways. `GET /public/{pk}/payment-methods` still lists at most one card gateway: the one routed for the `currency` asked for, else the default. The store currencies list gains `defaultCardGateway` and `cardGatewayByCurrency`, and `connectedGateways` now lists every card gateway some currency is routed to.

- Opening hours and closed date ranges on pickup locations. A pickup location gains `openingHours` (one `{weekday, opens, closes}` per open weekday, times `HH:MM` or both `null` when not set; `null` when the location has none) and `closedDates` (`{from, to}` ranges, inclusive), both writable on create and update. Pickup dates are now offered on the location's open days, and both pickup and local delivery dates skip its closed dates; the schedule's `weekdays` reads back as the open days and its `closedDates` is no longer where closed days are set. A pickup option in `GET /cart/shipping-options` and an order's `pickup` gain `openingHours`, to show beside the location.
- Closed dates are now set only on the location. A `pickupDates.closedDates` on a pickup location, or a `deliveryDates.closedDates` on one of its local delivery areas, sent on create or update is ignored: the field is still accepted and still read back, but it now holds the location's own closed days from today on, so an integration that sets holidays there must send them as the location's `closedDates` instead.
- Setting a location's `openingHours` to `null` (or no days) now leaves it no pickup days, rather than keeping the weekdays its pickup schedule held before. While its pickup asks for a date the update answers `422`; turn the schedule's `enabled` off first, or send `pickupDates` with its own `weekdays` in the same request.

8 November 2026 Added

- Local delivery dates. A local delivery area can ask the shopper which day their order arrives, with the same schedule as pickup dates. A local delivery option (`ldar_...`) in `GET /cart/shipping-options`'s `options` gains `availableDates`: the days that can be booked (`YYYY-MM-DD`, counted in the store's timezone), or `null` when the area does not ask. `PATCH /cart` accepts `deliveryDate` (with the `ldar_...` option as `shippingRateId`, or alone for the area already chosen) and answers `422` for a day not on offer; choosing another area or method clears it, and the cart gains `deliveryDate`. Checkout answers `409` with the new `delivery_date_required` when the area asks and the cart has no day, or a day that can no longer be booked. Orders gain `localDelivery.date` (and order summaries `deliveryDate`), the orders list takes `deliveryFrom`, `deliveryTo` and `sort=deliveryDate`, and an order update's `local_delivery` delivery takes a `date`. Delivery areas gain `deliveryDates`: `enabled`, `weekdays`, `minNoticeDays`, `maxDaysAhead` and `closedDates`.

6 November 2026 Changed

- A store moved from Shoprocket v2 that the seller switched back (`v2LinkState` `switched_back`) now refuses the same writes as a `linked` one, with 409 `store_linked_to_v2`, because it syncs from v2 again. Its orders, shipping labels and test orders stay writable, so orders taken while it ran on v3 can be fulfilled and refunded. A `switched` store refuses nothing. See [Moving from v2](https://shoprocket.io/docs/moving-from-v2.md).

6 November 2026 Added

- A signed item's picture can be a cart upload: `POST /cart/items` takes an optional `image`, the `token` from `POST /cart/uploads` (JPEG, PNG, WebP or GIF), only next to `signed`. The line's `imageUrl` is a resized copy on our media host, and wins over the signed payload's `image` URL. A token from another cart, one that no longer exists, or a PDF is refused with a 422. The widget adds `Shoprocket.cart.uploadFile(blob)` and `Shoprocket.cart.add({ signed, image })`. A signed `image` URL is now copied to our media host when the order is placed, and the order line's `imageUrl` points at the copy (the seller's URL is kept if the copy fails). See [Signed cart items](https://shoprocket.io/docs/signed-items.md#picture).

6 November 2026 Added

- A signed cart item can carry its own picture: an optional `image` in the signed payload, an absolute `https://` URL of at most 2048 characters. The cart line's `imageUrl` is that URL, and so is the order line's `imageUrl` on the order receipt after checkout; without it, the line shows the variant's or product's picture as before. An `http://`, `data:` or relative URL is refused with `signed_item_malformed`. See [Signed cart items](https://shoprocket.io/docs/signed-items.md).
- The store carries `v2LinkState`: `linked`, `switched` or `switched_back` for a store moved from Shoprocket v2, `null` for every other store. While a store is `linked` it still runs on v2 and syncs from it, so writes to its products, categories, attributes, product tabs, orders, customers, discounts, shipping, pickup locations, tax, checkout and invoice settings and team answer 409 with the new error code `store_linked_to_v2`. Reads are unchanged.

3 November 2026 Added

- Orders carry `importedFromV2`, `true` for an order the store took on Shoprocket v2 before it moved. v2 already invoiced these, so issuing an invoice for one answers 422 `invalid`.
- Signed cart items: `POST /public/{pk}/cart/items` takes `signed`, an item your server signed with the store's signing key (`v1.<keyId>.<payload>.<signature>`, HMAC-SHA256), carrying its own product, price, name, details and weight. The widget takes it as `Shoprocket.cart.add({ signed, quantity })`. See [Signed cart items](https://shoprocket.io/docs/signed-items.md).
- A refused signed item answers 422 `invalid` with a new `reason` field on the error, one of `signature_invalid`, `signed_item_expired`, `signing_key_revoked` and the others listed in the guide. `reason` is optional on every error and absent where an endpoint documents none.
- Cart lines carry `signed` (`true` for a line added from a signed item). Checkout can refuse with the new rejection `signed_item_invalid` and a `signedItem` object naming the line, when its key was revoked since it was added.
- `GET`, `POST /stores/{storeId}/signing-keys` and `DELETE /stores/{storeId}/signing-keys/{keyId}` list, create (returning the secret once, and giving older keys 7 more days) and revoke signing keys. They need `manage-api`.

3 November 2026 Added

- `PUT /stores/{storeId}/orders/{id}` takes `delivery`, which switches a placed order between `shipping`, `pickup` and `local_delivery` and sets or clears `pickup`, `pickupDate`, `localDelivery` and `shippingMethodName`. It changes no money: send `shippingTotal` for the charge. It answers 422 on a draft or cancelled order, once anything has shipped, and while the order is marked ready for pickup or out for delivery. Shipping and local delivery need a shipping address, and switching to pickup removes it.
- `notifyCustomer` on that route now also emails the customer about any other update that changed something. It still defaults to false.
- `POST /stores/{storeId}/orders/{id}/delivery-step/undo` takes back ready for pickup or out for delivery, while no units have gone.

2 November 2026 Added

- Orders now carry `balanceDue` and `overpaid`. When `PUT /stores/{storeId}/orders/{id}` changes the total of an order with a payment on it, `paymentStatus` is worked out from its payments against the new total, and a `paymentStatus` sent with `items` or a new total is ignored. Imported orders and orders with no recorded payment keep the status they have.
- `POST /stores/{storeId}/orders/{id}/payment-link` and `/payment-link/send` now work on a placed order that owes money: the link charges only what is owed, and the payment is added to the same order. They answer 409 once nothing is owed. `Cart.quote` gains `alreadyPaid` and `charge` for such a link, and `totals.amountDue` is what it charges.
- Invoices gain the kind `supplementary`: a document for a balance paid after the total was raised, with `reversesNumber` naming the invoice it adds to. The original stays as issued.

2 November 2026 Improved

- `PUT /stores/{storeId}/orders/{id}` now edits `items` in place instead of replacing them. Each line takes an optional `id` (`oitm_...`); a line sent without one is matched by product, variant, name and price, then by product and variant. A line's `id`, `properties`, download grants and subscription link now survive an edit. A line with shipped units or on a return cannot be removed or go below those units (422), and neither can an `id` that is not on the order. Stock holds follow the lines, and creating an order as `paid` now delivers its downloads, licence keys and gift cards.

2 November 2026 Added

- Tax registrations accept a third `scheme`, `small_seller`: an EU business under the EU's EUR 10,000 limit charges its own country's rate on consumer sales across the EU. It is only for the country in the store's business address and not alongside `oss`; anything else answers 422. Tax settings gain `businessCountry` and `smallSellerThreshold`. On those orders the tax row's name carries the country, such as `VAT (DE)`, so read `rateMilliPercent` rather than assuming the rate is the destination's.

2 November 2026 Added

- New product `kind`: `service`, for something that is neither shipped nor downloaded. A service never requires shipping and cannot be part of a bundle. Existing products with no shipping, no file and no licence key now read `service` instead of `physical`. If you branch on `kind`, treat an unknown value as non-physical.

- Two features now follow the plan they are sold on, and answer a `plan_limit` 403 (with `metric` naming the feature) on a plan without them. Live carrier rates (`automated-shipping-calculations`, Business and up): `POST /stores/{storeId}/shipping-methods` refuses `"type": "carrier"`, and an existing carrier method quotes only its fallback price. Customer groups (`customer-groups`, Business and up): a discount write that sets or changes `customerTagIds`, and a tax settings write that sets or changes `exTaxDisplayTagIds`, are refused; re-sending the values already saved is accepted. Customer accounts (`customer-dashboard`) are on every plan.

30 October 2026 Added

- New error code `two_factor_required` (403): the caller must turn on two-factor sign-in on their account before this request can succeed. Nothing about their permissions is wrong, so send them to their account settings rather than reporting a missing permission.

29 October 2026 Added

- Mix-and-match boxes: a `bundle` whose contents the shopper chooses. Products gain `bundleChoice` (`null` on a fixed bundle and every other kind): the box's exact `size`, where its items come from (`source`: `category` or `list`, with `categoryId`), and the `items` to choose from, each with `sellableQuantity` (`null` when it never runs out). `POST /public/{pk}/cart/items` accepts `bundleSelections`: the chosen variant ids and how many of each, totalling exactly the size; it answers 422 otherwise. A cart line lists the mix in `components`, and two different mixes are two lines. The seller product writes accept `bundleChoice`.

29 October 2026 Added

- Per-product delivery methods. Products gain `deliveryMethods`: any of `shipping`, `pickup` and `local_delivery` (all three by default), accepted on product create and update. Cart lines and the cart gain `deliveryMethods` too; the cart's is what every shipped line allows, and is what checkout offers. `GET /cart/shipping-options` leaves out what a line rules out (no shipping rates when a product is pickup only, an empty `pickup` list when one cannot be collected), `PATCH /cart` answers `422` for a selection a line rules out, and checkout answers `409` with `shipping_changed` for one, or with the new `delivery_unavailable` when the lines share no method at all (a line has to be removed).
- Pickup dates. A pickup location can ask the shopper which day they collect. Each entry in `GET /cart/shipping-options`'s `pickup` list gains `availableDates`: the days that can be booked (`YYYY-MM-DD`, counted in the store's timezone), or `null` when the location does not ask. `PATCH /cart` accepts `pickupDate` (with `pickupLocationId`, or alone for the location already chosen) and answers `422` for a day not on offer; the cart gains `pickupDate`. Checkout answers `409` with the new `pickup_date_required` when the location asks and the cart has no day, or a day that can no longer be booked. Orders gain `pickup.date` (and order summaries `pickupDate`), and the orders list takes `pickupFrom`, `pickupTo` and `sort=pickupDate`. Pickup locations gain `pickupDates`: `enabled`, `weekdays`, `minNoticeDays`, `maxDaysAhead` and `closedDates`.

24 October 2026 Added

- A shop icon, for browser tabs, bookmarks and home screens. The store object gains `icon` (a media object, or `null`); `PUT /stores/{storeId}` accepts `iconMediaId`. `GET /public/{pk}` and the hosted shop bootstrap gain `icon`: use it as your favicon. With none set, the hosted shop uses a roughly square `logo`, else the shop's first letter on its brand colour.

23 October 2026 Added

- A second logo, for dark backgrounds. The store object gains `logoDark` (a media object, or `null`) and `logoIsLight` (`true` when the main logo is mostly white); `PUT /stores/{storeId}` accepts `logoDarkMediaId` and `logoIsLight`. `GET /public/{pk}` and the hosted shop bootstrap gain `logoDark`: show it where your logo sits on a dark background, and `logo` everywhere else.

21 October 2026 Added

- `GET /public/{pk}` and the hosted shop bootstrap gain `unclaimed`: `true` for a test store made with `POST /agent-stores` that no one has claimed yet. Such a store sends no email, so do not tell a shopper a confirmation is on its way; the widget's order confirmation drops its "confirmation email has been sent" line. It turns `false` as soon as the store is claimed.

21 October 2026 Added

- Test stores for AI code builders. `POST /agent-stores` needs no authentication: it creates a store in test mode for someone with no Shoprocket account and answers with its `publishableKey`, a `secretKey` scoped to the catalogue and shipping methods (it expires with the store and is revoked when the store is claimed), a `claimUrl` for the person, `shopUrl` and `expiresAt` (7 days). Signing up at the claim URL makes the store theirs with everything in it. Until then the store takes test checkouts only, sends no email, holds at most 25 products and 50 MB of images, and every other seller call answers `403` with the new error code `claim_required` (so can `POST /stores/{storeId}/shipping-methods` for a `carrier` method). Creating is limited to 10 per IP address per day (`429`).

21 October 2026 Added

- Customer tags drive rules. A discount takes `customerTagIds` (customer tag ids, `ctag_...`): empty means everyone, otherwise only a signed-in customer carrying one of those tags can use it. It is checked on the cart and at checkout against the `X-Customer-Token` session, never against an email typed at checkout, so a guest never qualifies; a refused code reads `discountError.reason` `customer_tags`. On `PUT /stores/{storeId}/discounts/{id}` an absent `customerTagIds` leaves it unchanged. `exTaxDisplayTagIds` on `GET` and `PUT /stores/{storeId}/tax-settings` names the tags whose signed-in customers see prices without tax by default with the `toggle` price display; `taxDisplay.customerDefaults` on `GET /public/{pk}` says such a rule exists, and `GET /public/{pk}/customer/me` returns the signed-in customer's own `taxView` (`ex` or `null`). `GET /stores/{storeId}/customer-tags` lists each tag's `usedBy` rules; renaming a tag keeps every rule, and merging or deleting one moves or removes it from every rule.

21 October 2026 Added

- Widget: `Shoprocket.cart.add({ variantId, quantity })` adds to the cart from your own button the way the widget's own buttons do. The shopper sees the "Added to cart" card (or the error card when the store refuses the add), and `shoprocket:product:added` and the `shoprocket:add_to_cart` analytics event fire. It returns a promise for the new cart and rejects with an `Error` whose `message` says why. Use it in place of `getSdk().cart.addItem()` followed by `cart.open()`, which adds silently.
- `POST /public/{pk}/cart/items` now refuses a variant that is sold out, or has fewer left than asked for, with a `409` (`conflict`) whose message says so, instead of adding a line checkout would refuse. A variant whose policy is `continue` (backorders) is never refused.

21 October 2026 Added

- Prices with and without tax. `priceDisplay` on `GET` and `PUT /stores/{storeId}/tax-settings` is one of `single` (the default: prices as entered, the only behaviour before), `both` (the price with and without tax together) or `toggle` (the shopper switches). `GET /public/{pk}` carries it as `taxDisplay`: `null` for a single-figure store, otherwise the `mode`, the store's `pricing`, a `label` (`vat` or `tax`) and its home country's `rates` to work the other figure out with. Each cart line now carries its product's `taxClass`, so a front end can print the line with or without tax at the right rate. All of it is display only: what checkout charges does not change.

21 October 2026 Added

- A sign-up pop-up now says where its picture goes: `popup.imageLayout` on each promo in `GET /public/{pk}`, and `imageLayout` on the seller's promo read and write, one of `top` (a banner above the words, the default and the only look before), `side` (beside the words; above them on a phone) or `background` (behind everything, tinted dark so light text reads). It means nothing while `imageUrl` is `null`.
- Every product read now says what a listing page prints, so `GET /public/{pk}/products` needs no second call per row: `priceMin` and `priceMax` (the cheapest and dearest variant price in minor units, both `null` when `priceOnRequest` is `true` or there is no price), `categories` (each category's `id`, `name` and `slug`, translated for `?locale=`; public reads list only categories shoppers can browse, and `categoryIds` stays as it was), and `attributes` on list rows too, not only on the single product (visible ones only, as before).

19 October 2026 Added Changed

- A new first-party App, `quickbooks` (QuickBooks Online), in `GET /stores/{storeId}/apps` and `PUT /stores/{storeId}/apps/{appId}`, with `attention: true` on the same terms as Xero's. It is no longer a coming-soon app, so `quickbooks` leaves `POST /stores/{storeId}/apps/waitlist/{appId}`.

19 October 2026 Added

- `POST /public/{pk}/cart/items` takes an optional `sourceUrl`: the page the shopper is adding from, usually `window.location.href`. Every cart line now returns it as `sourceUrl` (`null` when none was sent), so a cart can link a line back to the page it came from. Only http(s) URLs of up to 2048 characters are kept; anything else is ignored, never refused. A repeat add of the same line keeps the page it first came from.

18 October 2026 Added

- Four new first-party Apps in `GET /stores/{storeId}/apps` and `PUT /stores/{storeId}/apps/{appId}`: `translations` (extra shop languages), `multi_currency` (extra shopper currencies), `redirects` and `b2b` (e-invoice settings). Each is in use, and so cannot be removed, while the store has another language switched on, an extra currency, any redirect, or e-invoice files attached to its invoice emails. Nothing about the languages, currencies, redirects or invoice endpoints themselves changed.

17 October 2026 Added

- `GET /stores/{storeId}/verifactu` also returns `signedRecords` (how many billing records carry the seller's XAdES signature) and `certificate`: the qualified certificate that signs a Spanish store's Veri\*Factu records (`holder`, `issuer`, `nif`, `validFrom`, `validTo`, `fingerprint`, `uploadedAt`), or `null`. The certificate itself is uploaded from the dashboard only; its private key is never returned by any endpoint.

17 October 2026 Added

- E-invoice files for business orders. When the buyer gave a VAT number and the store is in the EU, each invoice and credit note also gets two EN 16931 XML files: XRechnung 3.0 (UBL) and CII (the XML a ZUGFeRD / Factur-X PDF embeds). Invoices carry a new `einvoice` (`formats`, plus `blocked` naming what was missing when none could be made), and the order status page's `documents` carry `einvoice` download links. The files are served from `/public/invoices/{token}/einvoice/{format}` with the document's own token.

17 October 2026 Added

- The public store config's `analytics.pixels` gains `gtmContainerId`: the seller's Google Tag Manager web container (`GTM-...`), or `null`. The widget loads it under the same consent rule as the pixels and pushes `view_item`, `add_to_cart`, `begin_checkout` and `purchase` to `dataLayer` in GA4's ecommerce shape (value in major units, `transaction_id` = the order id).
- `GET` and `PUT /stores/{storeId}/tracking-settings` take and return `gtmContainerId` (`null` clears it).

17 October 2026 Added

- Invoices carry a new `documentType`: `invoice`, or `receipt` for a store whose business address is in Portugal. A receipt says it is not an invoice (Portuguese invoices must come from AT-certified software), and its `number` is the order's own (`R-1042`, `R-1042-1` for a refund), taken from no invoice series. The order status page's `documents` carry the same `documentType` when it is `receipt`.
- `pixelContext` on `POST /public/{pk}/cart/checkout` also takes `gaClientId` and `gaSessionId` (from the `_ga` cookies) and TikTok's `ttp` / `ttclid`. A store with the GA4 Measurement Protocol or the TikTok Events API set up sends the paid order from the server too, deduplicated with the browser on the order id. GA4 needs `gaClientId`: without it nothing is sent to GA4.
- `GET /stores/{storeId}/tracking-settings` returns `ga4ApiSecretSet`, `ga4ApiSecretLast4`, `ga4ServerEvents`, `tiktokEventsTokenSet`, `tiktokEventsTokenLast4`, `tiktokTestEventCode` and `tiktokServerEvents`. Every `*ServerEvents` object gains `lastErrorWillRetry`: true when the last failure is temporary and will be retried. `PUT` takes a write-only `ga4ApiSecret` and `tiktokEventsToken` (`null` removes either) and `tiktokTestEventCode`.

17 October 2026 Added

- `POST /public/{pk}/cart/checkout` takes an optional `pixelContext`: the shopper's ad consent (`granted`, `denied` or `unknown`) and Meta's `fbp` / `fbc` cookies. The widget sends it, and a store with the Meta Conversions API set up then sends the paid order to its pixel from the server too, deduplicated with the browser's Purchase on the order id. A checkout without it gets no server-side ad events.
- `GET /stores/{storeId}/tracking-settings` returns `metaCapiTokenSet`, `metaCapiTokenLast4`, `metaTestEventCode` and `metaServerEvents` (the last event Meta accepted or refused). `PUT` takes a write-only `metaCapiToken` (`null` removes it) and `metaTestEventCode`.
- `GET /stores/{storeId}/invoice-settings` returns `regime`: `standard`, `pt_receipt` or `es_verifactu`. The new `GET /stores/{storeId}/verifactu` reports a Spanish store's Veri\*Factu billing records (`issuerNif`, `records`, `events`, `lastRecordAt`, `lastHuella`).

17 October 2026 Added Changed Removed

- The new `POST /stores/{storeId}/reviews/{id}/edit-requests` emails the reviewer of a customer's review (`organic` or `requested`) a link to edit it themselves, stars included; their edit goes back to `pending`. Once a day per review (429 with `Retry-After` after that), within the store's 50 review requests a day; 422 for an imported or manual review, or one with no email.
- A text edit through `PUT /stores/{storeId}/reviews/{id}` on a customer's review now emails the reviewer what changed, at most once a day, with a link that restores their own words; after a restore the text is `locked`. A seller review carries `editNotice` (`none`, `queued` or `sent`), `editNoticeSentAt` and `restoredAt`.
- `POST /stores/{storeId}/reviews` is gone: a store can no longer write a review. The new `POST /stores/{storeId}/reviews/requests` takes `{ productId, name, email }` and emails that person a link to review the product themselves. Their review arrives with the new `source` value `requested`, and is a verified purchase only if they bought the product with that email. A store can send 50 requests a day; past that the call is a 429 with a `Retry-After` header.
- `PUT /stores/{storeId}/reviews/{id}` no longer changes a review's `rating` (a different value is a 422). On a review a customer wrote (`organic` or `requested`) the author is fixed too, and `title` plus `content` may differ from what the customer wrote by at most 30 characters in total, counted from their original text; past that, 422. Imported and manual reviews stay editable apart from the rating. A reviews import no longer changes a review's rating, and reports a row that matches a customer's review as an error instead of rewriting it.
- A seller review now carries `textEdits` (`free`, `typos` or `locked`), `originalTitle`, `originalContent` and `sellerEditedAt`. Public reviews can carry `source` `requested`; the widget and hosted shop label `imported` and `manual` reviews "Imported".

17 October 2026 Added

- The reverse charge for EU business buyers. `GET /stores/{storeId}/tax-settings` and its update carry `reverseChargeEnabled`. When it is on, a buyer VAT number sent to `PATCH /cart` is checked with VIES (or HMRC for a UK number), and the cart returns `taxNumberCheck` (`status`: `valid`, `invalid`, `unavailable` or `unchecked`, and `reverseCharge`).
- Checkout refuses a number the validator rejected with the new rejection `tax_number_invalid` (`409`). Orders gain the tax status `reverse_charge` and a `taxNumberCheck` object (status, when it was checked, the validator's consultation number, and the registered name and address).

17 October 2026 Added

- `GET /stores/{storeId}/invoice-settings` and `PUT /stores/{storeId}/invoice-settings` read and set a store's invoice and credit note prefixes and next numbers, its legal footer text and its small-business VAT exemption. A next number is refused with `409` once that series has issued a document, so the series stays gapless.
- An order's tax lines carry `taxableAmount`, the net amount each rate was charged on, and its lines carry `taxRateMilliPercent`, the rate each was taxed at. Both are `null` on orders placed before they were recorded. Creating or editing an order accepts an optional `taxableAmount` on each tax line.

17 October 2026 Added Changed

- A new first-party App, `xero`, in `GET /stores/{storeId}/apps` and `PUT /stores/{storeId}/apps/{appId}`. Each app in the list may now carry `attention: true` when something in it needs the seller (for Xero: the connection was refused, or a day's sales could not post).
- The coming-soon app `accounting` is now `quickbooks` in `POST /stores/{storeId}/apps/waitlist/{appId}` and the page's `waitlist`.

17 October 2026 Added

- Reviews can carry the reviewer's photos and a short video. Each review in `GET /public/{pk}/products/{idOrSlug}/reviews` has a `media` array (finished files only, in the reviewer's order), and `meta.media` lists the newest photos across all of the product's approved reviews, each with its `reviewId`, for a photo strip. A review in `GET /stores/{storeId}/reviews` has `media` too, including a video still being processed, and `PUT /stores/{storeId}/reviews/{id}` takes `mediaIds`: the files to keep. A seller can remove a reviewer's photo, never add one.

16 October 2026 Added

- `POST /stores/{storeId}/imports` and `POST /stores/{storeId}/imports/from-file-url` also accept an Excel or OpenDocument spreadsheet (`.xlsx`, `.xlsm`, `.xls`, `.ods`). The first sheet with data is read as the rows a CSV would give: dates come through as `YYYY-MM-DD`, numbers in full, and a zero-padded number format keeps its leading zeros.

16 October 2026 Added Changed

- A review's `authorEmail` can now be `null`: an imported review whose source had no email (an Etsy export carries none) is stored without one. Reviews you create or submit still require it.
- `POST /stores/{storeId}/imports` also accepts a JSON file (an array of objects, or an object holding one, like Etsy's `{ count, results }`), read as the same rows a CSV would give. The new `POST /stores/{storeId}/imports/from-file-url` takes `{ type, url }`, fetches a public CSV or JSON file (10MB, 15 seconds) and creates the same pending import an upload does.

15 October 2026 Added

- Shoppers can sign in from any page with a cart: the floating cart button has a person icon that opens the account drawer, showing the shopper's initials once signed in. Checkout settings carry it as `cartButtonAccount` (default `true`). Your own link can open the same drawer with `data-shoprocket-account-toggle`, which also gets `data-signed-in` while a shopper is signed in, or with `href="#!/login"`, which now works the same as `#!/account`.

15 October 2026 Improved

- The reference now describes every query parameter and every request and response field: what it is, its unit (money is always an integer in the currency's minor unit), its format, its allowed values and what `null` means. Documentation only: the API behaves as before.

15 October 2026 Added

- The catalogue embed has attribute filters: one dropdown per attribute or variant option, with counts, the same filters as the hosted shop. They are on by default; turn them off with the `filters:attributes` feature, and limit them to some attributes with `data-filter-attributes="colour,size"`. A filtered view keeps its `attr` in the page URL, so it can be shared. The JavaScript SDK's `products.list()` takes `attr` and `facets`.

15 October 2026 Changed

- The reference now explains every filter on `GET /public/{pk}/products`. `attr` filters by attributes and variant options, including your own: `attr=colour:red|blue,brand:fender`, a range as `length:100..250`. Values within one attribute match any; separate attributes must all match. Ask once with `facets=true` for every attribute's `handle` and its values' `slug` s. Documentation only: the API behaves as before.

14 October 2026 Changed

- The API is on every plan, Starter included: secret keys from `/stores/{storeId}/api-keys` work whatever the store pays for. Webhooks stay on Growth and up, so `POST /stores/{storeId}/webhooks` now answers `403` `plan_limit` on a plan without them. Endpoints a store already has keep delivering and stay editable.

14 October 2026 Added Changed

- One email look per store. `PUT /stores/{storeId}` takes `emailLook`: a `theme` (`shop` for the store's own look, or a theme id) plus optional `background`, `card`, `text`, `button`, `buttonText` and `link` colours, `corners` (`square`, `soft`, `round`) and a `fontPairing`. Every email with no look of its own wears it: campaigns, automated emails and the order and account emails. The store object returns it; `null` means the store's own look, including its brand colour and font pairing.
- A campaign's `theme` also accepts `shop`, and campaigns take a `look` of their own style changes in the same shape (without `theme`). A `null` theme now follows the store's default email look rather than its shop theme.

13 October 2026 Added Changed

- Local delivery. A pickup location on `/stores/{storeId}/pickup-locations` carries `deliveryAreas` (the whole list on create and update; an area left out is removed, an `id` keeps one), `offersPickup` (false for a base you only deliver from), and read-only `geoStatus` and `point`: where its address is on the map, which a radius area measures from. An area is a `radius` in `km` or `mi` (at most 160 km / 100 mi, never across a border) or a `postcodes` list, with a `price`, an optional `minOrder`, `orderValueBands`, `distanceBands` and `instructions`. An update that leaves a field out now leaves it alone (it used to reset the price, status and ready time).
- For storefronts: `GET /public/{pk}/cart/shipping-options` offers one `ldar_` option, the cheapest area covering the address, beside the other rates; choose it with `shippingRateId` on `PATCH /public/{pk}/cart`. `GET /public/{pk}/places/details` also returns `location` and a signed `geo` token: send it back as `shippingAddress.geo` so a radius area knows where the address is without a second lookup.
- Orders carry `localDelivery` (the area, its location, the distance, and when it went out and was delivered). `POST /stores/{storeId}/orders/{id}/local-delivery` with `step` `out_for_delivery` or `delivered`; delivered fulfils every unit still owed.

- Shipping zones narrowed by postcode. Each of a zone's `regions` on `/stores/{storeId}/shipping-methods` (the reads, and the input on create and update) carries `postcodes`: a list such as `["L", "CH41-CH49", "CH6*"]`, or null for every postcode. A plain entry matches where the postcode's parts break (`L1` matches L1 8JQ, not L10 1AA), a range takes district numbers in one area, and a trailing `*` is a plain prefix. A region with a list is more specific than a state or a whole country. Entries are stored upper case; an unrecognised one is refused with 422.
- `GET /public/{pk}/cart/shipping-options` also answers `addressRequired: true` when nothing is offered, the shipping address has no postcode yet, and a zone for its country is narrowed by postcode: ask for the postcode rather than saying the shop does not deliver there.

13 October 2026 Added

- A draft order's payment link. `POST /stores/{storeId}/orders/{id}/payment-link/send` emails the draft's customer the draft (worded as a quote when it was made from a quote request, as an order otherwise) with a link that opens checkout for exactly that draft, at its own prices, shipping and discount; `POST /stores/{storeId}/orders/{id}/payment-link` returns the same link without emailing. Both answer `{ url, expiresAt, sentAt, sentTo }`, restart the link's 30 days and keep its URL. Paying the link completes the draft into an ordinary order (a real number, `order.paid`, the confirmation email). Orders carry `quoteSentAt`, `quoteSentTo` and `quoteExpiresAt`: when the payment link was last emailed, to whom, and when it stops working. While a customer's payment for a draft is moving, `PUT` and `DELETE` on it answer `409`.
- For storefronts: `POST /public/{pk}/pay-links/{token}/open` answers a payment link's `state` (`payable`, `paid`, `expired` or `gone`) and, when payable, the `cartToken` of the draft's cart. That cart reads with a `quote` field; its lines, codes, gift card and delivery cannot be changed (they answer `409`), and checking it out answers `quote_unavailable` once the draft changed or can no longer be paid. Pay it with `POST /public/{pk}/orders/{orderId}/pay` as usual. The widget opens `#!/pay/{token}` itself.

12 October 2026 Added

- An embed's own words in every language. `GET /public/{pk}/embeds/{id}/config` carries `words`: locale to configuration key to words, for each language the shop sells in, when the embed has text of its own (`buttonText`, `optionsButtonText`, `viewButtonText`, `label`, `headline`, `subline`, `placeholder`). `configuration` still holds them in the shop's default language. Show the shopper's language's words; a language missing a key has no translation yet, so show your own default for that key rather than the default language's words. Absent for a shop that sells in one language. The seller read `GET /stores/{storeId}/embeds/{id}` carries the same `words`.
- A catalog embed's configuration takes `buttonText`: the Add to cart words on its cards and on the product pages it opens, null for the store's wording.

12 October 2026 Added Changed

- Cancellation emails, and cancel with a refund in one call. `PUT /stores/{storeId}/orders/{id}` takes three optional fields, read only on the save that moves the order into `cancelled`: `notifyCustomer` (default `false`) emails the shopper that their order was cancelled, with the reason in plain words; `refund` sends back everything still refundable before the cancel is written, and the cancellation email carries it (no separate refund notice); `acknowledgeManualRefund` accepts that part of it has to be sent by hand. A refund that cannot go ahead answers `422` with the refund route's `rejection` body and leaves the order untouched. A cancel that refunded also fires `order.refunded`. Leaving all three out keeps today's behaviour.
- Review reply emails. `PUT /stores/{storeId}/reviews/{id}` takes an optional `notifyReviewer` (default `false`). Set it to `true` with a reply and the reviewer is emailed once, in the language they reviewed in, with their review and your reply, when the review is published. Editing the reply later never emails again. A review now reads `replyNotice` (`none`, `queued` or `sent`) and `replyNoticeSentAt`. A public review's `reply` is now translated with the review into the shop language the request asks for.
- Refund emails. `POST /stores/{storeId}/orders/{id}/refunds` takes an optional `notifyCustomer` (default `false`). Set it to `true` and the shopper is emailed a refund notice with the amount, where it went and the credit note, once the money has actually gone back: at once for a tender that refunds on the spot, or when the gateway settles a refund that started `pending`. A failed refund sends nothing. Leaving it out keeps today's behaviour: no email.
- Quotes and enquiries. A product read (`GET /public/{pk}/products`, the single product, the hosted shop's reads and the cart's suggestions) carries `purchaseMode` (`buy` or `enquire`) and `priceOnRequest`. When `priceOnRequest` is true the price is hidden from shoppers: every variant's `price` and `compareAtPrice` are `null`, `priceBreaks` and `subscriptionPlans` are empty and a bundle's part prices are `null`. Show your own words (we show "Price on request") rather than a number. A product set to `enquire` cannot be added to the cart unless the store is in quote mode (422).
- A price filter (`priceMin`/`priceMax`) leaves products with a hidden price out, a price sort puts them last, and the list's `meta.priceMin`/`meta.priceMax` ignore them.
- New: `POST /public/{pk}/quote-requests` sends the store a quote request, one product's enquiry or a whole cart, with `name`, `email`, optional `phone` and `message`, and `lines` of `{ variantId, quantity }`. It answers `{ ok: true }`; the store emails the shopper a copy.
- The store bootstrap (`GET /public/{pk}` and `GET /public/shops/{slug}`) carries `quotes: { mode, hidePrices }`. In quote mode, `POST /public/{pk}/cart/checkout` refuses with the new rejection `quote_only`: send the cart as a quote request instead. Cart lines carry `priceOnRequest`, true for a line whose price is hidden (held at 0).
- Two new widget events: `shoprocket:enquire` opens the enquiry form (detail `{ product, variantId?, quantity? }`, or `{ cart: true }` for the cart), and `shoprocket:quote:requested` fires once a request is sent.
- The store read's `apps` can hold `facebook_instagram`: the Facebook & Instagram app, which connects the store's Meta business and keeps a Meta catalogue fed from the store's product feed. Like every app it only decides which screens the dashboard shows.
- Seller API: `GET /stores/{storeId}/contact-messages` takes `?kind=quote_request` and each message carries `kind`, `lines`, `currencyCode` and `draft`; `POST /stores/{storeId}/contact-messages/{id}/quote` makes the draft order (once per request); and `GET/PUT /stores/{storeId}/quote-settings` reads and sets quote mode.
- The words Shoprocket writes for a banner or pop-up when the seller leaves them blank (a sale bar's `text`, a pop-up's headline, its `popup.body` and `popup.offer`) now read in the shopper's language instead of always English, with money and percentages formatted that language's way. Words the seller typed are sent exactly as written.
- The store bootstrap (`GET /public/{pk}`) takes `?locale=`: its `promos` read in that language when the store sells in it, else in the store's own language. Each item also carries `words`, the same derived words keyed by every other language the store sells in (plus English), so a client that settles on a language after the bootstrap arrives can show its own without a second request.
- A pop-up sign-up (`POST /public/{pk}/promos/{id}/signup`) takes `?locale=` too: the `offer` it returns and the code email it sends are in that language.
- Shipping labels are now bought on the store's own ShipStation account and paid from the seller's ShipStation balance, never the Shoprocket bill. An order's `shippingLabels` entries no longer carry `billedAmount`, `billedCurrency`, `billingStatus` or `stripeInvoiceId`: a label's `cost` and `currency` are what ShipStation charged.
- ShipStation is an App: `shipstation` is a new `appId` for `PUT /stores/{storeId}/apps/{appId}` and in `GET /stores/{storeId}/apps`, in use (so Remove answers 409) while the store has a ShipStation account. It is no longer a coming-soon id, so `POST /stores/{storeId}/apps/waitlist/{appId}` refuses it (422) and the waitlist never lists it.

11 October 2026 Added Changed

- An embed's `fontsHref` (`GET /public/{pk}/embeds/{id}/config`) is now a stylesheet on our own font host, the folder beside the widget loader (for example `https://widget.shoprocket.dev/fonts/cormorant-garamond_jost.css`), not Google Fonts, and every embed loads it. The font files sit beside it, so a page with our widget makes no request to Google for its typefaces. A page with a Content Security Policy must allow the widget's own host in `style-src` and `font-src` as well as `script-src`; if it does not, the products still show, in the page's fallback font.
- The store bootstrap's `branding` (`GET /public/{pk}` and `GET /public/shops/{slug}`) carries the same stylesheet as `fontsHref`, or null for a theme of system faces, so a page with no embed on it (the floating cart alone) still draws in the store's fonts.
- The embed setting `themeFonts` is retired: every embed draws in the store design's fonts. A stored embed that still has it parses as before, and the key is left out of every embed read. A font override of `inherit` (the store's `font-body` and the other font tokens) is no longer accepted, and the store reads leave it out.
- The store read carries `apps`: the first-party Apps the seller has switched on in the dashboard (`reviews`, `gift_cards`, `developer_tools` and so on), or null before the store has been worked out. It only decides which screens the dashboard shows. Every endpoint keeps working whatever it holds, so an integration never needs to check it.

9 October 2026 Added Changed

- A store whose paid subscription has ended (the card failed after every retry, or the seller cancelled and the period ran out) now waits for a plan the same way a lapsed trial does: `402` `plan_required` on that store's writes and the shop paused for shoppers. The store read and the billing read carry `planRequiredReason` beside `planRequiredAt`: `trial_ended`, `payment_failed` or `cancelled`, and null when the store is not waiting for a plan.
- The store read carries `paymentFailing`, true while the store's last subscription payment failed and is being retried. The store keeps working meanwhile.
- The embed list (`GET /stores/{storeId}/embeds`) carries `siteCode`: the widget loader on its own, the one line a seller adds to their site's header so the cart, live chat and analytics run on every page. Every embed's own `embedCode` still starts with the same line, and a second copy of it on one page does nothing, so a snippet pasted somewhere without the header line keeps working.
- `GET /public/{pk}` accepts `surface=preview`, which the dashboard's own embed preview sends. It is answered like `website`. Embeds added to a page after the widget has loaded now mount on their own, with no call to make.

8 October 2026 Added

- A new error code, `plan_required`, with status `402`. When a store's free trial ends without a plan, the seller API refuses that store's writes with it until a plan is chosen in Settings > Billing. Reads keep working, and so do the billing routes. The store read (`GET /stores/{storeId}` and the list) carries `planRequiredAt`, set while the store is waiting for a plan, and the billing read carries it too.
- While a store is waiting for a plan its shop behaves exactly as a paused one: `GET /public/{pk}` carries `paused` with the platform's notice, adding to the cart and checking out return `409`, `payment-methods` reports `checkoutDisabled`, and the product feeds stop. Nothing new to handle if you already handle a pause.

7 October 2026 Added

- A new plan feature, `chat-ai`, in a store's `features`: the live chat's AI assistant, on Business and Plus. Live chat itself (`storefront-chat`) is now listed on every plan, which is what it already was.
- A new team permission, `manage-affiliates`, for the seller's affiliate programme: adding affiliates, changing their rates and rejecting a commission. It appears wherever permissions are listed (team members and API key scopes). The affiliate programme's own endpoints are dashboard-only for now.
- Live chat follows where the seller wants it. `GET /public/{pk}` takes an optional `surface`: `shop` on the hosted Shoprocket shop, `website` (the default) everywhere else. `chat` is `null` for a surface where the seller has switched chat off, so a custom storefront on the seller's own site sends nothing and gets the website answer. `chat` also carries `side` (`"right"` or `"left"`) and `offsetY` (px): the chat draws itself there, and a floating button of your own in that bottom corner should sit above it. Keep the chat off checkout; the Shoprocket widget hides it there.
- The floating cart button's distance from the page's edges. The checkout settings (`GET` and `PUT /stores/{storeId}/checkout-settings`) and the `checkout` object on `GET /public/{pk}` carry `cartButtonOffsetX` (px from its side) and `cartButtonOffsetY` (px from its top or bottom edge), whole numbers from 0 to 200, 20 by default. Neither applies at the two middle positions, where the button is a tab on the page edge. A cart placed with `data-shoprocket="cart"` takes the same as `data-button-offset-x` and `data-button-offset-y`.

6 October 2026 Added Improved

- The seller API's store read (`GET /stores/{storeId}` and the list) carries `chatEnabled`, the seller's switch for live chat on their shop.
- Live chat. `GET /public/{pk}` and the hosted shop's bootstrap carry `chat`: `{ scriptUrl, site }` when the store has live chat switched on, or `null`. Load `scriptUrl` as it is, as a `<script type="module">`, once per page; never build it yourself. The Shoprocket widget already does this, on the hosted shop and on an embed alike. For a signed-in shopper, `GET /public/{pk}/customer/chat-identity` (with the customer session token) returns `{ it, name, email }`, or `null` when the store's chat is not ready; the widget hands it to the chat before the script loads, so the seller sees who is writing. `it` is opaque and lives five minutes, so it is asked for per page.
- A catalog read's `featured` sort (the default) is now always the seller's own order: products the seller has placed first, in their places, then the rest newest first. With no category the places are store-wide; with a category they are that category's. It no longer goes through the store's or the category's `productSort` setting, which defaulted to best selling; that field is still accepted on `PUT /stores/{storeId}/product-order` and on categories but no longer changes any listing.
- `GET /stores/{storeId}/products` takes `category`: a `cat_` id, listing only the products in that category. The bulk endpoint's `filter` takes it too, so "select all" reaches the same products.
- EU product safety (GPSR). The single-product read (`GET /public/{pk}/products/{idOrSlug}`) carries `productSafety`: `manufacturer` and `euResponsiblePerson` (each `{ name, address, contact }` or `null`) and `warnings` (plain text in the requested language), already resolved against the store's defaults, or `null` when there is nothing to show. A front end selling into the EU should render it on the product page. Products also carry the raw `safetyManufacturer`, `safetyEuRep` and `safetyWarnings`, which the seller API's product create and update accept; the store read and update carry the defaults as `safetyManufacturer` and `safetyEuRep`. The Google feed sends them as `g:product_detail` rows under a "Product safety" section, and UCP product payloads as `metadata.product_safety`.
- `GET /public/{pk}` and the hosted shop's bootstrap now carry `labels`: the store's own words for a few storefront labels (add to cart, view product, checkout, view cart, sold out), by language, as `{ "de": { "add_to_cart": "Kaufen" } }`. A language with no entry uses the standard copy. The seller API's store read and update (`GET`/`PUT /stores/{storeId}`) carry the default language's set as `storefrontLabels`. This replaces the single `addToCartLabel` on the checkout settings, which was added earlier today and is gone.
- Checkout settings carry `billingAddressMode`: `full` (the default) or `minimal`, where the billing address asks only country, region and postcode. A delivery address is never affected. Checkout refuses with `billing_country_required` a payable order that has neither a delivery address nor a billing country, and with `company_required` or `address_line2_required` a blank field the seller marked required.
- `PATCH /public/{pk}/customer/me` lets a signed-in shopper change their own first name, last name and phone. An absent field is left as it is and an empty string clears it; the email is the sign-in identity and cannot be changed. The change sends `customer.updated`, as a seller edit does. `GET /public/{pk}/customer/me` now answers the `phone` too.
- `GET` and `PUT /stores/{storeId}/product-order`: the shop's own "All products" sort (`manual`, `best-selling`, `name`, `-name`, `price`, `-price` or `newest`) and, for `manual`, the order itself as a list of product ids. It is what a category's `productSort` and `productOrder` are for that category, for the whole shop.
- A storefront products read with no category and the default `featured` sort now follows that setting. It was always best-selling. A store migrated from v2 lists in its v2 hand order.
- A category's `productOrder` may now list up to 20,000 products (was 5,000).

5 October 2026 Added Fixed Improved

- The reference's servers list now names only the API that served it, so its built-in client always calls the same API as the base URLs on these pages. It used to list a second server that answered every `/v3` call with an error.
- `POST /public/{pk}/test-gateway/{paymentId}` is now in the reference: how a test-mode checkout approves or declines its payment. See [Test mode](https://shoprocket.io/docs/test-mode.md).
- Storefront product reads (catalogue, product page, cart suggestions) now answer `costPrice` as `null` on every variant. A seller's cost is their margin, and it was readable with the publishable key. The seller API and webhooks still carry it.
- The `/openapi.json` document is about a fifth of its old size and is cached at the edge.
- The widget's JavaScript API and events are documented: see [Widget JavaScript API](https://shoprocket.io/docs/javascript.md). Three fixes came with it. `shoprocket:cart:updated` now fires whenever the cart changes, with the cart in `detail.cart`; it never fired before. `shoprocket:purchase` for an order placed with an offline method, a gift card or at no cost now carries its order id, value and currency (it went out with none, and a value of 0). And product, cart-line and order-line prices are no longer reported as 0 in `view_item`, `select_item`, `view_item_list`, `remove_from_cart` and the `purchase` lines.

4 October 2026 Added

- Subscription webhooks: `subscription.created`, `subscription.renewed`, `subscription.renewal_failed`, `subscription.paused`, `subscription.resumed`, `subscription.cancelled` and `subscription.expired`. Before this, nothing told you that a renewal failed or a contract ended.
- Licence key webhooks, one per state change: `license_key.assigned`, `license_key.suspended`, `license_key.reinstated`, `license_key.expired` and `license_key.revoked`. A subscription's keys follow it: suspended while it is past due or paused, expired once it ends.
- `GET /stores/{storeId}/licence-keys`: find any key in the store by the key itself, its order, its buyer, its subscription or its status.
- The Licence API: `POST /public/licenses/activate`, `validate` and `deactivate`, for the software you sell. Each call carries the product's `product_secret`; validate is answered at the edge nearest the caller.
- `POST /public/{pk}/back-in-stock`: a shopper asks to be emailed when a sold-out variant is back.

3 October 2026 Added

- A product's licence keys can come from your own server: `/stores/{storeId}/products/{id}/licence-keys/endpoint-secret` (and `endpoint-test`) set up the call we make when a key is needed.

2 October 2026 Fixed

- `returnUrl` and `cancelUrl` on `POST /orders/{orderId}/pay` must now be on an address the store owns (its shop, custom domain, store page or website). Any other address is replaced with the store's own page instead of being followed. See [a headless checkout](https://shoprocket.io/docs/basics.md#checkout).

1 October 2026 Added Improved

- Contact form: `POST /public/{pk}/contact` sends a shopper's message to the store, and `GET /stores/{storeId}/contact-messages` (with `DELETE` for one) lists what arrived.
- `POST /public/{pk}/cart/card-setup` saves a card for a subscription whose first payment is zero, so its renewals can be charged.
- `GET /public/{pk}/orders/{orderId}/status` now asks Stripe directly when its webhook is late, so a paid card order no longer reads as pending.

30 September 2026 Added

- Two more `pay` handoffs, both only when you send `embedded: true`: `mollie_components` (post the card token to `POST /orders/{orderId}/mollie-pay`) and `authorize_net_frame` (iframe the hosted form).

29 September 2026 Added

- Personalised products: a product can ask the shopper for text or a file. Answers go in `properties` on `POST /public/{pk}/cart/items`, and a file is uploaded first with `POST /public/{pk}/cart/uploads`, whose `token` is the answer.

28 September 2026 Added Improved

- Local pickup: `GET /cart/shipping-options` carries a `pickup` list, and `PATCH /cart` takes a `pickupLocationId` instead of a shipping rate. Sellers manage locations at `/stores/{storeId}/pickup-locations`.
- Upsells: `/stores/{storeId}/upsells` for the rules, and `GET /public/{pk}/cart/suggestions` for what the cart should suggest.
- Storefront product search also matches variant SKUs.

26 September 2026 Added

- PayPal express: `POST /public/{pk}/cart/paypal-express` raises a PayPal order for a cart before any order exists (`PATCH` and `GET` on `/cart/paypal-express/{paypalOrderId}` keep it in step). Send its id as `paypalOrderId` on `pay`; a `total_changed` rejection means the approved figure no longer matches.

25 September 2026 Added

- Live carrier rates: a shipping method can quote carrier services at checkout. `GET /stores/{storeId}/shipping-carriers` lists the carriers and services one can offer.

24 September 2026 Added Deprecated Fixed

- The API moved to `/v3`. `/v1` paths still answer for now; they will be handed to the compatibility layer for Shoprocket v2 integrations before launch, so move to `/v3`.
- The [API reference](https://shoprocket.io/docs/api.md) is now generated from the API itself: every published endpoint, grouped by resource, with its request and response schema and the authentication it takes.
- Browsers can now send `X-Customer-Token` to the storefront API. Before this, a signed-in shopper's account reads were blocked by the browser.
- Square can take the card on your page: with `embedded: true`, `pay` answers a `square_card` handoff, and the tokenised card goes to `POST /orders/{orderId}/square-pay`.

Spotted something missing?

If a behavioural change happened but isn't listed here, that's a bug we want to fix. Email [dev@shoprocket.io](mailto:dev@shoprocket.io) and we'll add it.

---

- HTML version: https://shoprocket.io/docs/changelog
- Language: English (en)
