Receive stock notifications from Fulfillment

Configure your application with Mercado Libre notifications and you will be able to choose the marketplace_fbm_stock option to subscribe to fulfillment stock notifications.

Check operations

Get the list of stock operations for a particular inventory_id.

Parameters

inventory_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: operation type (inbound_reception, sale_confirmation, etc.)
external_references

• external_references.shipment_id: identifier of the shipment to the buyer.

limit: number of records to return per results “page”.
sort: field identifier and search order.

Request:

curl -X GET -H 'Authorization: Bearer $ACCESS_TOKEN' https://api.mercadolibre.com/marketplace/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/marketplace/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/marketplace/stock/fulfillment/operations/search?seller_id=384741716&inventory_id=NFWV18668&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": "ADJUSTMENT",
            "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,
            "inventory_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,
            "inventory_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,
            "inventory_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": []
}

Rules

• In the search for operations, the maximum query range is 60 days
• The date filter is not mandatory, but if you do not put them, bring the last 15 days

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 inventory ESZJ28231",
    "error": "forbidden",
    "cause": []
}

Errors examples

Status	Message	Error	Description
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 request limit parameter 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 greater 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
429	Too many request	too_many_request	The user has exceeded the number of requests allowed per minute
500	Internal server error	internal_error	Intern error




Search mode by scroll

Work with scroll + limit

El scroll it is used to get the list of stock operations for a particular inventory_id.

El limit is the number of records to return per "page" of results and scroll is the attribute that allows the results to be paged. To use it you must:

• Get a scroll field in the result that expires after 5 minutes.
• Add to the query the scroll obtained in the first GET. If you don't use the limit parameter, by default the maximum 1000 results per page is set.

Request to check the operations:

curl -X GET -H 'Authorization: Bearer $ACCESS_TOKEN' http://api.mercadolibre.com/marketplace/stock/fulfillment/operations/search?seller_id=$SELLER_ID&inventory_id=$INVENTORY_ID&date_from=$aaammdd&date_to=$aaammdd

Response:

"scroll":"YXBpY29yZS1pdGVtcw==:ZHMtYXBpY29yZS1pdGVtcy0wMQ==:DXF1ZXJ5QW5kRmV0Y2gBAAAAABIu7AgWMXl6anF3SU5SMVNaQXFxTkZubHBqQQ=="

We add the scroll obtained in the previous step:

curl -X GET -H 'Authorization: Bearer $ACCESS_TOKEN' https://api.mercadolibre.com/marketplace/stock/fulfillment/operations/search?seller_id=$SELLER_ID&inventory_id=$INVENTORY_ID&date_from=$aaammdd&date_to=$aaammdd&scroll=YXBpY29yZS1pdGVtcw==:ZHMtYXBpY29yZS1pdGVtcy0wMQ==:DXF1ZXJ5QW5kRmV0Y2gBAAAAABIu7AgWMXl6anF3SU5SMVNaQXFxTkZubHBqQQ==

To continue getting the next pages of results, just do the same GET until you reach the end. Only when scroll = null means that we reached the end and there are no more results.




Check operations with ID

You can obtain the details of a particular operation executed on the stock that the seller has stored in the Fulfillment warehouses.

Parameter

operation_id: operation id identifier

Request:

curl -X GET -H 'Authorization: Bearer $ACCESS_TOKEN' http://api.mercadolibre.com/marketplace/stock/fulfillment/operations/$OPERATION_ID

Example:

curl -X GET -H 'Authorization: Bearer $ACCESS_TOKEN' http://api.mercadolibre.com/marketplace/stock/fulfillment/operations/329663159

Response:

{
    "id": "329663159",
    "seller_id": 404584692,
    "inventory_id": "FIWU34511"
    "date_created": "2020-06-29T13:45:13Z"
    "type": "SALE_CONFIRMATION"
    "detail":{
           "available_quantity": -1
     "not_available_detail":[]
     },
    "result":{
           "total": 1
           "available_quantity": 0
     "not_available_detail":[
         {
            "status": "damaged",
            "quantity": 1,
         }
     ]
     },
     "external_references":[
   {
      "type": "shipment_id",
      "value": "28518304587",
   }
     ]
}

Errors example

Status	Message	Error	Description
400	Invalid operation_id abc34567	invalid_param	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
404	Operation not found	not_found	The requested operation cannot be found
500	Internal server error	internal_error	Internal error when obtaining the information



Nota:
La fecha de consulta retorna hasta el día -1. En este caso, retorna las operaciones desde el 29/06 hasta el 27/07, o sea no incluye el día 28.

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:

- 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.

• id: identifier of the stock operation
• seller_id: identifier of the seller who owns the inventory
• inventory_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.)

result: stock status

• 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.

status: item status not available.
quantity: number of items in the assigned state.
external_references: references to the entities that generate the operation.

• type: type of external reference, they can be:
• shipment_id: identifier of the shipment to the buyer.



Operations types

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.





Outbound

sale_confirmation: confirms the reservation of units for sale.
sale_cancelation: cancel the reservation of units for sale.
sale_delivery_cancelation: 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_removal: stock removed by abandon withdrawal.




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).
damaged_removal: removed and reimbursed for units damaged in FULL.




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.





Stock adjustments

ajustement: internal stock adjustments generated by the operation.




Next: Pictures.