Contents

4 Querying Coupons in Batch

5 Modifying Coupon Information

6 Modifying Inventory

7 Modifying Code

8 Deleting Coupons

9 Invalidating Coupons

10 Collecting Statistics on Coupon Data

10.1 Fetching Coupon Summary

10.2 Getting Data of Free Coupons

10.3 Fetching Member Card Summary

10.4 Fetching Data of a Single Member Card

# Querying Code

This API is used to query whether the current code can be redeemed and check the code status. Statuses include normal, redeemed, gifting to another user, deleted, unavailable, and invalid code.

API Request Format

HTTP request method: POSTURL:https://api.weixin.qq.com/card/code/get?access_token=TOKEN

Parameters

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

POST Data

{
   "card_id" : "card_id_123+",
   "code" : "123456789",
   "check_consume" : true
}

Parameters

Parameter	Required	Type	Example	Description
code	Yes	string(20)	110201201245	Unique ID for each coupon
card_id	No	string(32)	pFS7Fjg8kV1I dDz01r4SQwMkuCKc	Coupon ID that identifies a group of same coupons. It is required for a coupon with a custom code.
check_consume	No	bool	true	Indicates whether to check the code redemption status. The returned data for code status varies with different value (true or false).

The data returned when check_consume is set to true

When the coupon status is normal:


 {
  "errcode": 0,
  "errmsg": "ok",
  "card": {
    "card_id": "pbLatjk4T4Hx-QFQGL4zGQy27_Qg",
    "begin_time": 1457452800,
    "end_time": 1463155199
  },
  "openid": "obLatjm43RA5C6QfMO5szKYnT3dM",
  "can_consume": true,
  "outer_str": "12b",
  "user_card_status": "NORMAL"
}

When the coupon status is abnormal:

{
 "errcode": 40127,
 "errmsg": "invalid user-card status! Hint: the card was given to user, but may be deleted or set unavailable ! hint: [iHBD40040ent3]"
}

The data returned when check_consume is set to false

When the coupon status is normal:


 {
  "errcode": 0,
  "errmsg": "ok",
  "card": {
    "card_id": "pbLatjk4T4Hx-QFQGL4zGQy27_Qg",
    "begin_time": 1457452800,
    "end_time": 1463155199
  },
  "openid": "obLatjm43RA5C6QfMO5szKYnT3dM",
  "can_consume": true,
  "outer_str": "12b",
  "user_card_status": "NORMAL"
}

When the coupon status is abnormal:

 {
  "errcode": 0,
  "errmsg": "ok",
  "card": {
    "card_id": "pbLatjnK8NLbWgwMgfMtnj3gaglw",
    "begin_time": 1457625600,
    "end_time": 1460217599
  },
  "openid": "obLatjm43RA5C6QfMO5szKYnT3dM",
  "can_consume": false,
  "outer_str": "12b",
  "user_card_status": "GIFTING"
 }

Parameter	Description
errcode	Error code
errmsg	Error message
openid	The openid of the user
card_id	Coupon ID
begin_time	Start time
end_time	End time
user_card_status	The status of the coupon for the current code. NORMAL: Normal; CONSUMED: Redeemed; EXPIRE: Expired; GIFTING: Gifting to another user; GIFT_TIMEOUT: Gifting timed out; DELETE: Deleted; UNAVAILABLE: Unavailable. If the code is not added or is gifted and received, the error code "invalid serial code" is reported.
outer_str	The channel value passed in by the merchant when the coupon is received
can_consume	Indicates whether the coupon can be redeemed. True: Yes; False: No.

Notes:

1. A validity period with a fixed time range is converted based on the actual receipt time. For example, if a coupon is received on October 1, 2013 and the fixed time range is 90 days, then the validity period is from October 1, 2013 to December 29, 2013.

2. When the code is not added or it is gifted and received, the error code "invalid serial code" is reported, regardless of whether the check_consume field is set to true or false.

# Getting Coupons Received by User

This API is used to get all available coupons under the appid in the user's Cards & Offers, both normal and abnormal.

API Request Format

HTTP request method: POSTURL:https://api.weixin.qq.com/card/user/getcardlist?access_token=TOKEN

Parameters

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

POST Data


{
  "openid": "12312313",
  "card_id": "xxxxxxxxxx"
}

Parameters

