Dispatch Information

Now, sellers using the CAINIAO carrier can manage their dispatch information automatically through the /dispatch_preferences feature. This feature allows users to create or update the pick-up address and adjust shipping preferences, which include choosing between pick-up or selecting an agency for drop-off.

Dispatch Preferences

Search dispatch preferences

It is possible to consult the dispatch preferences associated with the merchant by performing the following request:

Request:

curl -X GET -H 'Authorization: Bearer $ACCESS_TOKEN' -H 'x-format-new: true' https://api.mercadolibre.com/marketplace/shipments/dispatch_preferences/carriers

For merchant who has active CAINIAO

Response:

{
        "name": "Cainiao",
        "has_pickup": true,
        "sites": [
            "MLC",
            "MLB",
            "MCO",
            "MLM"
        ],
        "dispatch_info": {
            "pickup": true
        }
    }

For merchant who does not have active CAINIAO

The successful response will be just a "200 - OK" with an empty return.

{}

Set dispatch preferences

There are two types of dispatch preferences that can be selected for seller, pickup (collection) or drop off agency (dispatch in agency). It is necessary to note that only one of the options can be chosen. If the seller chooses pickup, it will not be allowed to register an agency for drop off. If you choose drop off agency, pick-up address selection will not be allowed.

Associate Pick-Up as dispatch preference

For merchant who has active CAINIAO

Request:

curl -X PUT -H 'Authorization: Bearer $ACCESS_TOKEN' -H 'x-format-new: true' https://api.mercadolibre.com/marketplace/shipments/dispatch_preferences/carriers/$CARRIER_NAME
 -d '{
    "pickup": true

Example:

curl -X PUT -H 'Authorization: Bearer $ACCESS_TOKEN' -H 'x-format-new: true' https://api.mercadolibre.com/marketplace/shipments/dispatch_preferences/carriers/cainiao

The successful response will be just a "200 - OK" with an empty return.

{}

Possible errors when associating pick-up as dispatch preference

For merchant without active CAINIAO

{
    "message": "you don't have this carrier configured",
    "error": "some fields are invalid or not accepted in this request",
    "status": 400,
    "cause": null
}

For merchant with active CAINIAO but no registered pickup address

{
    "message": "you don't have pick up address registered",
    "error": "some fields are invalid or not accepted in this request",
    "status": 400,
    "cause": null
}

Associate Drop Off Agency as dispatch preference

For merchant with active CAINIAO

Request:

curl -X PUT -H 'Authorization: Bearer $ACCESS_TOKEN' -H 'x-format-new: true' https://api.mercadolibre.com/marketplace/shipments/dispatch_preferences/carriers/$CARRIER_NAME
 -d '{
    "drop_off_agency": "name agency "
}

Example:

curl -X PUT -H 'Authorization: Bearer $ACCESS_TOKEN' -H 'x-format-new: true' https://api.mercadolibre.com/marketplace/shipments/dispatch_preferences/carriers/cainiao 
-d '{
    "drop_off_agency": "TRAN_0001"
}

The successful response will be just a "200 - OK" with an empty return.

{}

List of valid agencies:

Province	City	Warehouse Address	Warehouse Name	Warehouse Code Drop off agency
Guangdong	Dongguan	Dongguan Shatian Town, Shatian Yanhe Road No. 281, Dongguan Shatian Logistics Park, No. Warehouse ( No. Warehouse [A, B, C, D] and project No. Warehouse [A, B] units)	Dongguan Shatian Warehouse	TRAN_STORE_31405735
Zhejiang-	Yiwu	Intersection of Yiwu Fourth Sea Avenue, Zhejiang Province and Shugang Expressway, Yiwu Baowan International Logistics Park, Warehouse 1#, third floor, sections 1 and 2	Yiwu Choujiang Baowan	TRAN_STORE_31405747

Possible errors when associating Drop Off Agency as dispatch preference

Invalid Drop Off Agency for merchant with active CAINIAO

Request:

curl -X PUT -H 'Authorization: Bearer $ACCESS_TOKEN' -H 'x-format-new: true' https://api.mercadolibre.com/marketplace/shipments/dispatch_preferences/carriers/cainiao
 -d '{
    "drop_off_agency": "TRAN_0001"
}

Response

{
    "message": "invalid agency informed for carrier Cainiao ",
    "error": "some fields are invalid or not accepted in this request",
    "status": 400,
    "cause": null
}
}

Drop Off Agency for merchant with invalid carrier

Request:

curl -X PUT -H 'Authorization: Bearer $ACCESS_TOKEN' -H 'x-format-new: true' https://api.mercadolibre.com/marketplace/shipments/dispatch_preferences/carriers/mailamericas
-d '{
    "drop_off_agency": "TRAN_STORE_31405735"
}

Response

{
    "message": "invalid agency informed for carrier MailAmericas",
    "error": "some fields are invalid or not accepted in this request",
    "status": 400,
    "cause": null
}
}

Associate pick-up address

To assign or update a pick-up address, you must enter the full address.

Request:

curl -X POST -H 'Authorization: Bearer $ACCESS_TOKEN' -H 'x-format-new: true' https://api.mercadolibre.com/marketplace/shipments/dispatch_preferences/pick_up_addresses
 -d '{
    "address_line": "广东省东莞市 厚街镇赤岭（三屯）福民路86号正通B幢二楼(I0798)",
    "zip_code": "100039",
    "city": {
        "id": "Q04tQUhDaHV6aG91",
        "name": "Chuzhou"
    },
    "state": {
        "id": "CN-AH",
        "name": "Anhui"
    },
    "country": {
        "id": "CN",
        "name": "China"
    }
}

The successful response will be just a "200 - OK" with an empty return.

{}

All fields are mandatory:

address_line:Full address of the pick up location (street and number). The field must contain the characters 省 and 市.
zip_code: Postal code, must be 6 digits.
city: Id and name identifier of the city.
state: Id and name state identifier.
country: Id and name identifier of the country.

Possible errors when associating the pick-up address

When associating the pick-up address, you may encounter the following errors. It is crucial to understand the cause of each error and know how to correct them in order to handle the situation efficiently. Here, you have the necessary information to identify and resolve these problems.

Body is invalid:

{
    "message": "Invalid body",
    "error": "bad_request",
    "status": 400,
    "cause": []
}

Body missing properties:

{
    "message": "Invalid body",
    "error": "bad_request",
    "status": 400,
    "cause": [
        "/: missing properties: 'city'",
        "/state: missing properties: 'name'"
    ]
}

Get pick-up address

To determine if the merchant has the correct pick-up address, you can make the following request:

Request:

curl -X GET -H 'Authorization: Bearer $ACCESS_TOKEN' -H 'x-format-new: true' https://api.mercadolibre.com/marketplace/shipments/dispatch_preferences/pick_up_addresses

Merchant with registered pick-up address

Response:

[
    {
        "sites": [
            "MLC",
            "MLB",
            "MCO",
            "MLM"
        ],
        "address_id": 1434131662,
        "address_line": "广东省东莞市 厚街镇赤岭（三屯）福民路86号正通B幢二楼(I0798)",
        "zip_code": "100039",
        "city": {
            "id": "Q04tQUhDaHV6aG91",
            "name": "Chuzhou"
        },
        "state": {
            "id": "CN-AH",
            "name": "Anhui"
        },
        "country": {
            "id": "CN",
            "name": "República Popular China"
        }
    }
]

Merchant without registered pick-up address

The successful response will be just a "200 - OK" with an empty return.

{}