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.comAuthentication
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| Endpoint | Scope |
|---|---|
POST /management/contracts/{id}/cancel | contracts:write |
POST /management/contracts/{id}/reactivate | contracts:write |
POST /management/contracts/{id}/bills/{billId}/refunds | contracts:write |
GET /management/contracts/{id}/bills/{billId}/refunds | bills: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.
| Field | Type | Description |
|---|---|---|
when | string | (Optional) end or now. Defaults to end |
reason | string | (Optional) Why the customer cancels: TOO_EXPENSIVE, NOT_USING, SWITCHED_COMPETITOR, MISSING_FEATURES, TECHNICAL_ISSUES, DUPLICATE, or OTHER |
comment | string | (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
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.
{
"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.
| Status | Meaning |
|---|---|
200 | The contract is cancelled or scheduled to cancel. Also returned if it was already cancelled |
400 | The body is invalid |
403 | The token lacks the contracts:write scope |
404 | No such contract for your vendor |
409 | The contract is in a status that cannot be cancelled, such as PENDING |
503 | Sesamy 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
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.
{
"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.
| Status | Meaning |
|---|---|
200 | The contract is no longer set to cancel. Also returned if it was not set to cancel |
403 | The token lacks the contracts:write scope |
404 | No such contract for your vendor |
409 | The contract has ended, or is in a status that cannot be reactivated, such as PENDING or FORTHCOMING |
503 | Sesamy 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.
| Field | Type | Description |
|---|---|---|
amount | integer | The amount to refund in minor units (öre or cents). A positive whole number |
reason | string | (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
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
{
"id": "B-acme-654321",
"contractId": "M-V1StGXR8_Z5jdHi6B-myT",
"status": "PAID",
"amount": 246,
"currency": "SEK",
"createdAt": "2026-11-11T10:00:00.000Z"
}| Status | Meaning |
|---|---|
200 | The refund is made |
400 | The body is invalid, for example a missing, zero, negative, or fractional amount |
403 | The token lacks the contracts:write scope |
404 | No such contract for your vendor |
503 | Sesamy 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.
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.