Pick up in store

Looking to improve our users’ experience, we added to our platform the possibility to load to an item the stores where pick up is available. Knowing this information in advance, the buyer will select which of the stores to pick up the order and, Mercado Libre will let the seller know so it can be prepared. To be a part of this initiative, we suggest you contact your sales representative.

Contents

→Associate stores to a user
    ↳Considerations
→Suggestions for the data format to load the stores
    ↳Name
    ↳Address
    ↳Streets
    ↳Hours
→Modify a store
→Pause a store
→Reactivate a store
    ↳Eliminate a store
→Check a store
→Check the stores associated to a user
→Associate a store to a publication
    ↳Considerations on the field availability_time
    ↳Hours rules
→Associate a store to a publication with variations
→Modify the availability time of a store
→Eliminate an available store in an item
→Identify an item with associated stores
→Check the stores associated to an item
→Identify an order with pick up in store
→Apply the pickups resource
→Modify the delivery time
    ↳Considerations
→Change the pickup status to delivered
→Possible status of a pickup
→How to receive the details to generate an invoice


Associate stores to a user

Note:
The configuration of test users, with the shipping method removed at the branch, must be done through the support team, and in the case of real sellers, the approval of this seller to withdraw in the store must be done with the commercial advisor.

First, the stores a user has must be created. The latitude and longitude fields have to be previously known to send them as parameters.

curl -X POST https://api.mercadolibre.com/users/$USER_ID/stores?access_token=$ACCESS_TOKEN

Example:

curl -X POST https://api.mercadolibre.com/users/1234567/stores?access_token=$ACCESS_TOKEN

{
    "description":"DOT",
    "open_hours": "Lunes a viernes de 8:30 a 12:30 y de 16:30 a 20:30 hs. - Sábado de 9 a 13 y de 16:30 a 20:30 hs.",
    "status": "active" |  "paused" ,
    "phone": 
    {
        "area_code":"011",
        "number":"1234"
    },
    "location":
    {
       "address_line": "B de Monteagudo 2833 - Florencio Varela - Buenos Aires",
       "latitude": -24.2344,
       "longitude": -15.122
    }
}

Response:

{
    "id": 1,
    "description":"DOT",
    "date_creation": "2017-02-08T08:40:51.620Z",
    "open_hours": "Lunes a viernes de 8:30 a 12:30 y de 16:30 a 20:30 hs. - Sábado de 9 a 13 y de 16:30 a 20:30 hs.",
    "status": "active" | "paused",
    "phone": 
    {
        "area_code":"011",
        "number":"1234"
    },
    "location":
    {
          "address_line": "B de Monteagudo 2833 - Florencio Varela - Buenos Aires",
          "latitude": -24.2344,
          "longitude": -15.122,
    }
}

Considerations

  • The parameter “open_hours” supports up to 100 characters.
  • The remaining parameters allow up to 60 characters.
  • The field phone is optional.

Suggestions for the data format to load stores

Name

To identify the store, it should be a reference to the location of the store, like “Saavedra” or “Shopping DOT”. Name of the store : Description (DOT)


Address

The requirements you need to consider when loading an address are:

  • State: In MLA: use always CABA (Not Ciudad Autónoma de Buenos Aires, Capital Federal, Cap. Fed., or Caba).Córdoba and Tucumán take a marked stressed.
  • In MLM: use always CDMX (Not Ciudad de México or DF).
  • In MLB: we use the same address format as Google (- Street, Number - Locality, City - shortened State) For example: R. Regente Feijó, 132 - Centro, Rio de Janeiro - RJ
    Av. São João, 439 - República, São Paulo - SP.
    We shorten the states with two letters in upper case:

Acre: AC
Alagoas: AL
Amazonas: AM
Bahía: BA
Ceará: CE
Distrito Federal: DF
Espírito Santo: ES
Goiás: GO
Maranhão: MA
Mato Grosso: MT
Mato Grosso do Sul: MS
Minas Gerais: MG
Pará: PA
Paraíba: PB
Paraná: PR
Pernambuco: PE
Piauí: PI
Río de Janeiro: RJ
Rio Grande do Norte: RN
Rio Grande do Sul: RS
Rondônia: RO
Roraima: RR
Santa Catarina: SC
São Paulo: SP
Sergipe: SE
Tocantins: TO


