Subscriptions

It's never been easier to create weekly, monthly, and annual recurring payments! Spend less time tracking down payments and more time benefiting from recurring revenue.

How Subscriptions Work

Subscriptions allow you to charge a customer on a recurring basis. They 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:

  1. The subscription is created with a status of pending
  2. At the billing_cycle_anchor date, a PaymentIntent is created and confirmed
  3. The subscription.status is set to active
  4. 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
Canceled MANUAL FINAL STATE Active Payment Succeeded? Paused Past Due NON-FINAL STATE New Subscription Pending Time to Pay CANCEL CANCEL EXPIRED RETRY PAUSE/ RESUME The Subscription Lifestyle

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.

In the event of a failed charge, updating a subscription's payment intent directly via the Update a PaymentIntent endpoint will not affect the subscription's status. Update the subscription with a valid payment method and retry it instead.

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.

Payment intent id=pi_xxx subscription_id=sub_xxx status= requires_ payment_method payment_intent.payment_ failed Subscription id=sub_xxx status= past_due next_payment_at= null subscription.updated Payment intent id=pi_xxx subscription_id=sub_xxx status= succeeded payment_intent.succeeded Subscription id=sub_xxx status= active next_payment_at= {date} subscription.updated Payment intent id=sub_xxx status= canceled next_payment_at= null canceled_at= {now} subscription.canceled Payment intent id= sub_xxx status= paused next_payment_at= null canceled_at= {now} subscription.updated ATTRIBUTES WEBHOOK ATTRIBUTES WEBHOOK ATTRIBUTES WEBHOOK ATTRIBUTES WEBHOOK ATTRIBUTES WEBHOOK ATTRIBUTES WEBHOOK Recurring Payment Fails Recurring Payment Succeeds Subscription Canceled Subscription Paused

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:

  1. A customer.created event is sent, indicating that a customer record was successfully created.
  2. A payment_method.attached event is sent, indicating that the payment method was successfully attached to the customer.
  3. A subscription.created event is sent, indicating the subscription was created.
  4. payment_intent.created, payment_intent.succeeded, and charge.succeeded events are sent, indicating that the customer's payment method was successfully charged.
  5. 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.