> ## 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

> 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](/api-reference/version/100/en/common/asyncNotification); see [Security and Signature](/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 (created, authorized, running, cancelled, closed, etc.)
* Top-level `bizStatus` matches `orderStatus` inside parsed `data`
* 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](/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 |
| ------------ | ----------- |
| `CREATED`    | Created     |
| `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\":\"\"}"
}
```


## OpenAPI

````yaml /api-reference/version/100/en/openapi/subscription/orderNotify-openapi.json webhook subscriptionOrderWebhook
openapi: 3.1.0
info:
  title: GatePay API
  version: 1.0.0
  description: GatePay Payment Platform API Documentation
servers: []
security: []
paths: {}

````