Zid Docs
Merchant APIApp APIThemes
Merchant APIApp APIThemes
Help Center
Slack
  1. App API
  • Create your First App
  • Embedded Apps
  • App Scripts
  • App Events
  • App Subscription
    • Get Subscription Details
      GET
    • Update Usage-Based Charges
      POST
  1. App API

App Events

Subscription app events notify applications about important subscription activities, such as installation, authorization, renewals, and expiration. These webhooks allow developers to stay updated on merchant interactions with their applications.

Subscription App Events#

The table below lists the subscription events along with their descriptions. Each event sends a notification based on specific subscription activities.
Event NameDescription
app.market.application.authorizedTriggered when a merchant authorizes an app prior to installation.
app.market.subscription.activeSend notification on successful activation of subscription.
app.market.application.installSend notification on the installation of the application.
app.market.subscription.warningSend notification 3 days before the last subscription date (T is the duration of the plan in days).
app.market.subscription.suspendedSend notification on completion of subscription.
app.market.subscription.expiredSend notification on T+5 days of subscription where 5 days are GRACE Period and T is in the duration of the plan in days.
app.market.subscription.renewSend notification on successful renewal of the same plan subscription 5 days before the last date.
app.market.subscription.upgradeSend notification on upgrade of subscription.
app.market.subscription.refundedSend notification on refund of subscription.
app.market.application.uninstallSend notification on uninstallation of the application.
app.market.application.ratedTriggered when a merchant submits a rating or review for the app.
app.market.private.plan.requestTriggered when a merchant submits a request for a private plan.

Subscribing to App Events#

To receive real-time notifications about specific events, partners must subscribe to webhooks using the Partner Dashboard.
App Events.png

Creating a Webhook Subscription#

1.
Navigate to the Webhooks section when creating or editing your app in the Partner Dashboard.
2.
Provide the endpoint where webhook notifications should be sent.
3.
Choose one or more events from the available list.
4.
If needed, specify additional headers for authentication or other requirements.
5.
Save and submit the changes. You can return later to edit or add more events as needed.

Testing Webhooks Using a Development Store#

1.
Utilize your created development stores to simulate real-world webhook events.
2.
Perform actions in the store that triggers to the subscribed events.
3.
Check the webhook logs for successful deliveries or errors. If a webhook fails, review the response details and retry as needed.

Webhook Event List and Payloads#

1. App Authorized#

Description:
Triggered when a merchant authorizes an app before installing it. This event ensures that the merchant has granted permissions required by the application.
Payload Example:
{
  "app_id": 1292,
  "store_id": 507530,
  "store_uuid": "d78468cd-4b44-4fee-a00d-76561f35787c",
  "store_url": "https:\/\/wyatt.com.sa\/",
  "plan_name": "\u0627\u0644\u0646\u0645\u0648",
  "status": "authorized",
  "start_date": "2025-02-21T08:05:29.000000Z",
  "end_date": "2025-03-22T08:05:29.000000Z",
  "amount_paid": 79.01,
  "old_plan_name": null,
  "merchant_email": "info@ehmp.com.sa",
  "merchant_phone_no": "966554349999",
  "event_name": "app.market.application.authorized",
  "plan_type": "Paid",
  "plan_id": 904,
  "payment_date": "2025-02-21T08:05:29.000000Z"
}

2. Subscription Activated#

Description:
Sent when a subscription is successfully activated after payment.
Payload Example:
{
  "app_id": 1292,
  "store_id": 507530,
  "store_uuid": "d78468cd-4b44-4fee-a00d-76561f35787c",
  "store_url": "https:\/\/wyatt.com.sa\/",
  "plan_name": "\u0627\u0644\u0646\u0645\u0648",
  "status": "active",
  "start_date": "2025-02-21T08:05:29.000000Z",
  "end_date": "2025-03-22T08:05:29.000000Z",
  "amount_paid": 79.01,
  "old_plan_name": null,
  "merchant_email": "info@ehmp.com.sa",
  "merchant_phone_no": "966554349999",
  "event_name": "app.market.subscription.active",
  "plan_type": "Paid",
  "plan_id": 904,
  "payment_date": "2025-02-21T08:05:29.000000Z"
}

3. App Installed#

