Skip to content

Cancelling Contracts and Refunding Bills ​

Learn how to cancel a contract and refund a bill on behalf of a customer through the Management API, for example from a customer service tool.

Overview ​

Three endpoints cover the common customer service requests:

  • Cancel a contract so it stops renewing, or ends at once.
  • Reactivate a contract that is set to cancel, when the customer changes their mind.
  • Refund all or part of a paid bill to the customer's original payment method.

They are separate on purpose. Cancelling a contract never refunds anything, and refunding a bill never cancels the contract. If a customer asks for both, make both calls.

Base URL ​

https://api2.sesamy.com

Authentication ​

These endpoints need a Management API token. Request the token from https://token.sesamy.com/oauth/token with the client credentials flow, and send it as a bearer token:

Authorization: Bearer YOUR_ACCESS_TOKEN
EndpointScope
POST /management/contracts/{id}/cancelcontracts:write
POST /management/contracts/{id}/reactivatecontracts:write
POST /management/contracts/{id}/bills/{billId}/refundscontracts:write
GET /management/contracts/{id}/bills/{billId}/refundsbills:read

You also need contracts:read to look up a contract, which you do to find the bill to refund and to check the result of a request that timed out. See Authentication for how to obtain a token.

Getting access

contracts:write is not part of the API key presets. Contact Sesamy to have it enabled for your client.

Cancel a Contract ​

POST https://api2.sesamy.com/management/contracts/{id}/cancel

Cancels a contract on behalf of its customer. By default the customer keeps access until the end of the current period and the contract does not renew. Send when: "now" to cancel at once.

The body is optional. An empty request cancels at the end of the period with no feedback.

FieldTypeDescription
whenstring(Optional) end or now. Defaults to end
reasonstring(Optional) Why the customer cancels: TOO_EXPENSIVE, NOT_USING, SWITCHED_COMPETITOR, MISSING_FEATURES, TECHNICAL_ISSUES, DUPLICATE, or OTHER
commentstring(Optional) Free text, at most 1000 characters. Saved only together with reason

With when: "end", a recurring contract is cancelled at its next bill date, and any other contract at its expiry date. A contract with no expiry date is cancelled at once.

Example Request ​

bash
curl -X POST "https://api2.sesamy.com/management/contracts/M-V1StGXR8_Z5jdHi6B-myT/cancel" \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "when": "end",
    "reason": "NOT_USING",
    "comment": "Asked customer service to cancel"
  }'

Example Response ​

Status: 200 OK

The response is the contract. For a cancellation at the end of the period, willCancelAt holds the date and the contract stays ACTIVE until then.

json
{
  "id": "M-V1StGXR8_Z5jdHi6B-myT",
  "status": "ACTIVE",
  "isActive": true,
  "willCancelAt": "2026-12-01T00:00:00.000Z",
  "canceledAt": null,
  "cancelReason": null,
  "items": [{ "sku": "sid:acme-plus-monthly", "name": "ACME Plus", "quantity": 1 }]
}

Only ACTIVE, OVERDUE, and FORTHCOMING contracts can be cancelled. A contract that is already CANCELED or EXPIRED is returned unchanged, so repeating a request is safe.

StatusMeaning
200The contract is cancelled or scheduled to cancel. Also returned if it was already cancelled
400The body is invalid
403The token lacks the contracts:write scope
404No such contract for your vendor
409The contract is in a status that cannot be cancelled, such as PENDING
503Sesamy could not confirm the outcome. Fetch the contract to see whether it was cancelled, then repeat the request if it was not

Cancelling does not refund

The customer keeps what they have already paid for. To return money, refund the bill.

Reactivate a Contract ​

POST https://api2.sesamy.com/management/contracts/{id}/reactivate

Removes a scheduled cancellation, so the contract renews again as if it had never been cancelled. Use it when a customer who cancelled at the end of the period changes their mind before the period ends. The request has no body.

Example Request ​

