| Event Name | Event Type | Trigger Condition | Data Structure | Description |
|---|---|---|---|---|
| Trial period expiring soon | v2.subscription.trial_period_expiring | When the trial expires in 3 days (single reminder) | Subscription | It’s triggered when a customer’s subscription trial period is due to expire in 3 days. Use Case Expiry reminder: Send a trial expiry reminder to the customer. |
| First subscription activated | v2.subscription.first | When a subscription is activated for the first time | Subscription | It is triggered when a subscription enters the trial or active state for the first time. It is sent only once per subscription. Use Case Subscription confirmation: To notify the customer of their successful initial subscription (e.g., via push notification or email). Features granting: To unlock the service permissions associated with the customer’s subscription (e.g., premium features, resource quotas). |
| Subscription canceled | v2.subscription.canceled | When a subscription is actively canceled | Subscription | It is triggered when a subscription is effectively terminated. Use Case Service termination notice: To inform the customer that their subscription has ended, specifying the exact time when service will cease. Features revocation: To revoke the user’s paid access and features. |
| Subscription changed | v2.subscription.price_changed | when a subscription is upgraded or downgraded. | Subscription | It is triggered when a subscription’s price changes, providing the specific details of the change. |
| Subscription Paused | v2.subscription.paused | When a subscription is paused | Subscription | It is triggered when a subscription is temporarily paused by the customer or system. Use Case Service suspension: To temporarily disable service access while maintaining the subscription record. Notification: To inform the customer that their subscription has been paused and when it will resume. |
| Subscription Resumed | v2.subscription.resumed | When a subscription is resumed | Subscription | It is triggered when a previously paused subscription is resumed and reactivated. Use Case Service restoration: To restore service access and features for the customer. Confirmation notification: To notify the customer that their subscription has been successfully resumed. |
| Subscription Past Due | v2.subscription.past_due | When a subscription payment is past due | Subscription | It is triggered when a subscription payment is overdue but the subscription has not yet been canceled. Use Case Payment reminder: To send urgent payment reminders to the customer. Grace period management: To track subscriptions in grace period before cancellation. |
| Subscription Unpaid | v2.subscription.unpaid | When a subscription is marked as unpaid | Subscription | It is triggered when a subscription is marked as unpaid after multiple failed payment attempts. Use Case Service suspension: To suspend service access due to non-payment. Final notice: To send a final notice to the customer before permanent cancellation. |
| Cancellation Revoked | v2.subscription.cancellation_revoked | When a subscription cancellation is revoked | Subscription | It is triggered when a customer revokes their previous cancellation request and chooses to continue their subscription. Use Case Subscription restoration: To restore the subscription to active status and prevent cancellation. Confirmation: To notify the customer that their cancellation has been successfully revoked. |
| Cancellation Requested | v2.subscription.cancellation_requested | When a subscription cancellation is requested | Subscription | It is triggered when a customer initiates a request to cancel their subscription. Use Case Cancellation processing: To begin the cancellation workflow and schedule the end date. Retention opportunity: To trigger retention campaigns or offer alternatives before finalizing cancellation. |
| Subscription Fixed Term Updated | v2.subscription.fixed_term_updated | When a subscription’s fixed term is modified | Subscription | It is triggered when the fixed-term settings of a subscription are changed, including modifying the number of periods, toggling auto-renewal on expiration, or converting to an ongoing subscription. The event data includes previous_fixed_term_info with the fixed-term details before the change.Use Case Status synchronization: To sync the fixed-term changes and update local records. Business logic: To adjust user entitlements or notification strategies based on the fixed-term change. |
| Invoice paid successfully | v2.invoice.paid | When an invoice is paid successfully | Invoice | It is sent upon successful payment for a one-time purchase or a subscription-related charge. It is used to synchronize invoice status and manage subscriptions. Use Case Invoice status synchronization: To update the invoice status to “completed”. Subscription management: For renewal invoices, this event contains subscription cycle details, such as the current cycle number and cycle timeframe. |
| Invoice payment failed | v2.invoice.payment_failed | When an attempt to pay an invoice fails | Invoice | It is sent when a payment for a one-time purchase or a subscription-related charge ultimately fails. It is not sent for every retry attempt, only upon the final payment failure. Use Case Failure notification and payment retry guidance: To alert the customer of the payment failure and provide a means to re-attempt payment. |
| Invoice Refunded | v2.invoice.refunded | Notify when the transaction order generated by the subscription is successfully refunded, for obtaining subscription refund information | Invoice | This event is sent when a refund occurs for one-time products and subscription-related payments. It is used to synchronize the refund status. |
| Trade order payment succeeded | v2.trades.succeeded | When a trade order is paid successfully | Trade | It is sent for any successful payment type and is suitable for closed-loop scenarios involving simple monetary transactions. |
| The transaction order payment failed. | v2.trades.payment_failed | When a trade order is paid fails | Trade | This notification will be sent when all types of payments fail, and it is applicable to closed-loop transactions of pure amounts. |
| Refund succeeded | v2.refunds.succeeded | When a refund is processed successfully | Refund | This event is triggered when a refund has been successfully processed and finalized Use Case Refund notification and status synchronization: To inform the user of the refunded amount and update the refund status to “completed”. |
| Refund failed | v2.refunds.failed | When an attempt to process a refund fails | Refund | This event is triggered when a refund attempt fails. Use Case Status synchronization: To update the refund status to “failed”. Retry mechanism and manual intervention: To trigger an automatic retry process or alert customer support for manual investigation, enabling a timely re-initiation of the refund to prevent customer complaints and financial disputes. |
| Dispute created | v2.disputes.created | When a dispute is first created | Dispute | It is triggered the first time the channel returns dispute data. Sent only once per channel_dispute_id.Use Case Dispute intake: Create the corresponding dispute ticket in the merchant system. Fund alert: Mark the frozen amount in the settlement view based on dispute_amount. |
| Dispute updated | v2.disputes.updated | When key fields of an existing dispute change | Dispute | It is triggered when key fields of an existing dispute change, such as status, reason, amount, or due time. Use Case Status synchronization: Update the local dispute status based on dispute_status.Defense reminder: Push evidence submission reminders to the merchant based on dispute_due_time. |