# Creating Friend's Vouchers

# 1 Style of Friend's Vouchers

Big changes have been made to the style of Friend's Vouchers. The vouchers have a neat and eye-catching design with more striking background, with merchants' elements highlighted more clearly. Text description and images can be inserted to give the merchants more exposure.

# 2 API Instructions

Before developing vouchers, you need to create vouchers. Generate a card_id by entering the voucher content, and then issue and redeem the vouchers upon approval. The following must be considered before the creation of vouchers.

# 2.1 Selecting a Right Threshold Type

Friend's Voucher supports both threshold-independent and threshold-dependent vouchers. Details and Voucher Title fields will be constructed automatically based on the threshold types entered by merchants. You can chose the best combination of threshold types to maximize the campaign effect.

Entering the threshold field as specified will ensure that the vouchers are approved quickly. Any vouchers with a threshold type other than the following types will be rejected.

In addition, Weixin backend sets different inventory prices for vouchers with different thresholds. The pricing criteria are as follows:

   (1) Threshold-independent vouchers: 0.2 tokens per voucher.
 (2) Vouchers with "Applicable to" and "/Minimum Purchase Amount" specified: 0.4 tokens per voucher; vouchers with only "Using with other vouchers is not allowed" selected: 0.2 tokens per voucher.

Fields for Different Threshold Types

Weixin backend determines the style and display of vouchers according to different threshold fields entered by developers. In the following table, we use a 50-CNY price-reduction voucher and an egg tart exchange voucher as examples to describe different display logic based on different thresholds.

Notes:

1. Threshold field is used to join the title and voucher description, and affects the merchant's pricing for the voucher inventory. Enter the fields as required and preview the generated vouchers.

2. The threshold field cannot be changed once set. Therefore, enter it carefully and preview the results in time.

3. When both least_cost and accept_category are specified, the values are joined like this: "50 CNY off 500 CNY for down jackets[TH1]" (the value of accept_catagory contains 5 Chinese characters at most), and "50 CNY off 500 CNY" (the value of accept_catagory contains more than 5 Chinese characters).

# 2.2 Selecting an Appropriate Code Display Type

The codes of vouchers can be displayed in five modes: QR code with numeric code, QR code without numeric code, barcode with numeric code, barcode without numeric code, only numeric code, and no code (for vouchers only).

The redemption methods vary with code display types. Vouchers that are displayed as QR code and barcode can be redeemed by scanning the code. Vouchers that are displayed as code only are redeemed by entering the code. Those without code can be used only for online purchases and must be redeemed via a custom page developed by the merchant.

Developers must pass in different code_type parameters for different code display types during voucher creation.

# 2.3 Recording Users' Voucher Receipt Behaviors

There are multiple ways to record users' voucher receipt behaviors:

1. After a user receives a voucher, an event is pushed to the developer. The voucher receipt event includes the voucher ID, code, the recipient's OpenID. Voucher redemption event is also pushed to the developer. For more information, see Voucher-Related Event Push.

2. Get the code status by calling the "Query Code" API to check whether the voucher is receipt, redeemed, or deleted. 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 voucher details page to an external link occurs, the voucher ID, code and other information are automatically passed by the Weixin backend. For details, see Parameters Contained by External Redirect URL.

# 2.4 Using Custom Entries

In order to meet the needs of merchants for feature expansion, three new custom entries in vouchers are added to allow customer to directly go to merchants' custom URLs.

The differences between the three custom entries are as follows:

# 3 API Calling Process

To create Friend's Vouchers, strictly follow the following API calling process to call appropriate APIs.

Developers must call the following APIs according to the preceding process.

# 4 API Details

# 4.1 Uploading Images

See the "Upload Images" API. You need to call this API to upload merchant's logo to the Weixin server, and obtain the logo_url for creating vouchers.

Notes:

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

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

3. Only image URL returned by the Weixin server can be uploaded. Otherwise, an error occurs.

# 4.2 Weixin Store API

See the Weixin Store API Documentation. Populate the field location_id_list in the "Create Voucher" API with the obtained store IDs to set the stores supporting the voucher.

# 4.3 Selecting Voucher Background Color

See the documentation for the "Select Voucher Background Color" API. Select the appropriate color value to make the voucher more distinct. Enter the color value (e.g. Color010) in the color filed when creating the voucher in the following step.

# 4.4 Creating Friend's Vouchers

