Zid Docs
Apps
ThemesPayments
Apps
ThemesPayments
Help Center
Slack
  1. App Management
  • πŸ—‚οΈ Overview
  • πŸš€ Start Here
  • Create your First App
  • Responses
  • Rate Limiting
  • Authorization
  • Embedded Apps
  • StoreFront Events
  • Zid MUI
  • Zid SDKs
  • Our custom MCP server
  • Merchant APIs
    • Account
      • Me
        • Me
        • Profile
      • Store
        • Store
        • Branding
        • Localization
        • Social
        • Operations
        • Business
        • Upload Logo Image
        • Delete Logo Image
        • Upload Icon Image
        • Delete Icon Image
        • Upload Cover Image
        • Delete Cover Image
    • Orders
      • Validate Order Request
      • Create Order
      • Change Order Status
      • Add Order Comment
      • View Order
      • List Orders
      • List Custom Order Statuses
      • List Order Credit Notes
    • Reverse Orders
      • Create Reverse Orders
      • Create Reverse Orders Waybill
      • Add Reverse Order Reasons
      • List Reverse Reasons
      • Calculate Reverse Totals
      • Create refund for reverse order
      • Upload bank transfer receipt
      • Update return products
      • Order Details – View for Return
    • Abandoned Carts
      • List Carts
      • View Cart
    • Products
      • Managing Products
        • Create Product Types
        • Create Product
        • List Products
        • View Product
        • List Product Settings
        • Update Product
        • Bulk Update Products
        • Delete Product
      • Digital Vouchers
        • List Vouchers
        • Order Vouchers
        • Create Voucher
        • Import Vouchers
        • Export Vouchers
        • Update Voucher
        • Remove Voucher
      • Product Categories
        • List Categories
        • View Category
        • Create Category
        • Create Subcategory
        • Update Category
        • Assign Product to Category
        • Bulk Assign Products to Category
        • Publish Category
        • Detach Category from All Products
        • Remove Product from Category
      • Product Badge
        • List Badges
      • Product Attributes
        • List Attributes
        • View Attribute
        • Create Attribute
        • Update Attribute
        • Delete Attribute
      • Product Attribute Presets
        • List Presets
        • Create Preset
        • Update Preset
        • Delete Preset
      • Product Variants
        • Create Variants
        • Create Custom Option
        • Update Custom Option
        • Delete Custom Option Field
        • Create Custom Input Field
        • Update Custom Input Field
        • Delete Custom Input Field
      • Product Sorting
        • Set Manual Product Order
        • Reset Manual Product Order
      • Product Images
        • List Images
        • Upload Image
        • Update Image Order
        • Delete Image
      • Product Availability Notifications
        • Notification Stats
        • Noticiation Settings
        • List Notifications
        • Create Notification
        • Update Settings
        • Send Notification Email
        • Export Notifications
      • Product Export
        • Email All Products to Store Owner
        • Import Products via CSV or xlsx File
      • Product Stock
        • Retrieve Product Stock
        • List Product Stock Records
        • Create Product Stock
        • Update Product Stock
        • Bulk Update Product Stock Records
      • Product Questions & Answers
        • Retrieve Product Question
        • Retrieve Product Answer
        • List Product Questions
        • List Answers for Question
        • Create Product Question
        • Create Product Answer
        • Update Product Question
        • Update Product Answer
        • Delete Product Question
        • Delete Product Answer
      • Product Reviews
        • List Reviews
        • Count Reviews
      • Digital Products
        • Create Downloadable Product
        • Generate Upload URL
        • Upload File to S3
        • Create Product Downloadable
        • Get Product Downloadables
        • Delete Product Downloadable
        • List Store Downloadables
        • Create Store Downloadable
        • Delete Store Downloadable
    • Inventories
      • Create Location
      • Update Location
      • Update Product Stock for Location
      • List Locations
      • View Location
    • Shipping
      • List Store Shipping Methods
    • Marketing
      • Coupons
        • List Coupons
        • View Coupon
        • Create Coupon
        • Generate Bulk Coupons
        • Duplicate Coupon
        • Duplicate Bulk Coupons
        • Update Coupon Note
        • Update Coupon
        • Update Bulk Coupons
        • Update Coupon Status
        • Update Bulk Coupons Status
        • Delete Coupon
        • Delete Bulk Coupons
      • Bundle Offers
        • List Bundle Offers
      • Loyalty Program
        • Loyalty Program Status
        • Loyalty Program Details
        • Loyalty Program Info
        • Customer Loyalty Summary
        • Customer Points History
        • Activate Loyalty Program
        • Set Points Expiration Rules
        • Update Cashback Rule
        • Create Points Redemption Method
        • Update Points Redemption Method
        • Delete Points Redemption Method
        • Adjust Customer Points
      • Discount Rules
        • List Discount Rules
        • View Discount Rule
        • Create Discount Rule
        • Update Discount Rule
    • Customers
      • Customer Tags
        • List Customer Tags
        • Add Customer Tag
        • Ω’Update Customer Tag
        • Delete Customer Tag
      • List Customers
      • View Customer
      • Primary Customer List
      • FInd Customer By Phone Number
      • Customer Profile
      • Add Customer
      • Update Customer
      • Delete Customer
      • Add Bulk Customers
      • Import Customers
    • Store Settings
      • πŸ“„ User Roles and Permissions
      • Retrieve Store Manager Profile
      • Retrieve VAT Settings
      • List Payment Methods
      • List Store Operating Countries
    • Countries and Cities
      • List Countries
      • List Cities for Country
  • Webhooks
    • Overview
    • Webhook Health Tracking
    • Events
      • Order
      • Product
      • Abandoned Cart
      • Customer
      • Product Category
    • APIs
      • Health Summary
      • Broken Webhooks
      • Recover Broken Webhooks
      • List Webhooks
      • Create Webhook
      • Delete Webhook
      • Delete Webhook By subscriber
  • App Management
    • Events
    • APIs
      • Subscription Details
      • Update Usage-Based Charges
  1. App Management

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.

App Subscription 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 Subscription 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"
}

Identifying Free Trial Subscriptions#

Applications can determine whether a merchant is currently on a free trial by monitoring subscription-related webhook events.

Relevant Webhook Events#

The following events include subscription details:
app.market.subscription.active
app.market.application.authorized
app.market.application.install

Free Trial Detection#

A subscription should be considered a free trial only when the following condition is met:
plan_type is equal to "Free Trial"

Example#

{
  "app_id": 6528,
  "store_id": 3104452,
  "store_uuid": "b2052c72-ddaa-411f-a428-748dcd885a6e",
  "store_url": "https://xle6e8.zid.store/",
  "plan_name": "Test Plan With Trial",
  "status": "active",
  "start_date": "2026-06-14T08:05:40.000000Z",
  "end_date": "2026-07-04T08:05:40.000000Z",
  "amount_paid": 0,
  "old_plan_name": null,
  "merchant_email": "bv3e7xxnx5@zam-partner.email",
  "merchant_phone_no": "+201101050117",
  "event_name": "app.market.subscription.active",
  "plan_type": "Free Trial",
  "plan_id": 3329,
  "payment_date": "2026-06-14T08:05:40.000000Z"
}
In the example above, the subscription is identified as a free trial because plan_type is "Free Trial". Applications should validate this field when determining whether a subscription is in a trial period and applying any trial-specific business logic.
Modified atΒ 2026-06-14 08:49:21
Previous
Delete Webhook By subscriber
Next
Subscription Details
Built with