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

Advanced Billing will always assist with helping you determine which Webhooks and APIs to use. Advanced Billing 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 Advanced Billing 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, Advanced Billing Admin UI, CRM.

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 Advanced Billing data: `status` - The subscription status (eg: active, past_due, etc) One of the following 3 methods to identify the subscription: `subscription_id` - The Advanced Billing-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 Advanced Billing-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 Advanced Billing. 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 Advanced Billing data you need. You'll either do this in real time or async (non real time).

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.

First, configure the signup_success webhook, by going to Config > Settings > Webhook > enable the webhook.

Next, create a subscription that mirrors your use case. The webhook will be sent to your server.

//Filtered webhook body for signup_success
{
  "id":1454785060,
  "event":"signup_success" //the webhook event type
  {
     "id"=>50652871, //the Chargify-generated subscriptionID
     "state"=>"active", //the subscription status
     ...
     "customer"=> {
       "reference"=>"ref_nxzfmNwEakbfWB9XY", //your unique customer reference
       ...
      },  
   ...
  }
}

Parse the relevant data from the webhook, and then update your database:

//Update your database (conceptual example)
//if event is signup_success
if (webhook.event == 'signup_success) {
  UPDATE users
  SET subscription_id='50652871', subscription_status='active'
  WHERE user_id='ref_nxzfmNwEakbfWB9XY';
}

You're finished. Test this portion of your workflow to make sure it's working correctly.

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 only applies when you are building your own billing portal with the Advanced Billing 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. Advanced Billing 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.

First, configure the subscription_state_change webhook, by going to Config > Settings > Webhook > enable the webhook.

Next, create a subscription (or use an existing one) that mirrors your use case. Change the status of the subscription by cancelling it. The subscription_state_change webhook will be sent to your server.

//Filtered webhook body for subscription_state_change
{
  "id":1454785111,
  "event":"subscription_state_change" //the webhook event type
  {
     "id"=>50652871, //the Chargify-generated subscriptionID
     "state"=>"canceled", //the subscription status
     "previous_state"=>"active", //the previous subscription status
     ...
     "customer"=> {
       "reference"=>"ref_nxzfmNwEakbfWB9XY", //your unique customer reference
       ...
      },  
   ...
  }
}

Parse the relevant data from the webhook, and then update your database. Consider creating different database queries for each of your relevant subscription state scenario (see examples in code block below), so you can control exactly what is fed to your database.

//Update your database based on your user_id (conceptual example)
//if event is subscription_state_change
if (webhook.event == 'subscription_state_change') {
  UPDATE users
  SET subscription_status='canceled' //pass the new state - Chargify's value, or your own
  WHERE user_id='ref_nxzfmNwEakbfWB9XY'; //find the subscription based on the reference value
}

//Update your database based on subscription_id (conceptual example)
if (webhook.event == 'subscription_state_change') {
  UPDATE users
  SET subscription_status='canceled' //pass Chargify's value of 'canceled' or your own value
  WHERE subscription_id='50652871';
}

//Reactivation
if (previous_state == 'canceled' && state == 'active') {...}

//Subscription becomes past due
if (previous_state == 'active' && state == 'past_due') {...}

//past_due subscription pays in full
if (previous_state == 'past_due' && state == 'active') {...}

//Subscription pauses
if (previous_state == 'active' && state == 'on_hold') {...}

//Subscription resumes
if (previous_state == 'on_hold' && state == 'active') {...}

//Subscription converts from trialing
if (previous_state == 'trialing' && state == 'active') {...)

You're finished. Test this portion of your workflow to make sure it's working correctly.

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 Advanced Billing 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, Advanced Billing Admin UI, CRM. Async plan changes include Billing Portal and CRM.

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 Advanced Billing 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 Advanced Billing-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 Advanced Billing-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 Advanced Billing. 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 Advanced Billing data you need. You'll either do this in real time or async (non real time).

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';

//Filtered webhook body for signup_success
{
  "id":1454785060,
  "event":"signup_success" //the webhook event type
  {
     "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
       ...
      },
   ...
  }
}

Parse the relevant data from the webhook, and then update your database:

//Update your database (conceptual example)
//if event is signup_success
if (webhook.event == 'signup_success) {
  UPDATE users
  SET subscription_id='50652871', subscription_status='active', plan='gold_plan'
  WHERE user_id='ref_nxzfmNwEakbfWB9XY';
}

You're finished. Test this portion of your workflow to make sure it's working correctly.

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 Advanced Billing 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 Advanced Billing Admin UI or a CRM).

Real time only applies when you are building your own billing portal with the Advanced Billing 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. Advanced Billing 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.

First, configure the subscription_product_change webhook, by going to Config > Settings > Webhook > enable the webhook.

Next, create a subscription (or use an existing one) that mirrors your use case. Change the subscription plan. The subscription_product_change webhook will be sent to your server.

//Filtered webhook body for subscription_product_change
{
  "id":1454785112,
  "event":"subscription_product_change" //the webhook event type
  {
     "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
       ...
      },
   ...
  }
}

Parse the relevant data from the webhook, and then update your database.

//Update your database based on your user_id (conceptual example)
//if event is subscription_product_change
if (webhook.event == 'subscription_product_change') {
  UPDATE users
  SET plan='gold_plan'
  WHERE user_id='ref_nxzfmNwEakbfWB9XY';
}

//Update your database based on subscription_id (conceptual example)
if (webhook.event == 'subscription_product_change') {
  UPDATE users
  SET plan='gold_plan'
  WHERE subscription_id='50652871';
}

You're finished. Test this portion of your workflow to make sure it's working correctly.

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 Advanced Billing Admin UI or a CRM.