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
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|
|The first of every month.|
|The first of every 3 months.|
|The last day of every month.|
|Every other Friday.|
|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
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
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|
To retrieve all the payment attempts (i.e. PaymentIntents) associated with a subscription, use the PaymentIntents API and pass the
subscription_id query parameter.
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
- At the
billing_cycle_anchordate, a PaymentIntent is created and confirmed
subscription.statusis set to
- The subscription will continue to run indefinitely in the
activestatus or until the
cancel_atdate at which time its
statuswill be set to
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
active statuses. Tilled will not attempt automatic payments during
||The subscription was created successfully and is waiting until
||The subscription is in good standing and the most recent payment was successful. It's safe to provision your product for your customer.|
||Payment on the latest billing cycle either failed or wasn't attempted. No payment attempts will occur until a retry is attempted.|
||The subscription has been paused and no payments will occur until resumed.|
||The subscription has been canceled and all future payments cease to occur.|
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:
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:
customer.createdevent is sent, indicating that a customer record was successfully created.
payment_method.attachedevent is sent, indicating that the payment method was successfully attached to the customer.
subscription.createdevent is sent, indicating the subscription was created.
charge.succeededevents are sent, indicating that the customer's payment method was successfully charged.
subscription.updatedevent is sent, where the payload will reflect that the
next_payment_atis the date of the next automatic payment attempt.