How subscriptions work

Learn how subscriptions work within Flex

With subscriptions, customers can use their HSA/FSA to make recurring payments for access to a product.

Subscription Entities

Use the following resources to build and manage subscriptions

Integration Example

Here we'll walk through the steps that happen creating a subscription on Flex.

Your website

On your website customers have iether added items to their cart or specified the plan they would like to purchase. They are presented with a "Pay with HSA/FSA" button. Upon selecting the option your application will interact with the Flex API server to create a checkout session.

Ensure you have passed the appropriate prices that match the amount and cadence you'd like to charge for your subscription. Learn more about products and prices here.

Flex Hosted Checkout Page

Upon being redirected the customer will enter their payment details. Flex will create a subscription that by default will have the status of incomplete. Once the payment has been approved the subscription will transition to active. Along with a subscription being created, an invoice for the first payment will be created and a payment intent that corresponds to that specific invocie.

Upon succesful payment, the customer will be redirected to the redirect URL specified as part of the checkout session request.

Provisioning

After a successful payment, you can safely provision the product for the customer. This generally means:

1. Verifying the checkout session was completed.
2. Verifying the status of the subscription is active.
3. Granting the customer access. This can mean shipping a physical good, unlocking an access code, or notifying the customer.

Recurring charges

Flex will handle charging the customer's HSA/FSA card for you automatically. Each charge will have its own corresponding invoice and payment intent. If the payment fails you can listen to webhooks to monitor the status of the subscription and decide what would be the best action.

Handling recurring charge failures

To manage failures, set up a webhook and listen to the customer.subscription.updated event so that you're notified when subscriptions enter a past_due state.

From here, you can email the client to request an alternative payment method.

The subscription lifecycle

The following is the lifecycle of a subscription as customer checks out with Flex.

1. When a subscription gets created. The subscription is of status incomplete.
2. An invoice for the subscription gets created. The status of the invoice is open.
3. Customer successfully pays using their HSA/FSA
4. When the payment succeeds
   • The subscription status moves to active
   • The invoice status is set to paid
   • An invoice.paid, checkout_session.completed, customer.subscription.updated webhook event gets
5. Provision access to your product

The status can also become trialing if you offer a trial period. When the trial is over, the subscription moves to active and the subscribed customer starts to be charged.