Streets

  • In MLA, MLM and MLB: Shorten Avenidas (Ex: Av. del Libertador, Av. Callao).
  • In MLB: Shorten Rúa with an R. (R. Cantareira, R. Ingaí).

Hours

The requirements for loading the hours are:

  • Report only the open hours (we do not say “Sunday Closed”).
  • Write full days, with all the letters and in lower case.
  • Use 24 hs. system without am/pm, with 1 digit for 1 hour and with 4 if it is ½ hour.
  • Don’t forget the final “.” in “hs.”: Continuous business hours example: from 9 to 19 hs. // from 9 to 19:30 hs. Broken business hours example (morning and afternoon): from 9 to 12 and from 15 to 19 hs.
  • Write all the days in lower case, except when it is at the beginning of a sentence. Example: Monday // Monday to Friday // Monday to Tuesday and Thursday to Saturday

Examples of days and hours:

  • Continuous business hours: Monday to Friday from 9 to 19 hs.; Monday to Saturday from 9 to 19 hs.; Monday to Friday from 9 to 19 hs.; Saturday from 9 to 12:30 hs.; Monday to Wednesday from 9 to 19 hs.; Thursday to Saturday from 9 to 12:30 hs.
  • Broken business hours: Monday to Friday from 9 to 12:30 and from 15 to 19:30 hs.; Monday to Saturday from 9 to 12:30 and 15 to 19:30 hs.; Monday to Friday from 9 to 12:30 and from 15 to 19:30 hs.; Saturday from 9 to 12:30 and 15 to 19:30 hs.; Monday to Wednesday from 9 to 12:30 and from 15 to 19:30 hs.; Thursday to Saturday from 9 to 12:30 and 15 to 19:30 hs.


Modify a store

When you want to modify the information of a store, you must only send what you wish to update.

Call:

curl -X PUT https://api.mercadolibre.com/users/$USER_ID/stores/{store_id}?access_token=$ACCESS_TOKEN

Example:

curl - X PUT https://api.mercadolibre.com/users/1234567/stores/1?access_token=ACCESS_TOKEN

{
    "open_hours": "Lunes a sábado de 9 a 20:30 hs.",
}

Pause a store

When you want to pause a store and the items associated with it to stop momentarily offering the pickup option, you should make a PUT to status.

Example:

curl -X PUT https://api.mercadolibre.com/users/1234567/stores/1?access_token=ACCESS_TOKEN
{
"status": "paused"
}
Note:
This stops the associated items from offering PUIS. But, when reactivating the store, the items automatically recover the association.

Reactivate a store

When you want a store to be available again and the associated items to offer pick up option, you should make a PUT to status.

Example:

curl -X PUT https://api.mercadolibre.com/users/1234567/stores/1?access_token=ACCESS_TOKEN

{
    "status": "active"
}

Eliminate a store

When you wish to eliminate a store associated to a user, you should make a delete.

Call:

curl -X DELETE https://api.mercadolibre.com/users/{user_id}/stores/{store_id}?access_token=$ACCESS_TOKEN

Example:

curl -X DELETE https://api.mercadolibre.com/users/1234567/stores/1?access_token=$ACCESS_TOKEN
Note:
When deleting the store, the store will not be deleted but it will remain “inactive”. The store cannot be reactivated.

Check a store

To bring forward the information loaded in a user’s store.

Call:

curl -X GET https://api.mercadolibre.com/stores/{store_id}?access_token=$ACCESS_TOKEN

Example:

curl -X GET https://api.mercadolibre.com/stores/1?access_token=$ACCESS_TOKEN

Response:

{
  "id": "1",
  "user_id": "221111122",
  "description": "Belgrano",
  "date_creation": "2017-06-27T13:26:52.94790119-04:00",
  "open_hours": "Lun-Sáb: 09:00-20:30. Dom: 12:00-20:30.",
  "status": "active",
  "tags": [
    "pickup"
  ],
  "phone": {
    "area_code": "011",
    "number": "22222222"
  },
  "location": {
    "address_line": "Av. Cabildo 111, Ciudad de Buenos Aires",
    "latitude": -32.562693359870195,
    "longitude": -75.45601654999198,
    "id": "AR-C",
    "type": "state"
  }
}

Check the stores associated to a user

To know which are all the stores that a user has registered, the following query can be done:


Call:

curl -X GET https://api.mercadolibre.com/users/$USER_ID/stores/search?limit={limit}&offset={offset}&status={status}

Example:

https://api.mercadolibre.com/users/1234567/stores/search?limit=100&offset=0&status=active,paused

Response:

{
    "paging": 
    {
        "limit": 10,
        "offset": 10,
        "total": 1495
    },
    "results": 
    [
        {
            "id": 1,
            "description":"DOT",
            "date_creation": "2017-02-08T08:40:51.620Z",
            "open_hours": "Lunes a sábado de 9 a 20:30 hs.",
            "status": "active",
            "phone": 
            {
                "area_code":"011",
                "number":"1234"
            },
            "location":
            {
                "address_line": "B de Monteagudo 2833 - Florencio Varela - Buenos Aires"
                "latitude": -24.2344
                "longitude": -15.122
            }
        },
        {
            "id": 2,
            "description":"DOT 2",
            "date_creation": "2017-02-08T08:40:51.620Z",
            "open_hours": "Lunes a sábado de 9 a 20:30 hs.",
            "status": "paused",
            "phone": 
            {
                "area_code":"011",
                "number":"1234"
            },
            "location":
            {
                "address_line": "B de Monteagudo 2833 - Florencio Varela - Buenos Aires"
                "latitude": -24.2344
                "longitude": -15.122
            }
        }
    ]
}

Associate a store with a publication

Once an item is created, previously registered stores, where the product is available to be picked up, can be associated to it. In the json, the “availability_time_in_hours” field, that shows as of when the buyer will be able to pick up the product, will be sent. The time posted should not exceed 5 days (120 hours).


Call:

curl -X POST https://api.mercadolibre.com/items/$ITEM_ID/stores/{store_id}?access_token=$ACCESS_TOKEN

Example:

curl -X POST https://api.mercadolibre.com/items/MLA12345678/stores/1?access_token=$ACCESS_TOKEN

JSON body

{
  "availability_time_in_hours": 72
}

Considerations on the field availability_time

  • The hours of business days and Saturdays will be counted. The predefined hours will be added to the date/hour of the order.
  • When the availability is 0hs and the order is placed after 18hs, we will say “As from tomorrow”. If not, it will be “Today”. This is defined this way to apply a general rule to all the businesses from the region.
  • For the time being, holidays are not considered for the calculation of the pick up date.

Hours rules

Zone 1 (Up to 48 hs) Zone 2 (Up to 72 hs) Zone 3 Rest of the country (up to 96 hs)
MLB SP (Capital) SP (State - Zone 1) RJ (capital). Rest of the country.
MLM CDMX (City) - Estado de México (City). Guadalajara (City) - Monterrey (City). Rest of the country.
MCO Bogota (City) - Medellin (City). Barranquilla (City) - Cali (City). Rest of the country.
MLU Montevideo (Departament) - Canelones (Departament) - Maldonado (Departament) Rest of the country. -
MLC Santiago Viña del Mar / Valparaíso - Concepción - La Serena. Rest of the country.
MLA CABA and Gran Buenos Aires. Ciudad de Rosario and Ciudad de Santa Fe - Ciudad de Córdoba - Ciudad de Mendoza. Rest of the country.

Associate a store with a publication with variations

Once an item has variations, previously registered stores, where the product is available to be picked up, can be associated to it.

Rules:

  • The base item (without variation) has to be associated to the store that has availability. These are the times that are going to be shown by “default” for all the variations. For that, the same POST is used as in the associations without variation.

