# logistics.addOrder

Call this API at the server side. For more information, see Server API.

This API supports Cloud Calls. The WeChat DevTools version must be 1.02.1904090 or later (download the latest stable version here), and the wx-server-sdk version must be 0.4.0 or later.

Generates a waybill.

Calling methods:

HTTPS call
Cloud call

# HTTPS Call

# Request Address

POST https://api.weixin.qq.com/cgi-bin/express/business/order/add?access_token=ACCESS_TOKEN

# Request Parameters

Attribute	Type	Required	Description
access_token	string	Yes	Credentials to call API
order_id	string	Yes	The ID of the order. It must be globally unique and contain a maximum of 512 characters.
openid	string	Yes	The OpenID of the user.
delivery_id	string	Yes	The ID of the express company. See `getAllDelivery`.
biz_id	string	Yes	The customer number or prepayment number of the express company.
custom_remark	string	No	Remarks of the express delivery, for example, "Fragile". It should not exceed 1024 bytes.
sender	Object	Yes	Sender information.
receiver	Object	Yes	Receiver information.
cargo	Object	Yes	Parcel information to be sent to the express company.
shop	Object	Yes	Commodity information to be displayed in logistics notifications.
insured	Object	Yes	Parcel insurance information.
service	Object	Yes	Service type.

sender is composed as follows

Property	Type	Required	Description
name	string	Yes	The name of the sender. It should not exceed 64 bytes.
tel	string	No	The telephone number of the sender. Either the telephone number or the mobile number is required. It should not exceed 32 bytes.
mobile	string	No	The mobile number of the sender. Either the mobile number or the telephone number is required. It should not exceed 32 bytes.
company	string	No	The company name of the sender. It should not exceed 64 bytes.
post_code	string	No	The postal code of the sender's address. It should not exceed 10 bytes.
country	string	No	The country where the sender is located. It should not exceed 64 bytes.
province	string	Yes	The province where the sender is located, for example, "Guangdong Province". It should not exceed 64 bytes.
city	string	Yes	The city/region where the sender is located, for example, "Guangzhou". It should not exceed 64 bytes.
area	string	Yes	The district/county where the sender is located, for example, "Haizhu District". It should not exceed 64 bytes.
address	string	Yes	The detailed address of the sender, for example, "xx on xx Building, No. xx, xx Road". It should not exceed 512 bytes.

receiver is composed as follows

Property	Type	Required	Description
name	string	Yes	The name of the receiver. It should not exceed 64 bytes.
tel	string	No	The telephone number of the receiver. Either the telephone number or the mobile number is required. It should not exceed 32 bytes.
mobile	string	No	The mobile number of the receiver. Either the mobile number or the telephone number is required. It should not exceed 32 bytes.
company	string	No	The company name of the receiver. It should not exceed 64 bytes.
post_code	string	No	The postal code of the receiver's address. It should not exceed 10 bytes.
country	string	No	The country where the receiver is located. It should not exceed 64 bytes.
province	string	Yes	The province where the receiver is located, for example, "Guangdong Province". It should not exceed 64 bytes.
city	string	Yes	The region/city where the receiver is located, for example, "Guangzhou". It should not exceed 64 bytes.
area	string	Yes	The district/county where the receiver is located, for example, "Tianhe District". It should not exceed 64 bytes.
address	string	Yes	The detailed address of the receiver, for example, "xx on xx Building, No. xx, xx Road". It should not exceed 512 bytes.

cargo is composed as follows

Property	Type	Required	Description
count	number	Yes	The quantity of parcels.
weight	number	Yes	The total weight of parcels (in kg).
space_x	number	Yes	The length of the parcel (in cm).
space_y	number	Yes	The width of the parcel (in cm).
space_z	number	Yes	The height of the parcel (in cm).
detail_list	Array.<Object>	Yes	List of commodity details in the parcel.

cargo.detail_list is composed as follows

Property	Type	Default	Required	Description
name	string		Yes	The name of the commodity. It should not exceed 128 bytes.
count	number		Yes	The quantity of commodities.

shop is composed as follows

Property	Type	Required	Description
wxa_path	string	Yes	The path to the merchant's Mini Program. The recommended value is the path to the order page.
img_url	string	Yes	The URL of the commodity's thumbnail.
goods_name	string	Yes	The name of the commodity.
goods_count	number	Yes	The quantity of commodities.

