# Friend's Vouchers Management APIs

# Updating Information on Friend's Vouchers

API Description

After creating a Friend's Voucher, the developer can call this API to change the voucher's information. Note that the code needs to be submitted for review again after fields are modified.

Notes

  1. When some fields of a voucher are modified, the code will be resubmitted for review. For the specific fields, see the field description. After the voucher is updated, you can call the "View Voucher Details" API to check the update results.

  2. Enter the to-be-updated fields only. If fields that cannot be modified, such as brandname, are entered when the API is called, the update will fail.

  3. If you update the voucher information by calling this API, call the "View Voucher Details" API to verify whether the update is successful.

API Request Format

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

Parameters

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

Example of POST data

{
    "card_id": "pbLatjgOY1_Cxi3mnWBThtG90HGg",
    "cash": {
        "base_info": {
            "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.",
            "can_share": false,
            "can_give_friend": false,
            "location_id_list": [
                272981040,
                400183234
            ],
            "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": {
            "time_limit": [
                {
                    "type": "MONDAY"
                },
                {
                    "type": "HOLIDAY"
                }
            ],
            "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/p98FjXy8LacgHxp3sJ3vn97bGLz0ib0Sfz1bjiaoOYA027iasqSG0sjpiby4vce3AtaPu6cIhBHkt6IjlkY9YnDsfw/0",
                    "text": "This dish offers balanced nutrition to cater for the taste of everyone at all ages."
                }
            ],
            "business_service": [
                "BIZ_SERVICE_FREE_WIFI",
                "BIZ_SERVICE_WITH_PET",
                "BIZ_SERVICE_FREE_PARK",
                "BIZ_SERVICE_DELIVER"
            ],
            "consume_share_card_list": [
                {
                    "card_id": "pbLatjpvp0Xq6jtgRRxCKtudkBz8k",
                    "num": 1
                }
            ],
            "consume_share_self_num": 0,
            "abstract": {
                "abstract": "Weixin Restaurant introduces a variety of new dishes. We look forward to your visit!",
                "icon_url_list": [
                    "http://mmbiz.qpic.cn/mmbiz/p98FjXy8LacgHxp3sJ3vn97bGLz0ib0Sfz1bjiaoOYA027iasqSG0sjpiby4vce3AtaPu6cIhBHkt6IjlkY9YnDsfw/0"
                ]
            }
        }
    }
}

Fields

base_info field:

Parameter Review Required Type Example Description
base_info - JSON structure Voucher basic information field
logo_url Yes string(128) http://mmbiz.qpic.cn/ The merchant's logo on the voucher. The recommended resolution is 300*300 pixels.
notice Yes string (48) Present the QR code for coupon redemption Coupon usage tip, with a maximum length of 16 Chinese characters (32 English characters).
description Yes string (3072) Using with other vouchers is not allowed\nAsk the merchant for an invoice for the group purchase during check-out\nAvailable for in-store dining only Usage instructions
service_phone No string(24) 40012234 Customer service number
color Yes string (3072) Color010 Coupon color
location_id_list No string (3072) 1234,2314 The list of applicable stores that can be updated
center_title No string (18) Quick Use Custom cell centered on the top of the coupon
center_sub_title No string (24) Tap Quick Redemption Description of custom cell centered on the top of the coupon
center_url No string (128) www.qq.com URL redirected to from the custom cell centered on the top of the coupon
location_id_list No string (3072) 1234,2314 The list of applicable stores that can be updated
custom_url_name No string (16) 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
promotion_url_name No string (16) 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
code_type No 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 code.
get_limit No int 1 Maximum number of coupons that each user can claim
can_share No bool false Indicates whether the native coupon receipt page is sharable.
can_give_friend No bool false Indicates whether the coupon can be gifted.
date_info No JSON structure See the example above. The date of the use. It is the information about the validity period. To modify the validity period, you can extend the effective date range only.
type No string DATE_TYPE_FIX_TIME_RANGE Type of validity period. Only timestamps whose type is set to DATE_TYPE_FIX_TIME_RANGE are supported.
begin_timestamp No unsigned int 14300000 Indicates the start time of validity period (in sec), and only takes effect when type is DATE_TYPE_FIX _TIME_RANGE.
end_timestamp No unsigned int 15300000 Indicates the end time of validity period, and only takes effect when type is DATE_TYPE_FIX _TIME_RANGE. The validity period of a voucher can be extended to a maximum of three months.

