Contents
2 Applying for a Sandbox Test Account
6.1 Applicable Weixin Versions
6.4 Parameters Contained by the External Redirect URL
# 1 Instructions
Before reading coupon-related APIs documentation, be sure to read Before Development and Getting Started chapters in the developer documentation on the Weixin Official Accounts Platform to learn about how to call the APIs on the Weixin Official Accounts Platform, the developer guidelines, and how to deal with errors occurred while calling APIs.
# 2 Applying for a Sandbox Test Account
If you don't have a coupon test account, apply for a temporary test account using the Weixin API test account application tool to test coupons. Log in to the API Test Account Application system and scan the QR code to get a new appid (assigned the card/coupon creation permission, including friend's coupons and member cards) and appsecret for calling coupon APIs.
Note: Coupons created with this appid will not be approved and can only be available to users in the whitelist. It is only used for small-scale testing.
# 3 HelloWorld
Developers can use the debug tool to quickly debug the process of coupon creation/issuance/redemption. See appropriate API documentation to better understand each coupon API.
Step 1: Get access_token
Page URL: http://mp.weixin.qq.com/debug/
API Type: Basic Support
API List: "Get access_token" API
Note: Enter the developer's appid and secret in Parameter List
Click Debug to get access_token. The access_token is valid for two hours, and you must get a new one thereafter.
API documentation: Getting Access token
Step 2: Upload the coupon logo
Page URL: http://mp.weixin.qq.com/debug/
API Type: Basic Support
API List: "Upload Image" API
access_token: The one obtained in the previous step
buffer: The image you selected
Click Debug to get the image URL, which is required in parameters in the following step.
API documentation: Creating Coupon
Step 3: Create a coupon
Page URL: http://mp.weixin.qq.com/debug/
API Type: Coupon APIs
API List: "Create Coupon" API
access_token: The one obtained in Step 1
JSON example:
{ "card": {
"card_type": "GROUPON",
"groupon": {
"base_info": {
"logo_url": "http://mmbiz.qpic.cn/mmbiz/iaL1LJM1mF9aRKPZJkmG8xXhiaHqkKSVMMWeN3hLut7X7hicFNjakmx ibMLGWpXrEXB33367o7zHN0CwngnQY7zb7g/0",
"brand_name":"Weixin Restaurant",
"code_type":"CODE_TYPE_TEXT",
"title": "132 CNY Hotpot Set Meal for Two Persons",
"sub_title": "Best choice for weekend fun",
"color": "Color010",
"notice": "Present this coupon to the waiter at the time of use",
"service_phone": "020-88888888",
"description": "Using with other coupons is not allowed\nAsk the merchant for an invoice for the group purchase during check-out\nAvailable for eat-in only",
"date_info": {
"type": "DATE_TYPE_FIX_TERM",
"fixed_term": 15 ,
"fixed_begin_term": 0
},
"sku": {
"quantity": 500000
},
"get_limit": 3,
"use_custom_code": false,
"bind_openid": false,
"can_share": true,
"can_give_friend": true,
"location_id_list" : [123, 12321, 345345],
"custom_url_name": "Use Now",
"custom_url": "http://www.qq.com",
"custom_url_sub_title": "6 Chinese characterstips",
"promotion_url_name": "More discounts",
"promotion_url": "http://www.qq.com"
},
"deal_detail": "Select a soup base from the following options: mushroom soup, spicy soup, bone soup, tomato soup, nourishing soup, pickled fish soup: \n1 Big Pot: 12 CNY; 2 Small Pots:16 CNY.
}}
Note: A Unix timestamp is used in date_info. "begin_timestamp" should be earlier than the current time, and "end_timestamp" should be later than the current time; otherwise, the coupon redemption test will fail.
API documentation: Creating Coupon
Step 4: Create a QR code to issue the coupon
Page URL: http://mp.weixin.qq.com/debug
API Type: Coupon APIs
API List: "Create QR Code Ticket" API
access_token: The one obtained in Step 1
JSON example:
{"action_name":
"QR_CARD",
"action_info": {
"card": {
"card_id": "po_2DjgJ2zrboM6SzK3qNuje5iWQ",
}
}
}
API documentation: Issuing Coupon
Step 5: Display the QR code
Click the URL in the show_qrcode_url field returned in the previous step to display the coupon receipt QR code.
Scan the QR code using Weixin to claim the coupon. If the coupon is not approved, then you need to set a whitelist; otherwise, you can skip step 6.
Scan the following QR code to claim a Weixin coupon:
Step 6: Set the test whitelist
Page URL: http://mp.weixin.qq.com/debug
API Type: Coupon APIs
API List: "Set Test Whitelist" API
access_token: The one obtained in Step 1
JSON example:
{ "username":["usr1","usr2"] }
Note: usr1 and sur2 are Weixin IDs receiving the coupon.
API documentation: Issuing Coupon
Step 7: Redeem the coupon
Page URL: http://mp.weixin.qq.com/debug/
API Type: Coupon APIs
API List: "Redeem Coupon" API
access_token: The one obtained in Step 1
JSON example:
{ "code": "759733467744" }
Note: Only approved and valid coupons are supported. API documentation: Redeeming Coupon
# 4 Overview of Coupon APIs
Weixin coupon-related APIs covers a range of APIs related to the creation, receipt, issuance and redemption of coupons.
Developers can develop industry-specific coupons using appropriate APIs as needed.
# 5 Coupon-related Parameters
Here are key parameters required in the coupon development:
| Parameter | Description |
|---|---|
| card_id | Coupon ID. A coupon ID identifies a group of same coupons and contains specified number of codes. |
| code | Coupon code, the unique identifier on the coupon. This code can be customized by merchants and required for coupon redemption. |
| openid | User's unique ID under the Official Account |
| access_token | Credential for calling an API. It is valid for 7200 seconds, and is refreshed for each API request. It can be obtained using the "Get access_token" API. You need to save it properly by enabling credential caching. |
| jsapi_ticket | The signature ticket to be used when calling JS-SDK APIs to invoke the Weixin native features in webpages within Weixin. For more information, see JS-SDK Documentation. |
| api_ticket | The temporary ticket signed when calling Weixin coupon APIs, which is valid for 7200s, within which it remains unchanged for repeated requests. This ticket can be obtained using the "Get api_ticket" API. |
| card_ext | Additional information of expandable coupons, which is used to pass basic coupon information when issuing coupons. |
| outer_str | Scene value of coupon receipt channel. The merchant can enter a custom scene value into card_ext for coupon issuance. The event of receiving coupon along with the appropriate scene value will be pushed to the merchant. |
| Event push | The event of approving, receiving, deleting or redeeming coupon will be pushed to the server URL entered by the developer in the Official Accounts Platform Developer Center. |
| Custom entry | For coupons created via API, the merchant can configure the feature of redirect from the coupon details page to an external URL. The URL will be suffixed with the coupon card_id and the encrypted code when a user is redirected to the URL. |
# 6 Notes
# 6.1 Applicable Weixin Versions
Since the Cards & Offers feature module is supported as of Weixin 6.0.2, JS-SDK is not available in earlier versions. The Weixin Team recommends that merchants use user agent to determine the version of Weixin currently used by the user, and then call the Add to Cards & Offers JS-SDK API. On iOS, for example, the user agent can be used to get the following version information:
"Mozilla/5.0(iphone;CPU iphone OS 5_1_1 like Mac OS X) AppleWebKit/534.46(KHTML,like Geocko)Mobile/9B206 MicroMessenger/6.0.2 "
"6.0.2" is the version number of the Weixin app installed by the user. The merchant can determine if the version number is higher or equal to 6.0.2.
# 6.2 Coupon Issuance Limit
In an Official Account chat, only the coupons under the Official Account's domain name can be called. It is not allowed to push any coupon of other merchants in the Official Account chat without the permission of the platform. Otherwise, the user who receives the coupon will be prompted with a message that "Unauthorized by the coupon creator. Cannot be issued." There is no such restriction in other scenarios such as Moments and chats.
Note
Behaviors that occur in the Official Account chat and web page URLs to be redirected to from the Official Account chat are all under the Official Account chat environment.
# 6.3 Encoding Rule
The POST data of all APIs must be UTF-8 encoded. Otherwise, an error will occur.
# 6.4 Parameters Contained by External Redirect URL
To allow merchants to extend the coupon services, we support adding external redirect URL in the coupon page.
External URLs redirected to from coupons can carry parameters that indicate coupon information, allowing the developer to identify the user in the page.
Parameters include encrypt_code, card_id, openid, and outer_str (member cards only).
Note: The encrypt_code is an encrypted code, and the Redeem Coupon API should be called to get the real code. If the specified URL is http://www.qq.com, when the user taps it, the redirect URL is http://www.qq.com?encrypt_code=ENCRYPT_CODE&card_id=CARDID&openid=xxxx&outer_str=xxxxx.
# 6.5 Contact Us
For any questions regarding coupon development, contact us by emailing to weixin_card@foxmail.com, or join the Developer QQ Group (653614989 (Group 7) or 642762748 (Group 8)). Provide the merchant name and service category when requesting to join the group.
# 7 Downloading Coupon Package
Download Coupon API Package:
Creation/Signature Tool SDK
Coupon APIs Calling Workflow
New API Features
SDK for Android
SDK for iOS