insured is composed as follows

Property	Type	Default	Required	Description
use_insured	number		Yes	Specifies whether to insure the cargo. " 0" indicates that the cargo is not insured, and "1" indicates that the cargo is insured.
insured_value	number		Yes	The insured value (in fen). For example, "10000" indicates 100 CNY.

service is composed as follows

Property	Type	Default	Required	Description
service_type	number		Yes	The ID of the service type. For details, see Basic Information of Supported Express Companies.
service_name	string		Yes	The name of the service. For details, see Basic Information of Supported Express Companies.

# Return Value

# Object

Property	Type	Description
order_id	string	The ID of the order. It is returned when the order is placed.
waybill_id	string	The ID of the waybill. It is returned when the order is placed.
waybill_data	Array.<Object>	The information of the waybill. It is returned when the order is placed.
errcode	number	The error code for WeChat. It is returned when the order failed to be placed.
errmsg	string	The error message for WeChat. It is returned when the order failed to be placed.
delivery_resultcode	number	The error code for the express delivery. It is returned when the order failed to be placed.
delivery_resultmsg	string	The error message for the express delivery. It is returned when the order fails to be placed.

waybill_data is composed as follows

Property	Type	Description
key	string	The key of the waybill information.
value	string	The value of the waybill information.

Valid values of errcode

Value	Description	Minimum Version
-1	System failure
9300501	Logic error during express delivery. For detailed reasons, see delivery_resultcode.
9300503	delivery_id does not exist.
9300510	service_type does not exist.
9300526	Incorrect field length.

# Request Example

{
  "order_id": "01234567890123456789",
  "openid": "oABC123456",
  "delivery_id": "SF",
  "biz_id": "xyz",
  "custom_remark": "Fragile",
  "sender": {
    "name": "Jim",
    "tel": "020-88888888",
    "mobile": "18666666666",
    "company": "Company name",
    "post_code": "123456",
    "country": "China",
    "province": "Guangdong Province",
    "city": "Guangzhou",
    "area": "Haizhu District",
    "address": "XXxx on Block XX, XX Building, No. XX, Road XX"
  },
  "receiver": {
    "name": "Wang Xiaomeng",
    "tel": "020-77777777",
    "mobile": "18610000000",
    "company": "Company name",
    "post_code": "654321",
    "country": "China",
    "province": "Guangdong Province",
    "city": "Guangzhou",
    "area": "Tianhe District",
    "address": "XXxx on Block XX, XX Building, No. XX, Road XX"
  },
  "shop": {
    "wxa_path": "/index/index?from=waybill&id=01234567890123456789",
    "img_url": "https://mmbiz.qpic.cn/mmbiz_png/OiaFLUqewuIDNQnTiaCInIG8ibdosYHhQHPbXJUrqYSNIcBL60vo4LIjlcoNG1QPkeH5GWWEB41Ny895CokeAah8A/640",
    "goods_name": "1001 Nights Diamond Purse & Hermes Birkin Bag",
    "goods_count": 2
  },
  "cargo": {
    "count": 2,
    "weight": 5.5,
    "space_x": 30.5,
    "space_y": 20,
    "space_z": 20,
    "detail_list": [
      {
        "name": "1001 Nights Diamond Purse",
        "count": 1
      },
      {
        "name": "Hermes Birkin Bag",
        "count": 1
      }
    ]
  },
  "insured": {
    "use_insured": 1,
    "insured_value": 10000
  },
  "service": {
    "service_type": 0,
    "service_name": "Standard express delivery"
  }
}

# Response Example

Order placed.

{
  "order_id": "01234567890123456789",
  "waybill_id": "123456789",
  "waybill_data": [
    {
      "key": "SF_bagAddr",
      "value": "Guangzhou"
    },
    {
      "key": "SF_mark",
      "value": "101- 07-03 509"
    }
  ]
}

Failed to place the order.

{
  "errcode": 9300501,
  "errmsg": "delivery logic fail",
  "delivery_resultcode": 10002,
  "delivery_resultmsg": "Incorrect customer password"
}

# Cloud Call

Cloud call is a capability provided by Mini Program·Cloud Base that allows you to call WeChat APIs in a cloud function. It must be used via wx-server-sdk in the cloud function.

# API Calling Method

