Contents

1 Creating QR Codes

2 Issuing Coupons via HTML5 Page (JS-SDK)

3 Issuing Coupons via Gallery

3.1 Creating Gallery

4 Issuing Coupons via Broadcast Messages

4.1 Importing Custom Codes

4.2 Issuing Coupons via Article Broadcast

4.3 Issuing Coupons via Broadcast Messages by Group

4.4 Issuing Coupons via Broadcast Messages Based on OpenID List

4.5 Issuing Coupons via Customer Service Messages

4.6 Preview

5 Collecting Issuance Channel Data

6 Setting Test Whitelist

# 1 Creating QR Codes

This API is used to generate a QR code for a coupon, so that users can add the coupon to Cards & Offers by scanning the QR code.

When calling this API to create a coupon with custom code, the code should be entered in POST data, and the specified openid is also needed. The specified QR code can only be scanned for coupon receipt for once.

Developers can exchange the ticket obtained for the QR code image.

API Request Format

HTTP request method: POSTURL:https://api.weixin.qq.com/card/qrcode/create?access_token=TOKEN

Parameters

POST Data

Developers can generate a QR code to allow users to receive a single coupon. In this case, the POST data is as follows:

 {
    "action_name": "QR_CARD",
    "expire_seconds": 1800,
    "action_info": {
    "card": {
    "card_id": "pFS7Fjg8kV1IdDz01r4SQwMkuCKc",
     "code": "198374613512",
    "openid": "oFS7Fjl0WsZ9AMZqrI80nbIq8xrA",
    "is_unique_code": false ,
    "outer_str":"12b"
  }
 }
}

Developers can generate a QR code to allow users to claim multiple coupons at a time. In this case, the POST data is as follows:

{
    "action_name": "QR_MULTIPLE_CARD",
    "action_info": {
    "multiple_card": {
    "card_list": [
 {
     "card_id": "p1Pj9jgj3BcomSgtuW8B1wl-wo88",
     "code":"2392583481",
     "outer_str":"12b"
},
 {
    "card_id": "p1Pj9jgj3BcomSgtuW8B1wl-wo98",
    "code":"2392583482",
    "outer_str":"12b"
}
]
}
}
}

Parameters

Response Parameters

{
    "errcode": 0,
    "errmsg": "ok",
 "ticket":  "gQHB8DoAAAAAAAAAASxodHRwOi8vd2VpeGluLnFxLmNvbS9xL0JIV3lhX3psZmlvSDZmWGVMMTZvAAIEsNnKVQMEIAMAAA==",  //After the ticket is obtained, call the "Exchange Ticket for QR Code" API to get the QR code image. See field description for details.
    "expire_seconds": 1800,
    "url": "http://weixin.qq.com/q/BHWya_zlfioH6fXeL16o ",
    "show_qrcode_url": " https://mp.weixin.qq.com/cgi-bin/showqrcode?  ticket=gQH98DoAAAAAAAAAASxodHRwOi8vd2VpeGluLnFxLmNvbS9xL0czVzRlSWpsamlyM2plWTNKVktvAAIE6SfgVQMEgDPhAQ%3D%3D"
 }

Parameters

Notes:

1. The QR code generated for a coupon with a custom code can be used for receipt only once. To develop a code system and issue coupons using Weixin QR code, import the custom code first.

2. Enter up to 5 card_ids if you want to generate a QR code for receiving multiple coupons. Otherwise, an error occurs.

# 2 Issuing Coupons via HTML5 Page (JS-SDK)

Weixin JS-SDK can only be used in the built-in browser in Weixin.

Weixin provides the addCard API for merchants to call at front-end webpage. This API can be used to add one or more coupons to the user's Cards & Offers. See JS-SDK Documentation for details.

# 3 Issuing Coupons via Gallery

Introduction to Gallery

The gallery allows developers to call an API to generate an HTML5 page for coupon receipt and obtain the page link required to issue coupons. The gallery only supports coupons with non-custom codes. For coupons with custom codes, call the "Import Code" API before using these coupons.

# 3.1 Creating Gallery

API Description

Developers can use this API to create a gallery URL for coupon issuance. The value of channel for issuance path is required when creating a gallery.

API Request Format

HTTP request method: POST
URL:https://api.weixin.qq.com/card/landingpage/create?access_token=$TOKEN

Request parameters

POST Data

{
  
"banner":"http://mmbiz.qpic.cn/mmbiz/iaL1LJM1mF9aRKPZJkmG8xXhiaHqkKSVMMWeN3hLut7X7h
  icFN",
   "page_title": "Special offers in Huicheng",
   "can_share": true,
   "scene": "SCENE_NEAR_BY",
   "card_list": [
       {
           "card_id": "pXch-jnOlGtbuWwIO2NDftZeynRE",
           "thumb_url": "www.qq.com/a.jpg"
       },
       {
           "card_id": "pXch-jnAN-ZBoRbiwgqBZ1RV60fI",           "thumb_url": "www.qq.com/b.jpg"       }  
 ]}

