1 Instructions

2 Applying for a Sandbox Test Account

3 HelloWorld

4 Overview of Coupon APIs

5 Coupon-related Parameters

6 Notes

6.1 Applicable Weixin Versions

6.2 Coupon Issuance Limits

6.3 Encoding Rules

6.4 Parameters Contained by the External Redirect URL

6.5 Contact Us

7 Downloading Coupon Packages

# 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:

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:

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:

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": " ibMLGWpXrEXB33367o7zHN0CwngnQY7zb7g/0",
          "brand_name":"Weixin Restaurant",
          "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": "",
          "custom_url_sub_title": "6 Chinese characterstips",
          "promotion_url_name": "More discounts",
        "promotion_url": ""
      "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:

API Type: Coupon APIs

API List: "Create QR Code Ticket" API

access_token: The one obtained in Step 1

JSON example:

 "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:

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:

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.


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, when the user taps it, the redirect URL is

# 6.5 Contact Us

For any questions regarding coupon development, contact us by emailing to, 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