Skip to content

API Changelog ​

Every change to the Sesamy Client and Management APIs that you can notice as a caller, grouped by week, newest first. Changes from before 18 November 2026 predate versioning, so they applied to every caller when they shipped.

Breaking changes only apply when you move your API version to their date or later. Everything else applies to every version as soon as it ships. Your integration should already tolerate it: see What we change without a new version.

Changes from before versioning

Entries before 18 November 2026 shipped before versioning existed, so no version protects you from them. A few of them required callers to adapt, for example signed links needing an expiry. Read the Changed entries from that period if your integration is older.

Week of 16 November 2026

AddedAPI versioning with the Sesamy-Version header

2026-11-18 · Client API, Management API

Send Sesamy-Version: YYYY-MM-DD to choose the API behaviour you were built against. Responses echo the version they were served with. Breaking changes only reach you when you move your version to their date or later. See Versioning.

AddedReactivate contracts and change plans

2026-11-18 · Client API, Management API

POST /contracts/{contract_id}/reactivate and POST /management/contracts/{id}/reactivate remove a scheduled cancellation. POST /contracts/{contract_id}/amendments accepts type: 'PLAN_CHANGE', and the Management API adds POST /management/contracts/{id}/amendments and POST /management/contracts/{id}/amendments/{amendmentId}/confirm. The new plan must be one of the contract's upgrade options, and the amendment previews the price difference in proration. See Changing plans.

ChangedAmendments return nextPrice, nextBillAt and currency

2026-11-18 · Client API, Management API

Amendments describe the next bill with nextPrice (in major units), nextBillAt (a timestamp) and currency. On the Client API, nextBill is still returned with its total in minor units, but new code should read the new fields.

FixedContracts whose last price period has no end

2026-11-18 · Client API, Management API

GET /contracts and GET /management/contracts/{id} no longer answer 500 for a contract whose last price period has no end date.

FixedProduct listings failing on incomplete catalog data

2026-11-18 · Management API

GET /management/products and GET /management/products/{sku} no longer answer 500 when a product has a purchase option with no price, a missing cover or language, or other fields the API does not return. A purchase option without a price is returned with an empty prices list, and a missing cover or language as an empty string.

AddedOpen Sesamy pages signed in with GET /auth/session-transfer

2026-11-18 · Client API

In cookie mode, GET /auth/session-transfer?target=… opens a Sesamy checkout, account or content page with the reader already signed in. Sesamy JS uses it for generateLink()'s sessionTransfer option. A target outside the Sesamy pages gets 400 INVALID_TARGET. See the Sesamy JS API reference.

AddedVendor hosts: <vendorId>.api.sesamy.com

2026-11-17 · Client API, Management API

Call both APIs on your own host, for example https://acme.api.sesamy.com and https://acme.api.sesamy.com/management. The host names the vendor, so anonymous requests need no Vendor-Id header. A request that names another vendor through its token, header or query is rejected with 403. api2.sesamy.com is unchanged. See Vendor hosts.

Week of 9 November 2026

2026-11-13 · Client API

POST /content/unlock with delivery: 'dca' grants the content keys when the reader arrived with a valid Sesamy signed link for that article. See Labrador DCA.

AddedReports: /management/report-types and /management/reports

2026-11-12 · Management API

List the report types you can generate, create a report, poll it and download the file. Requires the reports:read scope. Creating a report answers 202 with a Location to poll, or 200 when the report already exists. See Reports.

AddedContracts return recurringPrice, the contract's price schedule

2026-11-12 · Client API, Management API

Contracts carry recurringPrice: the price schedule ordered by start, with each period, price, billing interval and discount, including the discount codes behind it when they are recorded. Contract items gain their line id. recurringInterval, recurringTime and discount.endsAt are now also filled in for contracts that renewed since their last change, and a quarterly schedule is reported as three months.

AddedPage metadata on content access checks

2026-11-12 · Client API

