Update History:

Contents

Weixin Store API Documentation

1. API Introduction

2. Developer Guide

2.1 Applying for Activation

2.2 Development Process

3. Creating a Store

3.1 Uploading Images

3.2. Creating a Store

3.3 Audit Event Push

3.4 Querying Store Information

3.5 Querying Store List

3.6 Modifying Store Service Information

3.7 Deleting a Store

4. Store Category List

5. Common Error Codes

6. Contact Us

# Weixin Store API Documentation

# 1. API Introduction

Store Management APIs allow merchants to import, query, modify, and delete stores in batch to manage stores easily and efficiently.

When using the Store Management APIs, merchants should take the following considerations into account:

The store poi_id system has been updated so that the poi_ids are assigned immediately after their creation, without being affected by the audit.

A merchant can submit its internal or custom sid (in a string format) when creating a store to ensure the poi_id obtained after the store is approved is associated with the merchant's own data (Weixin does not verify the uniqueness of the sid. Please ensure its uniqueness).

The store availability parameter available_state indicates the audit status. An update is only allowed when the status is "Approved". Only extension fields (the first 11 fields in Table 1) can be updated.

The extension fields are open for editing. Any updates to them will be submitted to Weixin for audit, but do not affect the store availability (available_state still indicates "Approved"). In this case, the update_status changes to "1" (Under Update), which means no further updates can be made to the store until the submitted updates are approved and adopted by Weixin.

If you call the getpoi API when update_status=1 (Under Update), the obtained extension fields are the updated ones, but not the final results. The updates take effect only after being approved and adopted by Weixin (they may be rejected).

Example of a Store Page

# 2. Development Guide

# 2.1 Applying for Activation

You can apply for activating the store management features if you already have a verified Service Account.

The store management features are activated automatically when a verified Subscription Account has enabled the Cards & Offers, Wi-Fi, Shake, and Advertiser features.

Apply for the activation of store management features in Official Accounts Platform > Add Feature Plug-in > Select Store Features.

# 2.2 Development Process

After obtaining the API permissions, read the following procedures carefully before starting the development and debugging.

1. Preparations for Creating a Store

Upload images: Upload the images for creating the store. The uploaded image URL must be the Weixin domain name's URL.

2. Creating a Store

Call the Store Creation API. Upon a successful request, errcode, errmsg, and the final poiid are returned.

3. Audit Event Push

If a new store is approved, an event is pushed to the callback URL entered by the merchant (log in to the Official Accounts Platform and set it in the Developer Center) in order to obtain the store's unique ID: poi_id.

4. Querying Store Information

After the store is approved and poi_id is obtained, the merchant can query the details of the store using the poi_id.

5. Querying Store List

A merchant can query the list of stores under its name in batch through this API, and obtain the approved poi_ids and the merchant's own sid to be associated with the merchant name, outlet name, and address fields.

6. Modifying Store Service Information

This API is used to modify store service information including the "photo_list", "open_time", "recommend", "special", "introduction", "avg_price" and "telephone" fields, but such modifications are subject to a manual audit. "business_name", "longitude", "latitude", and "address" fields cannot be modified.

7. Deleting a Store

This API is used to delete created stores.

Note: The POST data of all APIs must be UTF-8 encoded. Otherwise, an error is returned.

# 3. Creating a Store

# 3.1 Uploading Images

API Description

When you create a store using the POI API, the image URL to be used must be the Weixin domain name's URL. Therefore, you need to upload the images with the "Upload Images" API and obtain the URL before creating a store.

The uploaded images cannot be larger than 1 MB. JPG files are supported.

API Request Format

Request Parameters

Response Data

Example of response for a successful request:

{
"url":"http://mmbiz.qpic.cn/XXXXX"
}

Example of response for a failed request (errcode is not 0, and errmsg is error message):

{
"errcode":40001,
"errmsg":"invalid credential"
}

# 3.2 Creating a Store

API Description

The Store Creation API allows merchants to create their own store data. A higher completeness of the field data means more details of the store will be shown on the merchant's page, thus attracting more users and leading to a higher exposure.

Upon a successful request of the Store Creation API, errcode 0, errmsg ok, and the unique poiid are returned.

API Request Format

Request Parameters

POST Data Example

Example of the page view containing the fields:

JSON Data Example

