Distributed Stock

Distributed Stock aims to allow sellers to set up different stock locations (stock_locations) for the same User Product.

Types of Stock

For stock management, we define the following three types of stock_locations:

Location Type	Use Case	Stock Manager	Allows Editing Stock via API
meli_facility	The seller sends their stock to Mercado Livre's Fulfillment warehouses.	Mercado Livre (Full)	No.
selling_address	The seller's origin warehouse when they have Flex stock in listings that are also in Mercado Livre Fulfillment (meli_facility).	User (Seller)	Yes, as long as the item has Flex enabled.
seller_warehouse	Multiple stock origins managed by the seller. Allows the seller to manage stock from multiple warehouses that correspond to the locations where they have their inventory.	User (Seller)	Yes, provided the seller has at least one warehouse set up.

Get Stock Details

Please note that the same UP can have up to two typologies, either (selling_address and meli_facility) or (seller_warehouse and meli_facility).

To inquire about the stock associated with a User Product, you must make the following request.

Call:

curl -X GET https://api.mercadolibre.com/user-products/$USER_PRODUCT_ID/stock -H 'Authorization: Bearer $ACCESS_TOKEN'

Example:

curl -X GET https://api.mercadolibre.com/user-products/MLAU123456789/stock -H 'Authorization: Bearer $ACCESS_TOKEN'

Example response for selling_address typology:

{
  "locations": [
    {
      "type": "selling_address",
      "quantity": 5
    }
  ],
  "user_id": 1234,
  "id": "MLBU206642488"
}

Example response for meli_facility typology:

{
  "locations": [
    {
      "type": "meli_facility", // fulfillment
      "quantity": 5
    }
  ],
  "user_id": 1234,
  "id": "MLBU206642488"
}

Example response for seller_warehouse typology:

{
   "locations": [
       {
           "type": "seller_warehouse",
           "network_node_id": "MXP123451",
           "store_id": "9876543",
           "quantity": 15
       },
       {
           "type": "seller_warehouse",
           "network_node_id": "MXP123452",
           "store_id": "9876553",
           "quantity": 15
       }
   ],
   "user_id": 1234,
   "id": "MLAU123456789"
}

Considerations:

• When inquiring about stock details, a header called x-version will be returned, which will have an integer value (of type long) representing the current version of /stock/.
• This header must be sent when making PUT calls to the /stock/ resource.
• If it is not sent, it will return a bad request (status code: 400).
• Additionally, if the version sent is not the latest, a conflict will be returned (status code: 409).
• In the case of a response with code 409, you should consult the stock again to obtain the updated version of the x-version header.

Manage Stock

Use the following call to send the stock quantity at the User Products level for these two types of stock locations selling_address and meli_facility.

Call:

curl -X PUT https://api.mercadolibre.com/user-products/$USER_PRODUCT_ID/stock/type/selling_address 
-H 'Content-Type: application/json' -H 'Authorization: Bearer $ACCESS_TOKEN' -H 'x-version: $HEADER' 
-d '{
    "quantity": $STOCK_QUANTITY
}'

Example:

curl -X PUT https://api.mercadolibre.com/user-products/MLAU123456789/stock/type/selling_address 
-H 'Content-Type: application/json' -H 'Authorization: Bearer $ACCESS_TOKEN' -H 'x-version: 1' 
-d '{
    "quantity": 10
}'

Response Status Codes:

Code	Message	Description	Recommendation
204	OK	The stock will be asynchronously updated in all the sales conditions of the user product.
400	You cannot modify selling address stock if associated items are fulfillment only or no items are associated.
400	You cannot modify selling address stock in items without inventory id.
400	You cannot modify selling address stock because you have to do a full inbound first before modifying.
400	Missing X-Version header	Header “x-version” not provided.	You must provide the “x-version” header.

Next documentation: Multi-origin stock.