Subscriptions
What is a Subscription?
Subscriptions are used to manage recurring payments. A Subscription ties a Payment Source to a Supporter and then regularly creates Payments for that Supporter based on the information in the Subscription.
Subscriptions use a Subscription Plan that defines dunning and notification settings. Based on the schedule Subscriptions will create Invoices, Charge Attempts and Payments.
What information does a Subscription hold?
A Subscription holds a reference to a Supporter, a Payment Source and a Subscription Plan. Additionally, it holds information about the interval and timezone (when Invoices should be created), payment provider, payment method, amount and currency that should be charged and information about the subscription's lifecycle.
A full list of Subscription fields can be gathered from the Subscription API.
Subscription interval and timezone
A Subscription will be charged based on the interval definition stored in the recurring_interval field. The interval definition is based on a cron expression without the minutes and hours part.
Some examples:
| Interval Definition | Description |
|---|---|
| * * * | Every day |
| 15 * * | Every 15th of the month |
| L * * | Last day of each month |
| L */6 * | Last day of June and December |
| 7 */3 * | 7th of January, April, July and October |
The charge day of a Subscription is based on the Subscription timezone. By default, the timezone is set to UTC, but a different timezone could be set when creating or updating a Subscription. Subscriptions will create an Invoice no earlier than midnight (in the Subscription timezone) of the day specified with the interval definition. Then a Charge Attempt will be created soon after. The exact time depends on payment network utilisation.
For example, a Subscription with the interval definition "L * *" in the Europe/Berlin timezone, will be charged at the earliest on the last day of each month at 1am UTC (or 2am depending on daylight saving times). Whereas a Subscription with the same interval definition, but in the America/NewYork timezone, will be charged one day earlier at 7pm UTC (or 8pm depending on daylight saving times ).
Subscription lifecycle
A Subscription can have one of the following statuses:
| Status | Description |
|---|---|
| pending | The Subscription is not yet active and needs to be activated in order to create charges. |
| active | The Subscription will be charged according to the interval definition. |
| suspended | The Subscription is currently suspended and will not create charges. |
| cancelled | The Subscription is cancelled and will no longer create charges. |
Planned effective date
Using the planned_effective_from field, a Subscription can be set up in a way that it will become active automatically on the specified date and charges will then be executed according to the interval definition.
The Subscription will be in a pending state until the planned_effective_from is reached.
The planned_effective_from date is interpreted in the timezone specified on the Subscription.
Activating a subscription with a planned_effective_from date
If a Subscription with a planned_effective_from date is activated via the Activate Subscription endpoint
the planned_effective_from is still taken into account when calculating the due date of the first Invoice.
The next_due_date of the Subscription will be the first match of the recurring_interval after or on the planned_effective_from date, however the effective_since date will be set to today.
Planned end date
Using the planned_end field, a Subscription can be set up in a way that it will be cancelled automatically on the specified date and no charges will be executed from that date onwards.
The planned_end date is interpreted in the timezone specified on the Subscription.
Invoices created before the planned_end date is reached are still subject to dunning.
Suspending a Subscription
The Suspend Subscription endpoint can be used to suspend Subscription.
The suspension_start and suspension_end dates are interpreted in the timezone specified on the Subscription.
When already set, the suspension_start or suspension_end dates can be modified with additional requests to the Suspend Subscription endpoint, until those days have been reached.
What is a Subscription Plan?
A Subscription Plan defines common behaviour for a group of Subscriptions. It defines notification settings and dunning configuration. A Subscription Plan can be configured to be the default Subscription Plan for an Organisation. When a Subscription is created and no Subscription Plan is specified in the request the default Subscription Plan is used.
The RaiseNow Global Default Subscription Plan
Raisenow provides a default Subscription Plan that is pre-configured with dunning best practices. Its name is "raisenow global default plan". The "RaiseNow Global Default Subscription Plan" cannot be modified.
When a Subscription is created, if no Subscription Plan is specified and no default Subscription Plan exists for that Organisation then the "RaiseNow Global Default Subscription Plan" is used.
What is an Invoice?
Everytime a Subscription is due (based on the interval definition) a new Invoice is created automatically. The Invoice amount is then collected by creating Charge Attempts following the Dunning Configuration. Invoices can also be created manually via the Create Invoice API endpoint to collect payments outside the subscription interval. Invoices can be closed via the Close an Invoice Manually API endpoint to stop the automatic collection of funds.
Invoices can have one of the following statuses:
| Status | Description |
|---|---|
| open | Funds have not been collected yet. |
| paid | All funds have been collected. |
| cancelled | Funds for this Invoice will no longer be collected. |
| refunded | Funds have been collected in the past, but have been refunded. |
| partially_refunded | Funds have been collected in the past, but parts of it have been refunded. |
What is a Charge Attempt?
Every time an Invoice tries to collect outstanding funds, it will create a new Charge Attempt. If a Charge Attempt fails, new Charge Attempts for the same Invoice will be created according to the dunning configuration of the Subscription Plan the Subscription uses.
Charge Attempts can have one of the following statuses:
| Status | Description |
|---|---|
| pending | Charge has been triggered, but the result is still open. |
| succeeded | Charge was successful. |
| failed | Charge has failed. |
| cancelled | Charge was cancelled. |
| refunded | Charge was successful, but has been refunded. |
| partially_refunded | Charge was successful, but parts of the funds have been refunded. |
| reversed | Charge was successful, but has been charged back. |
Subscription and Payments
For each Invoice of a Subscription, there can be several Charge Attempts. Each Charge Attempt relates to one Payment.
Dunning
If a Charge Attempt for an open Invoice fails, the Invoice can create new Charge Attempts to try to recover the funds later. The field dunning_configuration of a Subscription Plan describes how many Charge Attempts will be performed for an Invoice in case of failures, their delays, and whether a definitive failure should cancel the whole Subscription. Cancelled Charge Attempts are treated the same way as failed Charge Attempts and will follow the same dunning procedure.