Build your own Billing Portal with the Advanced Billing API

This guide contains a walkthrough with visual examples, and a list of all Core API Subscription Management objects.

Summary

Feature: Advanced Billing API
You Need: 1. Developers
2. Existing frontend UI for subscription management
3. Backend that recognizes a logged in user
Code: Yes
Difficulty: ◉◉◉◎◎

Core Subscription Management API Resources

The core API resources for managing subscriptions.

Basic Subscription/Customer Actions

Resource	Description
Read Customer’s Subscriptions	GET /customers/:id/subscriptions.json
Read Customer Payment Profiles	GET /payment_profiles.json?customer_id=:id
Update Customer	PUT /customers/:id.json
Read Subscription	GET /subscriptions/:id.json
Read Subscription Invoices	GET /invoices.json?subscription_id=:id
List Subscription’s Components (All)	GET /components.json
List Subscription’s Components (Only ones subscribed to)	GET /components.json > if allocated_quantity > 0, show. if kind is metered_component and price_point_id is not null, show.
Next billing amount and next renewal date	GET /subscriptions/:id.json > parse current_billing_amount_in_cents and next_assessment_at

Upgrade/Downgrade Actions

Resource	Description
Read Products from Catalog	GET product_families/:product_family_id/products.json
Preview Prorated Product U/D	POST /migrations/preview.json
Execute Prorated Product U/D	POST /migrations.json
Schedule Upgrade/Downgrade for Next Renewal	PUT /subscriptions/:id.json
Read Subscription’s Components	GET /components.json
Preview Component U/D	POST /allocations/preview.json
Execute Component U/D	POST /allocations.json
Read Offers from Catalog	GET /offers.json
Preview Offer U/D	POST /migrations/preview.json
Execute Offer U/D	POST /migrations.json
Enforce upgrades only	In your UI, only allow changes if the total cost of the change is greater than the current cost. Additionally, if you do not want to display lower cost options at all, filter out what you display to the user, based on price.

Cancel/Pause Actions

Resource	Description
View Invoices	GET /invoices.json?subscription_id=:id
Cancel Subscription (immediate)	DELETE /subscription/:id.json
Reactivate Subscription	PUT /reactivate.json
Create Pending Cancellation (delayed)	POST /delayed_cancel.json
Remove Pending Cancellation	DELETE /delayed_cancel.json
Pause Subscription	POST /hold.json
Resume Paused Subscription	PUT /resume.json

Payment Profile Actions

Resource	Description
Collect Payment Information	Docs: Chargify.js Guide: Here
Read Customer’s Payment Profiles	GET /payment_profiles.json?customer_id=:id
Create Payment Profile for Customer	POST /payment_profiles.json
Set Default Payment Method on Subscription	POST /change_payment_profile.json

Group/Hierarchy Actions

Resource	Description
Cancel a Group (immediate)	POST /subscription_groups/:uid/cancel.json
Cancel a Group (delayed)	POST /subscription_groups/:uid/delay_cancel.json
Read Consolidated Invoices for Group	GET /invoices.json?subscription_group_uid=:uid
Read Child Invoices	GET /invoices.json?subscription_id=:child_subscription_id
Remove Canceled Subscription from Group	DELETE /subscriptions/:id/group.json

Create a Subscription Management Dashboard

In this first section, you’ll create a subscription dashboard for your users, so they can view their subscription data, view their invoices, add/update payment methods, and perform actions on their subscription. These are visual examples, no code is available for these examples.

1. Display a subscription dashboard to your user

Let’s read the subscription, so you can display it in your UI.

Read the subscription
You’ll need the subscription id, and then perform GET /subscriptions/:id.json.
Parse the data you want to display
For example, the subscription id would be similar to response.subscription.id. Maybe you want the customer organization, which would be response.subscription.customer.organization
Pass the data to your frontend, and display it
Here is a sample image that shows what an end result might look like:

2. Display an invoices page to your user

Let’s read the subscription’s invoices, so you can display them.

Read the subscription’s invoices
You’ll need the subscription id, and then perform GET /invoices.json?subscription_id=:id
Parse the data you want to display
For example, the invoice uid would be similar to response.invoice.uid, or the invoice number response.invoice.number, or the invoice url response.invoice.public_url.
Pass the data to your frontend, and display it
Here is a sample image that shows what an end result might look like in a basic table/list layout:

3. Allow users to add/update payment information

On your subscription dashboard, you may provide a link to let users add/update their payment information. That link will take them to an "edit payment information" page. Use the guide called Collect Payment Methods in your App with Chargifyjs.

Optional - Add Component Changes

Let’s add component changes, so users can update them directly in your web application.

Display the components to change
Read the subscription’s components by performing GET /components.json.
Parse the data you want to display
For example, the component name would be similar to response[0].component.name.
Pass the data to your frontend, and display it
Here is a sample image that shows what an end result might look:
Add a preview changes section
Make a POST to /allocations/preview.json, parse the result, and display. This will show the user what the cost will be.
Submit the form with a “Change Add Ons” button
Make the api call with POST /allocations.json
Test your subscription dashboard
Your subscription dashboard should now reflect the changes of the subscription.

Optional - Allow Cancellations

Let’s add cancellations to your web application.

Add a cancel action
It might look like this:
Add a page in your UI, with a preview, confirmation, and submit button
It might look like this. This is a great place to clearly establish the terms of cancellation and informing the user of what will happen.

Upon submit, cancel the subscription
Choose which method you prefer:

Cancel Subscription (Immediate)	The user can cancel their subscription, and the cancellation takes effect immediately.	DELETE /subscription/:id.json
Cancel Subscription (Delayed)	The user can schedule their subscription to cancel at the end of the current billing period.	POST /delayed_cancel.json

Test your subscription dashboard
On your subscription dashboard, if you show the subscription state, it should now reflect the changes of the subscription. If there are certain actions that need to be shown/removed for a canceled subscription, or a subscription that is scheduled to cancel, do those in your UI.

Optional - Allow Reactivations of a Canceled Subscription

Let’s add reactivations to your web application.

Add a reactivation action, and only show it when a subscription is canceled
It might look like this:
Add a page in your UI, with a preview, confirmation, and submit button
It might look like this. This is a great place to clearly establish the terms of reactivation and informing the user of what will happen, such as how much they will be charged (if any), and anything else you need to communicate.
Upon submit, reactivate the subscription
Do this by performing a /subscriptions/:id/reactivate.json
Test your subscription dashboard
On your subscription dashboard, if you show the subscription state, it should now reflect the changes of the subscription. If there are certain actions that need to be shown/removed for an active subscription, do those in your UI.

Optional - Allow Pausing

Let’s add pausing a subscription to your web application.

Add a pause action
It might look like this:
Add a page in your UI, with a preview, confirmation, and submit button
It might look like this: This is a great place to clearly establish the terms of pausing and informing the user of what will happen.
Upon submit, cancel the subscription
Do this with POST /subscription/:id/hold.json
Test your subscription dashboard
On your subscription dashboard, if you show the subscription state, it should now reflect the changes of the subscription. If there are certain actions that need to be shown/removed for a paused subscription, do those in your UI.

Optional - Allow Resuming a Paused Subscription

Let’s add resuming to your web application.

Add a resume action, and only show it when a subscription is paused
It might look like this:
Add a page in your UI, with a preview, confirmation, and submit button
It might look like this. This is a great place to clearly establish the terms of resuming and informing the user of what will happen.
Upon submit, resume the subscription
Do this by performing /subscriptions/:id/resume.json
Test your subscription dashboard
On your subscription dashboard, if you show the subscription state, it should now reflect the changes of the subscription. If there are certain actions that need to be shown/removed for a active subscription, do those in your UI.