Parameter	Required	Type	Example	Description
openid	Yes	string(64)	1231231	OpenID of the user to be queried
card_id	No	string(32)	pFS7Fjg8kV1IdDz01xxxxx	Coupon ID. If it is not specified, coupons under the current appid are queried by default.

Response Data


 {"errcode":0,"errmsg":"ok","card_list": [
      {"code": "xxx1434079154", "card_id": "xxxxxxxxxx"},
      {"code": "xxx1434079155", "card_id": "xxxxxxxxxx"}
      ],
       "has_share_card": true
}

Parameters

Parameter	Description
errcode	Error code
errmsg	Error message
card_list	Coupon list
has_share_card	Indicates whether there are friend's coupons available

# Checking Coupons Details

This API is used to query the creation information, approval status and inventory of a coupon of a card_id.

API Request Format

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

Parameters

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

POST Data

{
  "card_id":"pFS7Fjg8kV1IdDz01r4SQwMkuCKc"
}

Parameter	Required	Type	Example	Description
card_id	Yes	string(32)	pFS7Fjg8kV1IdDz01r4SQwMkuCKc	Coupon ID

Response Data

{
  "errcode": 0,
  "errmsg": "ok",
  "card": {
    "card_type": "DISCOUNT",
    "discount": {
      "base_info": {
        "id": "pbLatjnP97_F9PudzBARQhn7xR7A",
        "logo_url": "http://mmbiz.qpic.cn/mmbiz/p98FjXy8LafmY25YclQ7vw5noBxeVH3DG5AKFR1ZsRgMgsvjll7EkUsZib00J964AEpTjkNXF2HorJHt5mtt45Q/0?wx_fmt=png",
        "code_type": "CODE_TYPE_NONE",
        "brand_name": "Weixin Restaurant",
        "title": "10%-off Coupon",
        "date_info": {
          "type": "DATE_TYPE_FIX_TERM",
          "fixed_term": 30,
          "fixed_begin_term": 0
        },
        "color": "#10AD61",
        "notice": "Available in Store",
        "description": "",
        "location_id_list": [
          218384742,
          402521653,
          402521608
        ],
        "get_limit": 3,
        "can_share": true,
        "can_give_friend": true,
        "status": "CARD_STATUS_VERIFY_OK",
        "sku": {
          "quantity": 100096,
          "total_quantity": 100100
        },
        "create_time": 1457525546,
        "update_time": 1457526240,
        "area_code_list": []
      },
      "discount": 10,
      "advanced_info": {
        "time_limit": [
          {
            "type": "MONDAY"
          },
          {
            "type": "TUESDAY"
          }
        ],
        "text_image_list": [],
        "business_service": [],
        "consume_share_card_list": [],
        "abstract": {
          "abstract": "Learn More",
          "icon_url_list": [
            "http://mmbiz.qpic.cn/mmbiz/p98FjXy8LafiawSeJeqBzk8qC40iaKIwUPm4TSCelulzEbAywKr7tWjkd5vRjbmFloUFeThfwhwMUZIXmsCtJpyQ/0?wx_fmt=jpeg"
          ]
        },
        "share_friends": false
      }
    }
  }
}

