Subscriptions allow payments to be created according to a schedule. The following guide details their capabilities and how best to implement them via the API.
Creating a subscription
To create a subscription for a customer, the following fields are required:
amount
- Amount in pence (GBP), cents (AUD/EUR/NZD), öre (SEK), or øre (DKK).
currency
- ISO 4217 currency code. Currently GBP, EUR, SEK, AUD, DKK, and NZD are supported.
interval_unit
- The unit of time between customer charge dates. One of weekly, monthly or yearly.
links[mandate]
- ID of the customer’s mandate which the subscription will create payments against.
In addition to these fields, the following optional parameters can be sent:
name
- Optional name for the subscription, which will also set the description of each payment.
interval
- the number of interval_units between each charge date. This must result in at least one charge per year, and will default to 1 if not provided.
count
- the total number of payments to be taken by the subscription.
day_of_month
- the day of the month (1-28) you’d like your customer to be charged on. You can also use -1 to indicate the last day of the month.
month
- the name of the month in which to charge a customer.
start_date
- the date on which the first payment should be charged. This date must be within a year of the subscription being created, and on or after the mandate’s next_possible_charge_date
. If this parameter isn’t included, the first payment will be charged as soon as possible.
payment_reference
- This parameter is restricted to Pro accounts only. An optional payment reference that will be set for all payments and will appear on your customer’s bank statement.
Specifying recurrence
The following rules apply when specifying recurrence:
- The first payment must be charged within 1 year.
- When neither month nor
day_of_month
are present, the subscription will recur from thestart_date
based on theinterval_unit
. - If month or
day_of_month
are present, the recurrence rules will be applied from the start_date, and the following validations apply:
|
|
|
---|---|---|
yearly |
optional (required if day_of_monthprovided) |
optional (required if monthprovided) |
monthly |
invalid |
required |
weekly |
invalid |
invalid |
Examples:
|
|
|
|
|
---|---|---|---|---|
yearly |
1 |
january |
-1 |
valid |
yearly |
1 |
march |
invalid - missing
|
|
monthly |
6 |
12 |
valid |
|
monthly |
6 |
august |
12 |
invalid -
|
weekly |
2 |
valid |
||
weekly |
2 |
october |
10 |
invalid -
|
One-time payments
In some cases, you may wish to charge a one-time fee in addition to the subscription e.g. A setup fee
To do this, you can simply send a request to create a single payment at the same time as creating the subscription.
Making changes to an existing subscription
To adjust the amount of a subscription e.g. to apply a discounted rate for x months, you can use the Update Subscription endpoint e.g.
To ensure that you update the amount at the correct time, you may need to consider tracking and storing the number payments created by a subscription by using webhooks or the events endpoint.
Unfortunately, it’s not possible to update the charge date of a subscription. To achieve this, you’ll need to cancel the existing subscription and create a new one with the updated billing dates.
Handling subscription related Events
If you’re using webhooks / the Events endpoint to update your own system, then you’ll need to be aware of the following subscription related events.
Whenever a payment is created by a subscription you'll receive two webhooks indicating this. One where the ResourceType is payments and one where this is subscriptions:
If you’re not storing any information on your side, you can link back to the subscription associated with the payment by making the following API calls:
Make a request to the Payments endpoint using the payment ID.
Within the response, locate the links[subscription]
field, which will contain the subscription ID of the relevant subscription.
You can then find the information relating to the subscription by making a request to the Subscriptions endpoint using the subscription ID.
Alternatives to subscriptions
Subscriptions can’t always provide the perfect solution for every integrator. Therefore, if you require additional functionality, we’d suggest looking into implementing your own subscription logic using the Payments endpoint.