Offline reference · 2026-10-17. For updates, visit https://yunshutoken.com/api-access/

UNIFIED PARTNER API / V1

Your storefront.
Our products & stock.

Keep your brand, pricing and checkout. Connect catalog, inventory, prepaid purchasing and eligible redemption with one key.

Create your key ↗Explore endpoints ↓

HTTPS · POST FORM · JSON · CNY

FIRST REQUEST · READ ONLY

curl -X POST "https://yunshutoken.com/partner/v1/connect" \
  -H "Authorization: Bearer $YUNSHU_API_KEY" \
  -H "Content-Type: application/x-www-form-urlencoded" \
  --data ""

01 / ACCOUNTSign in & create a key

Start with queries. Enable purchasing or redemption only when your server needs it.

02 / INTEGRATERead catalog & quote

Call from your server. Never expose the key in a browser.

03 / FULFILDeliver codes, or redeem for customers

Set your own retail price; procurement uses your store account pricing.

API BASE URLhttps://yunshutoken.com/partner/v1

REDEMPTION SERVICE · NOT ALL PRODUCTSredeem.yunshutoken.com

Keys & requests

All endpoints use the contract below. No app_id, MD5 signature or separate redemption Agent Key is required.

Setting	Contract
Authorization	`Bearer ysu_…`
Method / body	`POST` · `application/x-www-form-urlencoded` · UTF-8
Response	Check both HTTP 200 and code === 200. API success does not mean a subscription is active; inspect data.status for redemption progress.
Scopes	Read access includes balance, catalog, stock, quotes and your own orders with delivery codes. Buying products and redeeming codes require separate permissions.
Lifecycle	One active unified key per account. Shown only when created; only its hash is stored. Replacement invalidates the old key.
Limits	60 requests/minute per account, one request at a time; busy returns 429. No additional per-order purchase amount cap applies to unified keys. Balance, stock and product quantity rules still apply.

Checking a permission does not save changes or spend money. Create a key to apply selections; for an existing key, generate a replacement and update your server. Revocation blocks future requests, not accepted orders, and does not issue refunds.

Buying is not redeeming

Catalog sync or order queries: leave both optional permissions off.
Automated purchasing: enable purchase permission; /order spends your store balance.
Redeeming codes for customers: enable redemption permission for /plans, /check, /redeem and /result, limited to the service below. Selling codes for customers to redeem themselves does not need this permission.

RESPONSE · EXAMPLE ONLY

{"code":200,"data":{"shopName":"SHOP_NAME","balance":"0.00"}}

Store endpoints

All routes use POST. ? marks optional fields; follow item configuration for variants and widget fields. Inventory can change; verify the quote before purchase.

Path /partner/v1/…	Purpose	Fields	Response & constraints
`/connect`	Connection & balance	—	Returns shopName and balance.
`/items`	Catalog & stock snapshot	—	Category tree data[].children[]; public, active, API-enabled products only.
`/item`	Product details	code	Variants, quantity limits, widget and redemption_host.
`/stock`	Current stock	code; race?, sku?	data.stock; does not reserve stock.
`/quote`	Purchase quote	code, num; race?, sku?, card_id?	data.price is the quantity total; currency_code is the settlement currency. Not a price lock.
`/order`	Purchase · spends balance	shared_code, num, contact, request_no	Requires “Buy products with my store balance”. Debits real balance; returns tradeNo, amount, status and secret.
`/orderStatus`	Your order	tradeNo	Current account only. status is store payment status, not redemption status.

Field reference

Field	Rule
code / shared_code	Product API identifier from items; use shared_code for orders, not the display ID.
num	Integer 1–10000, also subject to product minimum / maximum.
race / sku	Use current item configuration. Encode variants as sku[NAME]=VALUE.
contact	Compatibility field: a 1–32 byte reference. The store generates its lookup identifier; query orders with tradeNo.
request_no	8–64 ASCII letters, digits, underscores or hyphens; unique per account.
card_id / device / password / coupon	Optional order fields, subject to product rules. password is the order lookup password. Include required widget fields from item.

PURCHASE · REAL BALANCE CHARGE

