• 1 Update Notes
• 2 Creating Coupons
• 2.1 API Workflow
• 2.2 API Instructions
• 2.3 Step 1: Upload Coupon Images
• 2.3.1 "Upload Images" API
• 2.4 Step 2: Set Stores Supporting the Coupons
• 2.5 Step 3: Select Coupon Background Color
• 2.6 Step 4: Select Coupon Type and Create Coupon
• 2.7 Coupon Basic Info Fields (Important)
• 2.8 Parameters Contained by External Redirect URL
• 3. Setting Weixin Checkout
• 3.1 "Set Weixin Checkout" API
• 3.2 Payment Event
• 4. Setting Self-Redemption
• 4.1 Setting Self-Redemption
• 5 API Debugging Tool

# 1.Update Notes

From May 15, 2016, the Weixin Coupons/Cards Team started to upgrade the member card capabilities to help merchants better manage their members.

-The primary entries to member cards were optimized on Weixin, so that members can locate the cards quickly in stores.

-Different card backgrounds can be customized based on membership levels.

-By scanning code in stores, new users can receive cards and existing users can open cards quickly to enjoy such features as ordering meals and making purchases.

-Issue membership invitation messages to users immediately after they make payments using Weixin to enroll new members quickly.

-New member card categories are added. As of April 20, 2016, only the merchants who provide products and services falling under the supported member card categories can create member cards. The existing member cards are not affected. For more information, please see"Update of Supported Weixin Member Card Categories"

# 2 Creating Coupons

# 2.1 API Workflow

# 2.2 API Instructions

The following are the considerations that must be taken into account before creation of coupons/cards.

2.2.1 Difference between Coupon ID and Code

A coupon ID identifies a group of same coupons and contains specified number of codes.

For example, when a CNY-50 coupon group of 1 million coupons is created, a coupon ID (card_id) is generated for the group, with a coupon inventory of 1 million.

When Customer A receives a CNY-50 coupon from the merchant, the customer gets a code, the unique identifier on the coupon. If all the coupons are claimed, 1 million different codes are issued to customers by Weixin.

2.2.2 Decide whether to use custom code

Weixin's coupon codes are randomly assigned by the Weixin backend. Merchants can also use custom codes. The differences between the two are as follows:

*Note: If you're a developer of coupons with custom codes and want to be able to issue coupons via broadcast messages or customer service messages as the merchants of non-custom coupons do, please import non-custom codes to the Weixin server using the "Import Custom Codes" API.*Importing codes is not required if the coupons are only issued on H5 pages. The imported codes are issued randomly by Weixin, and cannot be specified.

2.2.3 Select a right code type

Merchants can select the appropriate coupon code type based on the business model and the supported redemption methods, and fill in the code_type field when creating coupons.

Example: If Merchant A selects QR code-based coupons, the redemption processor of the merchant can redeem coupons by scanning the QR code using Mobile Merchant Assistant; if Merchant B selects "Only numeric code",

the redemption processor can redeem coupons by entering the numeric codes.

2.2.4 Record users' coupon receipt behaviors

Users' coupon receipt behaviors can be recorded in many ways:

1. After a user receives a coupon, an event is pushed to the developer. The coupon receipt event includes the coupon ID, code, the recipient's OpenID, and the transferor's OpenID. Coupon redemption event is also pushed to the developer. For more information, please see Coupon-Related Event Notifications.

2. Get the code status (whether the coupon has been received, redeemed or deleted) by calling the "Query Code" API. If the code has been received by a user and is valid, you can obtain the recipient's OpenID.

3. When a redirection from the coupon details page to an external link occurs, the coupon ID, code and other information are automatically passed by the Weixin backend. For more information, please see Parameters Contained by External Redirect Link.

4. Add the channel field outer_str in the coupon issuance API. The field value will be notified to merchant with the coupon receipt event.

Example: If you set outer_str to 1 when creating QR code-based coupons, and set it to 2 when adding coupon JS-SDK, you can analyze the coupon receipt results of different channels to adjust the coupon issuance strategies as early as possible.

2.2.5 Use custom entries

In order to meet the needs of merchants for feature expansion, two new custom entries in coupons are added to allow customers to directly enter merchants' custom HTML5 webpages.

The differences between the three custom entries are as follows:

Examples of different entries:

# 2.3 Step 1: Upload Coupon Images

To ensure that merchants' coupon images can be loaded in users' Weixin quickly and reliably, we recommend to import the images to Weixin CDN first by calling the relevant API.