Parameter	Description
card_type	Card/Coupon type. GROUPON: Group-purchase coupon; DISCOUNT: Discount coupon; GIFT: Gift coupon; CASH: Cash coupon; GENERAL_COUPON: General coupon; MEMBER_CARD: Member card; SCENIC_TICKET: Attractions ticket; MOVIE_TICKET: Movie ticket; BOARDING_PASS: Air ticket; MEETING_TICKET: Meeting ticket; BUS_TICKET: Bus ticket.
base_info	Basic coupon data. See the table below. This field is applicable to all cards/coupons.
deal_detail	Group purchase details. This field is only applicable to group-purchase coupons.
gift	Indicates the gift name. This field is only applicable to gift coupons.
least_cost	Indicates the minimum purchase amount (in cents). This filed is only applicable to cash coupons.
reduce_cost	Indicates the coupon amount (in cents). This filed is only applicable to cash coupons.
discount	Indicates the discount (%). This field is only applicable to discount coupons.
supply_balance	Indicates whether points are supported. Enter "true" or "false". Fields related to points are required. This field is only applicable to member cards.
supply_bonus	Indicates whether top-up is supported. Enter "true" or "false". Fields related to top-up are required. This field is only applicable to member cards.
bonus_cleared	Rules for clearing points. This field is only applicable to member cards.
bonus_rules	Rules for calculating points. This field is only applicable to member cards.
balance_rules	Top-up rules. This field is only applicable to member cards.
prerogative	Describes benefits of the member card. This field is only applicable to member cards.
bind_old_card_url	The URL to link an old member card. This field is only applicable to member cards.
activate_url	URL of activated member card. This field is only applicable to member cards.
need_push_on_view	Specifies whether to push an event if the user taps to open the member card. Enter "true" or "false". This field is only applicable to member cards.
from	Origin on the air ticket, with a maximum length of 18 Chinese characters (36 English characters). This field is only applicable to air tickets.
to	Destination on the air ticket, with a maximum length 18 Chinese characters (36 English characters). This field is only applicable to air tickets.
flight	Flight. This field is only applicable to air tickets.
departure_time	Departure time, expressed as a Unix timestamp. This field is only applicable to air tickets.
landing_time	Landing time, expressed as a Unix timestamp. This field is only applicable to air tickets.
check_in_url	URL for online check-in. This field is only applicable to air tickets.
gate	Gate. If this value changes, the merchant should call this API for update. This field is only applicable to air tickets.
boarding_time	Boarding time, expressed as a Unix timestamp. It is displayed in HH:MM format only. This field is only applicable to air tickets.
meeting_detail	Meeting details. This field is only applicable to meeting tickets.
map_url	Venue map. This field is only applicable to meeting tickets.

base_info

Parameter	Description
logo_url	Merchant logo of coupon. Recommended size 300*300 pixels.
code_type	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.
brand_name	Merchant name, which is the name of the merchant that provides services. Enter the third-party merchant name in the source field.
title	Coupon name
color	Background color of coupon
notice	Usage tip, with a maximum length of 16 Chinese characters (32 English characters).
description	Usage instructions in long text format
date_info	Information of coupon validity period
type	Coupon validity type. DATE_TYPE_FIX TIME_RANGE: a fixed time range; DATE_TYPE FIX_TERM: a fixed number of days (after coupon receipt); DATE_TYPE_PERMANENT: Permanent time. This field is only applicable to member cards.
begin_timestamp	Indicates the start time of validity period, and 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.
end_timestamp	Indicates the end time of validity period (in sec), and only takes effect when type = DATE_TYPE_FIX_TIME_RANGE.
fixed_term	Indicates the number of days during which the received coupon is valid, and only takes effect when type = DATE_TYPE_FIX_TERM. Enter 0 if the coupon becomes valid on the day of its receipt.
fixed_begin_term	Indicates the number of days after which the received coupon becomes valid, and only takes effect when type = DATE_TYPE_FIX_TERM.
sku	Product information
quantity	Existing coupon quantity
total_quantity	Total coupon inventory. Maximum is 100,000,000.
location_id_list	Store location ID
use_all_locations	Indicates the coupon is supported by all stores. Enter "true" or "false". This value id mutually exclusive with location_id_list.
use_custom_code	Indicates whether to use custom code. Enter "true" or "false" (default).
No
can_share	Indicates whether the coupon can be gifted. Enter "true" (default) or "false".
service_phone	Customer service phone number
source	Third-party source name, such as TravelGo, Dianping.
custom_url_name	Name of merchant's custom entry
custom_url	External URL redirected to via the merchant's custom entry. The content of the redirect page should match the custom cell name.
custom_url_sub_title	Tips shown to the right of the entry button, with a maximum length of 6 Chinese characters (12 English characters).
promotion_url_name	Custom entry button to the promotional page
promotion_url	URL of external redirect link
promotion_url_sub_title	Words shown to the right of the entry button to the promotional page
custom_url_name	Name of merchant's custom entry
status	CARD_STATUS_NOT_VERIFY: To be approved; CARD_STATUS_VERIFY_FAIL: Rejected; CARD_STATUS_VERIFY_OK: Approved; CARD_STATUS_DELETE: Deleted by merchant; CARD_STATUS_DISPATCH: Already issued on the Official Accounts Platform

Notes

*1. For merchants with special permissions, the fields returned by the "Query Coupon Details" API may contain specific APIs.

2. Coupon-related fields are updated in real time, and the fields actually returned include, without limitation, the fields in this documentation. Any fields that developers are not familiar with should not be processed to avoid errors.

