Subscriptions

Easily create weekly, monthly, and annual recurring payments and start benefitting from recurring revenue.

Subscriptions allow you to charge a customer on a recurring basis.

How Subscriptions Work

Subscriptions are created using the Subscriptions API. A customer and one of their associated payment methods is required. While the customer cannot be changed, the payment method can be updated as necessary.

A combination of billing_cycle_anchor, interval_unit, and interval_count are used to compute the billing cycles. The billing_cycle_anchor determines the date of the first payment and the day of week/month/year for subsequent payments. If a month doesn’t have the anchor day, the subscription will be billed on the last day of the month. For example, a monthly subscription starting on January 31 bills on Feb 28/29, then March 31, April 30, etc. The interval_count represents the number of intervals (specified in the interval_unit attribute) between subscription billings. Examples:

BILLING CYCLE ANCHOR	INTERVAL UNIT	INTERVAL COUNT	FIRST 5 PAYMENT DATES	DESCRIPTION
01/01/21	`month`	1	01/01/21 02/01/21 03/01/21 04/01/21 05/01/21	The first of every month.
01/01/21	`month`	3	01/01/21 04/01/21 07/01/21 10/01/21 01/01/22	The first of every 3 months.
01/31/21	`month`	1	01/31/21 02/28/21 03/31/21 04/30/21 05/31/21	The last day of every month.
01/01/21 (Fri)	`week`	2	01/01/21 (Fri) 01/15/21 (Fri) 01/29/21 (Fri) 02/12/21 (Fri) 02/26/21 (Fri)	Every other Friday.
01/01/21	`year`	1	01/01/21 01/01/22 01/01/23 01/01/24 01/01/25	The first of every year.

Subscriptions can be paused, which prevents any payment attempts from occuring during the paused status. They can be paused adhoc via API or at a future date via the pause_at attribute. Paused subscriptions can be resumed adhoc via API or at a future date via the resume_at attribute.

Subscriptions can be canceled, which cancels a customer’s subscription immediately and prevents all future payments from occurring. This can be done via API or at a future date via the cancel_at attribute.

How Payments Work with Subscriptions

The PaymentIntent tracks the lifecycle of every payment. Whenever a payment is due for a subscription, Tilled generates a PaymentIntent. The state of the PaymentIntent affects the state of the subscription.

PAYMENT OUTCOME	PAYMENTINTENT STATUS	SUBSCRIPTION STATUS
Success	`succeeded`	`active`
Failure	`requires_payment_method`	`past_due`

To retrieve all the payment attempts (i.e. PaymentIntents) associated with a subscription, use the PaymentIntents API and pass the subscription_id query parameter.

Succeeded

When the payment succeeds, the subscription is active and the status of the PaymentIntent is succeeded. The payment is complete and you should provision access to your product.

Requires Payment Method

If payment fails because of a card error such as a decline, the status of the PaymentIntent is requires_payment_method and the subscription is past_due. To resolve these scenarios:

Notify the customer
Collect new payment information by updating the payment method on the subscription
Retry the subscription payment via the Retry operation

Tilled will not automatically attempt a retry. It is your responsibility to update the payment method and retry the payment.

The Subscription Lifecycle

A successful subscription flow looks like this:

The subscription is created with a status of pending
At the billing_cycle_anchor date, a PaymentIntent is created and confirmed
The subscription.status is set to active
The subscription will continue to run indefinitely in the active status or until the cancel_at date at which time its status will be set to canceled

Subscriptions remain in status pending until their first payment is attempted at the billing_cycle_anchor. Once the first payment is successful, the subscription updates to active and will remain so as long as automatic payments succeed. If automatic payment fails, the subscription updates to past_due and will remain there until you attempt to Retry the payment.

Automatic payments are only attempted during the pending and active statuses. Tilled will not attempt automatic payments during paused, past_due, or canceled statuses.

Subscription Statuses

STATUS	DESCRIPTION
`pending`	The subscription was created successfully and is waiting until `billing_cycle_anchor` to process the first payment.
`active`	The subscription is in good standing and the most recent payment was successful. It’s safe to provision your product for your customer.
`past_due`	Payment on the latest billing cycle either failed or wasn’t attempted. No payment attempts will occur until a retry is attempted.
`paused`	The subscription has been paused and no payments will occur until resumed.
`canceled`	The subscription has been canceled and all future payments cease to occur.

Subscription Events

Events are triggered any time a subscription is created or changed. Some events are sent immediately when a subscription is created, while others recur on regular billing intervals.

Subscriptions explicitly generate 3 types of events:

subscription.created
subscription.updated
subscription.canceled

Additionally, payment_intent.* events (e.g. payment_intent.succeeded) are generated and include subscription_id in the payload.

Creating a customer with a valid payment method and associating them with a subscription causes Tilled to send the following events- though the exact order is not guaranteed:

A customer.created event is sent, indicating that a customer record was successfully created.
A payment_method.attached event is sent, indicating that the payment method was successfully attached to the customer.
A subscription.created event is sent, indicating the subscription was created.
payment_intent.created, payment_intent.succeeded, and charge.succeeded events are sent, indicating that the customer’s payment method was successfully charged.
A subscription.updated event is sent, where the payload will reflect that the status=active and next_payment_at is the date of the next automatic payment attempt.