curl -X POST "https://yunshutoken.com/partner/v1/order" \
  -H "Authorization: Bearer $YUNSHU_API_KEY" \
  --data-urlencode "shared_code=PRODUCT_CODE" \
  --data-urlencode "num=5" \
  --data-urlencode "contact=YOUR_ORDER_CONTACT" \
  --data-urlencode "request_no=YOUR_UNIQUE_REFERENCE"

Purchases use your CNY balance. USD display and your retail markup do not change procurement settlement. secret contains sensitive delivery data; never log it publicly.

Redemption

Path /partner/v1/…	Required fields	Behavior
`/plans`	—	Supported plans; not a guarantee of availability or product compatibility.
`/check`	tradeNo, code	Check an eligible code delivered in your own paid order.
`/redeem`	tradeNo, code, session	Redeem a purchased code with customer consent. Does not purchase another product or debit store purchase balance again.
`/result`	tradeNo, code	Query a redemption submitted through this unified API. Old standalone-key or website submissions are not automatically migrated.

All four endpoints require redemption permission. session is a customer-authorized sessionToken or a JSON string containing sessionToken / session_token; accessToken alone is insufficient. Prefer the hosted redemption page when possible to avoid handling sensitive credentials.

REDEMPTION · REAL ACTION

curl -X POST "https://yunshutoken.com/partner/v1/redeem" \
  -H "Authorization: Bearer $YUNSHU_API_KEY" \
  --data-urlencode "tradeNo=YOUR_PAID_ORDER" \
  --data-urlencode "code=CODE_DELIVERED_IN_THAT_ORDER" \
  --data-urlencode "session=$CUSTOMER_AUTHORIZED_SESSION"

RESULT · EXAMPLE ONLY

{"code":200,"data":{"ok":true,"order_id":null,"status":"processing",
 "payment_status":"pending","plus_active":null,"auto_renewal_status":"unknown"}}

status may be processing / completed / action_required / failed. paid is a payment fact, not proof of an active subscription. plus_active: null means unknown or not applicable.

Retries & errors

Persist request_no before purchasing. Same-account requests with the same reference and fields return an existing order without repurchasing; uncertain outcomes fail closed. A code is recorded for redemption submission once; failed or uncertain submissions need reconciliation with support.

Error / signal	Action
401 · INVALID_API_KEY	Invalid/revoked key or unavailable account.
403 · SCOPE_DENIED	Orders require purchase permission; plans / check / redeem / result all require redemption permission. Select the permission, replace the key and update your server.
403 · REDEMPTION_NOT_ALLOWED	Unpaid order, code not delivered in that order, or ineligible redemption service.
404 · PRODUCT_UNAVAILABLE / ORDER_NOT_FOUND	Unavailable/hidden/non-API product or order not owned by this account.
409 · IDEMPOTENCY_CONFLICT	A purchase reference was reused with different parameters; no new charge.
409 · ORDER_OUTCOME_UNCERTAIN	A prior request is recorded but its outcome is uncertain. Reconcile with support; do not use a new reference.
409 · REDEMPTION_ALREADY_SUBMITTED	Redemption already recorded. Query result instead of submitting again.
429 · RATE_LIMIT / ACCOUNT_BUSY	Follow Retry-After with jittered backoff.
Timeout / 5xx	A write may have been accepted. Check the original order or redemption before retrying.

Native store business failures may return HTTP 200 with code:0 and a msg; always inspect the business code. Additional edge IP limits are shared by clients behind the same public IP.

Security & migration

Server-side secrets only

Never embed keys in web pages, mobile bundles, URLs, screenshots or public repositories. Use HTTPS and redact Authorization and request-body logs.

Least privilege

Purchase and redemption are off by default. Read-only keys can still access your delivered codes and must remain secret. Do not share keys; revoke and reconcile balance/orders after suspected exposure. A leaked key exposes all of its enabled permissions.

Explicit legacy migration

Legacy app_id + sign and shop keys remain separate and are not governed by unified-key permission settings. Revoke the legacy key after migration. The new unified key cannot call legacy native endpoints directly.

Operational boundaries

There is currently no separate test sandbox. Start with read-only calls; purchase and redemption are real operations. Authentication and limits do not eliminate credential theft or volumetric attacks.

Your storefront.Our products & stock.