# **Querying Coupons in Batch

API Request Format

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

Parameters

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

POST Data


{
  "offset": 0,
  "count": 10,
   "status_list": ["CARD_STATUS_VERIFY_OK", "CARD_STATUS_DISPATCH"]
}

Parameter	Required	Type	Example	Description
offset	Yes	int	0	Start offset of the queried coupon list. The initial value is 0. If the offset is 5, then query starts from the sixth coupon in the list.
count	Yes	int	10	The number of coupons to be queried, which is up to 50.
string(32)	CARD_STATU S_VERIFY_OK	The developer can fetch the list of coupons with specified status. CARD_STATUS_NOT_VERIFY: To be approved; CARD_STATUS_VERIFY_FAIL: Rejected; CARD_STATUS_VERIFY_OK: Approved; CARD_STATUS_DELETE: Deleted by merchant; CARD_STATUS_DISPATCH: Already issued on the Official Accounts Platform

Response Data

{
  "errcode":0,
  "errmsg":"ok",
  "card_id_list":["ph_gmt7cUVrlRk8swPwx7aDyF-pg"],
  "total_num":1
}

Parameter	Description
errcode	Error code. 0 indicates a successful request.
errmsg	Error message
card_id_list	List of coupon IDs
total_num	Number of coupon IDs under the merchant name

Notes:

1. If no filter condition is passed, this API returns coupons of all statuses under the merchant name by default.

2. The status of each coupon can be determined later by calling the "Query Coupon Details" API.

# Modifying coupon Information

API Description

This API supports updating some common fields for cards/coupons of all types and specific fields for special coupons (member cards, air tickets, movie tickets, and meeting tickets).

API Request Format

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

Parameters

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

POST Data


{
       "card_id":"ph_gmt7cUVrlRk8swPwx7aDyF-pg",
       "member_card": {
        //Enter the coupon type (lower-case) corresponding to the card_id.
               "base_info": {
                   "logo_url": "http:\/\/www.supadmin.cn\/uploads\/allimg\/120216\/1_120216214725_1.jpg",
                   "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
                   Available for eat-in only\nTake-away is not allowed before dining\nThis coupon is for 2 persons.
                   You may have to pay a 5-CNY sauce fee for each extra person.\nDo not bring your own drink"
                   "location_id_list" : [123, 12321, 345345]
               },
                  "bonus_cleared": "aaaaaaaaaaaaaa",
                  "bonus_rules": "aaaaaaaaaaaaaa",
                  "prerogative": ""
       }
}

Common fields

Parameter	Review Required	Type	Example	Description
base_info	-	JSON structure	See the example above.	Coupon basic information field
logo_url	Yes	string(128)	mmbiz.qpic.cn/	Merchant logo of coupon. Recommended dimension 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)	It cannot be used with other coupons.	Coupon usage instructions
service_phone	No	string（24）	40012234	Customer service phone 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. Pass "0" if stores are all cleared.
custom_url_name	No	string (16)	Use Now	Title of the custom external redirect link
custom_url	No	string (128)	"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)	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
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_FI X_TIME_RANGE	Type of validity period. Only timestamps whose type is set to DATE_TYPE_FIX_TIME_RANGE are supported. DATE_TYPE_FIX_TERM is not allowed.
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 (in sec), and only takes effect when type is DATE_TYPE_FIX _TIME_RANGE. It can be extended only.

Fields specific to different types of cards/coupons:

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