# 2.3.1 "Upload Images" API

You need to call this API to upload the merchant's icons to the Weixin server, and obtain the logo_url/icon_list/image_url for creating coupons.

Notes

1. The image for upload cannot be larger than 1 MB, and can only be JPG and PNG files.

2. The image URL obtained by calling the API can only be used in the relevant Weixin business scenarios.

API Request Format

HTTP request method: POST/FROMURL:https://api.weixin.qq.com/cgi-bin/media/uploadimg?access_token=ACCESS_TOKEN

Parameters

Request data

Request example (upload an image using a form with the curl command FORM:curlFbuffer=@test.jpg

Response Data

Response for a successful request: {"url":"http://mmbiz.qpic.cn/mmbiz/iaL1LJM1mF9aRKPZJkmG8xXhiaHqkKSVMMWeN3hLut7X7hicFNjakmxibMLGWpXrEXB33367o7zHN0CwngnQY7zb7g/0"}Response for a failed request:{"errcode":40009,"errmsg":"invalid image size"}

Parameters

# 2.4 Step 2: Set Stores Supporting the Coupons

Please see Weixin Store API Documentation. Populate the field location_id_list in the "Create Coupon" API with the obtained store IDs to set the stores supporting the coupons.

# 2.5 Step 3: Select Coupon Background Color

Select the appropriate color. Enter the color value (e.g. Color010) in the color field when creating the coupon in Step 4.

The above 10 color values (a total of 14 tones) are available in Weixin.

##2.6 Step 4: Create Coupons

The "Create Coupon" API is a basic API of Weixin Coupons feature, and is used to create a new group of same coupons and obtain the card_id. After the coupons are created and approved, the merchant can issue the coupons to users using other APIs described in the document. The coupon inventory balance is decreased with each receipt of the coupons by users.

Notes

1. For a merchant who wants to use custom code, use_custom_code must be set to "true" during the coupon creation, and the specified code should be entered when the coupon issuance API is called. The specified OpenID is also needed. All coupons created on Official Accounts Platform have a non-custom code.

2. The field can_share indicates whether the native page of coupons can be shared. It is recommended to set it to "false" for the coupons with specified code and OpenID.

3. Only UTF-8 encoding is supported.

4. After being created, the coupons are automatically submitted for approval. The result will be notified to the merchant via an event. Developer can call "Set Whitelist" API to set a user whitelist and test the usage process of the rejected coupon by having the whitelist users receive the coupon.

API Request Format

HTTPRequest method: POSTURL: https://api.weixin.qq.com/card/create?access_token=ACCESS_TOKEN

Parameters

POST data example

{
  "card": {
      "card_type": "GROUPON",
      "groupon": {
          "base_info": {
              "logo_url":
  "http://mmbiz.qpic.cn/mmbiz/iaL1LJM1mF9aRKPZJkmG8xXhiaHqkKSVMMWeN3hLut7X7hicFNjakmxibMLGWpXrEXB33367o7zHN0CwngnQY7zb7g/0",
              "brand_name": "Weixin Restaurant",
              "code_type": "CODE_TYPE_TEXT",
              "title": "132 CNY Hotpot for Two Persons",
              "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_TIME_RANGE",
                  "begin_timestamp": 1397577600,
                  "end_timestamp": 1472724261
              },
              "sku": {
                  "quantity": 500000
              },
              "use_limit":100,
              "get_limit": 3,
              "use_custom_code": false,
              "bind_openid": false,
              "can_share": true,
              "can_give_friend": true,
              "location_id_list": [
                  123,
                  12321,
                  345345
              ],
              "center_title": "Centered button at the top",
              "center_sub_title": "Words under the button
              "center_url": "www.qq.com",
              "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",
              "source": "dianping.com"
          },
           "advanced_info": {
               "use_condition": {
                   "accept_category": "Shoes",
                   "reject_category": "Adidas",
                   "can_use_with_other_discount": true
               },
               "abstract": {
                   "abstract": "Weixin Restaurant introduces a variety of new dishes. We look forward to your visit!",
                   "icon_url_list": [
                       "http://mmbiz.qpic.cn/mmbiz/p98FjXy8LacgHxp3sJ3vn97bGLz0ib0Sfz1bjiaoOYA027iasqSG0sj
  piby4vce3AtaPu6cIhBHkt6IjlkY9YnDsfw/0"
                   ]
               },
               "text_image_list": [
                   {
                       "image_url": "http://mmbiz.qpic.cn/mmbiz/p98FjXy8LacgHxp3sJ3vn97bGLz0ib0Sfz1bjiaoOYA027iasqSG0sjpiby4vce3AtaPu6cIhBHkt6IjlkY9YnDsfw/0",
                       "text": "This dish is cooked in a unique way with selective ingredients to tickle the taste buds of diners to the greatest extent."
                   },
                   {
                       "image_url": "http://mmbiz.qpic.cn/mmbiz/p98FjXy8LacgHxp3sJ3vn97bGLz0ib0Sfz1bjiaoOYA027iasqSG0sj piby4vce3AtaPu6cIhBHkt6IjlkY9YnDsfw/0",
                       "text": "This dish offers balanced nutrition to cater for the taste of everyone at all ages."
                   }
               ],
               "time_limit": [
                   {
                       "type": "MONDAY",
                       "begin_hour":0,
                       "end_hour":10,
                       "begin_minute":10,
                       "end_minute":59
                   },
                   {
                       "type": "HOLIDAY"
                   }
               ],
               "business_service": [
                   "BIZ_SERVICE_FREE_WIFI",
                   "BIZ_SERVICE_WITH_PET",
                   "BIZ_SERVICE_FREE_PARK",
                   "BIZ_SERVICE_DELIVER"
               ]
           },
          "deal_detail":" Select a soup base from the following options: mushroom soup, spicy soup, bone soup, tomato soup, nourishing soup, pickled fish soup: \n 1 Big Pot: 12 CNY; 2 Small Pots: 16 CNY.
      }
  }}

