1.Update Notes

From May 15, 2016, the WeChat 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 WeChat, 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 WeChat 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 WeChat 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 WeChat.

Parameter Description
card_id Coupon ID that identifies a group of same coupons. It contains a specified number of codes.
code Coupon code that uniquely identifies a coupon. It is used in coupon redemption, and can be customized by merchants.

2.2.2 Decide whether to use custom code

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

Category Use Case Creation Issuance Redemption
Custom code Merchants' existing code systems are used. "use_custom_code": true. Coupons can only be created using API. The code value is required in Coupon Issuance API. Coupons can only be redeemed using API.
Non-custom code The WeChat's code system is used in coupon issuance and redemption. "use_custom_code": false. Coupons can be created using API or via Official Accounts Platform (non-custom code is used by default) The code value is not required in coupon issuance API, and is assigned by WeChat backend. Coupons can be redeemed via "Coupon Merchant Assistant" Official Account, Official Accounts Platform, and API.
Imported codes Merchants must use their code systems, and issue coupons via WeChat channels (such as QR code, broadcast messages, and galleries) "use_custom_code": tru e. get_custom_code_mode: "GET_CUSTOM_CODE_MODE_DEPOSIT" The imported codes are issued with coupons randomly and cannot be specified. The code field is not allowed in coupon issuance API. Card_id and code are required during coupon redemption, which can only be done using API.

*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 WeChat 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 WeChat, 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.

Type Field Name Redemption Method
QR code/Barcode with numeric code CODE_TYPE_QRCODE/CODE_TYPE_BARCODE Suitable for redemption by scanning QR code/entering numeric code
QR code without numeric code CODE_TYPE_ONLY_QRCODE Suitable for redemption by scanning QR code
Only numeric code CODE_TYPE_TEXT Only applicable to redemption by entering numeric code
No code CODE_TYPE_NONE Only applicable to online redemption. You need to customize the redirect link to redirect to the H5 page, where users can redeem their coupons. The custom "cell" can be named "Use Now".

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

Type Example Fields When to display
Entry to usage page Use Now center_title, center_sub_title, center_url Only displayed when a coupon within the validity period is received by a user (for any coupon that has not become available, will be transferred to another user or has been redeemed, the entry is not displayed).
Entry to service page Online Mall custom_url_name, custom_url_sub_title, custom_url Only displayed when a coupon within the validity period is received by a user (for any coupon that will be transferred to another user or has been redeemed, the entry is not displayed).
Entry to promotional page Buy Again promotion_url_name, promotion_url_sub_title, promotion_url The entry is always displayed whether the coupon is normal, will be transferred to others or has been redeemed.

Examples of different entries:

2.3 Step 1: Upload Coupon Images

To ensure that merchants' coupon images can be loaded in users' WeChat quickly and reliably, we recommend to import the images to WeChat 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 WeChat 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 WeChat business scenarios.

API Request Format

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

Parameters

Parameter Required Description
buffer Yes Data stream for a file
access_token Yes The credential for API call

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

Parameter Description
errcode Error code
errmsg Error message
url The merchant's image URL, which is entered when the "Create Coupon" API is called. It can only be used in the relevant WeChat business scenarios, and cannot be referenced.

2.4 Step 2: Set Stores Supporting the Coupons

Please see WeChat 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 WeChat.

Background Color Value
Color010 #63b359
Color020 #2c9f67
Color030 #509fc9
Color040 #5885cf
Color050 #9062c0
Color060 #d09a45
Color070 #e4b138
Color080 #ee903c
Color081 #f08500
Color082 #a9d92d
Color090 #dd6549
Color100 #cc463d
Color101 #cf3e36
Color102 #5E6671

##2.6 Step 4: Create Coupons

The "Create Coupon" API is a basic API of WeChat 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

Parameter Required Description
access_token Yes The credential for API call
POST data Yes JSON data

POST data example