Parameter	Review Required	Type	Example	Description
bonus_cleared	Yes	string(3072)	points are cleared on Dec. 30 of the year.	Rules for clearing points. This field is only applicable to member cards.
bonus_rules	Yes	string(3072)	1 CNY = 1 point	Rules for calculating points. This field is only applicable to member cards.
balance_rules	Yes	string(3072)	Account can be topped up online.	Top-up rules. This field is only applicable to member cards.
prerogative	Yes	string(3072)	20% off all products for XX members.	Describes benefits. This field is only applicable to member cards.
custom_field1	No	JSON structure	See the example of creating a member card.	A custom member information item. It is displayed after the member card is activated. This field is only applicable to member cards.
custom_field2	No	JSON structure	See the example of creating a member card.	A custom member information item. It is displayed after the member card is activated. This field is only applicable to member cards.
custom_field3	No	JSON structure	See the example of creating a member card.	A custom member information item. It is displayed after the member card is activated. This field is only applicable to member cards.
name_type	No	string(24)	FIELD_NAME _TYPE_LEVEL	The name of a member information item. FIELD_NAME_TYPE_LEVEL: Level; FIELD_NAME_TYPE_COUPON: Coupon; FIELD_NAME_TYPE_STAMP: Stamp; FIELD_NAME_TYPE_DISCOUNT: Discount; FIELD_NAME_TYPE_ACHIEVEMEN: Achievement; FIELD_NAME_TYPE_MILEAGE: Mileage.
url	No	string (128)	qq.com	The external redirect URL of a category
custom_cell1	No	JSON structure	See the above example.	A custom member information item. It is displayed after the member card is activated.
detail	Yes	string(3072)	Movie title: Avengers: Age of Ultron/nRelease date: May 12, 2015, 23:00/nTicket type: 3D	Movie ticket details
departure_time	No	unsigned int	1431271351	Departure time
landing_time	No	unsigned int	1441271351	Landing time
gate	No	string(12)	No. 3	Gate. If this value changes, the merchant should call this API for update.
boarding_time	No	unsigned int	1431271351	Boarding time, expressed as a Unix timestamp. It is displayed in HH:MM format only. If this value changes, the merchant should call this API for update.
guide_url	No	string(128)	www.qq.com	URL of the guide map for attractions tickets
map_url	No	string(128)	qq.com	Venue map

Response Data


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

Notes

1. When the update API is called, if the developer passes in the fields that are already submitted for review, the status of the coupon is changed to "Under review" again.

*2. The original fields will be overwritten by the updated ones when the update API is called. The developer needs only to pass in the fields to be modified. Otherwise, the coupon will be re-submitted for review.

*3. If some fields are not specified, "" (null) can be passed in during update.

4. If you update the coupon information by calling this API, call the Homepage to verify whether the update is successful.

5. Update are not allowed for fields that are not listed herein.

# Modifying Inventory

This API is used to increase/decrease the inventory of a coupon.

API Request Format

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

Parameters

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

POST Data

{
"card_id": "pFS7Fjg8kV1IdDz01r4SQwMkuCKc",
"increase_stock_value": 1231231,
"reduce_stock_value": 1231231
}

Parameter	Required	Type	Example	Description
card_id	Yes	string(32)	pFS7Fjg8kV1IdDz01r4SQwMkuCKc	Coupon ID
increase_stock_value	No	int	1231231	The number of coupons added to the inventory. Left it empty or enter 0.
reduce_stock_value	No	int	1231231	The number of coupons removed from the inventory. Left it empty or enter 0.

Response Data

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

Parameter	Description
errcode	Error code
errmsg	Error message

# Modifying Code

To ensure security after a coupon is gifted, the merchants of coupons with custom codes are allowed to modify the issued codes. It is recommended that the merchant modify the code only after a coupon is gifted (Weixin will notify the merchant of the code of the gifted coupon by pushing an event of coupon gift).

API Request Format

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

Parameters

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

POST Data


{
  "code": "12345678",
  "card_id": "pFS7Fjg8kV1IdDz01r4SQwMkuCKc",
  "new_code": "3495739475"
}

Parameter	Required	Type	Example	Description
card_id	No	string(32)	pFS7Fjg8kV1IdDz01r4SQwMkuCKc	Coupon ID. It is required for coupons with custom codes.
code	Yes	string(16)	110201201245	Code to be modified
new_code	Yes	string(64)	1231231	Valid code after modification

Response Data

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

Parameter	Description
errcode	Error code
errmsg	Error message

# Deleting Coupons

This API allows merchants to delete any types of coupons. After a coupon is deleted, the QR code generated for receipt and JS API added to the Cards & Offers of the coupon become invalid. Note: If a user receives one or more coupons before they are deleted by the merchant, such coupons are still valid. coupons that are received and stored in the Weixin app by users cannot be deleted.

API Request Format

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

Parameters

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

POST Data

{
   "card_id": "pFS7Fjg8kV1IdDz01r4SQwMkuCKc"
}

Parameter	Required	Type	Example	Description
card_id	Yes	string(32)	pFS7Fjg8kV1IdDz01r4SQwMkuCKc	Coupon ID

