Importing subscriptions

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 

Importing

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:

1. Get the existing subscription from the legacy platform
2. Create a subscription in Billforward matching the bill cycle of the legacy subscription
3. Ensure Billforward is the source of truth for this subscription, i.e represents the state of the customers account
4. 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;

1. Subscription is Paid
2. Subscription is Unpaid

Case 1: Paid subscriptions

When importing an existing subscription which is paid:

1. Get the date/time of the start of the period [ T1 → T2 ] that the legacy subscription is paid up to
2. Create a new paid subscription with the start set to T1 and the state set to Paid
3. The new subscription will not raise any invoice until the next billing period T2 and will be marked as paid.
4. 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.

Note:

• 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 \
    -d \
'{
  "accountID": "ACC-4CBC3628-E9C8-4F1A-83F6-8A81F5B0",
  "productRatePlan": "PRP-A86BDD6A-D47D-447D-B82E-6C46CA49",
  "state": "Paid",
  "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.