How can subscriptions be imported from legacy platforms?
Subscriptions can be created in such a way as to faciliate import from a legacy platform.
Subscription API documentation
When a subscription needs to be imported from a legacy platform it is key to make the transition seamless from the perspective of the customer. A common way to import is:
- Get the existing subscription from the legacy platform
- Create a subscription in Billforward matching the bill cycle of the legacy subscription
- Ensure Billforward is the source of truth for this subscription, i.e represents the state of the customers account
- Cancel the subscription in the legacy platform
Note: The following guide presumes subscriptions will be canceled for failed payment.
Creating a subscription
When importing a subscription from a legacy platform we need to be deal with 2 cases;
- Subscription is Paid
- Subscription is Unpaid
Case 1: Paid subscriptions
When importing an existing subscription which is paid:
- Get the date/time of the start of the period [ T1 → T2 ] that the legacy subscription is paid up to
- Create a new paid subscription with the start set to T1 and the state set to Paid
- The new subscription will not raise any invoice until the next billing period T2 and will be marked as paid.
- Disable notifications and cancel the subscription in the legacy platform
For example, if the existing subscriptions billing period was from the 15th of March until 15th of April, create a paid subscription that starts on 15th of March, the end time T2 will automatically be calculated.
- Billing periods in Billforward contain minutes, if your existing provider only has dates, you should choose a consistent time to align the subscriptions to, for example midnight. Billforward time is always UTC ( Further reading: Time)
- If an explicit T2 is required, use the end property on subscription creation
curl "https://api-sandbox.billforward.net/v1/subscriptions/create" \
-H "Authorization: Bearer INSERT_ACCESS_TOKEN_HERE" \
-H "Content-Type: application/json" \
-X POST \
"start" : "2030-03-15T00:00:00Z"
Case 2: Unpaid subscriptions
When possible it is recommended that subscription which are unpaid are not imported into the system until they become paid. This approach avoids a myriad of race-conditions and “what if” use cases and allows subscriptions in dunning to be naturally canceled.
If import for unpaid subscriptions is a must then setting state to AwaitingPayment can be used, but the various states that exist must be considered, for example an invoice for the same period in both platforms.