{
  "card": {
      "card_type": "GROUPON",
      "groupon": {
          "base_info": {
              "logo_url":
  "http://mmbiz.qpic.cn/mmbiz/iaL1LJM1mF9aRKPZJkmG8xXhiaHqkKSVMMWeN3hLut7X7hicFNjakmxibMLGWpXrEXB33367o7zHN0CwngnQY7zb7g/0",
              "brand_name": "WeChat 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": "WeChat 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

Parameter Required Type Example Description
card_type Yes string(24) GROUPON Group-purchase coupon type
base_info Yes JSON structure See the example above. Basic coupon data. See the table below. This field is applicable to all coupon types.
deal_detail Yes string( 3072 ) Double set menu\nA bottle of imported wine\nA helping of cumin beef Only applicable to group-purchase coupons. Group purchase details.

JSON Example

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

Cash Coupon

Parameter Required Type Example Description
card_type Yes string(24) CASH Cash coupon type
base_info Yes JSON structure See the example above. Basic coupon data (applicable to all coupons). See the table below.
least_cost Yes int 10000 Indicates the minimum purchase amount (in cents). It is only applicable to cash coupon, and defaults to 0 if no minimum purchase amount is set.
reduce_cost Yes int 10000 Indicates the coupon amount (in cents). This field is only applicable to cash coupons.

JSON Example

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

Discount Coupon

Parameter Required Type Example Description
card_type Yes string(24) DISCOUNT Discount coupon type
base_info Yes JSON structure See the example above. Basic coupon data. See the table below. This field is applicable to all coupons.
discount Yes int 30 Indicates the discount (%). This field is only applicable to discount coupons.

JSON example:

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

Exchange Coupon

Parameter Required Type Example Description
card_type Yes string(24) GIFT Exchange coupon type
base_info Yes JSON structure See the example above. Basic coupon data. This field is applicable to all coupons.
gift Yes string(3072) An exchange for a music box. Indicates the item for which the coupon can be exchanged. This field is only applicable to exchange coupons.

JSON Example

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

General Coupon

Parameter Required Type Example Description
card_type Yes string(24) GENERAL_COUPON General coupon type
base_info Yes JSON structure See the example above. Basic coupon data. See the table below. This field is applicable to all coupons.
default_detail Yes string(3072) Music box. Indicates the benefits provided by the coupon. This field is only applicable to general coupons.

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

Parameter Required Type Example Description
logo_url Yes strin g(128) http://mmbiz.qpic.cn/ Merchant logo of coupon. Recommended dimension: 300*300 pixels.
code_type Yes string(16) CODE_TYPE_TEXT Code type. CODE_TYPE_TEXT: text; CODE_TYPE_BARCODE: barcode; CODE_TYPE_QRCODE: QR code; CODE_TYPE_ONLY_QRCODE: QR code without numeric code; CODE_TYPE_ONLY_BARCODE: barcode without numeric code; CODE_TYPE_NONE: No QR code and barcode
brand_name Yes string (36) Haidilao Merchant name, with a maximum length of 12 Chinese characters (24 English characters).
title Yes string (27) 100-CNY coupon for double set menu Coupon title, with a maximum length of 9 Chinese characters (18 English characters). A combination of coupon attributes, service items and amount is recommended.
color Yes string (16) Color010 Coupon color. Enter a value between Color010 and Color100.
notice Yes string (48) Please present the QR code Coupon usage tip, with a maximum length of 16 Chinese characters (32 English characters).
description Yes string (3072) It cannot be used with other coupons. Coupon usage instructions, with a maximum length of 1024 Chinese characters (2048 English characters).
sku Yes JSON structure See example above Product information
quantity Yes int 100000 Coupon inventory. Maximum is 100,000,000.
date_info Yes JSON structure See example above. Information of coupon validity period.
type Yes string DATE_TYPE_FIX TIME_RANGE: a fixed time range; DATE_TYPE FIX_TERM: a fixed number of days (after coupon receipt). Coupon validity type. 1 and 2 used in old documents are still in effect.
begin_time stamp Yes unsigned int 14300000 Start time of validity period. This field only takes effect when type = DATE_TYPE_FIX_TIME_RANGE. It is expressed as a Unix timestamp, i.e. the number of seconds that have elapsed since 00:00:00 1/1/1970 (UTC+8).
end_time stamp Yes unsigned int 15300000 End time of validity period (in sec, UTC+8). It is recommended to set it to 23:59:59 on the end date.
fixed_term Yes int 15 Indicates the number of days during which the coupon is valid after its receipt, and only takes effect when type = DATE_TYPE_FIX_TERM. 0 is not allowed.
fixed_begin _term Yes int 0 Indicates the number of days after which the received coupon becomes valid, and only takes effect when type = DATE_TYPE_FIX_TERM. Enter 0 if the coupon becomes valid on the day of its receipt.
end_time s tamp No unsigned int 15300000 Indicates the unified expiration time of coupons and can be used for DATE_TYPE_FIX_TERM. It is recommended to set the field value to 23:59:59 on the expiration date. (UTC+8, in sec). Any coupon with a fixed_term expires when end_timestamp arrives.

base_info fields - optional fields

Parameter Required Type Example Description
use_custom_code No bool true Whether to use custom code. Enter "true" or "false". Default is "false". Generally, developers owning a coupon code system select custom codes and incorporate the codes in the coupons for issuance. For more information, see "Whether to use custom code".
get_custom_code_mode No string(32) GET_CUSTOM_COD E_MODE_DEPOSIT Fill in GET_CUSTOM_CODE_MODE_DEPOSIT to indicate that the coupons use pre-set codes. Such coupons can only be issued when the number of the imported custom codes exceeds the coupon inventory. After filling in this field, the "quantity" field must be 0. The inventory can only be increased after the codes are imported.
bind_openid No bool true Whether to specify the users to receive the coupons. Enter "true" or "false" . Default is "false". Specify this field value when you want to issue coupons to a specific group of users or prevent "coupon brushing".
service_phone No string(24) 40012234 Customer service number
location_id_list No array 1234, 2312 Poiid of store location. Obtain the value by calling the POI Store Management API. This value is required for merchants with offline stores.
use_all_locations No bool true Indicates the coupon is supported by all stores. This value is mutually exclusive with location_id_list.
center_title No string(18) Use Now The entry button centered on the top of the coupon. It is only displayed when the coupon status is normal (available for redemption).
center_sub_title No string (24) Enjoy Discount Now The words shown below the entry button. It is only displayed when the coupon status is normal (available for redemption).
center_url No string (128) www.qq.com URL centered on the top of the coupon. It is only displayed when the coupon status is normal (available for redemption).
center_app_brand_user_name No string (128) gh_86a091e50ad4@app User_name of the Mini Program to which the redirection is made from the coupon. The Mini Program must be linked to the Official Account.
center_app_brand_pass No string (128) API/cardPage Path of the Mini Program to which the redirection is made from the coupon.
custom_url_name No string (15) Use Now Title of the custom external redirect link.
custom_url No string (128) www.qq.com Custom redirect URL
custom_url_sub_title No string (18) More surprises Words shown to the right of the entry button
custom _app_brand_user_name No string (128) gh_86a091e50ad4@app User_name of the Mini Program to which the redirection is made from the coupon. The Mini Program must be linked to the Official Account.
custom _app_brand_pass No string (128) API/cardPage Path of the Mini Program to which the redirection is made from the coupon.
promotion_url_name No string (15) Product Overview Title of custom entry button to promotional page.
promotion_url No string (128) www.qq.com URL of external redirect link
promotion_url_sub_title No string (18) Big Offers! Words shown to the right of the entry button to the promotional page
promotion _app_brand_user_name No string (128) gh_86a091e50ad4@app User_name of the Mini Program to which the redirection is made from the coupon. The Mini Program must be linked to the Official Account.
promotion _app_brand_pass No string (128) API/cardPage Path of the Mini Program to which the redirection is made from the coupon.
get_limit No int 1 Maximum number of coupons that each user can claim. It defaults to 50 if left empty.
use_limit No int 100 Maximum number of coupons that each user can redeem. It defaults to 50 if left empty.
can_share No bool false Indicates whether the coupon claiming page is sharable.
can_give_friend No bool false Indicates whether the coupon is transferable.

advanced_info field

Parameter Required Type Description
advanced_info No JSON structure Advanced field specific to general coupons
use_condition No JSON structure Indicates the usage condition of a coupon. If it is left empty, "No minimum purchase amount/Available for all commodities" is indicated on the coupon, and "Using with other coupons is allowed" is displayed in the usage instructions.
accept_category No string (512) Specifies the product categories the coupon applies to. This field is only applicable to cash coupons. "Only for xxx" is shown on the coupon when this field is specified.
reject_category No string (512) Specifies the product categories the coupon does not apply to. This field is only applicable to cash coupons. "Not for xxx" is shown on the coupon when this field is specified.
least_cost No int Indicates the minimum purchase amount required to use the coupon (exchange/cash coupons). "For an order not below xx CNY" is shown on the coupon when this field is specified.
object_use_for No string (512) Indicates the product categories that need to be purchased before the exchange coupon can be used. "Available after purchase of xxx" is shown on the coupon when the field is specified.
can_use_with_other_discount No bool Indicates whether the coupon can be used with other coupons. If it is "false", "Using with other coupons is not allowed" is shown in the usage instructions. If it is "true", "Using with other coupons is allowed" is shown. Default is "true".
abstract No JSON structure Cover abstract structure name
abstract No string (24) Cover abstract description
icon_url_list No string (128) Cover image list. Only one cover image URL is allowed. Enter the image URL obtained by uploading the image with "Upload Image" API. If a non-CDN URL is entered, an error occurs. Recommended image dimension is 850*350 pixels.
text_image_list No JSON structure List of details (text and images), which are displayed in the details page. General coupon developers must pass at least one details list.
image_url No string (128) Image URL. Enter the image URL obtained by uploading the image using "Upload Image" API. Otherwise, an error occurs.
text No string (512) Details (text and image) description
business_service No arry Merchant service type: BIZ_SERVICE_DELIVER: food delivery; BIZ_SERVICE_FREE_PARK: parking lot; BIZ_SERVICE_WITH_PET: pets are allowed; BIZ_SERVICE_FREE_WIFI: Free WiFi is available. Multiple choices are allowed.
time_limit No JSON structure Time period to which the coupon usage is limited. It is composed of the following fields.
type No string (24) Enumerated values of the limit types. Supported values include MONDAY, TUESDAY, WEDNESDAY, THURSDAY, FRIDAY, SATURDAY, and SUNDAY. This field 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.
begin_hour No int Start time (hour) under the current limit type. For example, if Monday is entered for "type", and 10 is entered for this field, the coupon is available from 10:00 every Monday.
begin_minute No int Start time (minute) under the current limit type. For example, if Monday is entered for "type", 10 is entered for "begin_hour", and 59 is entered for this field, the coupon is available from 10:59 every Monday.
end_hour No int End time (hour) under the current limit type. For example, if Monday is entered for "type", and 20 is entered for this field, the coupon is available between 10:00 and 20:00 every Monday.
end_minute No int End time (minute) under the current limit type. For example, if Monday is entered for "type", 10 is entered for "begin_hour", and 59 is entered for this field, the coupon is available between 10:59 and 00:59 every Monday.

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 WeChat 6.5.8 or above supports redirecting to Mini Program from a coupon through a custom "cell". WeChat earlier than 6.5.7 supports redirecting to a webpage.

Response Description:

Example:

{   "errcode":0,   "errmsg":"ok",   "card_id":"p1Pj9jr90_SQRaVqYI239Ka1erkI"}
Parameter Description
errcode Error code. 0 indicates a successful request.
errmsg Error message
card_id Coupon ID

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 WeChat Checkout

Feature description

WeChat 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 WeChat 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 WeChat 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 WeChat 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 WeChat 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 WeChat Checkout" API

API Description

After creating the coupons, you can set the card_id to support WeChat Checkout by calling the "Set WeChat Checkout" API. Note: A store must be configured for the card_id before WeChat 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

Parameter Required Description
access_token Yes The credential for API call
POST data Yes JSON data

POST Data

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

Fields

Field Description
card_id Coupon ID
is_open Whether to enable WeChat Checkout. Enter "true" or "false".

Response Data

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

Fields

Field Description
Error code Error code. 0: normal; 43008: the merchant has not activated the permission for WeChat Pay, or has not applied for activating WeChat Checkout at the merchant backend.
errmsg Error message

Notes:

  1. The coupon for which WeChat 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 WeChat Checkout can take effect.

3.2 Payment Event

After a user makes a payment, WeChat 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>
Parameter Description
ToUserName Developer's WeChat ID
FromUserName Sender ID (OpenID)
CreateTime Creation time of message (integral)
MsgType Message type (event)
Event Event type. User_pay_from_pay_cell: A user makes a payment with WeChat Pay.
CardId Coupon ID
UserCardCode Coupon code
TransId Transaction order number generated in WeChat Pay (only applicable to the coupons redeemed with WeChat Checkout)
LocationName The name of the store where the coupon is redeemed. This field is only displayed when the coupon is redeemed via Coupon Merchant Assistant and WeChat Checkout.
Fee Amount actually paid (in cents)
OriginalFee The original amount before discount (in cents)

#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

Parameter Required Description
access_token Yes The credential for API call
POST data Yes JSON data

POST Data

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

Fields

Field Description
card_id Coupon ID
is_open Whether to enable self-redemption. Enter "true" or "false". Default is "false".
need_verify_cod Whether to enter the verification code during self-redemption. Enter "true" or "false". Default is "false".
need_remark_amount Whether to enter the redeemed amount in remarks. Enter "true" or "false". Default is "false"

Response Data

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

Fields

Field Description
Error code Error code. 0: normal; 45046: WeChat Checkout has been set for the card_id. Self-redemption is not allowed.
errmsg Error message

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.