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:
| Channel | You provide | Payment methods |
|---|---|---|
| Direct Alipay Open Platform | Your own app APPID and keys | QR 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 Connect | OAuth 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
- 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
- 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
methodsonly 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 - 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)
- 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
- On the WeChat Pay merchant platform, enable Native Payment (for mobile browsers also enable H5 Payment and register
connect.czl.netas 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 getapiclient_key.pemand the certificate serial number) and get the WeChat Pay public key and its ID (starting withPUB_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 - 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 - 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
- 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
- In the app's Billing → Settings, choose the Stripe account (alongside the Alipay account if you like) and enable billing
- 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
- 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
| Concept | Description |
|---|---|
| Plan | code (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-on | Units 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 |
| Product | One-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) |
| Coupon | Code (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) |
| Subscription | One per subject (user or organization) per app, with status trialing / active / past_due / grace / expired / canceled / refunded |
| Order | One 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
CNYorUSD. 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/currencyis what the provider charged,listAmountCents/listCurrencyis the list price (after discounts), andexchangeRateis 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:
amountCentsincludes it andfeeCentslists it separately (on orders, on previews that passmethod, and onorderinorder.paidand other webhooks; omitted when zero).listAmountCentsexcludes 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 inamountCents; the order'screditCentsis the credit andlistAmountCentswhat is paid. CZL Connect doesn't keep balances:order.paidcarriescreditCentsand 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_duewith entitlements kept for the grace days; a successful retry by Stripe restoresactive, and the subscription becomesexpiredafter 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 passperiodsto 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'squantityis 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 withperiods. 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 reportperiodEnd: nullandlifetime: 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
owneroradmin. With an active subscription the organization's seats = the plan'sseats(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
userwhen you can: the ID of the user signed in to your app (same as the OIDCsub/ userinfoid). 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 acceptsusertoo and returns 409 with"code": 40029on a mismatch -
addons: comma-separatedcode: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
subjectfor 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 -
couponpre-fills a coupon code; users can also enter one on the page -
returnmust match a registered redirect URI or a return URL in Billing → Settings by scheme, host and path (query strings may differ). Custom schemes such asmyapp://billing/donework; 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.
| Method | Path | Description |
|---|---|---|
| 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/entitlements | Entitlements of the user and each of their organizations |
| POST | /api/oauth2/billing/order-preview | Price 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/orders | Create an order |
| GET | /api/oauth2/billing/orders | My 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}/refund | Self-service refund |
| POST | /api/oauth2/billing/redeem | Redeem a code |
| POST | /api/oauth2/billing/trials | Start a trial ({"plan": "...", "subject": "..."}) |
| POST | /api/oauth2/billing/addon-quantity | Adjust 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-renew | Toggle auto-renewal: {"enabled": false} cancels at period end |
Create an order (QR code)
POST /api/oauth2/billing/orders
Content-Type: application/json
{"plan": "team", "subject": "org:0192f3a0-...", "method": "alipay_qr", "returnUrl": "myapp://billing/done"}- One of
plan,productor add-ons (a code); products acceptquantity(1 to 99) addons: several add-ons,[{"code": "storage10", "quantity": 2}, {"code": "seat", "quantity": 1}]. Withoutplanit is a standalone add-on purchase (the oldaddon+quantitystill works; use one or the other); withplanthey are bought together with the planuser: optional, the user ID as your app sees it; a mismatch with the token's user returns 409 with"code": 40029. The catalog'sme.idis the current user's ID (the hosted page also gets name and email for its prompt)subject:userororg:{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'smultiPeriodsoffers)coupon: optional coupon code; the order returnsdiscountCentsandcouponCode, andamountCentsis the discounted amount chargedmethod:alipay_qr(returns QR content) /wxpay_native(WeChat Pay Native, returns QR contentweixin://...) /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 CheckoutpayUrl. Seemethodsin 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 valuesstripe_card(stripe_recurringwhen eligible, otherwisestripe_once) andstripe_alipay(same asstripe_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
pendingafter the user submits and becomespaidonce confirmed; if it finally fails the order isclosedand 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
addonslines (code,name,quantity,amountCents= that line's list amount before coupons);order.addonsinorder.paidand other webhooks is the same
{
"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
{
"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: nullandlifetime: true(outgoing webhooks likewise sendcurrentPeriodEnd: nullwithlifetime) personal/entitlementisnullif there has never been a subscription; whenactiveisfalse,seats,quotas,featuresandaddonsare emptyseatsandquotasare totals of the plan and its add-ons (above: 5 GB plan + 2 × 10 GB add-ons), so check against them directly;addonslists the details, andpendingQuantityshows next period's unitsautoRenew: truemarks a Stripe subscription that renews automatically;cancelAtPeriodEnd: truemeans auto-renewal has been turned off- Status is computed from the current time and does not depend on scheduled jobs
pendingPlanmarks 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
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.
| Scope | Method | Path | Description |
|---|---|---|---|
billing:read | GET | /api/v1/app/users/{userId}/entitlements | A user's entitlements, same shape as above |
billing:read | GET | /api/v1/app/orgs/{orgId}/entitlements | Organization entitlements, same shape as one item of orgs[] above (without role); 404 org_not_found for an unknown organization |
billing:read | GET | /api/v1/app/billing/orders | List 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:read | GET | /api/v1/app/billing/orders/{orderId} | Look up an order (for compensating fulfillment) |
billing:write | POST | /api/v1/app/subscriptions/import | Import existing subscriptions |
billing:catalog | PUT | /api/v1/app/billing/catalog | Sync plans, products and add-ons |
billing:catalog or billing:read | GET | /api/v1/app/billing/catalog | Export 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):
{"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
codeis 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); withprune: 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
errorwithout affecting the rest. At most 200 items per call
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.
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 thattis 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
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:
| Status | Meaning |
|---|---|
| 400 | Invalid 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 |
| 402 | The charge for an auto-renewing subscription's upgrade / add-on failed |
| 403 | Billing not enabled, buying for an organization without owner / admin role, self-service refunds not allowed |
| 404 | Plan / product / add-on / order / subscription not found |
| 409 | user was passed but doesn't match the signed-in account ("code": 40029); ask the user to switch accounts |
| 429 | Too many failed redemptions |
| 502 | Payment provider unavailable or credentials rejected |