End and restore a subscription

This page covers the API. To end or restore a subscription in the app, see Subscriptions. For the lifecycle, see Subscriptions explained.

Both endpoints need the subscriptions:write scope. Both return the updated subscription.

End a subscription

POST /v1/subscriptions/{id}/end takes a single required field, when.

`when`	What happens
`period_end`	The subscription runs to its renewal date and doesn’t renew. It stays `active` with `cancel_at_period_end: true` and an `end_date`, then becomes `complete`.
`now`	The subscription ends immediately and its status becomes `ended`.

Ending a subscription doesn’t refund or credit the current period. The customer keeps what they’ve paid for.

End at period end

{ "when": "period_end" }

End now

With now you can also clean up the subscription’s invoices in Xero. Both options default to false, so Saasybill leaves your accounting documents alone unless you say otherwise.

{
  "when": "now",
  "delete_unsent_invoices": true,
  "void_approved_invoices": false
}

Field	Description
`delete_unsent_invoices`	Also delete the subscription’s invoices that were never sent, in Xero.
`void_approved_invoices`	Also void the subscription’s approved, unpaid invoices in Xero.

Both are refused, with 422, when when is period_end. Invoices are only removed when a subscription ends now.

Invoices are removed in Xero first, one at a time, and the subscription ends only if they all go. If Xero refuses one, the subscription keeps running and the API answers 409 invalid_state. Invoices already removed stay removed.

curl https://app.saasybill.com/api/v1/subscriptions/9d4e2b7a-13c5-4f8e-b6a0-2e1d7c9f5b33/end \
  -H "Authorization: Bearer $SAASYBILL_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: cancel_acme_2026-10-12" \
  -d '{ "when": "period_end" }'

await fetch(`https://app.saasybill.com/api/v1/subscriptions/${subscriptionId}/end`, {
  method: "POST",
  headers: {
    Authorization: `Bearer ${process.env.SAASYBILL_API_KEY}`,
    "Content-Type": "application/json",
    "Idempotency-Key": `cancel_${accountId}_${requestId}`,
  },
  body: JSON.stringify({ when: "period_end" }),
});

Ending near renewal

If the next period’s renewal invoice has already been raised, a subscription that won’t renew has no use for it. Ending the subscription, now or at period end, voids the invoice in Xero if it was approved, or deletes it. Restoring later raises the invoice again. The end is refused while that invoice has a payment or credit on it, because the customer has already paid for the next period. The answer is 409 invalid_state. To end it after that period, change End after in the subscription’s details in the app.

When it can’t be ended

A subscription that can’t be ended answers 409 invalid_state, with a message that says why. Examples include a subscription that has already ended, and Setup Mode when you ask to remove invoices, because nothing can be changed in Xero.

Restore a subscription

POST /v1/subscriptions/{id}/restore undoes an end. It takes an empty JSON object.

{}

It restores:

a subscription set to end at period end, which goes back to renewing
an ended subscription, before its renewal date

curl https://app.saasybill.com/api/v1/subscriptions/9d4e2b7a-13c5-4f8e-b6a0-2e1d7c9f5b33/restore \
  -H "Authorization: Bearer $SAASYBILL_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: restore_acme_2026-10-13" \
  -d '{}'

When it can’t be restored

A subscription that can’t be restored answers 409 invalid_state, with a message that says why.

Reason	What to do
The renewal date has passed.	The subscription can no longer be restored. Create a new one.
The customer isn’t active.	Restore the customer in Xero, then try again.
The plan isn’t active or legacy.	Change the plan’s status in Saasybill, then try again.
An add-on on the subscription isn’t active or legacy.	Change the add-on’s status in Saasybill, then try again.

Tell your platform

Both actions send webhooks, so you can confirm the outcome without polling.

Action	Events
End now	`subscription.ended`
End at period end	`subscription.updated` now, and `subscription.ended` when it completes
Restore	`subscription.updated`

See Webhook events.

Getting started

Fundamentals

Integration guides

Webhooks

Organisation

Customers

Plans

Charges

Subscriptions

Invoices

End and restore a subscription

End a subscription

End at period end

End now

Ending near renewal

When it can’t be ended

Restore a subscription

When it can’t be restored

Tell your platform

​End a subscription

​End at period end

​End now

​Ending near renewal

​When it can’t be ended

​Restore a subscription

​When it can’t be restored

​Tell your platform

End a subscription

End at period end

End now

Ending near renewal

When it can’t be ended

Restore a subscription

When it can’t be restored

Tell your platform