Skip to main content

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.

​
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:
priceTypeCapabilityHow debits work
FIX_AMOUNTFixed amount debited on the plan’s billing cycleAfter the user authorizes, the platform runs recurring debits according to the merchant’s subscription plan
ACCOUNT_AUTHAccount authorization; the merchant decides when to debitAfter 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: 
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. 
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):
  • subscriptionOrderNotifyWebhook: subscription order status updates
  • subscriptionOrderPaymentNotifyWebhook: 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

StatusDescription
CREATEDOrder created; waiting for user authorization
AUTHORIZEDAuthorized; waiting for the first debit or for the merchant to initiate a debit
CONFIRMINGConfirming; awaiting the first subscription confirmation deduction result
TRIALIn trial; formal debit has not started
RUNNINGRunning normally; waiting for the platform or the merchant to initiate the next debit
UNPAIDCurrent debit failed but close conditions are not met yet
COMPLETEDEnd condition reached or merchant completed manually
CANCELLEDCancelled by the merchant
CLOSEDClosed due to an exception, e.g. too many failed debits
BLOCKEDA debit was made but funds are under risk control