The fields are illustrated in the following figure:

Group-Purchase Coupon

JSON Example

{
 "card": {
     "card_type": "GROUPON",
     "groupon": {
         "base_info": {
         ················
         },
          "advanced_info": {
         ················
          },
         "deal_detail": "Example"
     }
 }
}

Cash Coupon

JSON Example

{
 "card": {
     "card_type": "CASH",
     "cash": {
         "base_info": {
         ················
         },
          "advanced_info": {
         ················
          },
         "least_cost": 1000,
         "reduce_cost": 100,
     }
 }
}

Discount Coupon

JSON example:

{
 "card": {
     "card_type": "DISCOUNT",
     "discount": {
         "base_info": {
         ················
         },
          "advanced_info": {
         ················
          },
         "discount": 30
     }
   }
}

Exchange Coupon

JSON Example

{
"card": {
    "card_type": "GIFT",
    "gift": {
        "base_info": {
        ················
        },
         "advanced_info": {
        ················
         },
        "gift":"An exchange for a music box"
    }
  }
}

General Coupon

JSON Example

{
"card": {
    "card_type": "GENERAL_COUPON",
    "general_coupon": {
        "base_info": {
        ················
        },
         "advanced_info": {
        ················
         },
        " Yes |"default_detail":" Indicates the benefits provided by the coupon. This field is only applicable to general coupons. |
    }
  }
}

# 2.7. Coupon Basic Info Fields (Important)

base_info fields - required fields

base_info fields - optional fields

advanced_info field

Notes:

1. Advanced fields are additional information fields for the merchant and are optional. But for some structured fields, all components must be entered before the structured fields can be displayed. For example, if a value is entered in the structured field text_image_list,

*both image_url and text must be entered. Otherwise, an error occurs. 2. The field "time_limit" only specifies whether the time period limit is displayed, instead of the usage logic. If it is left empty, no time period limit is displayed *

3. When creating coupons, you must specify a time stamp earlier than January 19, 2038.

4. For coupons with pre-set codes, "quantity" must be set to 0. The coupon inventory can only be increased after the codes are imported.

5. Only Weixin 6.5.8 or above supports redirecting to Mini Program from a coupon through a custom "cell". Weixin earlier than 6.5.7 supports redirecting to a webpage.

Response Description:

Example:

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

# 2.8 Parameters Contained by External Redirect URL

To allow merchants to extend the coupon services, we support adding an external redirect URL in the coupon page, with the fields encrypt_code and card_id.

Note: encrypt_code is an encrypted code, which needs to be decoded to a real code with Decoding API. If the specified URL is http://www.qq.com, when a user taps the URL, the redirect URL is: http://www.qq.com?encrypt_code=ENCRYPT_CODE&card_id=CARDID.

# 3 Setting Weixin Checkout

Feature description

Weixin Checkout is a new feature that allows consumers to enjoy the benefits provided by coupons automatically by entering the purchase amount and making payment using WeChat Pay.