This API is the most important of all creation APIs.

Friend's Vouchers are advanced vouchers that are derived from native vouchers. Different from other vouchers, Friend's Vouchers are displayed with promotion details that contain text description and images by using the advanced_info field, making service and product abstract information prominent.

API Description

Developers need to call this API to create Friend's Vouchers, and enter the merchant information, logo, stores, and related discount and usage fields. After a voucher is created, the card ID is obtained for voucher issuance.

API Request Format

HTTP request method: POST https://api.weixin.qq.com/card/create?access_token=ACCESS_TOKEN

Parameters

Example of POST data of a price-reduction voucher

{
    "card": {
        "card_type": "CASH",
        "cash": {
            "base_info": {
                "logo_url": "http://mmbiz.qpic.cn/mmbiz/iaL1LJM1mF9aRKPZJkmG8xXhiaHqkKSVMMWeN3hLut7X7hicFNjakmx ibMLGWpXrEXB33367o7zHN0CwngnQY7zb7g/0",
                "brand_name": "Weixin Restaurant",
                "code_type": "CODE_TYPE_TEXT",
                "color": "Color010",
                "service_phone": "020-88888888",
                "description": "Using with other vouchers is not allowed. Ask the merchant for an invoice for the group purchase during check-out.",
                "date_info": {
                    "type": "DATE_TYPE_FIX_TIME_RANGE",
                    "begin_timestamp": 1447397802,
                    "end_timestamp": 1449893532
                },
                "can_share": false,
                "can_give_friend": false,
                "location_id_list": [
                    272981040,
                    400183234
                ],
                "use_limit":50,
                "get_limit": 3,
                "center_title": "Quick redemption",
                "center_sub_title": "",
                "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"
            },
            "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"
                ],
                "consume_share_self_num": 1,
                "consume_share_card_list": [],
                "share_friends": true
            },
            "reduce_cost": 10
        }
    }}

Example of POST data of an exchange voucher

{
    "card": {
        "card_type": "GIFT",
        "gift": {
            "base_info": {
                ...
            },
            "advanced_info": {
                ...
            },
            "gift_name": "Apple",
            "gift_num": 1,
            "gift_unit": "gift(s)": "Get one apple"
        }
    }}

JSON structure of a Friend's Voucher

The settings of the preceding fields (except for the base_info field) are the same for price-reduction vouchers and exchange vouchers. Therefore, the JSON structure of the exchange voucher is not shown.

Voucher info fields

base_info field

advanced_info field

The use_condition field is added. For price-reduction vouchers, this field can be used with the least_cost field (valid with minimum purchase), the accept_category or reject_category field (valid/invalid for specific categories), or the can_use_with_other_discount field (using with other vouchers is not allowed).

For exchange vouchers, this field can be used with the least_cost field (valid with minimum purchase), the object_use_for field (valid after purchase), or the can_use_with_other_discount field (using with other vouchers is not allowed).

Notes:

1.1. Threshold field is used to join the title and voucher description on the voucher page. Ensure the fields are entered as required to avoid errors.

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.

Response Data

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

Fields

# 4.5 Pushing Approval Event

When a created voucher is approved, Weixin pushes this event to the URL entered by the developer. For details, see Voucher-Related Event Push.

# 4.6 Setting Weixin Checkout for Friend's Vouchers

Similar to common vouchers, Friend's Vouchers also support Weixin Checkout. A merchant who has activated WeChat Pay can enable Weixin Checkout for Friend's Vouchers by calling the "Set Weixin Checkout" API, thereby facilitating money receiving.

# 5 Help

# 5.1 Error Codes

For more error codes, see Common Error Codes.

# 5.2 FAQs

1. Why can't I add Friend's Vouchers to the inventory during creation?

The inventory mechanism for Friend's Vouchers is different from that for other vouchers. Developers must create Friend's Vouchers and then top up the inventory using tokens on MP (merchant backend).

2. Why is a Friend's Voucher effective for only three months?

Different from other vouchers, Friend's Vouchers are time-sensitive and flexible. To ensure the voucher list is updated in real time, each merchant is required to create vouchers that are effective for a maximum of three months (90 days).

3. Can tokens be refunded when a voucher expired?

If there are vouchers with the card_id available in the inventory when they expired, the inventory will be converted into tokens and refunded to the merchant's account in T+1 days (i.e. on the next day).