{"business":{
"base_info":{
"sid":"33788392",
"business_name":" Limited to 15 Chinese characters (30 English characters)",
"branch_name":" Limited to 10 Chinese characters (20 English characters). Parentheses and special characters are not allowed.",
"province":"Limited to 10 Chinese characters (20 English characters)",
"city":"Limited to 30 Chinese characters (20 English characters)",
"district":"Limited to 10 Chinese characters (20 English characters)",
"address":"Detailed address of the store without province and city: limited to 80 Chinese characters (160 English characters)",
"telephone":"Limited to 53 characters (only digits are allowed)",
"categories":["Food,Snack and Fast Food"],
"offset_type":1,
"longitude":115.32375,
"latitude":25.097486,
"photo_list":[{"photo_url":"https:// 20 images at most.com"}，{"photo_url":"https://XXX.com"}],
"recommend":"Limited to 200 Chinese characters (400 English characters). McCrispy Chicken Burger Combo Meal, Chicken McNuggets, Family Barrels",
"special":"Limited to 200 Chinese characters (400 English characters). Free wifi, delivery service",
"introduction":"Limited to 300 Chinese characters (600 English characters). Founded in 1940  in the US, McDonald's is a large global restaurant chain, with about 3 0,000 outlets all over the world.
It features hamburgers, French fries, chicken products, soft drinks, milkshakes, wraps, salad, and desserts. ",
"open_time":"8:00-20:00",
"avg_price":35
}
}
}

Store Basic Information Fields (important)

Store Service Information Fields

Response Data

Example of response for a successful request:

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

Example of response for a failed request (errcode is not 0, and errmsg is error message):

{
"errcode":40001,
"errmsg":"invalid credential"
}

Common Field Mistakes to Avoid

1) Store Name

Store name: This field cannot be left empty, and should be limited to 15 Chinese characters (30 English characters). Parentheses and special characters are not allowed. It should be the merchant (brand) name, such as HaiDiLao, Suning, Sinorama, and MOI Dept. Store, without any region, address and outlet information. Bad and good examples are shown below.

Outlet name: It should be limited to 20 Chinese characters (40 English characters ) without parentheses or special characters. This field is used to uniquely identity an outlet (such as Guomao Store, Chunxi Road Store, and Mixc Storeif) if there are multiple outlets under the same merchant (brand). It should not contain region information or contain any words duplicating the store name. Bad and good examples are shown below.

Bad Example 1:

{"business":{
    "base_info":{
                    "sid":"33788392",
                  "business_name":" Guangzhou Dongxingtang Pharmacy Chain Co., Ltd. (Yongxin Store) ",
                     "branch_name":"", 

Problem: The store name contains an outlet name, region information, and such expressions like "Chain Co., Ltd.".

Good Example:

{"business":{
    "base_info":{
                    "sid":"33788392",
                 "business_name":" Dongxingtang Pharmacy ",
                 "branch_name":" Yongxin Store ", 

Bad Example 2:

{"business":{
    "base_info":{
                    "sid":"33788392",
                  "business_name":" Shanxi GOME ",
                  "branch_name":" Taiyuan Changzhi Road Store ", 

Problem: The store and outlet names contain the region information.

Good Example:

{"business":{
    "base_info":{
                    "sid":"33788392",
                  "business_name":" GOME ",
                  "branch_name":" Changzhi Road Store ", 

Bad Example 3:

{"business":{
    "base_info":{
                    "sid":"33788392",
                  "business_name":" Watsons (Beijing Road Store) ",
                    "branch_name":"" 

Problem: The store name contains parentheses and outlet name.

Good Example:

{"business":{
    "base_info":{
                    "sid":"33788392",
                  "business_name":" Watsons ",
                  "branch_name":" Beijing Road Store ", 

Bad Example 4:

{"business":{
    "base_info":{
                    "sid":"33788392",
                  "business_name":" Simmer Huang ",
                  "branch_name":" Simmer Huang Chengdu Chunxi Road Store ", 

Problem: The outlet name contains words duplicating the store name.

Good Example:

{"business":{
    "base_info":{
                    "sid":"33788392",
                  "business_name":" Simmer Huang ",
                  "branch_name":" Chunxi Road Store ", 

Bad Example 5:

{"business":{
    "base_info":{
                    "sid":"33788392",
                  "business_name":" Living Mall ",
                  "branch_name":" McDonald's ", 

Problem: Store and outlet names are wrongly reversed.

Good Example:

{"business":{
    "base_info":{
                    "sid":"33788392",
                  "business_name":" McDonald's ",
                  "branch_name":" Living Mall ", 

Note: The store and outlet names are displayed in the format of "business_name (branch_name)", with the parentheses added automatically. Considering different field search and storage rules, please enter the field information by strictly following the specification to ensure users can find your store easily. No region information is needed in the names because it is included in the address field.

2) Detailed Address

Enter the store's detailed address and house number correctly, with the basic information "No. XX, Road XX" included. Do not simply enter such information as "XX downstairs", "100 meters to the left of XX", "First floor of XX Mall", or "100 meters to the north of XX Metro Station Exit D", as the search and GPS locating features are not available.

Do not enter province and city in the detailed address field. For a municipality, both "province" and "city" should be populated with the municipality name.

Bad Example:

                    "province":"Zhejiang",
                    "city":"Hangzhou",
                    "district":"Xiacheng District",
                    "address":" 5F, Century Mart Supermarket, No. 86, Qingchun Road, Xiacheng District, Hangzhou", |

Problem: The detailed address contains the city name, which results in a wrong display "5F, Century Mart Supermarket, No. 86, Qingchun Road, Xiacheng District, Hangzhou, Xiacheng District, Hangzhou, Zhejiang.

Good Example:

                    "province":"Zhejiang",
                    "city":"Hangzhou",
                    "district":"Xiacheng District",
                    "address":"5F, Century Mart Supermarket, No. 86, Qingchun Road", 

Correct display: 5F, Century Mart Supermarket, No. 86, Qingchun Road, Xiacheng District, Hangzhou, Zhejiang.

An example for municipality:

                    "province":"Shanghai",
                    "city":"Shanghai",
                    "district":"Xuhui District",
                    "address":"Building A, Zhonghuan International Plaza, No. 397, Tianlin Road", 

3) Category Information

Select the correct store categories according to the category list.

Bad Example:

{"business":{
    "base_info":{
                    "sid":"33788392",
                    "business_name":"McDonald's",
                    "branch_name":"Yiyuan Road Outlet",
                    "province":"Guangdong",
                    "city":"Guangzhou",
                    "district":"Haizhu District",
                    "address":"Yiyuan Road 11 ",
                    "telephone":"020-12345678",
                    "categories":["Food,Tea Restaurant"],
  

Problem: The McDonald's category filed value "Food,Tea Restaurant" is incorrect.

<a href="https://docs.google.com/spreadsheets/d/191n-uUJJFow_n1ySvPsLOpk88FJKXQuzSCKUe7vnjxQ/edit?usp=sharing "For more information on categories, see the "Weixin Store Category List" target="_blank">For more information on categories, see the "Weixin Store Category List"

4) Phone Number

The phone number entered must be true and valid. Spot check will be conducted during audit. An unanswered or invalid phone number can affect the audit result.

This field only consists of digits, with area code, phone number and extension number joined with "-". For a landline telephone number, area code is required. Multiple numbers are not allowed.

Bad Example 1:

"telephone":"(010)87632851", 

Problem: The area code is not joined with "-".

Bad Example 2:

"telephone":"34435764",

Problem: The area code is missing in the land-line telephone number.

Bad Example 3:

"telephone":"13880934557, 0351-34435764",

Problem: Multiple numbers are entered.

Bad Example 4:

"telephone":"138-8093-4557", 

Problem: The digits in a mobile number should not be separated with "-".

Bad Example 5:

"telephone":"8003800,4010", 

Problem: The extension number is not joined with "-".

Bad Example 6:

"telephone":"8003800#4010", 

Problem: The extension number is not joined with "-".

Good Example:

"telephone":"021-81445873", 
"telephone":"021-81445873-1003",

"telephone":"13867428497", 
"telephone":"4008002835", 

5) Longitude and Latitude

Obtain the longitude and latitude coordinates of a known location through a third-party platform, and then select the offset_type to upload the coordinates.

You can also find the store's coordinates with the following tool and export them.

For more information, see Coordinate Picker:

http://lbs.qq.com/tool/getpoint/index.html

Note: The longitude and latitude coordinates need to be converted into Tencent Maps coordinates.

For more information, see:

<a href="http://lbs.qq.com/webservice_v1/guide-convert.html "Converting Coordinates"" target="_blank">http://lbs.qq.com/webservice_v1/guide-convert.html

# 3.3 Audit Event Push

When a new store is approved, an event is pushed to the callback URL entered by the merchant (log in to the Official Accounts Platform and set it in the Developer Center).

If the Weixin server does not receive the response within five seconds, the connection is broken and the request is initiated again. A maximum of three retries are made. It is recommended to use FromUserName + CreateTime for de-duplication of requests.

If the merchant's server cannot ensure the request is processed and responded within five seconds, it can return an empty string. When receiving the string, the Weixin server will not take any action or make a retry.**

Example of XML packet:

<xml> 
  <ToUserName><![CDATA[toUser]]></ToUserName>  
  <FromUserName><![CDATA[fromUser]]></FromUserName>  
  <CreateTime>1408622107</CreateTime>  
  <MsgType><![CDATA[event]]></MsgType>  
  <Event><![CDATA[poi_check_notify]]></Event>  
  <UniqId><![CDATA[123adb]]></UniqId>  
  <PoiId><![CDATA[123123]]></PoiId>  
  <Result><![CDATA[fail]]></Result>  
  <msg><![CDATA[xxxxxx]]></msg> 
</xml>

Parameters:

# 3.4 Querying Store Information

API Description

After creating a store and obtaining the poi_id, the merchant can query the store information with the pio_id. During the query, update_status=1 indicates the store's extension fields have been modified with the Update API in the last 5 business days. The updated extension fields have not been approved and are not final. The result on whether the fields are adopted and take effect is given within 5 business days (This process does not affect the store's availability, and the available_state is still "Approved").

Note: The updates to the extension fields are pushed for audit, but do not affect the store's availability.

API Request Format

Request Parameters

POST Data Example

{
"poi_id":"271262077"
}

Response Data

Data example

{
		"errcode":0,
		"errmsg":"ok",
		"business ":{
		"base_info":{
		"sid":"001",
		"business_name":"McDonald's",
		"branch_name":"Yiyuan Road Outlet",
		"province":"Guangdong",
		"city":"Guangzhou",
		"address":"No. 11, Yiyuan Road, Haizhu District",
		"telephone":"020-12345678",
		"categories":["Food,Snack and Fast Food"],
		"offset_type":1,
		"longitude":115.32375,
		"latitude":25.097486,
		"photo_list":[{"photo_url":"https:// XXX.com"} , {"photo_url":"https://XXX.com"}],
		"recommend":"McCrispy Chicken Burger Combo Meal, Chicken McNuggets, Family Barrels",
		"special":"Free wifi, delivery service",
		"introduction":" Founded in 1940  in the US, McDonald's is a large global restaurant chain, with about 30,000 outlets all over the world.
		3 It features hamburgers, French fries, chicken products, soft drinks, milkshakes, wraps, salad, and desserts.",
		"open_time":"8:00-20:00",
		"avg_price":35
		"available_state":3
		"update_status":0
		}
	}
}

*Note: Other fields are same as above.

# 3.5 Querying Store List

API Description

A merchant can query the list of stores under its name in batch through this API, and obtain the approved poi_id, and the merchant's own sid to be associates with the merchant name, outlet name, and address fields.

API Request Format

Request Parameters

POST Data Example

{
"begin":0,
"limit":10
}

Field Description

Response Data

Example:

The first store has been approved and has a poi_id and all fields; the second one has been rejected and only has basic fields; the third one is under audit and only has basic fields.

{
	"errcode":0,
	"errmsg":"ok"
	"business_list":[
	{"base_info":{
	"sid":"101",
	"business_name":"McDonald's",
	"branch_name":"Yiyuan Road Outlet",
	"address":"Yiyuan Road 11",
	"telephone":"020-12345678",
	"categories":["Food,Snack and Fast Food"],
	"city":"Guangzhou",
	"province":"Guangdong",
	"offset_type":1,
	"longitude":115.32375,
	"latitude":25.097486,
	"photo_list":[{"photo_url":"http: ...."}],
	"introduction":"Founded in 1940  in the US, McDonald's is a large global restaurant chain, with about 3 0,000 outlets all over the world. It features hamburgers, French fries, chicken products, soft drinks, milkshakes, wraps, salad, and desserts.",
	"recommend":"McCrispy Chicken Burger Combo Meal, Chicken McNuggets, Family Barrels",
	"special":"Free wifi, delivery service",
	"open_time":"8:00-20:00",
	"avg_price":35,
	"poi_id":"285633617",
	"available_state":3,
	"district":"Haizhu District",
	"update_status":0
}},
{"base_info":{
	"sid":"101",
	"business_name":"McDonald's",
	"branch_name":"Beijing Road Outlet",
	"address":"No. 12, Beijing Road",
	"telephone":"020-12345689",
	"categories":["Food,Snack and Fast Food"],
	"city":"Guangzhou",
	"province":"Guangdong",
	"offset_type":1,
	"longitude":115.3235,
	"latitude":25.092386,
	"photo_list":[{"photo_url":"http: ...."}],
	"introduction":"Founded in 1940  in the US, McDonald's is a large global restaurant chain, with about 3 0,000 outlets all over the world. It features hamburgers, French fries, chicken products, soft drinks, milkshakes, wraps, salad, and desserts.",
	"recommend":"McCrispy Chicken Burger Combo Meal, Chicken McNuggets, Family Barrels",
	"special":"Free wifi, delivery service",
	"open_time":"8:00-20:00",
	"avg_price":35,
	"poi_id":"285633618",
	"available_state":4,
	"district":"Yuexiu District",
	"update_status":0
}},
{"base_info":{
	"sid":"101",
	"business_name":"McDonald's",
	"branch_name":"Longdong Outlet",
	"address":"No. 122, Yinglong Road",
	"telephone":"020-12345659",
	"categories":["Food,Snack and Fast Food"],
	"city":"Guangzhou",
	"province":"Guangdong",
	"offset_type":1,
	"longitude":115.32345,
	"latitude":25.056686,
	"photo_list":[{"photo_url":"http: ...."}],
	"introduction":"Founded in 1940  in the US, McDonald's is a large global restaurant chain, with about 3 0,000 outlets all over the world. It features hamburgers, French fries, chicken products, soft drinks, milkshakes, wraps, salad, and desserts.",
	"recommend":"McCrispy Chicken Burger Combo Meal, Chicken McNuggets, Family Barrels",
	"special":"Free wifi, delivery service",
	"open_time":"8:00-20:00",
	"avg_price":35,
	"poi_id":"285633619",
	"available_state":2,
	"district":"Tianhe District",
	"update_status":0
}},
],
"total_count":"3",
}

# 3.6 Modifying Store Service Information

API Description

This API is used to modify store service information including the sid, "photo_list", "open_time", "recommend", "special", "introduction", "avg_price" and "telephone" fields, but such modifications are subject to a manual audit. "business_name", "longitude", "latitude" and "address" fields cannot be modified.

API Request Format

Request Parameters

POST Data Example

{"business ":{
	"base_info":{
		"poi_id ":"271864249"
		"sid":"A00001"
		"telephone ":"020-12345678"
		"photo_list":[{"photo_url":"https:// XXX.com"},{"photo_url":"https://XXX.com"}],
		"recommend":"McCrispy Chicken Burger Combo Meal, Chicken McNuggets, Family Barrels",
		"special":"Free wifi, delivery service",
		"introduction":"Founded in 1940  in the US, McDonald's is a large global restaurant chain, with about 3 0,000 outlets all over the world. It features hamburgers, French fries, chicken products, soft drinks, milkshakes, wraps, salad, and desserts.",
		"open_time":"8:00-20:00",
		"avg_price":35
	}
}
}

Fields:

All field values are same as above.

Note:

For the above eight fields, any edit to a field will overwrite the old content. If no update is made to a field, the field remains unchanged. For any update to the photo_list field, the old list is completely overwritten with the new list. To add new images, you need to include both the previous and new images in the new list. For example, if you want to add images D and E to the list of images A, B, and C, you need to call the API to input the URLs of all the images (A, B, C, D, E) to the photo_list field.

Response Data

Example:

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

# 3.7 Deleting a Store

API Description

This API is used to delete created stores and should be used with caution.

API Request Format

Request Parameters

POST Data Example

{
"poi_id": "271262077"
}

Fields:

Response Data

Example:

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

# 4. Store Category List

API Description

This API is used to provide the store category information. It is recommended to make the categories as specific as possible to target more users accurately and improve exposure.

API Request Description

Response Data

{
"category_list":
["Food,Jiangzhe Cuisine,Shanghai Cuisine","Food,Jiangzhe Cuisine,Huaiyang Cuisine","Food,Jiangzhe Cuisine,Zhejiang Cuisine","Food,Jiangzhe Cuisine,Nanjing Cuisine ","Food,Jiangzhe Cuisine,Suzhou Cuisine..."]
}

# 5. Common Error Codes

For more error codes, see "Basic Support - Common Error Codes".