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, and choose when its final usage is invoiced. All three options default to false, so Saasybill leaves your accounting documents alone and waits the organisation’s usage grace period unless you say otherwise.

{
  "when": "now",
  "delete_unsent_invoices": true,
  "void_approved_invoices": false,
  "invoice_usage_now": 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.
`invoice_usage_now`	Raise the final usage invoice at once, instead of after the organisation’s usage grace period. Ignored when the plan bills no meters.

All three are refused, with 422, when when is period_end. Invoices are only removed or raised early when a subscription ends now.

Deferred line items

A subscription can hold deferred line items: lines generated but not yet invoiced, which wait for the next renewal invoice. An ending subscription has no renewal to carry them, so deferred_items says what to do with them.

`deferred_items`	What happens
`invoice_now`	Saasybill raises an invoice for them straight away.
`invoice_at_period_end`	Saasybill raises the invoice on the end date. Only with `when: period_end`.
`discard`	Saasybill deletes them. They are never invoiced.

{ "when": "period_end", "deferred_items": "invoice_at_period_end" }

invoice_at_period_end with when: now is refused with 422, and param is deferred_items. The field is ignored when there are no deferred items. If you leave deferred_items out, the organisation’s Deferred Items on End setting decides. A request that includes the field always wins over the setting.

With the default setting, Ask in Saasybill, the items are neither invoiced nor deleted, and the response doesn’t say a decision is pending. The subscription shows an attention prompt in Saasybill until someone chooses. Send the field, or change the setting, if your platform ends subscriptions that might have deferred items.

Set a default for the organisation

An owner or admin can change the default under Developer Settings, then Configuration. The setting is called Deferred Items on End.

Setting	What a request without `deferred_items` does
Ask in Saasybill	Leaves the items alone and prompts someone in Saasybill to choose. This is the default.
Invoice them now	Raises an invoice for the items as the subscription ends.
Discard them	Deletes the items without billing them.

The default applies to both now and period_end. With period_end, Invoice them now invoices the items at the call, not on the end date. invoice_at_period_end isn’t a setting option, so send it in the request when you want it.

Discard them can’t be undone. Saasybill logs the change with the person who made it.

A subscription on a plan that bills meters gets a final usage invoice for the usage up to its end date. See Usage-based billing.

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://api.saasybill.com/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://api.saasybill.com/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://api.saasybill.com/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.

Webhook events

Both actions send webhooks.

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

Credit notes

Usage

End and restore a subscription

End a subscription

End at period end

End now

Deferred line items

Set a default for the organisation

Ending near renewal

When it can’t be ended

Restore a subscription

When it can’t be restored

Webhook events