Documentation Mercado Libre

Check out all the necessary information about APIs Mercado Libre.
circulos azuis em degrade

Documentation

Last update 05/05/2026
FAQs › Multi-origin stock management / User Products

Multi-origin stock management / User Products


How should I update stock when the account has multi-origin / multi-warehouse management?

When the account has multi-origin, available_quantity should not be used on the /items endpoint. Stock is managed per warehouse and there are specific User Products endpoints for this: /user-products/{user_product_id}/stock/type/{seller_warehouse} (for seller warehouses) or the multi-origin stock endpoints. Updating available_quantity via /items will be ignored or return an error; stock must be updated by location (stores/warehouses) using the User Products endpoints.

Recommendation
Use User Products endpoints per seller_warehouse for all stock updates on multi-origin accounts, and ensure the user_product_id and locations are initialized before modifying quantities.
Why do I get "stock-locations not found" when querying /user-products/{id}/stock?

This error appears when the User Product has no initialized stock or no locations created; the stock resource does not exist until stock is created at the locations. The solution is to create the corresponding stock locations via the stock write endpoints (using seller_warehouse) before querying.

Recommendation
Ensure stock locations (store_id, network_node_id) are created for the user_product before reading or updating stock.
Which endpoint should I use for accounts in Mexico (MLM) with Full + Flex? Can I use selling_address?

The selling_address endpoint (/user-products/{id}/stock/type/selling_address) is only enabled for sites such as MLA and MLC. It is not available on sites like MLM; in those cases, use seller_warehouse management or the multi-origin flow supported for that market. The selling_address flow is not the same across all regions.

Recommendation
Verify selling_address availability per site and, if not supported, implement updates via seller_warehouse or the market-specific multi-origin flow.
Why does a PUT update to /items for available_quantity sometimes return OK but the stock doesn't change?

If the account has multi-origin or warehouse-based stock, a /items PUT with available_quantity may return 200 but not update the actual stock. On accounts with warehouse_management, stock must be updated via User Products (stock endpoint per seller_warehouse); the /items API does not modify stock in multi-origin mode.

Recommendation
Check whether the account uses warehouse_management and use User Products endpoints for stock changes in multi-origin mode.
How do I enable or associate a warehouse to an existing product?

The documentation states that creating/updating stock for multiwarehouse requires creating stock locations associated with the user_product via the stock endpoint. If network_node_id or stock-locations are missing, the operation fails; locations must be created and associated before updating stock.

Recommendation
Create and associate stock_locations with the required fields (store_id, network_node_id) before attempting to publish or update multiwarehouse stock.
Why does "the site is blocked for modifications to the selling address" appear when updating stock via API?

This message indicates you are using a selling_address endpoint not supported for that site. The ability to modify selling_address only exists on sites like MLA/MLC; on other sites (e.g. MLB) you must use seller_warehouse or the stock endpoint corresponding to that market.

Recommendation
Confirm which stock types (selling_address vs seller_warehouse) are enabled for the site and use the corresponding endpoint.
How do I detect if a User Product is in multi-origin mode and which endpoint should I use to update stock?

Check whether the item has stock_locations or a user_product_id; then query /user-products/{user_product_id}/stock. If the locations show type:seller_warehouse, it is in multi-origin mode and stock must be updated by location (seller_warehouse). Do not use available_quantity in /items if the account is in multi-origin mode.

Recommendation
Verify the presence of stock_locations and the location type before deciding on the stock update flow.
What happens if I try to publish multiwarehouse without including stock_locations?

The publication will fail with errors (e.g. validation error or stock-locations not found). You must provide valid stock_locations (store_id, network_node_id) and ensure the stores/warehouses are configured for the seller before creating or updating multiwarehouse items.

Recommendation
Always include complete and validated stock_locations when creating or publishing multiwarehouse items to avoid rejections.
When creating a multiwarehouse item I get "Conflict. Try again later" (409) with no further details. What can cause this conflict?

A 409 generally indicates conflicts from concurrent modifications or resource collisions (e.g. a SKU or GTIN already associated with another user_product) or attempts to create resources that already exist. It can also occur from simultaneous changes to the same key.

Recommendation
Implement retries with backoff, ensure SKU/GTIN uniqueness, and update existing user_products instead of creating duplicates.
If a listing is configured Full + Flex, can I update the FLEX stock via API in MLB?

On some sites, updating stock via selling_address for Flex is not enabled; in Mercado Libre Brazil this option is generally blocked and Full stock is usually managed by Mercado Libre, so it is not modifiable via the seller API.

Recommendation
Confirm the site's capabilities and use seller_warehouse where applicable; if Full+Flex coexists, expect certain locations to be managed by Mercado Libre's operation.
Why does a listing become "paused — out_of_stock" during multi-warehouse synchronization and how long does this process take?

During multi-warehouse synchronization the marketplace may pause listings while processing locations and stock; this process is asynchronous and can take more than a day in some cases, after which listings are automatically reactivated if stock is available.

Recommendation
Monitor process completion and ensure stock_locations are correctly configured to avoid prolonged pauses.