Description:
Sent when an application is installed by a merchant.
Payload Example:
{
  "app_id": 1292,
  "store_id": 507530,
  "store_uuid": "d78468cd-4b44-4fee-a00d-76561f35787c",
  "store_url": "https:\/\/wyatt.com.sa\/",
  "plan_name": "\u0627\u0644\u0646\u0645\u0648",
  "status": "install",
  "start_date": "2025-02-21T08:05:29.000000Z",
  "end_date": "2025-03-22T08:05:29.000000Z",
  "amount_paid": 79.01,
  "old_plan_name": null,
  "merchant_email": "info@ehmp.com.sa",
  "merchant_phone_no": "966554349999",
  "event_name": "app.market.application.install",
  "plan_type": "Paid",
  "plan_id": 904,
  "payment_date": "2025-02-21T08:05:29.000000Z"
}

4. Subscription Warning#

Description:
Sent 3 days before the last subscription date as a reminder to renew.
Payload Example:
{
  "app_id": 1292,
  "store_id": 507530,
  "store_uuid": "d78468cd-4b44-4fee-a00d-76561f35787c",
  "store_url": "https:\/\/wyatt.com.sa\/",
  "plan_name": "\u0627\u0644\u0646\u0645\u0648",
  "status": "warning",
  "start_date": "2025-02-21T08:05:29.000000Z",
  "end_date": "2025-03-22T08:05:29.000000Z",
  "amount_paid": 79.01,
  "old_plan_name": null,
  "merchant_email": "info@ehmp.com.sa",
  "merchant_phone_no": "966554349999",
  "event_name": "app.market.subscription.warning",
  "plan_type": "Paid",
  "plan_id": 904,
  "payment_date": "2025-02-21T08:05:29.000000Z"
}

5. Subscription Suspended#

Description:
Sent when a subscription is suspended after expiration.
Payload Example:
{
  "app_id": 1292,
  "store_id": 507530,
  "store_uuid": "d78468cd-4b44-4fee-a00d-76561f35787c",
  "store_url": "https:\/\/wyatt.com.sa\/",
  "plan_name": "\u0627\u0644\u0646\u0645\u0648",
  "status": "suspended",
  "start_date": "2025-02-21T08:05:29.000000Z",
  "end_date": "2025-03-22T08:05:29.000000Z",
  "amount_paid": 79.01,
  "old_plan_name": null,
  "merchant_email": "info@ehmp.com.sa",
  "merchant_phone_no": "966554349999",
  "event_name": "app.market.subscription.suspended",
  "plan_type": "Paid",
  "plan_id": 904,
  "payment_date": "2025-02-21T08:05:29.000000Z"
}

6. Subscription Expired#

Description:
Sent T+5 days after the subscription expires, where T is the plan duration and 5 days is the grace period.
Payload Example:
{
  "app_id": 1292,
  "store_id": 507530,
  "store_uuid": "d78468cd-4b44-4fee-a00d-76561f35787c",
  "store_url": "https:\/\/wyatt.com.sa\/",
  "plan_name": "\u0627\u0644\u0646\u0645\u0648",
  "status": "expired",
  "start_date": "2025-02-21T08:05:29.000000Z",
  "end_date": "2025-03-22T08:05:29.000000Z",
  "amount_paid": 79.01,
  "old_plan_name": null,
  "merchant_email": "info@ehmp.com.sa",
  "merchant_phone_no": "966554349999",
  "event_name": "app.market.subscription.expired",
  "plan_type": "Paid",
  "plan_id": 904,
  "payment_date": "2025-02-21T08:05:29.000000Z"
}

7. Subscription Renewed#

Description:
Sent 5 days before the last subscription date when the same plan is successfully renewed.
Payload Example:
{
  "app_id": 1292,
  "store_id": 507530,
  "store_uuid": "d78468cd-4b44-4fee-a00d-76561f35787c",
  "store_url": "https:\/\/wyatt.com.sa\/",
  "plan_name": "\u0627\u0644\u0646\u0645\u0648",
  "status": "renew",
  "start_date": "2025-02-21T08:05:29.000000Z",
  "end_date": "2025-03-22T08:05:29.000000Z",
  "amount_paid": 79.01,
  "old_plan_name": null,
  "merchant_email": "info@ehmp.com.sa",
  "merchant_phone_no": "966554349999",
  "event_name": "app.market.subscription.renew",
  "plan_type": "Paid",
  "plan_id": 904,
  "payment_date": "2025-02-21T08:05:29.000000Z"
}

8. Subscription Upgraded#

