Paid Apps

Implementing a paid app

An app can be defined as a paid one, thus the business needs to purchase it to be able to use it.

From the app's point of view, it needs to manage its lifecycle to make sure the business pays for the app to use it.

The app can register to the following webhooks:


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.

For Purchased, and Canceled states, the is_active property of a subscription returns true. When the subscription Expires, the is_active property turns to false.

Subscription webhooks

The below flows utilize the subscription created/updated webhooks. Following are examples of their payloads:

Subscription Created webhook:

{
  "entity_name": "purchasable_subscription",
  "event_type": "created",
  "data": {
    "uid": "3d3dc97a-7ea7-42d7-a287-9993530721fd",
    "display_name": "myappcodename",
    "purchasable_uid": "ee655c26-4a57-48df-8e2e-f85a994b335c",
    "buyer_uid": "ny1g1gau6o3x3yat",
    "business_uid": "ato1v2g3eg3xkyqm",
    "purchase_currency": "USD",
    "purchase_price": "5.00",
    "purchase_state": "purchased",
    "cancellation_date": null,
    "expiration_date": null,
    "updated_at": "2024-03-01T12:27:09.966Z",
    "created_at": "2024-03-01T12:27:09.966Z",
    "payment_type": "monthly",
    "bundled_from_subscription_uid": null,
    "is_active": true
    }
}

Subscription Updated webhook:

{
  "entity_name": "purchasable_subscription",
  "event_type": "update",
  "data": {
    "uid": "3d3dc97a-7ea7-42d7-a287-9993530721fd",
    "display_name": "myappcodename",
    "purchasable_uid": "ee655c26-4a57-48df-8e2e-f85a994b335c",
    "buyer_uid": "ny1g1gau6o3x3yat",
    "business_uid": "ato1v2g3eg3xkyqm",
    "purchase_currency": "USD",
    "purchase_price": "5.00",
    "purchase_state": "canceled",
    "cancellation_date": "2024-04-17T12:27:10.000Z",
    "expiration_date": null,
    "updated_at": "2024-03-17T12:27:10.000Z",
    "created_at": "2024-03-01T12:27:09.966Z",
    "payment_type": "monthly",
    "bundled_from_subscription_uid": null,
    "is_active": true
    }
}

Purchase stage

Step-by-Step

  1. Purchase app - The user clicks on the Purchase app CTA in the app info page.
  2. Payment result - Following a successful payment a new subscription is created and the app is installed for the business to use.

Listening to the subscription created event, the app can get the newly created subscription and check its status (is_active=true), to allow the business to use it.

Cancel app stage


Step-by-Step

  1. Uninstalling - An admin clicks on the Uninstall CTA in the app info page. This action changes the subscription's state to canceled, and sets the cancellation date. A Subscription Update webhook is fired. The app can still be used (until the end of the billing cycle period).
    Listening to the Subscription Update webhook, the app gets the status change, but should still allow the user to fully use it (is_active=true)
  2. Expiry date reached - When the current billing cycle ends, the subscription expires. A Subscription Update and App Uninstall webhooks are fired.
    Listening to the Subscription Update webhook, the app gets the subscription's new state - expired, and is_active=false. At this point, the app should not allow the user to use it any more.

Dunning

Step-by-Step

  1. Payment failed - A subscription's renewal payment failed. The billing system will try to re-bill the business for a certain period of time. There is no change to the app's subscription, and the business can use it.
  2. Dunning process completed - The billing system didn't manage to collect the payment, and expires the subscription. The business is no longer eligible to use the app.
    Listening to the Subscription Update webhook, the app gets the subscription status is_active=false and should block any user

Retrieving the business's subscription

At any stage of the app lifecycle the app can query the subscription to actively get the its state and is_active properties.

An example of the Get Subscriptions API call:

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

The above call response:

{
    "data": {
        "subscriptions": [
            {
                "uid": "b7ba1466-771e-432b-9c75-d738942bd7de",
                "display_name": "my paid app",
                "purchasable_uid": "ee655c26-4a57-48df-8e2e-f85a994b335c",
                "buyer_uid": "z7oeioxaqhinvcaa",
                "business_uid": "aasd2adfdsf34a",
                "purchase_currency": "USD",
                "purchase_price": "20.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
}


Updated about 2 months ago