Content access checks and unlocks accept contentType, section, tags, authors and publishedAt for the content, so paywall strategies can target on them. They only choose which paywall to show: they never grant access or set a price.

AddedCancel contracts and refund bills

2026-11-11 · Management API

POST /management/contracts/{id}/cancel cancels a contract, and POST /management/contracts/{id}/bills/{billId}/refunds refunds a bill. GET /management/contracts/{id}/bills/{billId}/refunds lists the refunds made. See Cancel and refund.

AddedLabrador DCA delivery on POST /content/unlock

2026-11-11 · Client API

POST /content/unlock accepts delivery: 'dca' for Labrador CMS Delegated Content Access, with Sesamy as the issuer. It verifies the Labrador-signed page, decides access like other Sesamy content, and returns the content keys. See Labrador DCA.

FixedGET /management/bills failing on older bills

2026-11-11 · Management API

GET /management/bills no longer answers 500 for bills created before some fields were recorded. A bill that still cannot be read answers 502 instead of 500.

ChangedVendor IDs must be at most 64 letters, digits, - or _

2026-11-09 · Client API, Management API

A vendor ID in the Vendor-Id header, in the Basic auth username, or in POST /management/vendors is rejected with 400 unless it is at most 64 characters and contains only letters, digits, - and _.

ChangedAn unknown paywall reference no longer fails content access

2026-11-09 · Client API

When an article's paywall reference names a paywall that does not exist, /content/has-access and /content/unlock treat it as no policy, so only the article's access level decides. A paywall reference that is a URL counts only if it ends in a Sesamy paywall ID or strategy ID. Fetching a missing paywall answers 404 instead of 503.

FixedReading Partner Checkout checkouts

2026-11-09 · Management API

GET /management/checkouts/{id} no longer answers 500 for checkouts created through the Partner Checkout API.

Week of 26 October 2026

AddedPurchase options on management products

2026-10-29 · Management API

Management product responses include their purchase options: IDs, market prices in major units, billing intervals, lease durations, seat and quantity limits, and sale and listing flags. Use the IDs in Partner Checkout requests. Requires products:read.

ChangedPaywalls return their dynamic pricing fields

2026-10-29 · Client API, Management API

GET /paywalls/{paywallId}, GET /management/paywalls and GET /management/paywalls/{paywallId} return subscriptions[].discountId, subscriptions[].priceMode, singlePurchase.discountId and settings.showPricesExVat. Rendered paywalls also return pricePeriod, discountPeriod, discountMonths and trialDays on automatic subscriptions.

ChangedPaused entitlements grant no access

2026-10-28 · Client API

Entitlements carry isPaused. A paused entitlement no longer grants access through content access checks, unlocks or the content proxy.

Week of 19 October 2026

AddedList a reader's checkouts: GET /management/checkouts

2026-10-23 · Management API

GET /management/checkouts?userId=… lists a reader's checkouts, newest first. Filter with status (for example PENDING to find incomplete ones) and page with limit and from. Requires checkouts:read.

AddedMulti-seat access on management entitlements

2026-10-23 · Management API

GET /management/entitlements marks an entitlement held through a multi-seat contract with origin.type: 'LICENSE', including the entitlements inside a bundle the seat unlocks. The origin carries contractId, the seat role (owner or member) and, outside bundles, licenseId.

AddedName the vendor in the query string on anonymous requests

2026-10-22 · Client API

Anonymous Client API requests can name the vendor with a vendor-id query parameter, for proxies that drop the Vendor-Id header. A token, Basic auth or the header take precedence. Management routes ignore the parameter.

AddedPaywall strategy decisions carry through to checkout

2026-10-22 · Client API

Strategy execution, content access checks, unlocks and Capsule denials return decisionId and strategyId with the selected paywall. GET /paywalls/{paywallId} accepts a strategy ID (st_…) from anonymous callers and runs the strategy, with optional referrer, utm_* and contentId query parameters. POST /checkouts accepts attribution.decisionId and attribution.strategyId, so purchases are attributed to the strategy that showed the paywall.

