Changing Plans
Learn how to move a subscription to another product or purchase option, such as from monthly to yearly billing, through the Management API or the client API.
Overview
A plan change takes three steps:
- List the options.
GET .../upgrade-optionsreturns the plans each item of the contract can change to. You define these as upgrade paths on the purchase options in your catalogue. - Create an amendment.
POST .../amendmentsprepares the change and returns aPENDINGamendment. Nothing changes and nothing is charged yet, so you can show the customer what the change costs. - Confirm the amendment.
POST .../amendments/{amendmentId}/confirmapplies it.
A contract can only change to a plan its upgrade options list. Only active recurring contracts can change plan, and not while they are set to cancel. If the customer has cancelled but the contract is still running, reactivate it first. A contract that has already ended cannot change plan: the customer buys the new plan through a checkout instead.
Base URL
https://api2.sesamy.comAuthentication
The Management API endpoints need a Management API token. Request it from https://token.sesamy.com/oauth/token with the client credentials flow, and send it as a bearer token. See Authentication for how to obtain a token.
| Endpoint | Scope |
|---|---|
GET /management/contracts/{id}/upgrade-options | contracts:read |
POST /management/contracts/{id}/amendments | contracts:write |
POST /management/contracts/{id}/amendments/{amendmentId}/confirm | contracts:write |
Getting access
contracts:write is not part of the API key presets. Contact Sesamy to have it enabled for your client.
The client API endpoints use the reader's own token. See Change a Plan as the Reader.
How the Price Difference Is Settled
When a contract changes plan in the middle of a period, the customer has already paid for the rest of it on the old price. The proration method decides what happens to the difference:
| Method | What happens |
|---|---|
IGNORE_CHANGES | The plan changes at once. The new price applies from the next bill. Nothing is settled |
POSTPONE | The plan and price change at the next bill. Nothing changes until then |
NEXT_PAYMENT | The plan changes at once. The difference is added to the next bill, as a credit when it is negative |
UPFRONT | The plan changes at once. The difference is charged to the saved payment method when you confirm. Upgrades only |
RESTART_PERIOD | The plan changes at once and a new period starts today. A full period, less the unused part of the old one, is charged on confirm |
The method comes from the upgrade path in your catalogue, then from your account settings, then defaults to IGNORE_CHANGES. On the Management API you can override it per request with prorationMethod.
List the Upgrade Options
GET https://api2.sesamy.com/management/contracts/{id}/upgrade-options
curl "https://api2.sesamy.com/management/contracts/M-V1StGXR8_Z5jdHi6B-myT/upgrade-options" \
-H "Authorization: Bearer $ACCESS_TOKEN"[
{
"itemId": "item_1",
"sku": "sid:acme-plus-monthly",
"purchaseOptionId": "monthly",
"paths": [
{
"type": "UPGRADE",
"sku": "sid:acme-plus-yearly",
"purchaseOptionId": "yearly",
"title": "ACME Plus Yearly"
}
]
}
]Each entry is one item of the contract. paths lists the plans it can change to.
Create the Amendment
POST https://api2.sesamy.com/management/contracts/{id}/amendments
| Field | Type | Description |
|---|---|---|
type | string | PLAN_CHANGE |
sku | string | The product to change to, from paths |
purchaseOptionId | string | The purchase option to change to. See Choosing the Purchase Option |
itemId | string | (Optional) The contract item to change. Only needed when the contract has more than one item |
prorationMethod | string | (Optional) Overrides how the price difference is settled. See How the Price Difference Is Settled |
Choosing the Purchase Option
Send the purchaseOptionId of the path you picked. A path can leave it out, which means the item can move to any purchase option of that product. Then choose one from the product's purchaseOptions, which GET /products/{sku} returns, and send its id.
Send itemId too when the contract has more than one item, so Sesamy knows which item the path belongs to.
Example Request
curl -X POST "https://api2.sesamy.com/management/contracts/M-V1StGXR8_Z5jdHi6B-myT/amendments" \
-H "Authorization: Bearer $ACCESS_TOKEN" \
-H "Content-Type: application/json" \
-d '{
"type": "PLAN_CHANGE",
"sku": "sid:acme-plus-yearly",
"purchaseOptionId": "yearly"
}'Example Response
Status: 201 Created
{
"id": "amendment123",
"contractId": "M-V1StGXR8_Z5jdHi6B-myT",
"status": "PENDING",
"amendmentType": "ITEMS",
"appliedDiscounts": [],
"nextBillAt": "2026-12-01T00:00:00.000Z",
"nextPrice": 990,
"currency": "SEK",
"items": [{ "id": "item_1", "sku": "sid:acme-plus-yearly", "purchaseOptionId": "yearly" }],
"proration": {
"method": "NEXT_PAYMENT",
"amount": 41.5,
"currency": "SEK",
"appliesAt": "2026-11-18T10:00:00.000Z"
}
}nextPrice is what the next bill totals after the change. proration.amount is the difference settled for the rest of the current period, including tax: positive is charged, negative is credited, and 0 means nothing is settled. Amounts are in major units, so 41.5 is 41.50 SEK.
| Status | Meaning |
|---|---|
201 | The amendment is prepared. Nothing has changed yet |
400 | The body is invalid, or the contract cannot change to that plan. Check the upgrade options |
403 | The token lacks the contracts:write scope |
404 | No such contract for your vendor |
409 | The contract cannot change plan now: it is set to cancel, not active, or not recurring |
An amendment you never confirm has no effect, so you can create one only to show a price.
Confirm the Amendment
POST https://api2.sesamy.com/management/contracts/{id}/amendments/{amendmentId}/confirm
curl -X POST "https://api2.sesamy.com/management/contracts/M-V1StGXR8_Z5jdHi6B-myT/amendments/amendment123/confirm" \
-H "Authorization: Bearer $ACCESS_TOKEN"The response is the amendment with status CONFIRMED, or SCHEDULED when the change applies later, as with POSTPONE. Fetch the contract to see its new plan.
| Status | Meaning |
|---|---|
200 | The amendment is applied or scheduled. Also returned if it was already confirmed |
400 | The payment was declined. Only possible with UPFRONT or RESTART_PERIOD |
404 | No such contract or amendment for your vendor |
409 | The amendment can no longer be confirmed, for example because it was cancelled or replaced by a newer one |
503 | Sesamy could not confirm the outcome. Confirming again is safe: an already confirmed amendment is returned unchanged |
Confirming can charge the customer
With UPFRONT or RESTART_PERIOD, confirming charges proration.amount to the customer's saved payment method straight away. Show the customer the amount before you confirm.
Change a Plan as the Reader
A signed-in reader can change their own plan with the same three steps on the client API:
| Endpoint | Description |
|---|---|
GET /contracts/{contract_id}/upgrade-options | List the plans they can move to |
POST /contracts/{contract_id}/amendments | Prepare the change |
POST /contracts/{contract_id}/amendments/{amendment_id}/confirm | Apply it |
The body of the create request is the same as above, without prorationMethod: the reader always gets the method from your catalogue or account. The response differs from the Management API in two ways:
appliedDiscountslists only the ids of the discounts, not the discount objects.- It also has the deprecated
nextBill, whosetotalis in minor units. UsenextPriceinstead.
Confirming returns { "success": true }.
Prepare the change when the reader picks a plan, and confirm it in a separate step once they have accepted the price:
// When the reader picks a plan: prepare it and show what it costs
async function previewPlanChange(
contractId: string,
itemId: string,
sku: string,
purchaseOptionId: string
) {
const amendment = await sdk.contracts.createAmendment(contractId, {
type: 'PLAN_CHANGE',
itemId,
sku,
purchaseOptionId,
});
// Show amendment.nextPrice and amendment.proration to the reader
return amendment;
}
// When the reader accepts the price: apply it
async function acceptPlanChange(contractId: string, amendmentId: string) {
await sdk.contracts.confirmAmendment(contractId, amendmentId);
}Build the reader's choices from sdk.contracts.getUpgradeOptions(contractId): each option's itemId and the sku and purchaseOptionId of one of its paths.
Errors
All endpoints return the standard error response. See Errors for its shape.