advanced_info field:

Note that the following modifiable fields are not contained in the structure of base_info.

Parameter Review Required Type Example Description
advanced_info Yes JSON structure
abstract No JSON structure Summary of voucher details
abstract No string(60) Note Each user can receive only one voucher. It cannot be used with other vouchers.
icon_url_list No string(3072) 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 size is 900*375 pixels. http://mmbiz.qpic.cn/mmbiz/xxxxx
text_image_list No string(3072) List of articles, which are displayed in the details page. Benefit voucher developers must pass at least one article list.
image_url No string(3072) Image URL. Enter the image URL obtained by uploading the image using "Upload Image" API. Otherwise, an error occurs. http://mmbiz.qpic.cn/mmbiz/xxxxx
text No string(3072) Article description, which consists up to 5,000 characters. It is generally product details.
business_service No string(24) Merchant service type. You can select multiple options. This field controls only what is displayed. It is not displayed if left empty. 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.
time_limit Yes string(24) Time period to which the voucher usage is limited.
type Yes string (24) It can be set to MONDAY, TUESDAY, WEDNESDAY, THURSDAY, FRIDAY, SATURDAY, SUNDAY, and HOLIDAY. Limit type. You can select multiple options. This field controls only what is displayed. It is not displayed if left empty.
consume_share_self_num Yes int The quantity of this voucher given way after redemption. Only one voucher is supported. This value id mutually exclusive with consume_share_card_list. 1
consume_share_card_list Yes JSON The list of other vouchers given away after redemption.
card_id Yes string (24) pbLatjhvf1xBtaOIhYOCnp7Wv4DA The card_id of another voucher given away after redemption. The card_id of only one shared voucher is supported. It is required for shared vouchers.
num Yes unsigned int 1 The number of vouchers of this card_id given away after redemption. It can be set only to 1.

Response Data

Example:

{"errcode":0, "errmsg":"ok", "send_check":false}
Parameter Description
errcode Error code. 0 indicates a successful request.
errmsg Error message
send_check Indicates whether to submit the modified fields for review. false: No; true: Yes. If it is set to true, the status of coupon becomes "Under review".

# Fetching Friend's Vouchers Data

API Description and Note

To enable developers to call the specified API to view voucher-related data, Weixin Cards & Offers Team encapsulates data APIs and provides them for developers who have permissions to use the Cards & Offers feature. These APIs allow developers to get the overall data of all vouchers and the data related to specified vouchers of the merchant.

# Fetching Voucher Summary

API Description

This API is used to fetch the merchant's overall data, including KPIs within a specified time range.

API Request Format

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

Request parameters

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

POST Data

{
    "begin_date": "2015-06-15",
    //Enter the data according to the example. Otherwise, a data format error is reported.
"end_date": "2015-06-30",
    "cond_source": 0
}

Parameters:

Field Description Required Type Example
begin_date Start time of data query Yes string(16) 2015-06-15
end_date End time of data query Yes string(16) 2015-06-30
cond_source Coupon source. 0: Official Accounts Platform; 1: Coupon is created via API. Yes unsigned int 0

Example of response data

{
    "list": [
        {
            "ref_date": "2015-06-23",
            "view_cnt": 1,
            "view_user": 1,
            "receive_cnt": 1,
            "receive_user": 1,
            "verify_cnt": 0,
            "verify_user": 0,
            "given_cnt": 0,
            "given_user": 0,
            "expire_cnt": 0,
            "expire_user": 0
        }
    ]
}

Fields:

Field Description
ref_date Date information
view_cnt Number of views
view_user Number of users who view the coupon
receive_cnt Number of receipts
receive_user Number of users who received the coupon
verify_cnt Number of redemptions
verify_user Number of users who redeemed the coupon
given_cnt Number of times the coupon is gifted
given_user Number of users that the coupon is gifted to
expire_cnt Number of coupons expired
expire_user Number of users who have the expired coupon

