Billing Flows via the API
Use Autumn’s API or SDK to roll your own upgrade/downgrade flows, paywalls and more.
Autumn handles your billing flows, so you don’t need to build and maintain user flows like:
- Purchasing a product
- Inputting quantities for prepaid products
- Upgrading, downgrading, cancelling or renewing a product’s subscription
- Paywalling features
- Failed payments [coming soon]
This page covers how to roll your own billing flows using our API or SDK. Alternatively, you can use our customizable shadcn/ui components to handle these out-of-the-box.
Product Change
Typically when charging a customer’s card, you’ll want them to confirm the payment beforehand. This is useful for upgrade, downgrade or add-on payment flows.
The check
function has a with_preview
parameter that can be used to get purchase preview information that can be displayed to the customer.
There are two options for handling these flows:
- Pass in a component to the
attach
React hook - Build your own flow from scratch
You can pass in a custom component (such as a dialog) to the attach()
hook. This will automatically call check
with with_preview: true
and pass down a params
object to the component.
Params contains the following properties:
open
: A boolean that will be true if an input is required from the customer, such as to confirm a purchase or input a quantity.setOpen
: A function that will be used to close the dialog.preview
: The preview object returned from thecheck
function.
If there is no preview
object, open
will be false
and the customer will be directed directly to a checkout page.
You can pass in a custom component (such as a dialog) to the attach()
hook. This will automatically call check
with with_preview: true
and pass down a params
object to the component.
Params contains the following properties:
open
: A boolean that will be true if an input is required from the customer, such as to confirm a purchase or input a quantity.setOpen
: A function that will be used to close the dialog.preview
: The preview object returned from thecheck
function.
If there is no preview
object, open
will be false
and the customer will be directed directly to a checkout page.
The preview
object that is returned from the check
function can be used to control the dialog’s contents. preview
can also be null
if there is no input required from the customer, suggesting that the customer can be directed directly to a checkout page.
Example implementation:
If preview
is returned, it will contain a scenario
enum, which can be one of the following:
Scenario | Description |
---|---|
upgrade | The customer is upgrading their product |
downgrade | The customer is downgrading to another paid tier |
cancel | The customer is downgrading to a free product |
renew | The customer is reactivating a product that was previously cancelled |
scheduled | The product is already scheduled to start at a future date (eg, for downgrades), so no changes are needed |
active | The customer already has the product active, so no changes are needed |
You can use this to control the dialog’s contents.
Paywall
A paywall that prompts users to upgrade to the next tier when they hit a usage limit, or don’t have access to a feature.
The check
function has a with_preview
parameter that can be used to get paywall preview information when a customer doesn’t have access to a feature. This will contain information about the next product tier (or an add-on) they should upgrade to, in order to access the feature.
There are two options for handling these flows:
- Pass in a component to the
check
React hook - Build your own flow from scratch
You can pass in a custom component (such as a dialog) to the check() hook. This will automatically call check with with_preview: true and pass down a params object to the component.
Params contains the following properties:
- open: A boolean that will be true if the feature is not allowed and a paywall should be shown.
- setOpen: A function that will be used to close the dialog.
- preview: The preview object returned from the check function.
If the feature is allowed, open will be false and no paywall will be shown.
You can pass in a custom component (such as a dialog) to the check() hook. This will automatically call check with with_preview: true and pass down a params object to the component.
Params contains the following properties:
- open: A boolean that will be true if the feature is not allowed and a paywall should be shown.
- setOpen: A function that will be used to close the dialog.
- preview: The preview object returned from the check function.
If the feature is allowed, open will be false and no paywall will be shown.
The preview object that is returned from the check function can be used to control the paywall’s contents. preview will be null if the feature is allowed and no paywall should be shown.
Example implementation:
If preview is returned, it will contain a scenario enum, which can be one of the following:
Scenario | Description |
---|---|
usage_limit | The customer has hit a usage limit for the feature |
feature_flag | The customer doesn’t have access to the feature |
You can use this to control the paywall’s contents.