Subscription Lifecycle
This page explains how dates, mail handling and billing work when you create, change and stop Virtual Office subscriptions through the Partner API.
Creating a subscription
Create a subscription with a
subscription.start_date in the request body.
start_dateis an ISO 8601 timestamp, e.g.2026-03-02T10:23:04Z. Fractional seconds such as2026-03-02T10:23:04.000Zare also accepted.start_datecan be in the past, so you can backdate a subscription.start_dateis saved exactly as sent and cannot be changed later through the API. Sending a differentstart_dateon an update has no effect, so check it before you create the subscription.- The grace period is counted from
start_date, not from when you send the request. Backdating a subscription shortens the grace period that is left. subscription.end_dateis accepted on create but ignored. To end a subscription, use the Stop endpoint.
Changing between monthly and yearly
Change the plan of a subscription with:
POST /api/v2/subscription/{external_id}/change-product
{ "product_id": 2247 }
product_id must be the monthly or yearly plan of the subscription's current product.
The subscription keeps its external_id, mail and KYC/AML checks, so there is no need
to stop it and create it again.
The new product is shown on the subscription straight away, but the new price starts at the end of the period that has already been paid for. Nothing is credited or charged for the change itself.
| Change | Example | First charge at the new price |
|---|---|---|
| Monthly to yearly | Billed on the 12th of each month, changed on 20 November | 12 December, then every year |
| Yearly to monthly | Billed on 12 March each year, changed on 20 November | 12 March, then every month |
- A yearly customer who moves to monthly keeps the year already paid for. Nothing is refunded for the rest of that year.
- If you change the plan on a billing date before that date has been charged, the new price is charged for it.
- If you change the plan before the subscription has been charged for the first time, the first charge is at the new price.
- You can change the plan back before the new price starts. Nothing extra is charged.
- If you stop the subscription with
END_OF_TERMafter a change, it ends at the end of the period already paid for.
The change is refused with a 400 when:
- the subscription has been stopped, or has a stop scheduled. Undo the stop with the Start endpoint first.
product_idis the current product, is not one of your products, or is not the monthly or yearly plan of the same product- your agreement has pricing tiers and the new product has no price on them
The Update endpoint still refuses a
change of product_id, so a normal update cannot change the plan by accident.
Stopping a subscription
Stop a subscription with:
POST /api/v2/subscription/{external_id}/stop/{end_date}/{cancellation_reason}
end_date must be one of:
end_date | What happens |
|---|---|
END_OF_TERM | The end date is set to the end of the current billing term (23:59:59 UTC on the subscription's next billing date). Post is handled and billing continues until then. |
YYYY-MM-DDTHH:MM:SSZ | A UTC timestamp, now or in the future, e.g. 2026-03-02T10:23:04Z. Post is handled and billing continues as normal until that time. |
cancellation_reason must be Requested or Defaulted.
- The timestamp format is strict: exactly
YYYY-MM-DDTHH:MM:SSZ, with no fractional seconds or timezone offset. Any other format returns a400. Note this is stricter than the format accepted forstart_date. end_datemust be now or in the future. Backdated stops are not supported. To stop a subscription straight away, send the current time.
Until the end date passes, the subscription's status is PENDING_CANCELLATION. After
it, the status is CANCELLED.
To undo a stop, or to reactivate a cancelled subscription, use the Start endpoint.
Mail after cancellation
Mail is not processed for cancelled subscriptions. Once a subscription's end date has passed, we stop scanning and forwarding post for it.
Grace period
Your commercial agreement sets a grace period of 15 days, 30 days or none.
If a subscription is stopped with an end date less than 15 or 30 days (your grace
period) after its start_date, you get a full refund for it. The refund is raised on
the day the subscription ends and appears on your invoice as a "Grace Period Refund"
credit.
There is no refund when:
- your agreement has no grace period
- the end date is 15 or 30 days (your grace period) or more after
start_date - the subscription starts and ends on the same day, because it was never charged
- the subscription was reactivated with the Start endpoint, because the grace period only applies to new subscriptions
Your commercial agreement may set further conditions.