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 ↓curl -X POST "https://yunshutoken.com/partner/v1/connect" \
-H "Authorization: Bearer $YUNSHU_API_KEY" \
-H "Content-Type: application/x-www-form-urlencoded" \
--data ""Start with queries. Enable purchasing or redemption only when your server needs it.
Call from your server. Never expose the key in a browser.
Set your own retail price; procurement uses your store account pricing.
https://yunshutoken.com/partner/v1redeem.yunshutoken.comKeys & 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. |
{"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. |
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"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.
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"{"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.