bash
curl -X POST "https://api2.sesamy.com/management/contracts/M-V1StGXR8_Z5jdHi6B-myT/reactivate" \
  -H "Authorization: Bearer $ACCESS_TOKEN"

Example Response ​

Status: 200 OK

The response is the contract. willCancelAt is back to null.

json
{
  "id": "M-V1StGXR8_Z5jdHi6B-myT",
  "status": "ACTIVE",
  "isActive": true,
  "willCancelAt": null,
  "canceledAt": null,
  "nextBillAt": "2026-12-01T00:00:00.000Z",
  "items": [{ "sku": "sid:acme-plus-monthly", "name": "ACME Plus", "quantity": 1 }]
}

Only a contract that is still running can be reactivated: ACTIVE, OVERDUE, or CLOSED. A contract that has already ended (CANCELED or EXPIRED) cannot come back. The customer buys again through a checkout instead. A contract that is not set to cancel is returned unchanged, so repeating a request is safe.

StatusMeaning
200The contract is no longer set to cancel. Also returned if it was not set to cancel
403The token lacks the contracts:write scope
404No such contract for your vendor
409The contract has ended, or is in a status that cannot be reactivated, such as PENDING or FORTHCOMING
503Sesamy could not confirm the outcome. Fetch the contract to see whether it was reactivated, then repeat the request if it was not

Let readers reactivate themselves

A signed-in reader can reactivate their own contract with POST https://api2.sesamy.com/contracts/{contract_id}/reactivate on the client API, or sdk.contracts.reactivate(contractId) in the Sesamy SDK. It follows the same rules and returns the contract.

Refund a Bill ​

POST https://api2.sesamy.com/management/contracts/{id}/bills/{billId}/refunds

Refunds part or all of a paid bill to the original payment method. The refund uses the currency of the bill.

FieldTypeDescription
amountintegerThe amount to refund in minor units (öre or cents). A positive whole number
reasonstring(Optional) Free text, at most 500 characters. Saved with the refund

Minor units in, major units out

You send amount in minor units: 24600 refunds 246.00 SEK. The response reports amount in major units, like prices everywhere else in the API.

Find the Bill ​

List the contract's bills with GET /management/bills?contractId={id}, which needs bills:read. Each bill has an id and a price.

Example Request ​

bash
curl -X POST "https://api2.sesamy.com/management/contracts/M-V1StGXR8_Z5jdHi6B-myT/bills/B-acme-123456/refunds" \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "amount": 24600,
    "reason": "Refunded at the customer request"
  }'

Example Response ​

Status: 200 OK

json
{
  "id": "B-acme-654321",
  "contractId": "M-V1StGXR8_Z5jdHi6B-myT",
  "status": "PAID",
  "amount": 246,
  "currency": "SEK",
  "createdAt": "2026-11-11T10:00:00.000Z"
}
StatusMeaning
200The refund is made
400The body is invalid, for example a missing, zero, negative, or fractional amount
403The token lacks the contracts:write scope
404No such contract for your vendor
503Sesamy could not confirm the outcome. Check the list of refunds before you repeat the request

Refunds work for card and wallet providers such as Stripe, Klarna, Swish, and Vipps. Invoice payments cannot be refunded with this endpoint.

Never repeat a refund without checking first

A refund has no idempotency key, and Sesamy never retries it for you. If a request times out or returns 503, the refund may still have gone through. List the refunds of the bill and confirm that yours is missing before you send it again, or the customer is refunded twice.

List the Refunds of a Bill ​

GET https://api2.sesamy.com/management/contracts/{id}/bills/{billId}/refunds

Returns the refunds made on a bill, in the same shape as the response above. Use it to check the result of a request that timed out, and to see how much has already been refunded before you refund again.

bash
curl "https://api2.sesamy.com/management/contracts/M-V1StGXR8_Z5jdHi6B-myT/bills/B-acme-123456/refunds" \
  -H "Authorization: Bearer $ACCESS_TOKEN"

Errors ​

All endpoints return the standard error response. See Errors for its shape.

Next Steps ​

Released under the MIT License.