AddedDetailed content access response

2026-10-22 · Client API

POST /content/has-access returns the selected paywall along with the decision when you ask for application/vnd.sesamy.content-access+json, so a paywall can render the same server decision without running the strategy again. The plain boolean response is unchanged. See Content.

AddedUnified content access: POST /content/has-access and POST /content/unlock

2026-10-21 · Client API

POST /content/has-access checks access without using up a read. POST /content/unlock grants it and returns Capsule key material, a scoped proxy token, or a decision for locally encoded content. The server resolves fixed paywalls and strategies. See Content.

DeprecatedLegacy paywall strategy and access routes

2026-10-21 · Client API

Use POST /content/has-access and POST /content/unlock instead of POST /paywalls/strategies/{strategyId}/execute, .../read and .../access, and POST /paywalls/{paywallId}/access and .../access/check. They keep working unchanged.

ChangedCapsule unlocks enforce signed paywall policies

2026-10-21 · Client API

When a verified publisher resource JWT names a paywall in data.paywallUrl, Capsule unlock evaluates that paywall's strategy on the server before handing out keys, and returns the selected paywall when it denies access. Policy-bound content must use the article-specific encryption scope. Older manifests without a policy keep working as before. See Client-side locking.

AddedRegister paywall reads through a strategy

2026-10-19 · Client API

POST /paywalls/strategies/{strategyId}/access resolves the strategy and registers the read on the paywall it chose.

FixedGET /profile for readers who sign in by SMS

2026-10-19 · Client API

GET /profile no longer answers 500 for readers who sign in with a phone number and have no email address.

Week of 12 October 2026

ChangedGrant statuses match the access-list service

2026-10-15 · Management API

Grant status is one of PENDING, ACTIVE, CANCELED, EXPIRED or DELETED. INACTIVE is gone: no grant ever had it. GET /management/access-lists/{id}/grants no longer answers 500 for grants with a status outside the old list.

FixedGET /vendors for readers without a vendor

2026-10-15 · Client API

GET /vendors no longer answers 400 vendorId is required for tokens that name no vendor.

AddedredirectLabel on checkouts

2026-10-13 · Client API

POST /checkouts accepts redirectLabel, which replaces "Go to {vendor}" on the button back to redirectUrl on the confirmation page and in the order confirmation email. Paywalls keep settings.redirectLabel and subscriptions[].redirectLabel.

FixedAccess-list errors

2026-10-13 · Management API

Access-list and grant endpoints answer with the actual 4xx and its reason instead of a bare 500.

FixedPOST /checkouts with an email address

2026-10-12 · Client API

POST /checkouts no longer fails when the request includes email. Errors from creating the checkout reach you as 4xx with the reason instead of 503.

2026-10-12 · Client API

PATCH /profile and GET /fulfillments work when you authenticate with the session cookie instead of an Authorization header. They answered 503 before.

Week of 5 October 2026

ChangedNew issue codes in validation errors

2026-10-08 · Client API, Management API

Request validation errors keep their { success, error: { name, issues } } shape, but the issue codes and messages changed, for example invalid_format instead of invalid_string. Match on the status code and field path, not on issue messages. See Error Handling.

AddedcanceledAt on contracts

2026-10-07 · Client API, Management API

Contracts carry canceledAt, the date the contract was actually canceled. It is null until then.

ChangedClear the mobile phone with PATCH /profile

2026-10-07 · Client API

PATCH /profile with mobilePhone set to null or an empty string clears the number. Before, the value was ignored.

FixedUpstream 4xx on contract, bill and transaction listings

2026-10-07 · Management API

Listing contracts, bills and transactions with an invalid filter answers with the 4xx and its reason instead of a 5xx. Reading a business checkout without a VAT number no longer answers 500.