Parameters

Response Data

{
     "errcode":0,
     "errmsg":"ok",
     "url":"www.test.url",
     "page_id":1 
 }

Fields

# 4 Issuing Coupons via Broadcast Messages

Note that this API is only used to issue coupons with non-custom codes. Merchants of coupons with custom codes must import custom codes to the Weixin server by calling the "Import Code" API before using this feature.

See the "use_custom_code" field to determine whether custom codes or non-custom codes are used.

# 4.1 Importing Custom Codes (for merchants of coupons with custom codes only)

API Description

This module is only applicable to merchants of coupons with custom codes. Developers can import custom codes to the Weixin server in advance to get the same issuance capacities as those of merchants of coupons with non-custom codes, including broadcasting coupons by group and issuing coupons via customer service messages.

Coupons with imported codes are equivalent to those with non-custom codes during issuance.

New coupons

To create a coupon with imported code, you can create a coupon that uses a pre-set code by following the procedure below. Otherwise, an error occurs.

Step 1: Create a coupon with a pre-set code via the "Create Coupon" API. Set the initial value of coupon inventory (quantity) to 0 and fill in the get_custom_code_mode field.

Step 2: When the coupon is approved, call the "Import Code" API and then the "Verify Code" API.

Step 3: Call the "Manage Coupons" API. The coupon inventory must be less than or equal to the number of imported code (set to the same value to avoid confusion).

Existing coupons

If you've already created a coupon and want to change it to the one that uses a pre-set code, then follow the procedure below to update the coupon.

Step 1: Call the "Import Code" API to import a certain quantity of custom codes and then call the "Verify Code" API.

Step 2: Call the "Manage Coupons" API. Fill in the get_custom_code_mode field.

Step 3: Call the * "Modify Inventory" API* . Set the coupon inventory (quantity) to be the same as the number of imported codes.

4.1.1 Entering/Updating Required Fields of Imported Codes

API Description

Coupons with custom codes can be created via API only. Be sure to add the following fields in base_info (see the CreateCard API documentation for details) before you can import codes using the "Import Code" API.

JSON example of coupon creation

{
 "card": {
     "card_type": "GROUPON",
     "groupon": {
     "base_info": {
     ··········
     "use_custom_code":true,
     "get_custom_code_mode":"GET_CUSTOM_CODE_MODE_DEPOSIT",
         },
          "advanced_info": {
      ··········
          },
         "deal_detail": "Example"
     }
   }
}

JSON example of coupon update

 {
      "card_id":"ph_gmt7cUVrlRk8swPwx7aDyF-pg",
      "groupon": { 
      "base_info": {
      ·········		            
        "get_custom_code_mode":"GET_CUSTOM_CODE_MODE_DEPOSIT",
      ·········
              }
        }
 }

Note:

When filling in the get_custom_code_mode field during creation/update, ensure that the coupon inventory is less than or equal to the number of imported codes. Otherwise, an error occurs.

4.1.2 Importing Code

After the coupons with custom codes are created and approved, call the "Import Code" API to import the custom codes to the Weixin backend according to the quantity as agreed with the coupon issuer.

API Description

Custom codes can be imported to the Weixin backend via this API, and then stored and issued by Weixin.

Notes: (1) The number of codes imported at a time via this API is 100.

(2) Do not use an empty string for each code.

(3) After the codes are imported, the system will automatically determine whether the coupon inventory set by the provider is the same as the actual number of imported codes.

(4) If the import failed, you can make another attempt until the codes are imported successfully.

API Request Format

HTTP request method: POST URL: http://api.weixin.qq.com/card/code/deposit?access_token=ACCESS_TOKEN

Request parameters

POST Data

{
     "card_id": "pDF3iY0_dVjb_Pua96MMewA96qvA",
    "code": [
       "11111",
       "22222",
       "33333",
       "44444",
       "55555"
   ]
}

Fields

Response Data

{
  "errcode":0,
  "errmsg":"ok"
 }

Fields

4.1.3 Querying the Number of Imported Codes

API Description

This API is used to query the number of codes that are successfully imported to the Weixin backend.

API Request Format

HTTP request method: POST URL: http://api.weixin.qq.com/card/code/getdepositcount?access_token=ACCESS_TOKEN

Request parameters

POST Data

{
    "card_id" : " pDF3iY0_dVjb_Pua96MMewA96qvA "
}

Fields

Response Data

{
  "errcode":0,
  "errmsg":"ok",
  "count":123
}

Fields

4.1.4 Verifying Code

To avoid errors during the import operation, we strongly recommend that developers verify the codes imported in the Weixin backend by calling the "Verify Code" API after querying the number of imported codes.

API Description

This API is used to check the codes that are imported to the Weixin backend.

API Request Format

HTTP request method: POST URL: http://api.weixin.qq.com/card/code/checkcode?access_token=ACCESS_TOKEN

Request parameters

POST Data

