Building Workflows with APIs and Webhooks

This guide will walk you examples of workflows, writing your own custom code, using APIs and webhooks. When you're finished, you'll be able to implement these workflows into your web applications.

Support

Chargify will always assist with helping you determine which Webhooks and APIs to use. Chargify does not assist in building, debugging, maintaining, or supporting your workflow now or on an ongoing basis.

Paid-user access Feature-gating plans


Summary

Feature
Webhooks and API
You Need
Database, App Login, Signup Process, your App restricts based on status (See step 2 for details)
Code
Yes
Difficulty
◉◉◉◎◎

How to manage access to your app based on subscription status

Most SaaS applications allow user access based on a customer's subscription status. For example, if a subscriptions status is active, a user can use your app. If a subscriptions status is canceled, your user cannot. Let's set this up for your Chargify implementation.

1. How it works  Diagram
Here is an example of the paid-user access billing lifecycle. User access can be real time, or non-real time (async). Real time signups include Chargifyjs and API. Aysnc signups include PSP, OSP, Chargify Admin UI, CRM.

Real time (API) Async (Webhooks)
Quickstart_-_Paid-user_access__real_time_signup_.png
2. Set the foundation
Before implementing, you need to make sure your application has these prerequisites in place. You most likely already have all (or most) of these in place today. If you do not have any of these in place today, make sure to set them up before you proceed.

You need a... That meets these prerequisites...
Database
Required
  • Has a user record table
  • The table stores, at a minimum, this Chargify data:
    • status - The subscription status (eg: active, past_due, etc)
    • One of the following 3 methods to identify the subscription:
      • subscription_id - The Chargify-generated subscription_id of the subscription record (eg: 50124876)
      • subscription_reference - Your unique user ID that is also stored on the reference value on the subscription record. Use this value, if you'd like to store your own ID, rather than the Chargify-generated subscription_id. (less common)
      • customer_reference Your unique user ID that is also stored on the reference value on the customer record. (more common)
App Login
Required
A web application that handles new user account creation (eg: a standard email address and password login, where you create a new user record in your database). You most likely already have this.
New User Signup Process
Required
A new user can signup and subscribe to your services, which creates a subscription in Chargify. You most likely already have this, but if you do not, start by designing your new user signups.
Code that shows/restricts user access
Required
Application code that allows/restricts user access.


3. Store the subscription status on signup
First, when the user subscribes to your services, you'll want to store the main Chargify data you need. You'll either do this in real time or async (non real time).

Real time (API) Async (Webhooks)
When you create your subscription with the API, you are typically 1) creating a paid subscription with a Chargifyjs token, or 2) creating a free trial with no credit card. In both cases, you'll want to parse the subscription response, look for state and subscription.id, and store them in your database.

Here's a subscription API response, but filtered to only show the important fields for this workflow:
//Filtered API response when creating a subscription
{
  "subscription": {
    "id": 50652871, //the Chargify-generated subscriptionID
    "state": "active", //the subscription status
    ...
    "customer": {
      "reference": "ref_nxzfmNwEakbfWB9XY", //your unique customer reference
      ...
    },
    ...
  }
}


Then update your database: 
//Update your database (conceptual example)
UPDATE users
SET subscription_id='50652871', subscription_status='active'
WHERE user_id='ref_nxzfmNwEakbfWB9XY';