Description:
Sent when a merchant upgrades their subscription to a higher-tier plan.
Payload Example:
{
  "app_id": 1292,
  "store_id": 507530,
  "store_uuid": "d78468cd-4b44-4fee-a00d-76561f35787c",
  "store_url": "https:\/\/wyatt.com.sa\/",
  "plan_name": "\u0627\u0644\u0646\u0645\u0648",
  "status": "upgrade",
  "start_date": "2025-02-21T08:05:29.000000Z",
  "end_date": "2025-03-22T08:05:29.000000Z",
  "amount_paid": 79.01,
  "old_plan_name": null,
  "merchant_email": "info@ehmp.com.sa",
  "merchant_phone_no": "966554349999",
  "event_name": "app.market.subscription.upgrade",
  "plan_type": "Paid",
  "plan_id": 904,
  "payment_date": "2025-02-21T08:05:29.000000Z"
}

9. Subscription Refunded#

Description:
Sent when a subscription payment is refunded to the merchant.
Payload Example:
{
  "app_id": 1292,
  "store_id": 507530,
  "store_uuid": "d78468cd-4b44-4fee-a00d-76561f35787c",
  "store_url": "https:\/\/wyatt.com.sa\/",
  "plan_name": "\u0627\u0644\u0646\u0645\u0648",
  "status": "refunded",
  "start_date": "2025-02-21T08:05:29.000000Z",
  "end_date": "2025-03-22T08:05:29.000000Z",
  "amount_paid": 79.01,
  "old_plan_name": null,
  "merchant_email": "info@ehmp.com.sa",
  "merchant_phone_no": "966554349999",
  "event_name": "app.market.subscription.refunded",
  "plan_type": "Paid",
  "plan_id": 904,
  "payment_date": "2025-02-21T08:05:29.000000Z"
}

10. App Uninstalled#

Description:
Sent when a merchant uninstalls the application.
Payload Example:
{
  "app_id": 1292,
  "store_id": 507530,
  "store_uuid": "d78468cd-4b44-4fee-a00d-76561f35787c",
  "store_url": "https:\/\/wyatt.com.sa\/",
  "plan_name": "\u0627\u0644\u0646\u0645\u0648",
  "status": "uninstall",
  "start_date": "2025-02-21T08:05:29.000000Z",
  "end_date": "2025-03-22T08:05:29.000000Z",
  "amount_paid": 79.01,
  "old_plan_name": null,
  "merchant_email": "info@ehmp.com.sa",
  "merchant_phone_no": "966554349999",
  "event_name": "app.market.application.uninstall",
  "plan_type": "Paid",
  "plan_id": 904,
  "payment_date": "2025-02-21T08:05:29.000000Z"
}

11. App Rated#

Description:
Triggered when a merchant submits a rating or review for the application.
Payload Example:
{
  "app_id": 1292,
  "store_id": 507530,
  "store_uuid": "d78468cd-4b44-4fee-a00d-76561f35787c",
  "store_url": "https:\/\/wyatt.com.sa\/",
  "plan_name": "\u0627\u0644\u0646\u0645\u0648",
  "status": "rated",
  "start_date": "2025-02-21T08:05:29.000000Z",
  "end_date": "2025-03-22T08:05:29.000000Z",
  "amount_paid": 79.01,
  "old_plan_name": null,
  "merchant_email": "info@ehmp.com.sa",
  "merchant_phone_no": "966554349999",
  "event_name": "app.market.application.rated",
  "plan_type": "Paid",
  "plan_id": 904,
  "payment_date": "2025-02-21T08:05:29.000000Z"
}

12. Private Plan Requested#

Description:
Triggered when a merchant submits a request for a private plan.
Payload Example:
{
  "app_id": 1292,
  "store_id": 507530,
  "store_uuid": "d78468cd-4b44-4fee-a00d-76561f35787c",
  "store_url": "https:\/\/wyatt.com.sa\/",
  "plan_name": "\u0627\u0644\u0646\u0645\u0648",
  "status": "request",
  "start_date": "2025-02-21T08:05:29.000000Z",
  "end_date": "2025-03-22T08:05:29.000000Z",
  "amount_paid": 79.01,
  "old_plan_name": null,
  "merchant_email": "info@ehmp.com.sa",
  "merchant_phone_no": "966554349999",
  "event_name": "app.market.private.plan.request",
  "plan_type": "Paid",
  "plan_id": 904,
  "payment_date": "2025-02-21T08:05:29.000000Z"
}
Modified at 2025-03-18 08:09:13
Previous
App Scripts
Next
Get Subscription Details
Built with