Build your own Billing Portal with the Chargify API

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


Summary

Chargify Feature
Chargify API
You Need
Developers; an existing frontend UI for subscription management; a backend that already recognizes a logged in user.
Code
Yes
Difficulty
◉◉

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.

 

  1. Read the subscription
    You’ll need the subscription id, and then perform GET /subscriptions/:id.json.

  2. 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

  3. Pass the data to your frontend, and display it
    Here is a sample image that shows what an end result might look like:

    image4.png

2. Display an invoices page to your user
Let’s read the subscription’s invoices, so you can display them.

 

  1. Read the subscription’s invoices
    You’ll need the subscription id, and then perform GET /invoices.json?subscription_id=:id

  2. 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.

  3. 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:

    image12.png
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.

 

  1. Display the components to change
    Read the subscription’s components by performing GET /components.json.

  2. Parse the data you want to display
    For example, the component name would be similar to response[0].component.name.

  3. Pass the data to your frontend, and display it
    Here is a sample image that shows what an end result might look:

    image7.png

  4. 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.

  5. Submit the form with a “Change Add Ons” button
    Make the api call wi
    th POST /allocations.json

  6. 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.

 

  1. Add a cancel action
    It might look like this:

    image6.png

  2. 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.

    image1.png

  3. 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

  4. 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.

 

  1. Add a reactivation action, and only show it when a subscription is canceled
    It might look like this:

    image13.png

  2. 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.

    image8.png

  3. Upon submit, reactivate the subscription
    Do this by performing a /subscriptions/:id/reactivate.json

  4. 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.

 

  1. Add a pause action
    It might look like this:

    image6.png

  2. 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.

    image9.png

  3. Upon submit, cancel the subscription
    Do this with POST /subscription/:id/hold.json

  4. 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.

 

  1. Add a resume action, and only show it when a subscription is paused
    It might look like this:

    image10.png

  2. 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.

    image11.png

  3. Upon submit, resume the subscription
    Do this by performing /subscriptions/:id/resume.json

  4. 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.


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

 

Was this article helpful?
0 out of 0 found this helpful