Manage Subscriptions

InTandem provides flexible billing flow integrations for its platform, empowering partners to incorporate their billing systems seamlessly. This approach allows partners to control the billing process while leveraging inTandem's robust subscription management capabilities.

By handling subscriptions through inTandem, partners can focus on managing the financial transactions and billing cycles with their preferred systems, ensuring a cohesive and efficient billing experience for users.

Glossary

Product - a software functionality scope for end users. For example - Core CRM Modules, Quickbook app, 250 SMS monthly quota.
Purchasable - a commercial agreement between inTandem and a partner to sell a product, a subset of a product or a bundle of products for a certain price.
For Example - Platinum Subscription, Quickbook app.
Subscription - a record describing a product purchased by a specific user and its commercial - create date, product id, price, related purchasable, commercial terms (price, expiration date, auto renewal etc.).

Subscription States

InTandem subscriptions are structured to exist in one of three states:

Purchased - This is the initial status upon subscription creation, signifying that the business has earned the rights to the subscription's assets, whether through direct payment or as part of a bundle with another subscription.
Canceled - A cancel request was sent. The package is still available until expriration_date date reaches.
Expired - This status indicates that the business's rights to the subscription's assets have ceased, either due to the cancellation of the subscription or the completion of a dunning process.

Retrieving the business's subscriptions

when creating a business using the Create Business API, inTandem automatically sets the business up with a default subscription in its Subscriptions Manager. This subscription is accessible to the business, inTandem, and future apps that the user installs (and consent). The subscriptions, and any other subscription the business acquires, can be retrieved using the Get Subscriptions API.

An example of how to get the business's subscriptions:

curl --location --globoff 'https://api.vcita.biz/business/subscriptionsmng/v1/subscriptions?[filter][business_uid]={business uid}' \
--header 'Authorization: Bearer {Business token}' \
--header 'Content-Type: application/json' \

The above call response:

{
    "data": {
        "subscriptions": [
            {
                "uid": "b7ba1466-771e-432b-9c75-d738942bd7de",
                "display_name": "permium plan",
                "purchasable_uid": "ee655c26-4a57-48df-8e2e-f85a994b335c",
                "buyer_uid": "z7oeioxaqhinvcaa",
                "business_uid": "aasd2adfdsf34a",
                "purchase_currency": "USD",
                "purchase_price": "50.00",
                "purchase_state": "purchased",
                "cancellation_date": null,
                "expiration_date": null,
                "updated_at": "2024-03-24T12:54:16.000Z",
                "created_at": "2024-03-19T07:50:01.594Z",
                "payment_type": "monthly",
                "bundled_from_subscription_uid": null,
                "is_active": true
            }
        ]
    },
    "success": true
}

obtaining Business Token

In the flows below APIs calls are done in a business context, i.e. a business API token is required. A directory can obtain a business API token, assuming the business belongs to that directory, by calling the following API:

curl --location 'https://api.vcita.biz/platform/v1/tokens' \
--header 'accept: application/json' \
--header 'Authorization: Bearer {Directory API Token}' \
--header 'Content-Type: application/json' \
--data '{
    "business_id": "5awpy58fyup759m5"
}'

The response of this call is:

{
    "status": "OK",
    "data": {
        "token": "0e46xx1dcfcf53675d4d1f544ec3f317d9ec5d6923b145a9074e1fd7a48689e2"
    }
}

Copy the token value and use it for further API calls

Billing Flows

inTandem implements four types of billing-related flows. Apart from Dunning, every flow necessitates user involvement for actions such as choosing a product, confirming payments, and cancellations.

The inTandem platform enables a specific configuration for different product types. Configuration includes a URL that starts the flow and where it should end. For further details on External Pricing Page Integration, click here.

InTandem has a built-in billing system that handles all payment, change plan and cancellation flows. To implement your billing system, you must implement the following flows for each product type you wish to charge for.

Purchase Flow

A process is activated when a user buys a new type of product (for example, a plan, a specific app, or a consumable package like SMS.)

Step-by-Step Process

Select product - Conducted outside the inTandem ecosystem, this step involves the user picking a product for purchase (the main subscription or an additional product).
Payment - For the first payment, the user typically enters payment method details to create a billable account then, your billing system executes the payment.
Payment complete - The billing system records the purchase, invoice, and charge accordingly.
Create subscription - an API call to inTandem's Subscriptions Manager to create a corresponding subscription for the purchased product. After the subscription has been established, it is marked as Purchased, and the business gains access to all the associated benefits and resources.
The API call returns the subscription uid. Store this as reference for update and delete flows.
The Create Subscription API call includes:
- Authorization token (Directory)
- purchasable_price_uid - Purchasable Price UID (can be acquired through the Get Purchasable API)

An example of how to call the Create Subscription API is as follows:

curl --location 'https://api.vcita.biz/business/subscriptionsmng/v1/subscriptions' \
--header 'Authorization: Bearer {Business API token}' \
--header 'Content-Type: application/json' \
--data '{
		"business_uid":"{business uid}",
    "subscription": {
        "purchasable_price_uid": "{Selected purchasable id}"
    }
}'

An example of return load from the Create subscription API:

{
  "success": true,
  "data": {
    "subscription": {
      "is_active": true,
      "uid": "string",
      "updated_at": "2024-03-03T13:23:13.963Z",
      "created_at": "2024-03-03T13:23:13.963Z",
      "purchasable_uid": "string",
      "purchase_state": "string",
      "cancellation_date": "2024-03-03T13:23:13.963Z",
      "expiration_date": "2024-03-03T13:23:13.963Z",
      "buyer_uid": "string",
      "business_uid": "string",
      "purchase_price": 0,
      "purchase_currency": "string",
      "payment_type": "string",
      "pay_per_unit": [
        "string"
      ]
    }
  }
}

Change Plan Flow

Changing an existing product's plan with another. For example, when upgrading the main subscription from Business to Platinum.

Step-by-Step Process

Select new plan - This time, the business already has an active subscription for the product and needs to select a new plan. The existing plan is sent to the selected new plan page from the CRM when invoking the flow. The "select new plan" page should communicate the existing plan to the billing page. (as described here)
Stop old plan - The existing plan billing cycle needs to be canceled in the billing system.
Delete subscription - Once the billing cycle cancellation is completed, communicate with inTandem using the Update Subscription API, to mark the subscription as expired.

The update subscription call takes the following parameters
1. Authorization token (Business)
2. purchase_state - expired
An example of the Delete subscription by purchasable call:
```
curl --location --request PUT 'https://api.vcita.biz/business/subscriptionsmng/v1/subscriptions/{subscription uid}' \
--header 'Authorization: Bearer {Business API token}' \
--header 'Content-Type: application/json' \
--data '{
  "subscription":
  {
    "purchase_state":"expired"
  }
}'
```
Payment - The billing system records the new plan's purchase, invoice, and charge accordingly.

Create subscription - Using an API call to inTndem's Subscriptions Manager to create a corresponding subscription for the new plan (Like the "Purchase flow")
An example of the Create subscription call:

curl --location 'https://api.vcita.biz/business/subscriptionsmng/v1/subscriptions' \
--header 'Authorization: Bearer {Business API token}' \
--header 'Content-Type: application/json' \
--data '{
    "subscription": {
        "purchasable_price_uid": "{Selected purchasable id}"
    }
}'

Cancel and Expire Flow

inTandem's cancellation policy states that upon cancellation, the business is entitled to the subscription's assets until the end of the billing cycle. During the period between the cancellation and the termination, the subscription is still active.

Step-by-Step Process

Stop payments - Update your billing system to stop collecting in the next billing cycle.
Update Subscription - Communicate the cancellation to the inTandem using the Update Subscription API.
The update subscription call takes the following parameters
1. Authorization token (Directory )
2. purchase_state - change to "canceled" to let inTandem know that a cancel is requested
3. expiration_date - the date the subscription will expire

An example of the Update subscription call:

curl --location --request PUT 'https://api.vcita.biz/business/subscriptionsmng/v1/subscriptions/{subscription uid}' \
--header 'Authorization: Bearer {Business API token}' \
--header 'Content-Type: application/json' \
--data '{
  "subscription":
  {
    "purchase_state":"canceled",
    "expiration_date":"2024-01-01"
  }
}'

When the subscription reaches the billing cycle last date, call the update subscription again to mark it as expired:

curl --location --request PUT 'https://api.vcita.biz/business/subscriptionsmng/v1/subscriptions/{subscription uid}' \
--header 'Authorization: Bearer {Business API token}' \
--header 'Content-Type: application/json' \
--data '{
  "subscription":
  {
    "purchase_state":"expired"
  }
}'

Dunning Flow

Dunning happens when the business fails to pay for one or more subscriptions. inTandem deals with every subscription separately, i.e. this flow is per subscription.

Step-by-Step Process

Payment fails - The billing system bills the business's payment method and fails to get the money. Each billing system implements its dunning process during which it tries to collect the money
Dunning period Ends - If the dunning process fails and ends without collecting the money, the billing system needs to stop future billings.
Delete subscription - following the end of the dunning process, an API call should be made to delete the current subscription, thus revoking the business rights to the product.

An example of the Delete subscription call:

curl --location --request DELETE 'https://apigw-integration.external.int-eks.vchost.co/business/subscriptionsmng/v1/subscriptions/{subscription uid}' \
--header 'Authorization: Bearer {Directory API token}' \
--data ''