With Weixin Checkout, merchants can:

1. Generate orders and connect to WeChat Pay without the need of having development capability for WeChat Pay.

2. Receive money, check redemption records, reconcile transaction accounts, and download files offline via Official Accounts on mobile phones, or merchant backends on PCs.

3. Realize membership marketing and second marketing, such as giving points for a transaction via membership card, redeeming points, and giving coupons after payment.

Activating Weixin Checkout

Step 1: After applying for the permission to activate whitelist, log in to the Official Accounts Platform (mp.weixin.qq.com) to go to Cards & Offers > Overview, and click to view the details and permissions.

Step 2: In the advanced permission area, there is a permission status for Weixin Checkout. You need to activate WeChat Pay and configure the redemption processors for the store before you can apply for activating the permission. If you do not have the permission, click Apply to activate the permission for Weixin Checkout.

Step 3: Configure cashiers for the store or directly click Redeem Coupon to add redemption processors for the store, so that you can receive the transaction settlement notifications later.

# 3.1 "Set Weixin Checkout" API

API Description

After creating the coupons, you can set the card_id to support Weixin Checkout by calling the "Set Weixin Checkout" API. Note: A store must be configured for the card_id before Weixin Checkout can be set. Otherwise, an error occurs.

API Request Format

HTTPRequest method: POSTURL:https://api.weixin.qq.com/card/paycell/set?access_token=TOKEN

Parameters

POST Data

{  "card_id":"ph_gmt7cUVrlRk8swPwx7aDyF-pg",  "is_open": true}

Fields

Response Data

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

Fields

Notes:

1. The coupon for which Weixin Checkout is set must be supported by at least one store with a redemption processor. Otherwise, the setting is not successful.

2. If center_url (a redirect link is used in the centered button) has been set for the coupon, the field must be changed to an empty value before Weixin Checkout can take effect.

# 3.2 Payment Event

After a user makes a payment, Weixin pushes the event to the URL entered by the developer. The following is an example of XML packet for push:

<xml>
<ToUserName>< ![CDATA[gh_e2243xxxxxxx] ]></ToUserName>
<FromUserName>< ![CDATA[oo2VNuOUuZGMxxxxxxxx] ]></FromUserName>
<CreateTime>1442390947</CreateTime>
<MsgType>< ![CDATA[event] ]></MsgType>
<Event>< ![CDATA[user_pay_from_pay_cell] ]></Event>
<CardId>< ![CDATA[po2VNuCuRo-8sxxxxxxxxxxx] ]></CardId>
<UserCardCode>< ![CDATA[38050000000] ]></UserCardCode>
<TransId>< ![CDATA[10022403432015000000000] ]></TransId>
<LocationId>291710000</LocationId>
<Fee>< ![CDATA[10000] ]></Fee>
<OriginalFee>< ![CDATA[10000] ]> </OriginalFee>
</xml>

#4 Setting Self-Redemption

Feature description

Coupon redemption via Coupon Merchant Assistant ensures authenticity of coupons by involving code scanning/entering, and is suitable for merchants having higher requirement for account reconciliation. Self-redemption is initiated and operated by users and is suitable for merchants having lower requirement for account reconciliation.

Self-redemption is ideal for the following scenarios:

1. Store clerks are not allowed to carry a mobile phone during work.

2. During peak hours, the redemption via code scanning/entering is not fast enough to handle a large visitor traffic.

3. A huge workload of redemption is required within a short period for entry management during events such as a conference.

##4.1 Setting Self-Redemption

API Description

After creating coupons, you can set the card_id to support self-redemption by calling the "Set Self-Redemption" API. Note: A store must be configured for the card_id before the self-redemption can be set. Otherwise, an error occurs.

API Request Format

HTTPRequest method: POSTURL:https://api.weixin.qq.com/card/selfconsumecell/set?access_token=TOKEN

Parameters

POST Data

{  "card_id":"ph_gmt7cUVrlRk8swPwx7aDyF-pg",  "is_open": true}

Fields

Response Data

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

Fields

Note:

1. The coupon for which self-redemption is set must be supported by at least one store. Otherwise, the setting is not successful.

2. If center_url (a redirect link is used in the centered button) has been set for the coupon, the field must be changed to an empty value before self-redemption can take effect.

#5 API Debugging Tool

You can create a coupon HelloWorld using the online debugging tool for the "Create Coupon" API. After obtaining the access_token, paste the JSON data to be passed via POST request method in the debugging tool to get the card_id for issuing the coupon.