Billing and Entitlements

App services

Billing and Entitlements

On this page

Let apps integrated with CZL Connect charge their own end users: sell plans (for individuals or organizations), plan add-ons (extra seats, extra storage) and one-time products. CZL Connect creates orders, verifies payments, keeps subscription state and entitlements, and pushes changes to your backend. Money goes straight to your own Alipay, WeChat Pay or Stripe account; CZL Connect never holds funds and takes no commission. Refunds, taxes and invoices are your responsibility.

The channels can be used alone or together; checkout lists every available method:

ChannelYou providePayment methods
Direct Alipay Open PlatformYour own app APPID and keysQR code, desktop web, mobile web (one-time payments)
Direct WeChat Pay merchant (APIv3)Your merchant ID, AppID, APIv3 key, merchant API certificate and WeChat Pay public key (or platform certificate)Native QR code and H5 (opens WeChat from mobile browsers), one-time payments
Stripe ConnectOAuth authorization of your Stripe account (Standard); CZL Connect does not store your keys"Stripe auto-renew" (starts a plan that is charged every period) and "Stripe one-time payment"; the actual payment methods are whatever your Stripe account has enabled

Setup

Alipay

  1. On the Alipay Open Platform, create an app and sign up for whichever of Face-to-Face Payment, Desktop Website Payment and Mobile Website Payment you need. Choose RSA2 signing, in either public key mode or public key certificate mode. A dedicated app for CZL Connect is recommended
  2. In CZL Connect, go to Account settings → Integrations → Payment accounts and add the APPID, app private key and Alipay public key (or the app public key certificate, Alipay public key certificate and Alipay root certificate). Also tick the products you signed (at least one; changing only the ticks doesn't require re-entering keys). Saving runs a trade query as a connectivity check (independent of which products are signed) and fails if the credentials are wrong; credentials are stored encrypted and never shown again. Checkout and the catalog methods only offer methods for the ticked products: Face-to-Face Payment → alipay_qr, Desktop Website Payment → alipay_page, Mobile Website Payment → alipay_wap. On desktop the hosted checkout offers the QR code (Face-to-Face) and the web cashier (Desktop Website), falling back to Mobile Website Payment if neither is signed; on phones it prefers Mobile Website, then Desktop Website, then QR
  3. In the app's Billing → Settings, choose the payment account and enable billing. Billing requires the Plus plan or above on CZL Connect (Plus 300 successful orders per month, Pro 3000, Enterprise unlimited; renewals are never blocked)
  4. Create plans under Billing → Plans and one-time products under Products

You don't need to configure a notify URL in Alipay: each order carries https://connect.czl.net/api/pay/notify/alipay/{payment account ID}.

WeChat Pay

  1. On the WeChat Pay merchant platform, enable Native Payment (for mobile browsers also enable H5 Payment and register connect.czl.net as the H5 payment domain under Product center → Development settings), then under Account center → API security set the APIv3 key (32 characters), apply for the merchant API certificate (you get apiclient_key.pem and the certificate serial number) and get the WeChat Pay public key and its ID (starting with PUB_KEY_ID_; older merchants can use the platform certificate instead). The AppID used for orders must be an Official Account, Mini Program or Open Platform app bound to the merchant ID
  2. Under Account settings → Integrations → Payment accounts, click "Add WeChat Pay account" and enter the merchant ID, AppID, APIv3 key, merchant API private key and certificate serial number, and the WeChat Pay public key and ID (or platform certificate), then tick the enabled products (Native Payment → wxpay_native, H5 Payment → wxpay_h5; without the registered domain the WeChat payment page reports a merchant parameter error). Saving requires passkey verification and queries a non-existent order as a connectivity check (it passes only when the merchant ID, private key, certificate serial number and WeChat Pay public key all match); it is not saved if the check fails. Keys are stored encrypted and never shown again; only the first and last few characters of the certificate serial number and public key ID are shown for reference. Whether the AppID is bound to the merchant ID is checked on the first order, and the APIv3 key on the first callback (with a wrong key callbacks fail verification and orders are credited by polling instead). For older merchants WeChat Pay may keep signing with the platform certificate after you apply for the public key; CZL Connect then downloads the platform certificates with the APIv3 key automatically, so just enter the public key as usual
  3. In the app's Billing → Settings, choose the account (alongside Alipay and Stripe if you like) and enable billing

WeChat Pay only charges CNY; the merchant order number is the order ID without hyphens (32 characters). You don't need to configure a callback URL on the merchant platform: orders and refunds carry https://connect.czl.net/api/pay/notify/wxpay/{payment account ID}. Refunds are asynchronous: once WeChat Pay accepts a refund it is recorded as refunded, and the refund callback confirms it (if WeChat Pay finally fails the refund it is only logged; handle it on the merchant platform); after a partial refund on the merchant platform, refunding the order from CZL Connect is rejected by WeChat Pay; refunds made directly on the merchant platform are synced too, and the order counts as refunded once the full amount has been returned.

Stripe

  1. Under Account settings → Integrations → Payment accounts, click "Connect Stripe" (passkey verification required), sign in to Stripe and authorize. You return to account settings with the payment account added. A Stripe account can be connected to only one CZL Connect account
  2. In the app's Billing → Settings, choose the Stripe account (alongside the Alipay account if you like) and enable billing
  3. Plan prices are in CNY, so your Stripe account must be able to accept CNY. Enable the methods you want (Alipay, WeChat Pay, Apple Pay, Google Pay, Link, etc.) under Settings → Payment methods in your own Stripe Dashboard. Checkout uses Stripe dynamic payment methods: the session is created on your account, so the methods shown come from your account's own payment method settings, filtered by currency, customer location and payment type — "Stripe auto-renew" only shows methods that support recurring payments (cards, Apple Pay, Google Pay, Link, etc.), while Alipay, WeChat Pay and similar appear only under "Stripe one-time payment". The platform's defaults for connected accounts only apply to accounts that haven't customised their settings; a method that isn't available on your account is simply not shown
  4. Consider turning off Stripe's own receipt emails; CZL Connect sends payment and renewal emails in your app's name

There is no webhook to configure in Stripe: the Connect platform receives your account's events. Every checkout, subscription, price and payment CZL Connect creates on your account carries metadata.app=czlconnect, app_id, order, subject and plan, so your other business on the account is unaffected. The first time a plan is sold as an auto-renewing subscription, a Product and Price are created on your account (price changes create a new Price instead of editing the old one). Deleting the Stripe payment account also revokes the authorization; it cannot be deleted while an app uses it or auto-renewing subscriptions remain. If you revoke access in Stripe, the account is marked "Disconnected" and apps using it stop accepting new Stripe orders.

Concepts

ConceptDescription
Plancode (identifies the plan in clients, immutable), price (cents), period (year / month / fixed days / lifetime lifetime), multi-period options multiPeriods (buy 2-12 periods at once with a discount each, e.g. 20% off 3 years), subject (user or org), seats (organization plans), quotas and features (open key-value maps returned as-is), trial days
Add-onUnits added on top of a plan (e.g. 1 seat / 10 GB): price per unit (per plan period), amount per unit, target (seats or a key of the plan quotas), maximum units, eligible plans
ProductOne-time purchase (top-ups etc.). Its payload is passed to your backend with order.paid for fulfillment; kind: "topup" is a top-up by amount (see below)
CouponCode (case-insensitive), fixed amount or percentage (1-99%), total uses (1 = single use, 0 = unlimited), uses per subject, minimum spend (pre-discount amount), start / end time, scope (everything, or specific plan / product / add-on codes)
SubscriptionOne per subject (user or organization) per app, with status trialing / active / past_due / grace / expired / canceled / refunded
OrderOne per checkout, pending / paid / closed / refunded; kind plan / upgrade / addon / product; the order ID is the Alipay merchant order number (for WeChat Pay, the order ID without hyphens)

Changing a plan's price, period or subject archives the current row and creates a new row with the same code: existing subscriptions keep their price and renew at the new price. Archiving stops sales; existing subscriptions keep their entitlements until they expire. Changing an add-on's price, amount per unit or target archives the row and creates a new one with the same code; units already bought keep their purchase price, and one-time renewals are priced from the active row. After an add-on is archived, or the subscription moves to a plan that doesn't allow it, the paid current period stays intact; from the next period it no longer applies and is no longer billed (on auto-renewing subscriptions the item is removed from Stripe right away, without proration).

Currencies and top-ups

  • Currency: plans, products (including top-ups), add-ons and fixed-amount coupons can be priced in CNY or USD. Stripe charges the listed currency directly; Alipay and WeChat Pay only charge CNY, so USD prices are converted at Billing → Settings → USD exchange rate (rounded to the cent). Without a rate the order returns 400 with "code": 40027. Orders record both amounts: amountCents / currency is what the provider charged, listAmountCents / listCurrency is the list price (after discounts), and exchangeRate is the rate at order time; refunds return the charged amount. Add-ons must use the plan's currency, and plans in different currencies can't be upgraded or downgraded into each other mid-period
  • Fees: the owner can set a percentage and a fixed amount (per charge currency) for each payment method (Alipay / WeChat Pay / Stripe) under "Billing → Settings → Fees". The fee is added to the charged amount: amountCents includes it and feeCents lists it separately (on orders, on previews that pass method, and on order in order.paid and other webhooks; omitted when zero). listAmountCents excludes the fee. Zero-amount orders and Stripe auto-renewals are not charged a fee; refunds return the full charged amount, fee included
  • Top-ups (product kind: "topup"): the owner sets a minimum, maximum and step (in the list currency) and optional tier discounts (once the credited amount reaches a threshold the user pays a percentage less; the highest tier reached applies). The order passes the credited amount in amountCents; the order's creditCents is the credit and listAmountCents what is paid. CZL Connect doesn't keep balances: order.paid carries creditCents and the paid amount for your backend to credit. Amounts outside the range or off-step return 400; a converted amount below the provider's minimum charge returns 400 with "code": 40026. Top-up products can't be used for redeem codes

Purchase rules

  • One-time payments (direct Alipay, direct WeChat Pay, Stripe one-time payment): no automatic renewal; reminder emails 7 days and 1 day before expiry; renewing the same plan extends from the current end date and costs the plan plus next period's add-on units
  • Stripe auto-renew: when the subject has no active paid subscription, a plan can be started with "Stripe auto-renew", which creates an auto-renewing subscription. Periods follow Stripe and each renewal is charged automatically (plan plus add-ons); yearly plans get a reminder email 7 days before the charge. A failed charge sets past_due with entitlements kept for the grace days; a successful retry by Stripe restores active, and the subscription becomes expired after the grace period or when Stripe ends it. Users can turn auto-renewal off (cancel at period end, usable until the period ends) or back on under My subscriptions. Auto-renewing subscriptions cannot be renewed with one-time payments; a one-time subscription can switch to auto-renewal only after it ends
  • Upgrade (more expensive plan, same period): for one-time subscriptions the difference = (new price − old price) × remaining days / period days, at least 1 cent, and the plan switches after payment; auto-renewing subscriptions are charged the prorated difference on their payment method right away (a failed charge returns an error and nothing changes). The end date stays the same either way
  • Downgrade (cheaper plan): one-time subscriptions switch at the end of the current period after payment; auto-renewing subscriptions cannot downgrade yet — turn off auto-renewal and buy again after it ends
  • Multi-period purchases: when a plan has multiPeriods (e.g. [{"periods": 3, "percentOff": 20}]), new plans, renewals and downgrades can pass periods to buy several periods at once. Plan price = unit price × periods × (1 − discount); add-on units on renewal are charged at full price per period. The end date moves by that many periods and the order's quantity is the number of periods. One-time payments only (no Stripe auto-renew); upgrades charge the difference for the remaining time (prorated per single period, so the remaining time can exceed one period) and can't be combined with periods. A number of periods the plan doesn't offer returns 400 with "code": 40028
  • Lifetime plans (periodUnit: "lifetime"): a one-time purchase with no end date, no renewal and no add-ons; entitlements report periodEnd: null and lifetime: true. They can only be paid one-time (Alipay, WeChat Pay, Stripe one-time payment; no Stripe auto-renew). Buying a lifetime plan while on a periodic subscription charges the full price and replaces it immediately (remaining time isn't credited; an auto-renewing subscription is canceled on Stripe). With a lifetime plan you can't buy it again or switch to another plan (upgrading from lifetime isn't supported yet): 400 with "code": 40025. Refunds always end it immediately; redeem codes and imports that target a lifetime plan ignore days / periodEnd
  • After expiry there is a grace period (app setting, default 3 days) with entitlements intact, then expired
  • Several add-ons at once: one order can carry several add-ons, each with its own units. Each line is prorated on its own, the order amount is the total, and the minimum charge applies to the total; a refund returns the whole order and removes all of its units. A coupon scoped to only some of the add-ons can't be used on it
  • Add-ons with a new plan: when starting a plan (no subscription, expired, trialing or in grace) you can pass addons; each line costs unit price × units × periods, ends with the plan and renews with it. With Stripe auto-renew the add-ons become extra subscription items charged every period. Renewals, upgrades and downgrades of an active subscription can't include add-ons (400) — buy them separately; lifetime plans don't support add-ons. If the subscription was already started by another order when the payment arrives (so this one became a stacked renewal), or the add-ons no longer apply, the whole order is refunded
  • Add-ons: only subjects with an active subscription can buy add-ons allowed for their plan. Price = unit price × units × remaining days / plan period days (at least 1 cent); they take effect immediately and end with the plan. On auto-renewing subscriptions add-ons are charged right away on the subscription's payment method and then renew with it. Reducing units takes effect at the end of the current period ("Adjust add-on units"); restarting an expired subscription does not carry add-ons over. When so little time is left that the prorated amount is below the minimum charge (¥1 for Alipay and WeChat Pay, ¥4 for Stripe), the order is refused with 400 and "code": 40021; add it after renewing. If a one-time payment arrives after the subscription has ended, the plan no longer allows the add-on or the unit limit is reached, the order is refunded automatically
  • Buying for an organization requires the organization owner or admin. With an active subscription the organization's seats = the plan's seats (or the app's default seats if unset) + add-on seats; otherwise the default seats. When members exceed seats the organization becomes read-only (no one is removed) until it renews, upgrades, adds seats or removes members
  • Coupons: orders, previews and the hosted checkout all accept a coupon code; plan coupons apply to new plans, renewals and upgrade differences. Uses are counted by orders carrying the coupon (pending, paid and refunded): unpaid orders that close give the use back, full refunds do not. Ordering the same thing again reuses the user's own pending coupon order; changing the quantity or payment method closes the earlier one first, so each user holds at most one pending order per coupon. Ten unknown codes in a row lock that user out of coupons for an hour (429). The discounted amount must be at least 1 cent and not below the payment method's minimum charge (¥1 for Alipay and WeChat Pay, ¥4 for Stripe), otherwise 400 with "code": 40024; an invalid, not yet active, expired, disabled, used-up or inapplicable coupon, or one whose minimum spend isn't met, returns 400 with "code": 40023. Coupons can't be used with Stripe auto-renew (including upgrades and add-ons on an auto-renewing subscription)
  • Self-service refunds: the app can allow refunds within N hours of payment, M times per period; the subscription ends immediately (auto-renewing subscriptions are also canceled in Stripe). Owners can refund from the console without the time window and choose to end now or at period end (auto-renewing subscriptions then cancel at period end); refunding an add-on order removes only those units. Refunds made in the Stripe Dashboard are synced to orders and subscriptions

Hosted checkout

Without your own UI, open this in the system browser:

https://connect.czl.net/pay/{app ID}/{plan or product code}?user={user ID}&subject=org:{organization ID}&periods={periods}&addons={add-on code}:{units}&coupon={code}&return={return URL}
https://connect.czl.net/pay/{app ID}?user={user ID}&addons={add-on code}:{units},{add-on code}:{units}&subject=org:{organization ID}&return={return URL}
  • Always pass user when you can: the ID of the user signed in to your app (same as the OIDC sub / userinfo id). If the browser is signed in to a different Connect account, the page blocks payment and offers "Switch account" (sign out, sign back in, return here), so the subscription doesn't land on an account your app can't find. It is only a check and never changes who pays, so it needs no signature; the order API accepts user too and returns 409 with "code": 40029 on a mismatch

  • addons: comma-separated code:units (units default to 1). With a plan code in the path they are bought together with the plan (see "Add-ons"); without one it is a standalone add-on purchase of one or more items, with units adjustable on the page. The old ?addon={code}&qty={units} still works

  • Omit subject for an individual purchase; for organization plans the page lets the user pick an organization they manage; for add-ons the user picks themselves or an organization they manage

  • coupon pre-fills a coupon code; users can also enter one on the page

  • return must match a registered redirect URI or a return URL in Billing → Settings by scheme, host and path (query strings may differ). Custom schemes such as myapp://billing/done work; anything else is ignored

  • Alipay: desktop browsers get a QR code and the web cashier, phones are sent to Alipay; WeChat Pay: a Native QR code on desktop and in the WeChat in-app browser, and on mobile browsers with H5 enabled the user is sent straight to WeChat and back to the result page; Stripe: the user is sent to Stripe Checkout. After paying, the result page offers "Back to the app" with return

Users can view subscriptions and add-ons, renew, toggle auto-renewal, buy more add-ons and request refunds under Account settings → Subscriptions (https://connect.czl.net/profile/subscriptions; link your app's "Manage subscription" button straight to it).

User token API

Clients call these with an OAuth2 access token (Authorization: Bearer <access_token>); the app is taken from the token.

MethodPathDescription
GET/api/oauth2/billing/catalog?subject=Plans, products and payment methods on sale, plus add-ons available for the current plan of subject (default: the user)
GET/api/oauth2/billing/entitlementsEntitlements of the user and each of their organizations
POST/api/oauth2/billing/order-previewPrice an order and validate a coupon without creating it (same parameters as ordering, method optional; when given, the minimum charge for that method is checked); returns originalCents, discountCents, amountCents (list currency), creditCents (top-ups), chargeCents (fee included) / chargeCurrency / exchangeRate / feeCents when method is given, and coupon
POST/api/oauth2/billing/ordersCreate an order
GET/api/oauth2/billing/ordersMy orders
GET/api/oauth2/billing/orders/{orderId}Order status (for polling; pending orders are actively queried from the payment provider)
POST/api/oauth2/billing/orders/{orderId}/refundSelf-service refund
POST/api/oauth2/billing/redeemRedeem a code
POST/api/oauth2/billing/trialsStart a trial ({"plan": "...", "subject": "..."})
POST/api/oauth2/billing/addon-quantityAdjust add-on units (decrease only, from the next period; pass the current units to undo): {"subject": "user", "addon": "seat", "quantity": 1}
POST/api/oauth2/billing/subscriptions/{subscriptionId}/auto-renewToggle auto-renewal: {"enabled": false} cancels at period end

Create an order (QR code)

HTTP
POST /api/oauth2/billing/orders
Content-Type: application/json

{"plan": "team", "subject": "org:0192f3a0-...", "method": "alipay_qr", "returnUrl": "myapp://billing/done"}
  • One of plan, product or add-ons (a code); products accept quantity (1 to 99)
  • addons: several add-ons, [{"code": "storage10", "quantity": 2}, {"code": "seat", "quantity": 1}]. Without plan it is a standalone add-on purchase (the old addon + quantity still works; use one or the other); with plan they are bought together with the plan
  • user: optional, the user ID as your app sees it; a mismatch with the token's user returns 409 with "code": 40029. The catalog's me.id is the current user's ID (the hosted page also gets name and email for its prompt)
  • subject: user or org:{organization ID}
  • amountCents: the credited amount for top-up products (list currency, cents)
  • periods: how many plan periods to buy at once (default 1; must be one the plan's multiPeriods offers)
  • coupon: optional coupon code; the order returns discountCents and couponCode, and amountCents is the discounted amount charged
  • method: alipay_qr (returns QR content) / wxpay_native (WeChat Pay Native, returns QR content weixin://...) / wxpay_h5 (WeChat Pay H5, returns a redirect URL for mobile browsers only, not the WeChat in-app browser; the order uses the caller's IP, so call it from the user's device) / alipay_page (desktop web, returns a redirect URL) / alipay_wap (mobile web) / stripe_recurring (Stripe auto-renew; only for plan orders that can start auto-renewal, otherwise an error) / stripe_once (Stripe one-time payment for plans, add-ons and products); the last two return a Stripe Checkout payUrl. See methods in the catalog (Alipay and WeChat Pay methods follow the payment account's signed or enabled products); a method the account doesn't offer returns 400 with "code": 40022. The old values stripe_card (stripe_recurring when eligible, otherwise stripe_once) and stripe_alipay (same as stripe_once) are still accepted; orders record the resolved method
  • When a Stripe one-time payment uses an asynchronous method such as Alipay or WeChat Pay, the order stays pending after the user submits and becomes paid once confirmed; if it finally fails the order is closed and the user can order again
  • When the subject already has an auto-renewing subscription, upgrades and add-ons skip checkout: the charge is made right away and the order returns with status: "paid"; a failed charge returns 402. Several add-ons at once produce a single invoice
  • Orders and previews carry addons lines (code, name, quantity, amountCents = that line's list amount before coupons); order.addons in order.paid and other webhooks is the same
JSON
{
  "id": "0192f3b1-7c2e-7a10-9d55-0f1c2b3a4d5e",
  "kind": "plan",
  "itemCode": "team",
  "amountCents": 14900,
  "status": "pending",
  "qrCode": "https://qr.alipay.com/bax0...",
  "expiresAt": "2026-11-20T10:15:00Z",
  "refundable": false
}

Add-on example: {"addon": "storage10", "quantity": 2, "subject": "user", "method": "alipay_qr"} returns kind: "addon" with the prorated amountCents. Each catalog add-on has currentQuantity, maxUnits, priceCents (per unit per period) and proratedUnitCents (per unit for the rest of this period).

Desktop clients render qrCode (Alipay or WeChat Pay), poll GET /orders/{id} every 2 seconds and refresh entitlements once status is paid. QR codes are valid for 15 minutes; expired orders are closed. Web payments return payUrl to open in a browser. Repeating the same order while it is valid returns the same order. When kind is upgrade, amountCents is the prorated difference.

Entitlements

JSON
{
  "personal": {
    "subscriptionId": "0192...",
    "active": true,
    "plan": "personal",
    "planName": "Personal Sync",
    "status": "active",
    "periodStart": "2026-11-20T10:00:00Z",
    "periodEnd": "2027-11-20T10:00:00Z",
    "lifetime": false,
    "graceUntil": null,
    "cancelAtPeriodEnd": false,
    "seats": 0,
    "quotas": {"syncStorageGB": 25},
    "features": {},
    "addons": [
      {"code": "storage10", "name": "+10 GB storage", "target": "syncStorageGB", "unitAmount": 10, "quantity": 2, "amount": 20, "pendingQuantity": null, "pendingEffectiveAt": null}
    ],
    "provider": "stripe_connect",
    "autoRenew": true
  },
  "orgs": [
    {"orgId": "0192...", "name": "Export Team", "role": "member", "orgStatus": "active", "seats": 5, "memberCount": 3, "entitlement": {"plan": "team", "active": true, "...": "..."}}
  ]
}
  • Lifetime plans have periodEnd: null and lifetime: true (outgoing webhooks likewise send currentPeriodEnd: null with lifetime)
  • personal / entitlement is null if there has never been a subscription; when active is false, seats, quotas, features and addons are empty
  • seats and quotas are totals of the plan and its add-ons (above: 5 GB plan + 2 × 10 GB add-ons), so check against them directly; addons lists the details, and pendingQuantity shows next period's units
  • autoRenew: true marks a Stripe subscription that renews automatically; cancelAtPeriodEnd: true means auto-renewal has been turned off
  • Status is computed from the current time and does not depend on scheduled jobs
  • pendingPlan marks a paid downgrade that starts at the end of the current period
  • Entitlements are not in the ID Token; desktop clients refetch when returning to the foreground or after payment

Redeem codes

HTTP
POST /api/oauth2/billing/redeem
{"code": "ABCD-EFGH-JKLM-NPQR", "subject": "user"}

Plan codes add days to the current subscription (switching to the code's plan when the current one is cheaper, or starting a new period when there is none). Product codes create a zero-amount paid order and send order.paid. Each code works once; 10 consecutive failures lock the user out for an hour.

App API

Call from your backend with an API key (czlc_live_…), see App API.

ScopeMethodPathDescription
billing:readGET/api/v1/app/users/{userId}/entitlementsA user's entitlements, same shape as above
billing:readGET/api/v1/app/orgs/{orgId}/entitlementsOrganization entitlements, same shape as one item of orgs[] above (without role); 404 org_not_found for an unknown organization
billing:readGET/api/v1/app/billing/ordersList orders in ascending update order for incremental reconciliation: since (RFC 3339, only orders updated at or after it), status (comma-separated pending / paid / closed / refunded), limit (1-100, default 50), cursor (nextCursor from the previous page). Returns items (same shape as order in webhooks), nextCursor and hasMore. An order updated later (paid, refunded) shows up again in a later page, so handle it idempotently by order ID. Only orders updated more than 30 seconds ago are listed; nextCursor is returned on the last page too, so store it and resume from it next time
billing:readGET/api/v1/app/billing/orders/{orderId}Look up an order (for compensating fulfillment)
billing:writePOST/api/v1/app/subscriptions/importImport existing subscriptions
billing:catalogPUT/api/v1/app/billing/catalogSync plans, products and add-ons
billing:catalog or billing:readGET/api/v1/app/billing/catalogExport the catalog (?includeArchived=1 includes archived items)

Import existing subscriptions

Migrate existing paying users (one-time payments or other channels). They are recorded as manual subscriptions without emails, idempotent by (subject, externalId):

JSON
{"items": [
  {"externalId": "legacy-123", "userId": "0192...", "plan": "personal", "periodEnd": "2027-03-01T00:00:00+08:00", "note": "migrated"},
  {"externalId": "legacy-456", "orgId": "0192...", "plan": "team", "periodEnd": "2027-01-01T00:00:00+08:00"}
]}

Each item may carry addons (e.g. [{"code": "storage10", "quantity": 1}], for gifting "plan + extra storage"): those add-ons on the subscription are set to the given units (not added), end with the plan and renew with it; a subscription that restarts doesn't keep the previous period's add-ons. Items with addons fail when the subject's subscription is still on a different plan or is a Stripe auto-renew subscription.

Each item returns a status: created / exists / error (with error). 1 to 500 items per request.

Sync the catalog

If you maintain plans in your own backend, push the catalog here instead of creating it by hand in the CZL Connect console. It is idempotent by code and follows the console rules:

  • No active item with that code → created (created)
  • Price, period or subject changed (for add-ons: unit price, amount per unit or target) → the old row is archived and a new row with the same code is created (repriced); existing subscriptions keep their price and renew at the new one
  • Other fields changed (names, quotas, features, seats, sort order, etc.) → updated in place (updated); nothing changed → unchanged, so pushing repeatedly is safe
  • status: "archived" → archived (archived); with prune: true, active items missing from the request are archived too
  • Plans are processed before add-ons; each item is independent and a failing item reports error without affecting the rest. At most 200 items per call
HTTP
PUT /api/v1/app/billing/catalog
Authorization: Bearer czlc_live_...

{"plans": [{"code": "pro-1y", "nameZh": "专业版 1 年", "nameEn": "Pro 1 year", "priceCents": 19900, "periodUnit": "year", "periodCount": 1, "subjectType": "user",
            "quotas": {"storageGB": 100}, "features": {"group": "pro"}}],
 "products": [{"code": "pack-10g", "nameZh": "10 GB 流量包", "priceCents": 990, "payload": {"trafficGB": 10}}],
 "addons": [],
 "prune": false}

Returns {"items": [{"type": "plan", "code": "pro-1y", "result": "created", "id": "0192..."}, ...]}. Fields match the console forms (plans: code, nameZh, nameEn, priceCents, periodUnit, periodCount, subjectType, seats, quotas, features, trialDays, sortOrder; products: payload etc.; add-ons: unitAmount, target, maxUnits, planCodes). GET exports the same structure (each item also has id and status) so you can edit and push it back.

Outgoing webhooks

Add https endpoints under Billing → Webhook (up to 5 per app, optionally filtered by event). Events:

subscription.activated · subscription.renewed · subscription.upgraded · subscription.past_due · subscription.expired · subscription.canceled · subscription.refunded · subscription.addons_changed · order.paid · order.refunded · org.member_added · org.member_removed

subscription.addons_changed fires when add-ons are bought, reduced or refunded; refetch entitlements when you receive it. Each successful auto-renewal sends order.paid + subscription.renewed; a failed charge sends subscription.past_due.

HTTP
POST https://api.example.com/czl/webhook
Content-Type: application/json
X-CZL-Event-Id: 0192f3c4-...
X-CZL-Event-Type: order.paid
X-CZL-Signature: t=1795000000,v1=5f0c...

{"id": "0192f3c4-...", "type": "order.paid", "createdAt": "2026-11-20T10:01:02Z",
 "data": {"order": {"id": "0192...", "kind": "product", "itemCode": "chars-1m", "quantity": 1, "amountCents": 990,
   "status": "paid", "subject": {"type": "user", "userId": "0192..."}, "payerUserId": "0192...", "payload": {"chars": 1000000}, "discountCents": 0, "couponCode": "", "listAmountCents": 990, "listCurrency": "CNY", "creditCents": 0, "exchangeRate": ""}}}
  • Signature: v1 = hex(HMAC-SHA256(signing secret, t + "." + raw body)); check that t is within 5 minutes and compare in constant time
  • Deduplicate by id: an event may be delivered more than once
  • Any 2xx is success; otherwise retries after 1 minute, 5 minutes, 30 minutes, 2 hours, 6 hours, 12 hours and 24 hours, then the delivery is marked failed and can be redelivered from the delivery log
  • Endpoints must be public https URLs; private addresses are refused
Go
func verify(secret, header string, body []byte) bool {
	var ts, sig string
	for _, p := range strings.Split(header, ",") {
		k, v, _ := strings.Cut(p, "=")
		if k == "t" { ts = v } else if k == "v1" { sig = v }
	}
	t, _ := strconv.ParseInt(ts, 10, 64)
	if time.Since(time.Unix(t, 0)).Abs() > 5*time.Minute { return false }
	mac := hmac.New(sha256.New, []byte(secret))
	mac.Write([]byte(ts + "." + string(body)))
	return hmac.Equal([]byte(hex.EncodeToString(mac.Sum(nil))), []byte(sig))
}

Emails and notifications

Payment received, 7-day and 1-day expiry reminders for one-time subscriptions, a reminder 7 days before yearly auto-renewal charges, auto-renewal succeeded, auto-renewal failed (with a Stripe invoice link to pay with a new method), expiry and refund emails are sent in your app's name (sender "App name (via CZL Connect)") and also written to the user's notification center; organization subscriptions copy the organization owner. These are transactional emails: users cannot unsubscribe and they don't count against your broadcast quota. The payment account owner is notified when Alipay or WeChat Pay rejects the credentials or a Stripe account's authorization is revoked.

Errors

Errors are {"error": "human-readable message"} in the request language; the App API returns {"error": "snake_case_code", "message": "..."}. Common status codes:

StatusMeaning
400Invalid parameters, subject mismatch, refund not eligible, etc.; add-on amounts below the minimum charge also carry "code": 40021, a payment method the account doesn't offer carries "code": 40022, an unusable coupon carries "code": 40023, a discounted amount below the minimum charge carries "code": 40024, buying or switching while on a lifetime plan carries "code": 40025, a top-up below the provider's minimum charge carries "code": 40026, a USD price without an exchange rate configured carries "code": 40027, and a number of periods the plan doesn't offer carries "code": 40028
402The charge for an auto-renewing subscription's upgrade / add-on failed
403Billing not enabled, buying for an organization without owner / admin role, self-service refunds not allowed
404Plan / product / add-on / order / subscription not found
409user was passed but doesn't match the signed-in account ("code": 40029); ask the user to switch accounts
429Too many failed redemptions
502Payment provider unavailable or credentials rejected