Response Data

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

Parameter	Description
errcode	Error code
errmsg	Error message

# Invalidating Coupons

This API is used to invalidate a user's coupon in case of change or refund.

API Request Format

HTTP request method: POSTURL:https://api.weixin.qq.com/card/code/unavailable?access_token=TOKEN

Parameters

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

POST Data

Request for coupon with non-custom code {  "code": "12312313",  "reason":"Refund"} or request for coupon with custom code {  "code": "12312313",  "card_id": "pFS7Fjg8kV1IdDz01r4SQwMkuCKc"}

Parameter	Required	Type	Example	Description
card_id	Yes	string(32)	pFS7Fjg8kV1IdDz01r4SQwMkuCKc	Coupon ID
code	Yes	string(20)	1231231	The code of invalidated coupon
reason	No	string(64)	A user initiates a refund	Reason for invalidation

Response Data

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

Parameter	Description
errcode	Error code
errmsg	Error message

Notes:

1. The invalidation operation cannot be undone. Please proceed with caution.

2. Before calling this API, merchants shall inform users of such operation and obtain their prior consent. Otherwise, they will be subject to penalty according to Penalty Rules for Weixin Operations in case of user complaints.

# Collecting Statistics on Coupon Data

To enable developers to call the specified API to view coupon-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 coupons and the data related to specified coupons of the merchant.

# Fetching Coupon 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: POSTURL: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

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

Note:

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

3. This API cannot fetch the data of the day. Otherwise, an error is reported.

# Getting Data of Free Coupons

API Description

This API is used to get the data of free coupons (general coupons, group-purchase coupons, discount coupons, and gift coupons) within a fixed time range.

API Request Format

HTTP request method: POSThttps://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

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	Coupon type. 0: Discount coupon; 1: Cash coupon; 2: Gift coupon; 3: General coupon; 4: Group-purchase coupon. 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

Note:

1. This API is only used to get the data of free coupons (general coupons, group-purchase coupons, discount coupons, and gift coupons). The data of special tickets (movie tickets, meeting tickets, attractions tickets, and air tickets) cannot be fetched.

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

3. 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"}.

4. This API cannot fetch the data of the day. Otherwise, an error is reported.

# Fetching Member Card Summary

API Description

This API is used to get the data of member cards created via Official Accounts Platform.

API Request Format

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

Parameters

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

POST Data

｛
 "begin_date":"2015-06-15",
 "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

Response Data


{
   "list": [
       {
           "ref_date": "2015-06-23",
           "view_cnt": 0,
              "view_user": 0,
              "receive_cnt": 0,
              "receive_user": 0,
              "active_user": 0,
              "verify_cnt": 0,
              "verify_user": 0,
              "total_user": 86,
              "total_receive_user": 95
   ]
}

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
active_user	Number of users who activated the member card
total_user	Number of valid members
total_receive_user	Total number of users who received the member card

# Fetching Data of a Single Member Card

API Description

This API is used to get the data of a member card created via API.

API Request Format

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

Parameters

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

POST Data

｛
 "begin_date":"2015-06-15",
 "end_date":"2015-06-30",
 "card_id":"xxxxxxxxxxxxxxxx"
｝

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
card_id	Card ID	Yes	string(32)	p4WkzwieuDBzzn7Jed6SBO0-ZgaU

Response Data


{
  "list": [
    {
      "ref_date": "2016-07-06",
      "merchanttype": 2,
      "cardid": "p4WkzwieuDBzzn7Jed6SBO0-ZgaU",
      "submerchantid": 0,
      "view_cnt": 2,
      "view_user": 1,
      "receive_cnt": 1,
      "receive_user": 1,
      "verify_cnt": 0,
      "verify_user": 0,
      "active_cnt": 1,
      "active_user": 1,
      "total_user": 249,
      "new_user": 0,
      "payOriginalFee": 0,
      "fee": 0
    }
  ]
}

Fields:

Field	Description
ref_date	Date information
merchanttype	Sub-merchant type
submerchantid	Sub-merchant ID
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
active_user	Number of users who activated the member card
total_user	Number of valid members
total_receive_user	Total number of users who received the member card
new_user	Number of new users
payOriginalFee	Amount receivable (limited to the member cards for which Weixin Checkout is set)
fee	Amount received (limited to the member cards for which Weixin Checkout is set)