Notes:

  1. The query time range must be less than or equal to 62 days. Otherwise, an error is reported: {errcode: 61501, errmsg: "date range error"}.

  2. The format of the time passed in must be strictly consistent with the example: "2015-06-15". Otherwise, an error is reported: {errcode":61500,"errmsg":"date format error"}.

# Getting Friend's Vouchers Data

API Description

This API is used to get Friend's Vouchers data generated within a fixed time range.

API Request Format

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

Request parameters

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

POST Data

{
    "begin_date": "2015-06-15",
    "end_date": "2015-06-30",
    "cond_source": 0,
    "card_id": "po8pktyDLmakNY2fn2VyhkiEPqGE"}

Parameters:

Field Description Required Type Example
begin_date Start time of data query Yes string(16) 2015-06-15
end_date End time of data query Yes string(16) 2015-06-30
cond_source Coupon source. 0: Official Accounts Platform; 1: Coupon is created via API. Yes unsigned int 0
card_id Coupon ID. If specified, the data of the coupon is fetched. No string(32) po8pktyDLmakNY2fn2VyhkiEPqGE

Example of response data

{
    "list": [
        {
            "ref_date": "2015-06-23",
            "card_id": "po8pktyDLmakNY2fn2VyhkiEPqGE",
            "card_type": 3,
            "view_cnt": 1,
            "view_user": 1,
            "receive_cnt": 1,
            "receive_user": 1,
            "verify_cnt": 0,
            "verify_user": 0,
            "given_cnt": 0,
            "given_user": 0,
            "expire_cnt": 0,
            "expire_user": 0
        }
    ]
}

Fields:

Field Description
ref_date Date information
card_id Coupon ID
card_type Voucher type. 0: Discount voucher; 1: Price-reduction voucher; 2: Gift voucher; 3: Benefit voucher; 4: Group-purchase voucher. The data of special tickets such as movie tickets, air tickets, meeting tickets, and attractions tickets cannot be fetched.
view_cnt Number of views
view_user Number of users who view the coupon
receive_cnt Number of receipts
receive_user Number of users who received the coupon
verify_cnt Number of redemptions
verify_user Number of users who redeemed the coupon
given_cnt Number of times the coupon is gifted
given_user Number of users that the coupon is gifted to
expire_cnt Number of coupons expired
expire_user Number of users who have the expired coupon

Notes:

  1. The query time range must be less than or equal to 62 days. Otherwise, an error is reported: {errcode: 61501, errmsg: "date range error"}.

  2. The format of the time passed in must be strictly consistent with the example: "2015-06-15". Otherwise, an error is reported: {"errcode":"date format error"}.

# I Am a Third-Party Developer/Provider

The MP procedure is now available to Friend's Vouchers and allows developers to create Friend's Vouchers via API. Third parties and providers can leverage available capabilities to help merchants without development capabilities to create, issue, and redeem Friend's Vouchers, and manage voucher-related data.

Third parties and providers can complete the basic procedure for Friend's Vouchers as follows:

  1. A third party or provider logs in to Weixin Open Platform to sign up for the Official Accounts Third-Party Platform, and publishes its platform across the network. See Official Accounts Third-Party Platform for details.

  2. A merchant authorizes the voucher authorizations set of its Official Account to the third-party platform via the Official Account, so that the third-party platform can call APIs on behalf of the merchant. See Calling APIs on Behalf of Official Accounts.

  3. Based on the features of vertical industries, the developer helps the merchant create, issue, and redeem Friend's Vouchers, redeem the inventory via an API, top up credit account, and manage data of Friend's Vouchers.

  4. Developers having development capability can build their own voucher platforms for sub-merchants by integrating Authorization to Third-party and Entrusted Voucher Creation modes.

# Feedback

Developers of Friend's Vouchers can join the Developer QQ Group (512568283 (Group 5) or 205482166 (Group 6)). For any questions regarding the development, contact us by emailing to weixin_card@foxmail.com.