Call:

curl -X POST https://api.mercadolibre.com/items/$ITEM_ID/stores/{store_id}?access_token=$ACCESS_TOKEN

Example:

curl -X POST https://api.mercadolibre.com/items/MLA12345678/stores/1?access_token=$ACCESS_TOKEN

JSON body

{
  "availability_time_in_hours": 72
}
  • If the seller wants to set a different availability for a specific variation, a POST must be done.

Call:

curl -X POST https://api.mercadolibre.com/items/{item_id}/variations/{variation_id}/stores/{store_id}?access_token=$ACCESS_TOKEN

Example:

curl -X POST https://api.mercadolibre.com/items/{item_id}/variations/{variation_id}/stores/{store_id}?access_token=$ACCESS_TOKEN

JSON body

{
  "availability_time_in_hours": 72
}

Example:
An item “T-shirt” with 3 variations (Sizes: S, M, L), availability 48hs in 5 stores is associated to the item (without specifying variation as it is done nowadays), so:

  • All the variations have an availability of 48 hs.
  • If a POST is done for the variation “size M” to the store 3 for 72hs, it will show 48hs for all the stores in all sizes except for the size M of store 3 (where it will show 72hs).

Modify the availability time of a store

curl -X PUT https://api.mercadolibre.com/items/{item_id}/stores/{store_id}?access_token=$ACCESS_TOKEN

Example:

curl -X PUT
https://api.mercadolibre.com/items/MLA12345678/stores/1?access_token=


{
  "availability_time_in_hours": 48
}

Eliminate an available store in an item

To take away the association of an available store to a publication, you should make a delete.

curl -X DELETE https://api.mercadolibre.com/items/{item_id}/stores/{store_id}?access_token=$ACCESS_TOKEN

Example:

curl -X DELETE https://api.mercadolibre.com/items/MLA12345678/stores/1?access_token=ACCESS_TOKEN

Identify an item with associated stores

Nowadays, an item indicates that it offers, or not, “Pickup in Store” in the following way: local_pick_up: true | false. Independently, we will add the field that will show if there are specific stores associated to the item: store_pick_up: true | false.


Check the stores associated to an item

To know which are all the stores associated to an item, the following query can be done:

Call:

curl -X GET https://api.mercadolibre.com/items/$ITEM_ID/stores

Example:

curl -X GET https://api.mercadolibre.com/items/MLX123456789/stores

Response:

{
  "paging": {
    "limit": 50,
    "offset": 0,
    "total": 1
  },
  "results": [
    {
      "id": "16666000",
      "user_id": "144999999",
      "description": "Test",
      "date_creation": "2017-09-24T16:00:40.327726325-04:00",
      "open_hours": "Lunes a sábados de 9 a 20:30 hs.",
      "status": "active",
      "phone": {
        "area_code": "11",
        "number": "2222-2222"
      },
      "location": {
        "address_line": "Av. 9 de Julio 1000",
        "latitude": -10.660000,
        "longitude": -50.720000,
        "availability_time_in_hours": 120
      }
    }
  ]
}

Identify an order with pick up in store

Within the json of an order, it can be identified if the buyer chose, or not, the option to pick up in store. For that, there is the attribute “pickup_id”, that will allow to turn to the new endpoint/pickups, which contains the store the buyer chose to pick up the order. In the event that the order has an associated delivery, in other words, that there is no pickup in store, the pickup_id will be null. When there is a pickup in store created for that order:


Apply the pickups resource

Call:

curl -X GET https://api.mercadolibre.com/pickups/$PICKUP_ID?access_token=$ACCESS_TOKEN

Example:

curl -X GET https://api.mercadolibre.com/pickups/123?access_token=$ACCESS_TOKEN

Response:

{
"id": "12345667",
"store_id": 11332211,
"order_id": 1510999999,
"item_id": "MLA555555555",
"buyer_id": 111111222,
"date_created": "2017-10-20T16:57:26.543801741-04:00",
"date_ready": "2017-10-23T16:57:53-04:00",
"status": "ready_for_pickup",
"store_info": {
"id": "11332211",
"user_id": "166663322",
"description": "DOT",
"date_creation": "2017-10-20T08:39:27.689379203-04:00",
"open_hours": "Lunes a viernes de 11 a 21 hs.",
"status": "active",
"phone": {
"area_code": "011",
"number": "3333 4444"
},
"location": {
"address_line": "Dirección de Test",
"latitude": -34.1111111,
"longitude": -52.2222222
}
},
"pickup_person": {
"full_name": "Juan Gutierrez"
}
}

Status: The initial status of a pickup is always “active”. Once the order is ready to be picked up in store, considering the field “availability_time_in_hours”, it will automatically change to “ready_for_pickup”.


Modify the delivery time

The delivery time of a product can be modified, either to bring forward or to delay the store pickup time. We make available the field "date_override" for those extraordinary cases where it is necessary to overwrite the value in “availability_time_in_hours”. The buyer will receive a notification informing of the delay or that the product is ready to be picked up.


Call:

curl -X PUT https://api.mercadolibre.com/pickups/{pickup_id}?access_token=$ACCESS_TOKEN

Example:

curl -X PUT 
https://api.mercadolibre.com/pickups/13092158?access_token=$ACCESS_TOKEN
{
  "date_override": "2018-06-30T10:42:11-04:00"
}

Response:

{
    "id": "13092158",
    "store_id": 12859008,
    "order_id": 1745150310,
    "item_id": "MLB997548861",
    "buyer_id": 311800820,
    "date_created": "2018-06-26T20:50:46Z",
    "date_ready": "2018-06-28T08:50:47Z",
    "date_override": "2018-06-30T10:42:11-04:00",
    "status": "active",
    "store_info": {
        "id": "",
        "description": null,
        "date_creation": "0001-01-01T00:00:00Z",
        "open_hours": null,
        "status": null,
        "phone": null,
        "location": null
    },
    "pickup_person": {
        "full_name": "Nombre y apellido"
    }
}

Considerations

  • The format of the field "date_override" is: "2017-11-09T10:42:11-04:00"
  • The resource /pickups will only show when making a GET to the “date_override” field, with a value other than null.
  • The PUT can be made as long as the pickup status is “active”.
  • The date_ready field keeps the original date of when the pickup was created. The date_override since it has a value different to null, will be the one that determines when the product will be available at the store.

Change the pickup status to delivered

In order to change the pickup status to “delivered”, you need to rate following the traditional feedback flow i.e., making a PUT to the order. Once that is done, the pickup status in the resource is automatically updated.

Call:

curl -X POST https://api.mercadolibre.com/orders/$ORDER_ID/feedback?access_token=$ACCESS_TOKEN

Example:

curl -X POST https://api.mercadolibre.com/orders/1766688268/feedback?access_token=$ACCESS_TOKEN

{ 
    "fulfilled": "true", 
    "rating": "positive"
}

Response:

{
    "status": "hidden",
    "reason": null,
    "site_id": "MLB",
    "date_created": "2018-07-25T15:18:44.571-04:00",
    "cust_role": "seller",
    "reply_status": null,
    "order_id": 1766688268,
    "id": 9040862017153,
    "message": "",
    "cust_from": 305860144,
    "fulfilled": true,
    "reply_date": null,
    "visibility_date": null,
    "reply": null,
    "cust_to": 311800820,
    "rating": "POSITIVE"
}

The options for the fields are:

  • fulfilled -> "true", "false",
  • rating -> "positive", "negative", "neutral"

Possible status of a pickup

ACTIVE: the initial status of the pickup.
READY FOR PICKUP: it is shown when the deadline is met in the field “availability_time_in_hours”.
DELIVERED: it is shown when the seller states that the order was delivered but the buyer hasn’t confirmed it yet.
FINISHED: it is shown when both parties confirm that the order was delivered.


How to receive the details to generate an invoice

To know how to receive the details to generate an invoice we have a new resource that allows you to receive the buyer’s details to generate an invoice. We invite you to check the following documentation.