{
    "card_id": "pDF3iY0_dVjb_Pua96MMewA96qvA",
    "code": [
       "11111",
       "22222",
       "33333",
       "44444",
       "55555"
   ]
}

Fields

Response Data

{
    "errcode":0,
    "errmsg":"ok"
    "exist_code":["11111","22222","33333"],
    "not_exist_code":["44444","55555"]
}

Fields

# 4.2 Issuing Coupons via Article Broadcast

This API is used to get the code of the standard format that coupons are subject to when they are inserted into articles, and enter the returned code into The content field of the "Add Temporary Asset" API to get the article assets of inserted coupons.

Note: This API is only applicable to coupons with non-custom codes. For coupons with custom codes, the custom codes should be imported before this API can be called.

API Request Format

HTTP request method: POSTURL:https://api.weixin.qq.com/card/mpnews/gethtml?access_token=TOKEN

Parameters

POST Data

{  "card_id":"p1Pj9jr90_SQRaVqYI239Ka1erkI"}

Response Data

{
    "errcode":0,
    "errmsg":"ok",
    "content":"<iframeclass=\"res_iframecard_iframejs_editor_card\"data-src=\"http: \/\/mp.weixin.qq.com\/bizmall\/appmsgcard?action=show&biz=MjM5OTAwODk4MA%3D%3D&cardid=p1Pj9jnXTLf2nF7lccYScFUYqJ0&wechat_card_js=1#wechat_redirect\">"
}

# 4.3 Issuing Coupons via Broadcast Messages by Group

This API is used to issuing coupons via broadcast messages to the specific group of users. See Homepage for details.

This API is only applicable to coupons with non-custom codes. For coupons with custom codes, the custom codes should be imported before this API can be called.

# 4.4 Issuing Coupons via Broadcast Messages Based on OpenID List

This API is used to issue native coupons via broadcast messages based on OpenID. This API is not applicable to Subscription Accounts and applicable to verified Service Accounts. For details, see Issuing Coupons via Broadcast Messages Based on OpenID List.

This API is only applicable to coupons with non-custom codes. For coupons with custom codes, the custom codes should be imported before this API can be called.

# 4.5 Issuing Coupons via Customer Service Messages

This API is used to issue coupons. This API is not applicable to Subscription Accounts and applicable to verified Service Accounts. For details, see Customer Service Messages.

This API is only applicable to coupons with non-custom codes. For coupons with custom codes, the custom codes should be imported before this API can be called.

# 4.6 Preview

This API is used to issue coupons. This API is not applicable to Subscription Accounts and applicable to verified Service Accounts. For details, see

Homepage.

# 5 Collecting Issuance Channel Data

The outer_str (originally the outer_id) field is added to help developers collect statistics about coupon issuance data of each channel. After different values of outer_str (originally the outer_id) are entered in the JSON structure of card_ext, when users claim coupons, the corresponding values of outer_str are passed into the Coupon-related Events, which are pushed to the developer server.

Example: Set outer_str to 12b in the QR code issuance mode.

{
    "action_name": "QR_CARD",
    "action_info": {
    "card": {
    "card_id": "pFS7Fjg8kV1IdDz01r4SQwMkuCKc",
    "code": "198374613512",
    "openid": "oFS7Fjl0WsZ9AMZqrI80nbIq8xrA",
    "expire_seconds": "1800",
    "is_unique_code": false ,
    "outer_str" : "12b"
  }
 }
}

Get the event XML file

<xml> 
  <ToUserName><![CDATA[toUser]]></ToUserName>  
  <FromUserName><![CDATA[FromUser]]></FromUserName>  
  <FriendUserName><![CDATA[FriendUser]]></FriendUserName>  
  <CreateTime>123456789</CreateTime>  
  <MsgType><![CDATA[event]]></MsgType>  
  <Event><![CDATA[user_get_card]]></Event>  
  <CardId><![CDATA[cardid]]></CardId>  
  <IsGiveByFriend>1</IsGiveByFriend>  
  <UserCardCode><![CDATA[12312312]]></UserCardCode>  
  <OuterStr>12b</OuterStr> 
</xml>

# 6 Setting Test Whitelist

API Description

Coupons must be submitted for review. Therefore, to help Official Accounts debug coupons, test accounts can be set to allow users claim unapproved coupons for trial use.

Notes

1. Both "openid" and "username" can be used to set a whitelist. The maximum number of users in the whitelist is 10.

2. If there is any change to the test whitelist, IDs of all testers must be passed again with this API.

3. Note that the invalidation status of a coupon will be ignored when a user in the whitelist receives the coupon.

API Request Format

HTTP request method: POSTURL:https://api.weixin.qq.com/card/testwhitelist/set?access_token=TOKEN

Parameters

POST Data

{
    "openid": [
      "o1Pj9jmZvwSyyyyyyBa4aULW2mA",
       "o1Pj9jmZvxxxxxxxxxULW2mA"
    ],
    "username": [
      "afdvvf",
      "abcd"
     ]
 }

Parameters

Response Description

{   "errcode":0,   "errmsg":"ok"}