openapi.logistics.addOrder

You need to configure the permissions for the logistics.addOrder API via config.json. Details

# Request Parameters

Attribute	Type	Required	Description
orderId	string	Yes	The ID of the order. It must be globally unique and contain a maximum of 512 characters.
openid	string	Yes	The OpenID of the user.
deliveryId	string	Yes	The ID of the express company. See `getAllDelivery`.
bizId	string	Yes	The customer number or prepayment number of the express company.
customRemark	string	No	Remarks of the express delivery, for example, "Fragile". It should not exceed 1024 bytes.
sender	Object	Yes	Sender information.
receiver	Object	Yes	Receiver information.
cargo	Object	Yes	Parcel information to be sent to the express company.
shop	Object	Yes	Commodity information to be displayed in logistics notifications.
insured	Object	Yes	Parcel insurance information.
service	Object	Yes	Service type.

sender is composed as follows

Property	Type	Required	Description
name	string	Yes	The name of the sender. It should not exceed 64 bytes.
tel	string	No	The telephone number of the sender. Either the telephone number or the mobile number is required. It should not exceed 32 bytes.
mobile	string	No	The mobile number of the sender. Either the mobile number or the telephone number is required. It should not exceed 32 bytes.
company	string	No	The company name of the sender. It should not exceed 64 bytes.
postCode	string	No	The postal code of the sender's address. It should not exceed 10 bytes.
country	string	No	The country where the sender is located. It should not exceed 64 bytes.
province	string	Yes	The province where the sender is located, for example, "Guangdong Province". It should not exceed 64 bytes.
city	string	Yes	The city/region where the sender is located, for example, "Guangzhou". It should not exceed 64 bytes.
area	string	Yes	The district/county where the sender is located, for example, "Haizhu District". It should not exceed 64 bytes.
address	string	Yes	The detailed address of the sender, for example, "xx on xx Building, No. xx, xx Road". It should not exceed 512 bytes.

receiver is composed as follows

Property	Type	Required	Description
name	string	Yes	The name of the receiver. It should not exceed 64 bytes.
tel	string	No	The telephone number of the receiver. Either the telephone number or the mobile number is required. It should not exceed 32 bytes.
mobile	string	No	The mobile number of the receiver. Either the mobile number or the telephone number is required. It should not exceed 32 bytes.
company	string	No	The company name of the receiver. It should not exceed 64 bytes.
postCode	string	No	The postal code of the receiver's address. It should not exceed 10 bytes.
country	string	No	The country where the receiver is located. It should not exceed 64 bytes.
province	string	Yes	The province where the receiver is located, for example, "Guangdong Province". It should not exceed 64 bytes.
city	string	Yes	The region/city where the receiver is located, for example, "Guangzhou". It should not exceed 64 bytes.
area	string	Yes	The district/county where the receiver is located, for example, "Tianhe District". It should not exceed 64 bytes.
address	string	Yes	The detailed address of the receiver, for example, "xx on xx Building, No. xx, xx Road". It should not exceed 512 bytes.

cargo is composed as follows

Property	Type	Required	Description
count	number	Yes	The quantity of parcels.
weight	number	Yes	The total weight of parcels (in kg).
spaceX	number	Yes	The length of the parcel (in cm).
spaceY	number	Yes	The width of the parcel (in cm).
spaceZ	number	Yes	The height of the parcel (in cm).
detailList	Array.<Object>	Yes	List of commodity details in the parcel.

cargo.detailList is composed as follows

Property	Type	Default	Required	Description
name	string		Yes	The name of the commodity. It should not exceed 128 bytes.
count	number		Yes	The quantity of commodities.

shop is composed as follows

Property	Type	Required	Description
wxaPath	string	Yes	The path to the merchant's Mini Program. The recommended value is the path to the order page.
imgUrl	string	Yes	The URL of the commodity's thumbnail.
goodsName	string	Yes	The name of the commodity.
goodsCount	number	Yes	The quantity of commodities.

insured is composed as follows

Property	Type	Default	Required	Description
useInsured	number		Yes	Specifies whether to insure the cargo. " 0" indicates that the cargo is not insured, and "1" indicates that the cargo is insured.
insuredValue	number		Yes	The insured value (in fen). For example, "10000" indicates 100 CNY.

service is composed as follows

