# 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

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

The query time range must be less than or equal to 62 days. Otherwise, an error is reported: {errcode: 61501, errmsg: "date range error"}.
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:

The query time range must be less than or equal to 62 days. Otherwise, an error is reported: {errcode: 61501, errmsg: "date range error"}.
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:

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.
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.
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.
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.