Fulfillment stock
Get the inventory_id
To query the stock and the operations of the item in fulfillment, you must first get the inventory_id which is the code that identifies the item when it is in fulfillment. For this, consult the inventory_id through the /items resource.
Request:
curl -X GET -H 'Authorization: Bearer $ACCESS_TOKEN' https://api.mercadolibre.com/items/$ITEM_ID
Example:
curl -X GET -H 'Authorization: Bearer $ACCESS_TOKEN' https://api.mercadolibre.com/items/MLB1557246024
Response:
{
"id": "MLB1557246024",
"site_id": "MLB",
"title": "Kit Capa Chuva Test 228",
"subtitle": null,
"seller_id": 384324657,
"category_id": "MLB22675",
"official_store_id": null,
"price": 87,
"base_price": 87,
"original_price": null,
"inventory_id": "LCQI05831",
"currency_id": "BRL",
"initial_quantity": 50,
"available_quantity": 50,
"sold_quantity": 0,
"sale_terms": []
}
Check the seller's stock
Also, you can check the total stock of a seller in all Fulfillment warehouses and know the status of the unavailable parts.
Request:
curl -X GET -H 'Authorization: Bearer $ACCESS_TOKEN' https://api.mercadolibre.com/inventories/$INVENTORY_ID/stock/fulfillment
Example:
curl -X GET -H 'Authorization: Bearer $ACCESS_TOKEN' https://api.mercadolibre.com/inventories/LCQI05831/stock/fulfillment
Response:
{
"inventory_id": "LCQI05831",
"total": 20,
"available_quantity": 5,
"not_available_quantity": 15,
"not_available_detail":[
{
"status": "damage",
"quantity": 2
},
{
"status": "lost",
"quantity": 1
},
{
"status": "noFiscalCoverage"
"quantity": 5
},
{
"status": "withdrawal",
"quantity": 5
},
{
"status": "internal_process",
"quantity": 1
},
{
"status": "transfer",
"quantity": 1
}
],
"external_references": [
{
"type": "item",
"id": "MLB1557246024",
"variation_id": 4742223403
}
]
}
Response fields
total: is the sum of the available_quantity and not_available_quantity fields.
available_quantity: quantity of items available for sale.
not_available_quantity: total items that are not available for sale.
not_available_detail: detail of the status of the items that are not available.
- damaged: total of damaged items (includes damaged seller, meli and carrier).
- lost: total items that were lost and not found.
- withdrawal: total items reserved for pick up.
internal_process: total of items reserved by quality processes of the warehouse.
transfer: total reserved to be transferred deposit.
noFiscalCoverage: total items that are not for sale because they do not have tax coverage.
not_supported: all items entered are unidentifiable or unprocessable.
external_references: information on the relationship of the seller product with the marketplace publication, and an identification of the type.
type: type of relationship between publication and stored stock.
id: identifier of the item related to the seller product.
variation_id: identifier of the variation associated with the seller product.
Errors
Response with error:
{
"status": 403,
"error": "forbidden",
"message": "User 281349747 cannot access to seller_product ESZJ28231",
"cause": []
}
Possible errors
Status | Mensaje | Error | Descripción |
---|---|---|---|
404 | Seller product not found with id: ESZJ28232 | seller_product_not_found | The requested seller product cannot be found |
400 | The field seller_product_id has an invalid value | validation_error | Invalid parameter |
403 | The caller is not authorized to access this resource | forbidden | The caller is not authorized to access the resource |
401 | No autorizado | unauthorized | The caller is not authenticated on the platform |
429 | Too many request | too_many_request | The user has exceeded the number of requests allowed per minute |
500 | Internal server error | internal_error | Internal error to get the information |
Consult operations
You can then get the list of stock operations for a particular seller_product_id.
Parameters
seller_product_id: comma separated list of identifiers.
seller_id: seller identifier.
date_from: search start date. If you don't define it in the GET, by default it is 15 days.
date_to: search end date. If you don't define it in the GET, by default it is the current date.
type: type of operation (inbound_reception, sale_confirmation, others).
external_references
- external_references.shipment_id: identifier of the shipment to the buyer.
limit: number of records to return per “page” of results.
sort: field identifier and search order.
Request:
curl -X GET -H 'Authorization: Bearer $ACCESS_TOKEN' https://api.mercadolibre.com/stock/fulfillment/operations/search?seller_id=$SELLER_ID&inventory_id=$INVENTORY_ID&date_from=$aaammdd&date_to=$aaammdd
Example:
curl -X GET -H 'Authorization: Bearer $ACCESS_TOKEN' https://api.mercadolibre.com/stock/fulfillment/operations/search?seller_id=384324657&inventory_id=DEHW09303&date_from=2020-06-01&date_to=2020-06-30
Example with filters:
curl -X GET -H 'Authorization: Bearer $ACCESS_TOKEN' https://api.mercadolibre.com/stock/fulfillment/operations/search?seller_id=384741716&inventory_id=NFWV18668&caller.id=384741716&date_from=2020-06-29&date_to=2020-07-28&type=SALE_CONFIRMATION&external_references.shipment_id=1111
Response:
{
"paging": {
"total": 4,
"scroll": ""
},
"results": [
{
"id": 306811273,
"seller_id": 384324657,
"inventory_id": "DEHW09303",
"date_created": "2020-06-18T18:43:26Z",
"type": "STOCK_AUDIT",
"detail": {
"available_quantity": -5,
"not_available_quantity": 5,
"not_available_detail": [
{
"status": "lost",
"quantity": 5
}
]
},
"result": {
"total": 100,
"available_quantity": 95,
"not_available_quantity": 5,
"not_available_detail": [
{
"status": "lost",
"quantity": 5
}
]
},
"external_references": []
},
{
"id": 306745917,
"seller_id": 384324657,
"seller_product_id": "DEHW09303",
"date_created": "2020-06-18T18:15:13Z",
"type": "SALE_CANCELATION",
"detail": {
"available_quantity": 10,
"not_available_detail": []
},
"result": {
"total": 100,
"available_quantity": 100,
"not_available_quantity": 0,
"not_available_detail": []
},
"external_references": [
{
"type": "shipment_id",
"value": "28312959315"
}
]
},
{
"id": 306718974,
"seller_id": 384324657,
"seller_product_id": "DEHW09303",
"date_created": "2020-06-18T18:02:33Z",
"type": "SALE_CONFIRMATION",
"detail": {
"available_quantity": -10,
"not_available_detail": []
},
"result": {
"total": 90,
"available_quantity": 90,
"not_available_quantity": 0,
"not_available_detail": []
},
"external_references": [
{
"type": "shipment_id",
"value": "28312961122"
}
]
},
{
"id": 306705012,
"seller_id": 384324657,
"seller_product_id": "DEHW09303",
"date_created": "2020-06-18T17:55:42Z",
"type": "INBOUND_RECEPTION",
"detail": {
"available_quantity": 100,
"not_available_detail": []
},
"result": {
"total": 100,
"available_quantity": 100,
"not_available_quantity": 0,
"not_available_detail": []
},
"external_references": [
{
"type": "inbound_id",
"value": "0001"
}
]
}
],
"filters": [],
"available_filters": [],
"available_sort": [],
"sort": [],
"available_sorts": []
}
Response fields
Paging
- limit: number of records to return per “page” of results. By default it will be 1000
- scroll: scroll id from which the search continues. When it returns scroll = null means that it has no more records on the next page. The scroll rules are:
- id: identifier of the stock operation
- seller_id: identifier of the seller who owns the seller product
- seller_product_id: product identifier in the warehouse
- date_created: creation date of the operation (type date UTC)
- type: type of operation executed (income, sale, sale canceled, etc.)
- available_quantity: quantity of products available for sale.
- not_available_quantity: total of products that are not available.
- not_available_detail: detail of the status of the different unavailable units.
- type: type of external reference, they can be:
- shipment_id: identifier of the shipment to the buyer.
- In the result you get a scroll_id field that expires in 5 minutes.
- You must add the same scroll_id to the query of the field obtained previously.
- If you don´t use the limit parameter, it will return 1000 operations of the total by default. You can add a maximum limit of 1000.
- To continue getting the next pages of results, just do the same GET to the request until you reach the end of the list.
results: list of operations found.
result: stock status
status: item status not available.
quantity: number of items in the assigned state.
external_references: references to the entities that generate the operation.
Types of operations
These types of operations reflect the interactions of the different flows in the stored units.
Inbound
inbound_reception Ingreso de stock: The inbound process makes units available for sale at the end of the income stream. They can have: Entry of units that arrived damaged. Entry of units without tax coverage (only for Brazil). fiscal_coverage_ajustment: adjustment of fiscal coverage (only for Brazil).
Outbound
sale_confirmation: confirms the reservation of units for sale.
sale_cancelation: cancel the reservation of units for sale.
sale_delivery_cancelation
Venta no entregada: it was not possible to deliver to the buyer and returns to the deposit.
sale_return: sales return by buyer.
Withdrawal
This is the seller's withdrawal request.
withdrawal_reservation: reserve units for a stock picked.
withdrawal_cancelation: total or partial cancellation of withdrawal reservation, the reservation of units for a stock picked is canceled.
withdrawal_delivery: the seller physically pick up the reserved units.
withdrawal_discarded: stock removal requested by the seller.
Transfer
It is about the internal management of the stock by Mercado Libre, not the seller.
transfer_reservation: units are reserved for a multi-warehouse transfer or pick up.
transfer_ajustment: after inspecting the units, the quality status is determined and restocked as available or damaged.
transfer_delivery: enter the units in transfer.
Quarantine
It's about internal management over quality control.
quarantine_reservation: They reserve units by the quality area for inspection.
quarantine_restock: After inspecting the units, determine the quality status and restock as available or damaged.
lost_refund: permanent cancellation of lost units (refunded).
Removal QA
This is an internally driven retreat.
removal_reservation: after inspecting the units, the quality status is determined and they are retired.
removal_completion: units with poor quality status are eliminated.
stranded_disposal_removal: stock removal due to lack of rotation.
Stock adjustments
ajustement: internal stock adjustments generated by the operation.
Example with available filters:
"available_filters": [
{
"id": "inventory_id",
"name": "inventory id"
},
{
"id": "date_from",
"name": "Date created from"
}
]
Example with selected filters:
"filters": {
{
"id": "inventory_id",
"name": "inventory id"
"values": [
"ESZJ28231"
]
}
]
Possible errors:
Response with error:
{
"status": 403,
"message": "User 281349747 cannot access to seller_product ESZJ28231",
"error": "forbidden",
"cause": []
}
Errors examples
Status | Mensaje | Error | Descripción |
---|---|---|---|
400 | The field ‘seller_id’ is required | validation_error | The seller_id parameter is not found |
400 | The field ‘type’ has an invalid value | validation_error | Invalid parameter |
400 | The limit param must be greater than 0 | validation_error | The limit parameter of the call must be greater than 0 |
400 | Date range can’t be greater than “60” days | validation_error | The date range exceeds the limit allowed by days |
400 | The field date_from and date_to are required | validation_error | The date_from and date_to fields are required |
400 | The field date_from and date_to are required | validation_error | The date_from field cannot be bigger than or equal to the date_to field |
403 | Access denied for user 30265782 | forbidden | The caller is not authorized to access the resource |
401 | No autorizado | unauthorized | |
500 | Internal server error | internal_error | Internal error |