Scheduling subscriptions

How can subscriptions be scheduled?

Subscriptions can be scheduled to start at a future or past date

Subscription API documentation 

Start in Future

There are scenarios when a subscription needs to be invoiced at a future date. For example:

1. Contract start is at a future date
2. Want to align subscription start to a particular date

Starting a subscription in the future is easily achieved, so let’s have a look:

Create in the Future

When a subscription is created using the Create a subscription API endpoint  the start value can be provided. This is the date and time when the subscription will begin invoicing. In the following example we provide the 8th of April, 2024 as the start date.

By default the state of a newly created subscription is Provisioned state, this state prevents the subscription from automatically raising invoices. To allow invoices to be generated we need to set state of the subscription to AwaitingPayment.

An invoice will only be raised once the start date is reached.

Example:

# Create a subscription in 2024 and set the state to AwaitingPayment.
# No invoice is raised until the 8th of April 2024 at 10PM (UTC)

curl "https://api-sandbox.billforward.net/v1/subscriptions/create" \
    -H "Authorization: Bearer INSERT_ACCESS_TOKEN_HERE" \
    -H "Content-Type: application/json" \
    -X POST \
    -d \
'{
  "start" : "2024-04-08T22:00:00Z",
  "accountID": "ACC-{ID}",
  "product": "Business",
  "productRatePlan": "Standard",
  "state": "AwaitingPayment"
}'

Start as Provisioned

What if we created a subscription in the Provisioned state and want it to start in the future or adjust the start date to the future? The Update subscription  API call can be used to set the state to AwaitingPayment and the start date.

The start date can be provided when the sub is created or updated.

Note: if no start date is provided at creation it will default to the current time and a future start date could be provided on update.

Example:

# Create a subscription in 2024 with the state set as default, Provisioned

curl "https://api-sandbox.billforward.net/v1/subscriptions/create" \
    -H "Authorization: Bearer INSERT_ACCESS_TOKEN_HERE" \
    -H "Content-Type: application/json" \
    -X POST \
    -d \
'{
  "start" : "2024-04-08T22:00:00Z",
  "accountID": "ACC-{ID}",
  "product": "Business",
  "productRatePlan": "Standard"
}'

# Update the state of the subscription to AwaitingPayment, which will allow automatic invoicing
# As before, no invoice is raised until the 8th of April 2024 at 10PM (UTC)

curl "https://api-sandbox.billforward.net/v1/subscriptions/update" \
    -H "Authorization: Bearer INSERT_ACCESS_TOKEN_HERE" \
    -H "Content-Type: application/json" \
    -X POST \
    -d \
'{
  "id": "SUB-{ID}",
  "state": "AwaitingPayment"
}'