Documentation Mercado Libre
Check out all the necessary information about APIs Mercado Libre.
Documentation
Total and partial refund
Benefits
- The seller will be able to recover a proportional amount of the sale of the product, the sales fee and the shipping fees.
- Applies to all types of claims: different, defective, incomplete product and buyer's regret.
- If the seller offers Partial Refunds before 72 hours the opened claim, it will not affect their reputation and therefore if the buyer accepts the offer it does not impact too.
Partial refund view in Global Selling
Confirmation: through this interface, the seller is informed of the benefits and what will happen when the partial is offered (this part should be reflected in the manual) and later, by clicking on the confirm button, the proposal is sent to the buyer.
Total Refund: initially, it is validated if it is possible to make a total refund.
By clicking on the refund money button, the following interface is displayed through this interface the Seller returns the entire amount of the product.
Check claims
To provide a better experience, we recommend you check open claims: If the reason_id field is PDD, validate that it can offer a partial or full refund through the available_actions tag, containing refund (for Total refund) or allow_partial_refund (for Partial refund):
Example:
curl -X GET -H 'Authorization: Bearer $ACCESS_TOKEN' https://api.mercadolibre.com/marketplace/claims/search?stage=dispute&status=openedResponse with Total refund option
In the event that the claim has a total refund available, in the claim info, specifically in the available_actions tag for the seller-type player, there must be an action refund:
{
"id": 123,
"type": "mediations",
"stage": "dispute",
"status": "opened",
"parent_id": null,
"client_id": null,
"resource_id": 123,
"resource": "order",
"reason_id": "PDD9562",
"fulfilled": true,
"players":
[
{
"role": "complainant",
"type": "buyer",
"user_id": 1232,
"available_actions":
[]
},
{
"role": "respondent",
"type": "seller",
"user_id": 1234,
"available_actions":
[
{
"action": "send_message_to_mediator",
"due_date": null,
"mandatory": false
},
{
"action": "refund",
"due_date": null,
"mandatory": false
}
]
}
],
"resolution": null,
"labels": null,
"site_id": "MLB",
"date_created": "2022-03-17T15:45:55.000-04:00",
"last_updated": "2022-03-22T22:57:12.000-04:00"
}If the claim is enabled to offer a total refund, you can offer a total refund.
Response with Partial refund option
In case the claim has a partial refund available, in the claim info, especially in the array available_actions of the seller, it must have the action allow_partial_refund.
{
"id": 123,
"type": "mediations",
"stage": "claim",
"status": "opened",
"parent_id": null,
"client_id": null,
"resource_id": 123,
"resource": "order",
"reason_id": "PDD9551",
"fulfilled": true,
"players":
[
{
"role": "complainant",
"type": "buyer",
"user_id": 123,
"available_actions":
[]
},
{
"role": "respondent",
"type": "seller",
"user_id": 123,
"available_actions":
[
{
"action": "send_message_to_complainant",
"due_date": "2023-01-27T22:43:59.000-04:00",
"mandatory": true
},
{
"action": "refund",
"due_date": null,
"mandatory": false
},
{
"action": "allow_partial_refund",
"due_date": null,
"mandatory": false
}
]
}
],
"resolution": null,
"labels": null,
"site_id": "MLB",
"date_created": "2023-01-23T09:59:05.000-04:00",
"last_updated": "2023-01-23T11:18:01.000-04:00"
}If the claim is available to offer a partial refund:
1. The seller must consult the percentage and amount of return that allows him to obtain the percentages available to offer and its equivalence with respect to the amount of the product.
2. Then the seller offers partial refund, which will send the buyer the seller's offer.
Percentage and amount of return
Check the refund percentages available for a partial refund and how much would be the amount to be refunded. See more about make a good partial refund offer.
Request:
curl -X GET -H 'Authorization: Bearer $ACCESS_TOKEN' -H 'Content-Type: application/json' https://api.mercadolibre.com/marketplace/claims/$CLAIM_ID/partial_refund/percentageExample:
curl -X GET -H 'Authorization: Bearer $ACCESS_TOKEN' -H 'Content-Type: application/json' https://api.mercadolibre.com/marketplace/claims/5154622534/partial_refund/percentageResponse:
{
"default_percentege":50,
"pencentages_refund_partial":
[
{
"value": "100 USD",
"percentage": 100
},
{
"value": "90 USD",
"percentage": 90
},
{
"value": "80 USD",
"percentage": 80
},
{
"value": "70 USD",
"percentage": 70
},
{
"value": "60 USD",
"percentage": 60
},
{
"value": "50 USD",
"percentage": 50
},
{
"value": "40 USD",
"percentage": 40
},
{
"value": "30 USD",
"percentage": 30
},
{
"value": "20 USD",
"percentage": 20
}
]
}Response fields
default_percentage: defect returns percentage.
pencentages_refund_partial: available partial returns percentage.
value: amount in US dollars (USD).
percentage: percentage of return representing the above amount.
If the claim is not available to do a partial refund, the response will be something like:
{
"message": "the claim does not have the partial refund enabled.",
"error": "forbidden",
"status": 403,
"cause": []
}Offer partial refund
To offer a partial refund, the claim must be PDD with expected_resolution return_product and status pending.
1. Check the possible amount and percentages available to offer partial refund (Consult percentage and return amount).
2. Choose percentage to return: if you don't send a return percentage, by default will be assigned default_percentege.
Request:
curl -X POST -H 'Authorization: Bearer $ACCESS_TOKEN' https://api.mercadolibre.com/marketplace/claims/$CLAIM_ID/expected_resolutionsExample:
curl -X POST -H 'Authorization: Bearer $ACCESS_TOKEN' https://api.mercadolibre.com/marketplace/claims/950463475/expected_resolutions - d
{
"expected_resolution": "allow_partial_refund",
"detail": {
"key": "percentage",
"value": "50.0"
}
}Response:
[
{
"player_role": "complainant",
"user_id": 710928120,
"expected_resolution": "return_product",
"detail": [],
"date_created": "2022-11-04T12:23:44.000-05:00",
"last_updated": "2022-11-04T12:23:44.000-05:00",
"status": "rejected"
},
{
"player_role": "respondent",
"user_id": 823876519,
"expected_resolution": "partial_refund",
"detail": [
{
"key": "percentage",
"value": "50.0"
},
{
"key": "seller_amount",
"value": "114.52"
},
{
"key": "seller_currency",
"value": "R$"
}
],
"date_created": "2022-11-04T12:43:06.000-05:00",
"last_updated": "2022-11-04T12:43:06.000-05:00",
"status": "pending"
}
]If you send a different amount from the allowed ones, you will get this response:
{
"message": "Percentage not found 35.0",
"error": "error checking configuration percentage",
"status": 400,
"cause": []
}In case the seller does not have a partial-refund enabled, it will be:
{
"message": "Action allow_partial_refund not available for player",
"error": "bad_request",
"status": 400,
"cause": []
}- If the partial refund is accepted by the buyer: the claim is closed and the money corresponding to the percentage offered will be returned to the buyer.
- If the partial_refund is not accepted by the buyer: the expected_resolution partial_refund will have status rejected.
Offer total refund
For claims of type PDD and PNR, with expected_resolution refund and status pending, you can offer a total refund as follows.
Request filtering the above conditions:
curl -X POST -H 'Authorization: Bearer $ACCESS_TOKEN' https://api.mercadolibre.com/marketplace/claims/$CLAIM_ID/expected_resolutionsExample:
curl -X POST -H 'Authorization: Bearer $ACCESS_TOKEN' https://api.mercadolibre.com/marketplace/claims/950463475/expected_resolutions - d
{
"expected_resolution": "refund",
"detail": {}
}Response:
{
"player_role": "complainant",
"user_id": 710928120,
"expected_resolution": "return_product",
"detail": [],
"date_created": "2022-11-04T12:23:44.000-05:00",
"last_updated": "2022-11-04T12:23:44.000-05:00",
"status": "pending"
}Response fields
player_role: claim player role.
user_id: claim player ID.
expected_resolution: claim resolution loaded by the player specified in the above parameter. possible values are:
- refund: the player expects a money refund.
- product: the player expects to receive the product.
- change_product: the player expects to change the product.
- return_product: the player expects to have the product returned with the.
- allow_partial_refund: the player offers an order amount partial refund.
detail: show us additional information about the expected resolution, for example: which was the percentage seller offer.
date_created: expected resolution creation date.
last_updated: time when the expected resolution was last updated.
status:expected resolution status. It may take one of the following values:
- pending: the player loaded the expected resolution, but its counterparty has not accepted it yet.
- accepted: the resolution loaded by the player was accepted by its counterparty or, otherwise, by Mercado Libre's mediator.
- rejected: the player does not accept the expected resolution.
The claims must be in an expected_resolution: return_product y status: pending.
{
"player_role": "complainant",
"user_id": 710928120,
"expected_resolution": "return_product",
"detail": [],
"date_created": "2022-11-04T12:23:44.000-05:00",
"last_updated": "2022-11-04T12:23:44.000-05:00",
"status": "rejected"
}Considerations
When you offer a total refund, the previous expected_resolution that was next to the seller player_role: complainant must be in status rejected and a new expected_resolution = refund will be created, where status is equal to accepted and the response must be next to the buyer player_role: complainant.
[
{
"player_role": "complainant",
"user_id": 710928120,
"expected_resolution": "return_product",
"detail": [],
"date_created": "2022-11-04T12:23:44.000-05:00",
"last_updated": "2022-11-04T12:23:44.000-05:00",
"status": "rejected"
},
{
"player_role": "complainant",
"user_id": 823876519,
"expected_resolution": "refund",
"detail": [],
"date_created": "2022-11-04T12:43:06.000-05:00",
"last_updated": "2022-11-04T12:43:06.000-05:00",
"status": "accepted"
}
]When you offer a total refund, the claim will be closed and the money will be returned to the buyer.
Send notifications
When a partial refund offer or a full refund closing is made, the seller will be notified through the marketplace claim topic.
We recommend that you notify the seller when some kind of interaction from the seller is required to continue the resolution flow. For this, there must be a status change of the expected_resolution that is notified to the seller.