Finally, redirect your user to their end destination, such as a dashboard page, or a thank-you-for-signing-up page in your app. This flow will be in real time, and once the user is redirected they should have access to paid features in your app.
4. Update the subscription status when it changes
Next, you'll need to update the subscription status for your user, any time it changes. Common examples include: when a user cancels, when a subscription goes past due, etc. Even if you have real time subscription state changes to your database, you still may need to implement webhooks to catch subscription state changes your users can't initiate (for example, when a renewal payment fails and a user's subscription changes to past due).

Real time (API) Async (Webhooks)
Real time only applies when you are building your own billing portal with the Chargify API. For example, a user is in your application, clicks a button to cancel, and you immediately update your database, which subsequently restricts access to your app. 

Let's say the user clicks the cancel button in your app, your server-side code makes a DELETE /cancel/{subscription_id} API request, and is successful. Chargify returns an API response:
//Filtered API response when creating a subscription
{
  "subscription": {
    "id": 15254809,
    "state": "canceled",
    "previous_state": "active",
    ...
    "customer": {
      "reference": "ref_nxzfmNwEakbfWB9XY",
      ...
    },
    ...
  }
}


Since the API response returns a 200 or 201 status code (signaling it is successful), you can update your database: 
//Update your database based on your user_id (conceptual example)
UPDATE users
SET subscription_status='canceled' //pass Chargify's value of 'canceled' or your own value
WHERE user_id='ref_nxzfmNwEakbfWB9XY';

//Update your database based on subscription_id (conceptual example)
UPDATE users
SET subscription_status='canceled' //pass Chargify's value of 'canceled' or your own value
WHERE subscription_id='15254809';


Finally, redirect your user to their end destination. This flow will be in real time, and once the user is redirected they should have access removed.
5. Test your application
Now that you have implemented this, you can test. Here's a checklist of scenarios to test:

1. When a user subscribes, do they have access?
2. When a user cancels, do they have access removed?
3. Test other scenarios, as they are relevant to you:
    - A user pauses/unpauses their subscription
    - A user reactivates their subscription
    - A user's renewal payment fails
    - A user upgrades their trialing account

Summary

Feature
Webhooks and API
You Need
Database, App Login, Signup Process, your App restricts based on subscription plan (See step 2 for details)
Code
Yes
Difficulty
◉◉◉◎◎

How to build feature gating in your app

Most SaaS applications show or restrict features, based on a customer's subscription plan. For example, if a subscription's status is active and the subscription plan bronze, you show features relevant to the bronze plan in your app. If the gold plan, you show features for gold. Let's set this up for your Chargify implementation.

1. How it works  Diagram
Here is an example of the feature-gating access billing lifecycle. User access can be real time, or non-real time (async). Real time signups include Chargifyjs and API. Real time plan changes include Billing Portal and CRM. Aysnc signups include PSP, OSP, Chargify Admin UI, CRM. Async plan changes include Billing Portal and CRM.

Real time (API) Async (Webhooks)
Quickstart_-_Feature-gating__real_time_.png
2. Set the foundation
Before building, you need to make sure your application has these prerequisites in place. You most likely already have all (or most) of these in place today. If you do not have any of these in place today, make sure to set them up before you proceed.

You need a... That meets these prerequisites...
Database
Required
  • User record table
  • The table stores this Chargify data:
    • status - The subscription status (eg: active, past_due, etc)
    • plan - The subscription's product handle (eg: bronze, gold, etc)
    • One of the following 3 methods to identify the subscription:
      • subscription_id - The Chargify-generated subscription_id of the subscription record (eg: 50124876)
      • subscription_reference - Your unique user ID that is also stored on the reference value on the subscription record. Use this value, if you'd like to store your own ID, rather than the Chargify-generated subscription_id. (less common)
      • customer_reference Your unique user ID that is also stored on the reference value on the customer record. (more common)
App Login
Required
A web application that handles new user account creation (eg: a standard email address and password login, where you create a new user record in your database). You most likely already have this.
New User Signup Process
Required
A new user can signup and subscribe to your services, which creates a subscription in Chargify. You most likely already have this, but if you do not, start by designing your new user signups.
Code that shows/restricts features
Required
Application code that shows/restricts features based on plan type.


3. Store the subscription plan on signup
First, when the user subscribes to your services, you'll want to store the main Chargify data you need. You'll either do this in real time or async (non real time).

Real time (API) Async (Webhooks)
When you create your subscription with the API, you are typically 1) creating a paid subscription with a Chargifyjs token, or 2) creating a free trial with no credit card. In both cases, you'll want to parse the subscription response, look for state, subscription.id, and plan name handle, and store them in your database.

Here's a subscription API response, but filtered to only show the important fields for this workflow:
//Filtered API response when creating a subscription
{
  "subscription": {
    "id": 50652871, //the Chargify-generated subscriptionID
    "state": "active", //the subscription status
    ...
    "customer": {
      "reference": "ref_nxzfmNwEakbfWB9XY", //your unique customer reference
      ...
    },
    "product": {
      "handle": "gold_plan", //your plan handle
      ...
    },
    ...
  }
}


Then update your database: 
//Update your database (conceptual example)
UPDATE users
SET subscription_id='50652871', subscription_status='active', plan='gold_plan'
WHERE user_id='ref_nxzfmNwEakbfWB9XY';


Finally, redirect your user to their end destination, such as a dashboard page, or a thank-you-for-signing-up page in your app. This flow will be in real time, and once the user is redirected they should have access to paid features in your app.
4. Update the subscription plan in your database when it changes
Next, you'll need to update the subscription plan for your user, any time it changes. Common examples include: a) when a user upgrades to gold, update your database b) when a staff member updates a subscription plan in the Chargify Admin UI or CRM, update your database. Even if you have real time plan changes, you still may need to implement webhooks to catch plan changes your staff initiate (such as from the Chargify Admin UI or a CRM).

Real time (API) Async (Webhooks)
Real time only applies when you are building your own billing portal with the Chargify API. For example, a user clicks a button to upgrade to the gold plan, and you immediately update your database, which immediately unlocks the gold plan features.

Let's say the user clicks the 'upgrade to gold' button in your app, your server-side code makes a POST /subscription/{subscription_id}/migrations API request, and is successful. Chargify returns an API response:
//Filtered API response when changing a subscription plan
{
  "subscription": {
    "id": 15254809,
    "state": "active",
    ...
    "customer": {
      "reference": "ref_nxzfmNwEakbfWB9XY",
      ...
    },
    "product": {
      "handle": "gold_plan",
      ...
    },
    ...
  }
}


Since the API response returns a 200 or 201 status code (signaling it is successful), you can update your database: 
//Update your database based on your user_id (conceptual example)
UPDATE users
SET plan='gold_plan'
WHERE user_id='ref_nxzfmNwEakbfWB9XY';

//Update your database based on subscription_id (conceptual example)
UPDATE users
SET plan='gold_plan'
WHERE subscription_id='15254809';


Finally, redirect your user to their end destination. This flow will be in real time, and once the user is redirected they should have the relevant features added or removed.
5. Test your application
Now that you have implemented this, you can test. Here's a checklist to get started:

1. When a user subscribe to a specific plan, do they have access to that plan's features?
2. When a user changes plans, do they have access to that new plan's features (and by extension, do not have access to the old plan's features)?
3. Same as #2, but if your staff updates the plan in Chargify Admin UI or a CRM.
Was this article helpful?
1 out of 1 found this helpful