Skip to content

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:

  1. List the options. GET .../upgrade-options returns the plans each item of the contract can change to. You define these as upgrade paths on the purchase options in your catalogue.
  2. Create an amendment. POST .../amendments prepares the change and returns a PENDING amendment. Nothing changes and nothing is charged yet, so you can show the customer what the change costs.
  3. Confirm the amendment. POST .../amendments/{amendmentId}/confirm applies 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.com

Authentication ​

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.

EndpointScope
GET /management/contracts/{id}/upgrade-optionscontracts:read
POST /management/contracts/{id}/amendmentscontracts:write
POST /management/contracts/{id}/amendments/{amendmentId}/confirmcontracts: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:

MethodWhat happens
IGNORE_CHANGESThe plan changes at once. The new price applies from the next bill. Nothing is settled
POSTPONEThe plan and price change at the next bill. Nothing changes until then
NEXT_PAYMENTThe plan changes at once. The difference is added to the next bill, as a credit when it is negative
UPFRONTThe plan changes at once. The difference is charged to the saved payment method when you confirm. Upgrades only
RESTART_PERIODThe 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

bash
curl "https://api2.sesamy.com/management/contracts/M-V1StGXR8_Z5jdHi6B-myT/upgrade-options" \
  -H "Authorization: Bearer $ACCESS_TOKEN"
json
[
  {
    "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

FieldTypeDescription
typestringPLAN_CHANGE
skustringThe product to change to, from paths
purchaseOptionIdstringThe purchase option to change to. See Choosing the Purchase Option
itemIdstring(Optional) The contract item to change. Only needed when the contract has more than one item
prorationMethodstring(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 ​

bash
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

json
{
  "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.

StatusMeaning
201The amendment is prepared. Nothing has changed yet
400The body is invalid, or the contract cannot change to that plan. Check the upgrade options
403The token lacks the contracts:write scope
404No such contract for your vendor
409The 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

bash
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.

StatusMeaning
200The amendment is applied or scheduled. Also returned if it was already confirmed
400The payment was declined. Only possible with UPFRONT or RESTART_PERIOD
404No such contract or amendment for your vendor
409The amendment can no longer be confirmed, for example because it was cancelled or replaced by a newer one
503Sesamy 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:

EndpointDescription
GET /contracts/{contract_id}/upgrade-optionsList the plans they can move to
POST /contracts/{contract_id}/amendmentsPrepare the change
POST /contracts/{contract_id}/amendments/{amendment_id}/confirmApply 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:

  • appliedDiscounts lists only the ids of the discounts, not the discount objects.
  • It also has the deprecated nextBill, whose total is in minor units. Use nextPrice instead.

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:

typescript
// 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.

Next Steps ​

Released under the MIT License.