FixedChanging a login identifier to an email a linked identity holds

2026-10-06 · Management API

POST /management/users/{user_id}/change-login-identifier updates the login when a linked identity already holds the new email. Before, it reported success without changing anything.

ChangedSeat users no longer need a sku

2026-10-05 · Management API

POST /management/contracts/{id}/seats/users and DELETE /management/contracts/{id}/seats/users/{userId} act on the contract's license without a sku. This fixes the 409 they answered on multi-seat contracts. The list leaves out removed seats.

Week of 28 September 2026

AddedManage the users on a multi-seat contract

2026-10-02 · Management API

GET, POST /management/contracts/{id}/seats/users and DELETE /management/contracts/{id}/seats/users/{userId} list, assign and remove the users holding seats. See Creating contracts.

DeprecatedGET /management/contracts/{id}/licenses

2026-10-02 · Management API

Use GET /management/contracts/{id}/seats/users instead.

AddedChange the seats on a contract: PUT /management/contracts/{id}/seats

2026-09-30 · Management API

Change the number of seats on a multi-seat contract without changing what is billed. Requires contracts:write. It refuses to go below the number of users holding a seat. See Creating contracts.

2026-09-30 · Client API, Management API

POST /management/create-signed-link accepts optional scopes and writes them into the link with the sku. A link with scopes unlocks only those scopes. Capsule unlock rejects links without an expiry, so links issued before this without one stopped working.

ChangedProfile addresses require a city

2026-09-29 · Client API

PATCH /profile rejects a billingAddress or deliveryAddress without city with a 400 naming the field. Before, it failed with 503.

ChangedCursor paging on discounts

2026-09-29 · Management API

GET /management/discounts and GET /management/discounts/{id}/codes return a nextCursor to pass back as cursor for the next page. See Managing discounts.

AddedDiscounts: /management/discounts

2026-09-28 · Management API

List, create, read, update, activate, pause and cancel discounts, and generate, list and cancel one-time codes. Requires the discounts:read and discounts:write scopes. See Managing discounts.

ChangedSigned links unlock only their own article

2026-09-28 · Client API

Capsule unlock accepts a signed link only for the article it was issued for, and rejects expired links. Readers on a signed link can unlock without signing in. When a link doesn't cover the article but the reader is signed in, their entitlements decide.

Week of 21 September 2026

Fixedattribution.referrer on checkouts

2026-09-25 · Client API

POST /checkouts passes attribution.referrer on. It was dropped before.

FixedPOST /management/contracts answering 503 after success

2026-09-25 · Management API

POST /management/contracts returns the created contract instead of 503 "the outcome is unknown".

AddedGet one vendor: GET /management/vendors/{vendorId}

2026-09-24 · Management API

Read a single vendor you have access to.

AddedDelete users who have one-off purchases

2026-09-24 · Management API

DELETE /management/users/{user_id}?allowPurchases=true deletes a user who holds one-off purchases. Subscriptions and active, overdue or upcoming subscription contracts still block deletion.

ChangedGET /management/users returns addresses

2026-09-24 · Management API

Users in GET /management/users include billingAddress and deliveryAddress.

AddedUser logs and sessions

2026-09-23 · Management API

GET /management/users/{user_id}/logs and GET /management/users/{user_id}/sessions page through a user's sign-in activity. Requires users:read.

AddedCreate contracts: POST /management/contracts

2026-09-22 · Management API

POST /management/contracts and POST /management/contracts/{id}/confirm create invoiced contracts without a checkout, including multi-seat contracts. Requires contracts:write. Contract items report quantity and seats, and a contract names its payer when someone other than the user is billed. See Creating contracts.

ChangedMatomo visitor ID on checkouts

2026-09-22 · Client API

POST /checkouts accepts the Matomo visitor ID as attribution._pk_id.

Week of 14 September 2026

ChangedRequests time out after 30 seconds

2026-09-18 · Client API, Management API

