Subscription ('create', 'update')

🚧

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

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

JSON

{
  "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

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

JSON

{
  "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

curl --location 'https://api.vcita.biz/business/subscriptionsmng/v1/subscriptions?[filter][uid]=230003ab-f334-42f3-ae39-2d066a6068a4' \
--header 'Authorization: ‘Authorization: "Bearer APP_TOKEN”\
--header 'Content-Type: application/json'

Note that the app token required for this API call must be generated via this API (user the access_tijen returned from this API)

cURL

curl --location --request POST 'https://api2.vcita.com/oauth/token?client_id=CLIENT_ID&client_secret=CLIENT_SECRET&grant_type=assertion&type=token&business_uid=BUSINESS_UID'

Response

JSON

{
    "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