To get the paid app payment lifecycle events, you first need to create and deploy a paid app to our app market.
Check our API documentation for how to create an app.
Registering for the subscription create an event
curl --location --request POST '/platform/v1/webhook/subscribe' \
--header 'Authorization: Bearer APP_TOKEN'\
--header 'Content-Type: application/json' \
--data-raw '{
"event": "purchasable_subscription/create",
"target_url": "url"
}'
Event payload:
{
"entity_name": "purchasable_subscription",
"event_type": "created",
"data": {
"business_id": "3in0a3b32nut67l6",
"purchasable_uid": "s8k2s72-59fe-4710-2d22-dsbbd5c7e222",
"subscription_uid": "83661fb9-59fe-4710-aa53-f6bbd5c7e258"
}
Registering for the subscription update an event
curl --location --request POST '/platform/v1/webhook/subscribe' \
--header 'Authorization: Bearer APP_TOKEN'\
--header 'Content-Type: application/json' \
--data-raw '{
"event": "purchasable_subscription/update",
"target_url": "url"
}'
Event payload:
{
"entity_name": "purchasable_subscription",
"event_type": "update",
"data": {
"business_id": "3in0a3b32nut67l6",
"purchasable_uid": "s8k2s72-59fe-4710-2d22-dsbbd5c7e222",
"subscription_uid": "83661fb9-59fe-4710-aa53-f6bbd5c7e258"
}
Payload data
- Entity name - the purchasable_subscription
- Event type - Either create or update
- Data - the purchasing business id, the purchasable id, and the subscription id.
Following a subscription event (mainly 'update' events) you can get the app’s purchase status, using the returned subscription_uid with this API call:
curl --location 'https://api.vcita.biz/business/subscriptionsmng/v1/subscriptions?[filter][uid]=230003ab-f334-42f3-ae39-2d066a6068a4' \
--header 'Authorization: ‘Authorization: "Bearer BUSINESS-APP_TOKEN"\
--header 'Content-Type: application/json'
Note that the business-app token required for this API call must be generated via the following API (use the access_token from the response):
curl --location --request POST 'https://https://api.vcita.biz/oauth/token?client_id=CLIENT_ID&client_secret=CLIENT_SECRET&grant_type=assertion&type=token&business_uid=BUSINESS_UID'
Response
{
"data": {
"subscriptions": [
{
"uid": "230003ab-f334-42f3-ae39-2d066a6068a4",
"purchasable_uid": "8e31b758-27b1-495e-9730-4695468fcdbc",
"buyer_uid": "fxey12krp0d8pacr",
"business_uid": "lh0fnhdzcufbvkwd",
"purchase_currency": "USD",
"purchase_price": "7.00",
"purchase_state": "purchased",
"cancellation_date": null,
"expiration_date": null,
"updated_at": "2023-08-09T12:57:29.948Z",
"created_at": "2023-08-09T12:57:29.948Z",
"payment_type": "monthly"
}]}
}
purchase_state
- Purchased - The business is eligible to use the app
- Suspended - There is a payment issue and the business is not eligible to use the app
- Cancelled - The business actively cancelled the app’s subscription and is no longer eligible to use the app
Once a business purchases an app, a new subscription is created with the above data. This creation triggers the purchasable_subscription/create hook. Only after checking that the purchase_state is indeed Purchased, the app should made itself available to the business.
Any change to the purchase_state will trigger the purchasable_subscription/update hook. Again, the app should check the purchase_state to make sure the business can use the app.
The following diagram shows the different states and the transitions between these states:
| Action | Hook | Previous Purchase_state value | Purchase_state | Notes |
|---|---|---|---|---|
| User purchases an app | purchasable_subscription/create | N/A | purchased or suspended | Depends on whether payment succeeded or not |
| Payment confirmation received | purchasable_subscription/update | suspended | purchased | In case the previous purchase_state was purchased, no hook is triggered |
| Payment issue received | purchasable_subscription/update | purchased | suspended | In case the previous purchase_state was suspended, no hook is triggered |
| User cancels the app’s subscription | purchasable_subscription/update | suspended or purchased | canceled | Either the user uninstalls the app or cancels the entire vcita’s subscription |