A request that takes longer than 30 seconds answers 504 instead of staying open. Retry idempotent requests with backoff.

Week of 7 September 2026

ChangedAnonymous paywall requests need a vendor

2026-09-11 · Client API

An anonymous paywall request that names no vendor answers 400 Missing vendor. Name it with the Vendor-Id header. A failed paywall fetch passes on the 4xx it got, such as an unknown paywall, instead of answering 503.

ChangedUnexpected errors return a plain body

2026-09-11 · Client API, Management API

An unexpected error answers 500 with the body Internal Server Error. GET /profile answers 404 when there is no profile.

AddedDiscount details on contracts

2026-09-10 · Client API, Management API

appliedDiscounts[] gains status, startsAt and endsAt, and contracts gain a discount block for the next bill: endsAt, amount, percentage and fullPrice. Use it to see when an introductory price ends and what the reader pays after. On listings, appliedDiscounts[].startsAt and endsAt are empty; read the contract by ID.

AddedSubscriber count in stats

2026-09-09 · Management API

GET /management/stats/series/totalSubscribers returns how many subscribers hold an active subscription on each day, per product. It is a count, so currency is null. See Reading stats.

ChangedCheckouts return their campaign attribution

2026-09-09 · Client API, Management API

Checkout responses fill attribution with the utm* values the checkout was created with, including when you read a checkout from a checkout.1#confirm webhook.

FixedReading checkouts and fulfillments with missing fields

2026-09-09 · Client API, Management API

GET /management/checkouts/{id} no longer answers 500 for checkouts without a redirect URL, language or full VAT details. redirectUrl is optional on a checkout response. GET /fulfillments no longer answers 500 when an item has no delivery address.

FixedReading checkouts older than 7 days

2026-09-07 · Management API

GET /management/checkouts/{id} reads checkouts of any age.

ChangedBill date filters must be ISO 8601

2026-09-07 · Management API

createdGte, createdLte, modifiedGte and modifiedLte on GET /management/bills must be ISO 8601 date-times with Z or an offset. Anything else answers 400.

Week of 31 August 2026

Addedorigin on contracts

2026-09-04 · Client API, Management API

Contracts carry an optional origin ({ type, id }). type is CHECKOUT, CHECKOUT_LEGACY, MANUAL, IMPORTED, THIRD_PARTY or OFFER. For CHECKOUT, id is the checkout ID, so you can match a contract to the checkout that created it.

AddedDate filters on GET /management/bills

2026-09-04 · Management API

GET /management/bills accepts createdGte, createdLte, modifiedGte and modifiedLte, and now applies the status and contractId filters. Bills report their real created and modified timestamps and receiptUrl.

FixedBills without payment data

2026-09-04 · Management API

GET /management/bills no longer answers 500 for draft, pending or unpaid bills, and GET /management/bills/{id} returns the right bill for machine-to-machine tokens.

2026-09-04 · Client API

POST /auth/{clientId}/session turns a bearer access token into a cookie-mode session, for example from an app deep link. The session ends when the token expires. See Authentication.

ChangedPaywalls return all their fields

2026-09-04 · Client API, Management API

Paywall responses include description, subscriptionsUrl, settings.redirectUrl, settings.loginFields, and comparePeriodText, readMoreLink and redirectUrl on subscriptions, which were dropped before. Paywalls that leave out optional fields no longer answer 5xx. Admin fields (name, status, createdAt, modifiedAt, previewUrl) are only on GET /management/paywalls.

FixedCreating API keys

2026-09-03 · Management API

POST /management/api-keys no longer fails with 503. A key that asks for a scope that does not exist fails with the missing scopes named.

ChangedPaywall strategy execution fails closed

2026-09-03 · Client API

POST /paywalls/strategies/{strategyId}/execute answers 404 for an unknown strategy and 503 for any other failure. It never succeeds without a paywall to show.

Next Steps ​

Released under the MIT License.