> ## Documentation Index
> Fetch the complete documentation index at: https://docs.gate.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Subscription Order Status Update Notification

## Overview

This page documents `webhook subscriptionOrderWebhook`. The full schema, parameters, and examples are rendered from the linked OpenAPI or webhook definition above.

When a subscription order status changes, GatePay sends an asynchronous notification to the merchant-configured callback URL (`bizType` is `SUBSCRIPTION_ORDER_STATUS`).

## Notes

* Use `bizId` or `data.subscriptionOrderNo` for idempotency after parsing `data`.
* Signature verification, retries, parsing `data`, and the success response are covered in [Notifications Overview](/global/api-reference/version/100/en/common/asyncNotification); see [Security and Signature](/global/api-reference/version/100/en/common/securityAndSignature) for signing rules.

## When notifications are sent

* GatePay sends a notification to the merchant **callback URL** when the subscription order status changes (authorized, running, cancelled, closed, etc.)
* Top-level `bizStatus` matches `orderStatus` inside parsed `data`
* No notification is sent when `bizStatus=CREATED`
* If delivery fails, GatePay retries after **15 seconds (twice), 30 seconds, 3 minutes, 10 minutes, 20 minutes, 30 minutes (three times), 60 minutes, 3 hours (three times), and 6 hours (twice)**; you can also call [Subscription order detail](/global/api-reference/version/100/en/endpoint/subscription/orderDetail) to fetch the latest state

## Message structure

| Field | Type | Description |
| - | - | - |
| `bizType` | string | Always `SUBSCRIPTION_ORDER_STATUS` |
| `bizId` | string | Subscription order number (usually matches `data.subscriptionOrderNo`) |
| `bizStatus` | string | Subscription order status; see table below |
| `data` | string | Subscription order details as a JSON string |

### Structure example

```json theme={null}
{
  "bizType": "SUBSCRIPTION_ORDER_STATUS",
  "bizId": "79544752854007999",
  "bizStatus": "CANCELLED",
  "data": "{\"authorizedAmount\":\"0\",\"chain\":\"\",\"createTime\":1779951098025,\"cryptoAmount\":\"0\",\"cryptoCurrency\":\"USDT\",\"endTime\":0,\"interval\":1,\"lastPayTime\":0,\"merchantId\":\"50372118\",\"merchantSubscriptionOrderNo\":\"SUB_1779951098000_2059889959980175360\",\"orderStatus\":\"CANCELLED\",\"paidCount\":0,\"paymentChannel\":\"\",\"period\":\"NONE\",\"planDesc\":\"Users can authorize payment directly without topping up\",\"planName\":\"gateRouter authorization payment plan\",\"planNo\":\"84670588016525315\",\"productName\":\"gateRouter authorization payment plan\",\"productNo\":\"79396121215631409\",\"subscriptionOrderNo\":\"79544752854007999\",\"totalPaidAmount\":\"0\",\"totalPayCount\":0,\"trialDays\":0,\"updateTime\":1780037500658,\"userAddress\":\"\"}"
}
```

## bizStatus / orderStatus values

| Value | Description |
| - | - |
| `AUTHORIZED` | Authorized |
| `CONFIRMING` | Confirming |
| `TRIAL` | In trial |
| `RUNNING` | Running |
| `UNPAID` | Unpaid |
| `COMPLETED` | Completed |
| `CANCELLED` | Cancelled |
| `CLOSED` | Closed |
| `BLOCKED` | Blocked |

## data fields

After parsing the `data` JSON string, common fields include:

| Field | Type | Description |
| - | - | - |
| `subscriptionOrderNo` | string | Subscription order number |
| `merchantSubscriptionOrderNo` | string | Merchant subscription order number |
| `planNo` | string | Platform subscription plan number |
| `planName` | string | Subscription plan name |
| `planDesc` | string | Subscription plan description |
| `merchantId` | string | Merchant ID that created the plan |
| `productNo` | string | Product number |
| `productName` | string | Product name |
| `cryptoCurrency` | string | Cryptocurrency |
| `chain` | string | Blockchain network (may be empty when no on-chain authorization) |
| `userAddress` | string | User authorized address |
| `authorizedAmount` | string | Authorized amount |
| `cryptoAmount` | string | Single deduction amount |
| `paidCount` | integer | Number of completed deductions |
| `totalPaidAmount` | string | Total deducted amount |
| `paymentChannel` | string | Payment channel, e.g. `GATEPAY`, `WEB3` (may be empty) |
| `period` | string | Billing period, e.g. `MONTH`, `NONE` |
| `interval` | integer | Billing interval |
| `totalPayCount` | integer | Total number of deductions required |
| `trialDays` | integer | Trial days |
| `endTime` | int64 | Subscription end time in ms (`0` if not set) |
| `lastPayTime` | int64 | Last deduction time in ms (`0` if none) |
| `orderStatus` | string | Order status; matches top-level `bizStatus` |
| `createTime` | int64 | Order creation time in ms |
| `updateTime` | int64 | Order update time in ms |

## Callback example

### Running (`bizStatus=RUNNING`)

```json theme={null}
{
  "bizType": "SUBSCRIPTION_ORDER_STATUS",
  "bizId": "79544752854007999",
  "bizStatus": "RUNNING",
  "data": "{\"authorizedAmount\":\"0\",\"chain\":\"\",\"createTime\":1779951098025,\"cryptoAmount\":\"0\",\"cryptoCurrency\":\"USDT\",\"endTime\":0,\"interval\":1,\"lastPayTime\":0,\"merchantId\":\"50372118\",\"merchantSubscriptionOrderNo\":\"SUB_1779951098000_2059889959980175360\",\"orderStatus\":\"RUNNING\",\"paidCount\":2,\"paymentChannel\":\"\",\"period\":\"NONE\",\"planDesc\":\"Users can authorize payment directly without topping up\",\"planName\":\"gateRouter authorization payment plan\",\"planNo\":\"84670588016525315\",\"productName\":\"gateRouter authorization payment plan\",\"productNo\":\"79396121215631409\",\"subscriptionOrderNo\":\"79544752854007999\",\"totalPaidAmount\":\"0.2\",\"totalPayCount\":0,\"trialDays\":0,\"updateTime\":1780037500658,\"userAddress\":\"\"}"
}
```

### Order cancelled (`bizStatus=CANCELLED`)

```json theme={null}
{
  "bizType": "SUBSCRIPTION_ORDER_STATUS",
  "bizId": "79544752854007999",
  "bizStatus": "CANCELLED",
  "data": "{\"authorizedAmount\":\"0\",\"chain\":\"\",\"createTime\":1779951098025,\"cryptoAmount\":\"0\",\"cryptoCurrency\":\"USDT\",\"endTime\":0,\"interval\":1,\"lastPayTime\":0,\"merchantId\":\"50372118\",\"merchantSubscriptionOrderNo\":\"SUB_1779951098000_2059889959980175360\",\"orderStatus\":\"CANCELLED\",\"paidCount\":0,\"paymentChannel\":\"\",\"period\":\"NONE\",\"planDesc\":\"Users can authorize payment directly without topping up\",\"planName\":\"gateRouter authorization payment plan\",\"planNo\":\"84670588016525315\",\"productName\":\"gateRouter authorization payment plan\",\"productNo\":\"79396121215631409\",\"subscriptionOrderNo\":\"79544752854007999\",\"totalPaidAmount\":\"0\",\"totalPayCount\":0,\"trialDays\":0,\"updateTime\":1780037500658,\"userAddress\":\"\"}"
}
```


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.