Skip to main content

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_date is an ISO 8601 timestamp, e.g. 2026-03-02T10:23:04Z. Fractional seconds such as 2026-03-02T10:23:04.000Z are also accepted.
  • start_date can be in the past, so you can backdate a subscription.
  • start_date is saved exactly as sent and cannot be changed later through the API. Sending a different start_date on 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_date is 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.

ChangeExampleFirst charge at the new price
Monthly to yearlyBilled on the 12th of each month, changed on 20 November12 December, then every year
Yearly to monthlyBilled on 12 March each year, changed on 20 November12 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_TERM after 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_id is 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_dateWhat happens
END_OF_TERMThe 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:SSZA 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.

warning
  • The timestamp format is strict: exactly YYYY-MM-DDTHH:MM:SSZ, with no fractional seconds or timezone offset. Any other format returns a 400. Note this is stricter than the format accepted for start_date.
  • end_date must 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.