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

> Covers subscription payment product setup, plan management, authorization, deduction modes, and querying recurring or on-demand debit status.

## Overview

Subscription payment fits memberships, SaaS, recurring services, and any scenario that needs ongoing authorization and debits. Products are split into two capability classes, distinguished by `priceType` on the product price:

| `priceType`    | Capability                                                | How debits work                                                                                             |
| -------------- | --------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------- |
| `FIX_AMOUNT`   | Fixed amount debited on the plan’s billing cycle          | After the user authorizes, the platform runs recurring debits according to the merchant’s subscription plan |
| `ACCOUNT_AUTH` | Account authorization; the merchant decides when to debit | After the user authorizes, the merchant initiates debits when the business requires                         |

Compared with one-time payments, subscriptions emphasize long-term lifecycle management. Beyond placing orders and authorization, merchants should monitor plan or authorization scope, debit outcomes, retries, and termination rules.

## Standard integration flow

Both product types share the same main path: create product → create plan → create subscription order → guide the user to authorize. They diverge **after** authorization succeeds:

```text theme={null} theme={null}
Create product -> Create plan -> Create subscription order -> Guide user authorization -> [Debit phase branches by priceType] -> Query and notification tracking
```

### Debit phase branches

* **FIX\_AMOUNT**: After authorization → recurring debits (automatic per plan) → query and notification tracking
* **ACCOUNT\_AUTH**: After authorization → merchant-initiated debits on demand → query and notification tracking

## Minimum runnable path

For a first integration, run the smallest path end to end, then add trials, first-period discounts, and completion rules.

```text theme={null} theme={null}
Create product -> Create plan -> Create subscription order -> Open subscriptionLink to authorize -> Receive debit notifications -> Query order and debit details to confirm
```

* **FIX\_AMOUNT**: After this path works, focus on automatic cycle debits and failure retries.
* **ACCOUNT\_AUTH**: After authorization, trigger debits from your backend and still confirm via notifications + queries.

### Step 1: Create products

Create subscription products and pricing first to define what is sold, billing currency, and presentation. When creating a price, set `priceType` so you know whether debits are cyclic or merchant-initiated after auth.

Core APIs:

* `POST /merchant/open/v1/pay/merchant/product/create`
* `GET /merchant/open/v1/pay/merchant/product/pageQuery`
* `GET /merchant/open/v1/pay/merchant/product/queryOne`

### Step 2: Create subscription plans

Plans define rules such as billing cycle, trial, end conditions, and promotions. Associate each plan with the product or price created earlier.

Core APIs:

* `POST /open/v1/plan/save`
* `GET /open/v1/plan/list`
* `GET /open/v1/plan/detail`

### Step 3: Create subscription orders

When the user confirms purchase, your backend creates a subscription order. The response includes `subscriptionLink` for the authorization page.

Core APIs:

* `POST /open/v1/order/create`
* `GET /open/v1/order/list`
* `GET /open/v1/order/detail`

### Step 4: Guide the user through authorization

Redirect the user to `subscriptionLink` to complete authorization.

* **FIX\_AMOUNT**: After authorization, the subscription enters the planned recurring debit phase.
* **ACCOUNT\_AUTH**: After authorization, you hold account debit authorization; call `POST /open/v1/order/deduct` from your server when you need to debit.

### Step 5: Track order and debit status

Prefer **notifications** for subscription order status and each debit outcome; use **query APIs** as a fallback.

Core APIs:

* `GET /open/v1/deduction/order/list`
* `GET /open/v1/deduction/order/detail`
* `POST /open/v1/order/deduct` (merchant-initiated debit for `ACCOUNT_AUTH`)

Webhooks (see API Reference):

* `subscriptionOrderWebhook`: subscription order status updates
* `subscriptionOrderPaymentWebhook`: payment / deduction notifications

## Integration notes

* Store separate business IDs for products, plans, and orders to simplify reconciliation and support.
* After order creation, send users to authorization quickly to reduce drop-off.
* Treat “subscription order status” and “debit status” as two related but separate tracks; for `ACCOUNT_AUTH`, also distinguish **authorized amount** vs **total debited**.
* **FIX\_AMOUNT**: recurring debits are ongoing—do not infer long-term health from a single API response.
* **ACCOUNT\_AUTH**: implement authorization validity, idempotent debits, and retry policy on the server to avoid duplicate or missing debits.
* If you have a membership or entitlement system, map subscription states explicitly to internal entitlements instead of equating a single payment result with access.

## FAQ

### Which currencies and payment methods are supported?

Major Web3 wallets are supported, or users can authorize USDT/USDC in the Gate App for subscription. If you have enabled Stripe, linked accounts can be used for fiat subscription payments.

### How long is a subscription order valid?

There is no single fixed “validity” window. The order ends based on configured termination such as `totalPayCount` or `endTime`. If neither is set, it is usually treated as an ongoing subscription.

### How do I configure a trial period?

Set `trialDays` on the subscription plan. No formal debit runs during the trial; after the trial, debits follow product and plan rules.

### How do I configure a first-period discount?

When creating product pricing for subscription, set `promoConfigType`:

* `FIX_AMOUNT`: set `promoAmount` as the discounted amount for the first period
* `RATE`: set `promoRate` as the discount ratio, e.g. `0.1` for a 10% price

### How can a merchant manually end a subscription?

Call `POST /open/v1/order/complete` with `operationType=FINISH`. No further debits are executed after completion.

### Who initiates debits in ACCOUNT\_AUTH mode?

The merchant triggers debits from the backend when needed by calling `POST /open/v1/order/deduct` with amount and currency, then reconcile with notifications and deduction query APIs.

## Order status

| Status       | Description                                                                           |
| ------------ | ------------------------------------------------------------------------------------- |
| `CREATED`    | Order created; waiting for user authorization                                         |
| `AUTHORIZED` | Authorized; waiting for the first debit or for the merchant to initiate a debit       |
| `CONFIRMING` | Confirming; awaiting the first subscription confirmation deduction result             |
| `TRIAL`      | In trial; formal debit has not started                                                |
| `RUNNING`    | Running normally; waiting for the platform or the merchant to initiate the next debit |
| `UNPAID`     | Current debit failed but close conditions are not met yet                             |
| `COMPLETED`  | End condition reached or merchant completed manually                                  |
| `CANCELLED`  | Cancelled by the merchant                                                             |
| `CLOSED`     | Closed due to an exception, e.g. too many failed debits                               |
| `BLOCKED`    | A debit was made but funds are under risk control                                     |

## Related guides

* [Payment](/essentials/version/100/en/inflow/payment/payment)
* [Notification](/essentials/version/100/en/common/notification)
* [Authentication](/essentials/version/100/en/common/authentication)
* [Error](/essentials/version/100/en/common/error)
* [API Reference](/api-reference/version/100/en/introduction)