Property	Type	Default	Required	Description
serviceType	number		Yes	The ID of the service type. For details, see Basic Information of Supported Express Companies.
serviceName	string		Yes	The name of the service. For details, see Basic Information of Supported Express Companies.

# Return Value

# Object

Property	Type	Description
orderId	string	The ID of the order. It is returned when the order is placed.
waybillId	string	The ID of the waybill. It is returned when the order is placed.
waybillData	Array.<Object>	The information of the waybill. It is returned when the order is placed.
errCode	number	The error code for WeChat. It is returned when the order failed to be placed.
errMsg	string	The error message for WeChat. It is returned when the order failed to be placed.
deliveryResultcode	number	The error code for the express delivery. It is returned when the order failed to be placed.
deliveryResultmsg	string	The error message for the express delivery. It is returned when the order fails to be placed.

waybillData is composed as follows

Property	Type	Description
key	string	The key of the waybill information.
value	string	The value of the waybill information.

Valid values of errCode

Value	Description	Minimum Version
0	Succeeded

# Exceptions

# Object

Thrown Exceptions

Property	Type	Description
errCode	number	The error code for WeChat. It is returned when the order failed to be placed.
errMsg	string	The error message for WeChat. It is returned when the order failed to be placed.

Valid values of errCode

Value	Description	Minimum Version
-1	System failure
9300501	Logic error during express delivery. For detailed reasons, see delivery_resultcode.
9300503	delivery_id does not exist.
9300510	service_type does not exist.
9300526	Incorrect field length.

# Request Example

const cloud = require('wx-server-sdk')
  cloud.init()
  exports.main = async (event, context) => {
    try {
      const result = await cloud.openapi.logistics.addOrder({
        openid: 'oABC123456',
        sender: {
          name: 'Jim',
          tel: '020-88888888',
          mobile: '18666666666',
          company: 'Company name',
          country: 'China',
          province: 'Guangdong Province',
          city: 'Guangzhou',
          area: 'Haizhu District',
          address: 'XXxx on Block XX, XX Building, No. XX, Road XX',
          postCode: '123456'
        },
        receiver: {
          name: 'Wang Xiaomeng',
          tel: '020-77777777',
          mobile: '18610000000',
          company: 'Company name',
          country: 'China',
          province: 'Guangdong Province',
          city: 'Guangzhou',
          area: 'Tianhe District',
          address: 'XXxx on Block XX, XX Building, No. XX, Road XX',
          postCode: '654321'
        },
        shop: {
          wxaPath: '/index/index?from=waybill&id=01234567890123456789',
          imgUrl: 'https://mmbiz.qpic.cn/mmbiz_png/OiaFLUqewuIDNQnTiaCInIG8ibdosYHhQHPbXJUrqYSNIcBL60vo4LIjlcoNG1QPkeH5GWWEB41Ny895CokeAah8A/640',
          goodsName: '1001 Nights Diamond Purse & Hermes Birkin Bag',
          goodsCount: 2
        },
        cargo: {
          count: 2,
          weight: 5.5,
          spaceX: 30.5,
          spaceY: 20,
          spaceZ: 20,
          detailList: [
            {
              name: '1001 Nights Diamond Purse',
              count: 1
            },
            {
              name: 'Hermes Birkin Bag',
              count: 1
            }
          ]
        },
        insured: {
          useInsured: 1,
          insuredValue: 10000
        },
        service: {
          serviceType: 0,
          serviceName: 'Standard express delivery'
        },
        orderId: '01234567890123456789',
        deliveryId: 'SF',
        bizId: 'xyz',
        customRemark: 'Fragile'
      })
      console.log(result)
      return result
    } catch (err) {
      console.log(err)
      return err
    }
  }

# Response Example

Order placed.

{
  "orderId": "01234567890123456789",
  "waybillId": "123456789",
  "waybillData": [
    {
      "key": "SF_bagAddr",
      "value": "Guangzhou"
    },
    {
      "key": "SF_mark",
      "value": "101- 07-03 509"
    }
  ],
  "errMsg": "openapi.logistics.addOrder:ok"
}

Failed to place the order.

{
  "errCode": 9300501,
  "errMsg": "openapi.logistics.addOrder:fail delivery logic fail",
  "deliveryResultcode": 10002,
  "deliveryResultmsg": "Incorrect customer password"
}