Shopping experience

The resource /purchase_experience/ allows you to identify the status of your listings, with the level reached and their corresponding actionable items in case they need to be improved with respect to the shopping experience offered.

Request:

curl -X GET -H 'Authorization: Bearer $ACCESS_TOKEN' https://api.mercadolibre.com/marketplace/items/$ITEM_ID/purchase_experience

Example:

curl -X GET -H 'Authorization: Bearer $ACCESS_TOKEN' https://api.mercadolibre.com/marketplace/items/CBT939406528/purchase_experience

Response:

[
    {
        "item_id": "MLC1755787034",
        "freeze": {
         "text": ""
        },
        "title": {
            "text": "Your shopping experience cannot be measured yet"
        },
        "subtitles": [
            {
                "order": 0,
                "text": "We did not calculate it yet because your listing did not have any orders in the last 180 days."
            }
        ],
        "actions": [],
        "reputation": {
            "color": "gray",
            "value": -1
        },
        "status": {},
        "metrics_details": {
            "empty_state_title": "You had no orders with problems in the last 180 days.",
            "problems": null,
            "distribution": {
                "level_one": null
            }
        }
    },
    {
        "item_id": "MLM1884643783",
        "freeze": {},
        "title": {
            "text": "Your shopping experience cannot be measured yet"
        },
        "subtitles": [
            {
                "order": 0,
                "text": "We did not calculate it yet because your listing did not have any orders in the last 180 days."
            }
        ],
        "actions": [],
        "reputation": {
            "color": "gray",
            "value": -1
        },
        "status": {
            "id": "moderated"
        },
        "metrics_details": {
            "empty_state_title": "You had no orders with problems in the last 180 days.",
            "problems": null,
            "distribution": {
                "from": "2023-04-20T23:41:45Z",
                "to": "2023-10-17T23:41:45Z",
                "level_one": []
            }
        }
    },
    {
        "item_id": "MCO1288981083",
        "freeze": {},
        "title": {
            "text": "Shopping experience"
        },
        "subtitles": [
            {
                "order": 0,
                "text": "There is an issue with this product. Check the tips on how to improve the shopping experience."
            },
            {
                "order": 1,
                "text": "You are providing a good shopping experience."
            }
        ],
        "actions": [
            {
                "order": 0,
                "text": "Edit listing"
            },
            {
                "order": 1,
                "text": "Pause from the list"
            }
        ],
        "reputation": {
            "color": "green",
            "text": "Good",
            "value": 100
        },
        "status": {
            "id": "active"
        },
        "metrics_details": {
            "empty_state_title": "",
            "problems": [
                {
                    "order": 0,
                    "key": "PRODUCT",
                    "color": "#7267E4",
                    "quantity": "1 issue",
                    "cancellations": 0,
                    "claims": 1,
                    "tag": "MAIN ISSUE",
                    "level_two": {
                        "key": "DIFFERENT_FROM_REQUESTED",
                        "title": {
                            "text": "Product didn't match the order"
                        }
                    },
                    "level_three": {
                        "key": "QUALITY_ISSUES",
                        "title": {
                            "text": "The quality of the product was not what the buyer expected"
                        },
                        "remedy": {
                            "text": "Make sure to include the material of the products in the description to avoid complaints related to quality. Try selling products of the best quality in general."
                        }
                    }
                }
            ],
            "distribution": {
                "from": "2023-06-22T02:56:04Z",
                "to": "2023-12-19T02:56:04Z",
                "level_one": [
                    {
                        "key": "PRODUCT",
                        "title": {
                            "text": "With the delivered product"
                        },
                        "color": "#7267E4",
                        "percentage": 100,
                        "quantities_level_two": [
                            {
                                "key": "DIFFERENT_FROM_REQUESTED",
                                "title": {
                                    "text": "Product didn't match the order"
                                },
                                "quantity": 1
                            }
                        ]
                    }
                ]
            }
        }
    }
 ]

Response fields

item_id: identification of the item being checked.
freeze: experience freeze notice due to which no actions are generated over the item.
status: status information of the listing (active | paused | moderated).
title: main reason why the item is in the current status.
subtitles: details due to which the item is in the current status.
actions: possible actionables to edit the current situation of the item
reputation: current color, detail and value of the reputation according to the shopping experience.
metrics_details: details of the problem, levels, possible solutions, actionables and the distribution to give details about the shopping experience of the item.

• Status -> paused

• Status -> active

Fields and Response components

Text

{
    "order": uint,
    "text": string,
    "placeholders": []string,
}

Ejemplo: asdasd {0} asdasd {1}. [0]

• Los {} deberán ser reemplazados por los placeholders.
• Los [] deberán ser reemplazados por los action.

{
        "text": "Por el momento {0}esta publicación no perderá exposición ni será pausada o anulada por brindar experiencia mala o media.{1} Es importante solucionar sus problemas para mejorar la experiencia que brindas.",
        "placeholders": [
            "",
            ""
        ]
}

Freeze

The first part of the freeze wording changes according to the type of freeze applied.

• Req_commercial

"freeze": {
       "text": "Debido a un Acuerdo comercial, {0}esta publicación no perderá exposición, ni será pausada o anulada por tener experiencia de compra mala o media.{1} Ten en cuenta que es importante solucionar los problemas para mejorar la experiencia que brindas.",
       "placeholders": [
           "",
           ""
       ]
   },

• Internal_recovery_grntee

 "freeze": {
       "text": "Debido al Beneficio de reputación, {0}esta publicación no perderá exposición, ni será pausada o anulada por tener experiencia de compra mala o media.{1} Ten en cuenta que es importante solucionar los problemas para mejorar la experiencia que brindas.",
       "placeholders": [
           "",
           ""
       ]
   },

• Internal_recovery

"freeze": {
       "text": "Debido al Beneficio Verde claro, {0}esta publicación no perderá exposición, ni será pausada o anulada por tener experiencia de compra mala o media.{1} Ten en cuenta que es importante solucionar los problemas para mejorar la experiencia que brindas.",
       "placeholders": [
           "",
           ""
       ]
   },

• Internal_newbie_grntee

"freeze": {
       "text": "Debido al Beneficio de reputación, {0}esta publicación no perderá exposición, ni será pausada o anulada por tener experiencia de compra mala o media.{1} Ten en cuenta que es importante solucionar los problemas para mejorar la experiencia que brindas.",
       "placeholders": [
           "",
           ""
       ]
   },

• Rest of freezed

The other freeze types are: grace_time, internal_reputation, req_legal, frozen.

 "freeze": {
       "text": "Por el momento {0}esta publicación no perderá exposición ni será pausada o anulada por brindar experiencia mala o media.{1} Es importante solucionar sus problemas para mejorar la experiencia que brindas.",
       "placeholders": [
           "",
           ""
       ]
   },

Status

{
    "id": enum (active | paused | moderated),
    "assigned_by": enum (reputation | other),
    "text": string
}

Subtitle

A change was added to obtain the amount of sales of an item in the last 180 days and show it in the fronts.

Current response

  "subtitles": [
    {
        "order": 0,
        "text": "Tienes 9 problemas con este producto. Revisa los consejos sobre cómo mejorar."
    },
    {
        "order": 1,
        "text": "La experiencia que brinda tu publicación afecta tu exposición y podríamos anularla."
    }
],

New response

  "subtitles": [
    {
        "order": 0,
        "text": "En los últimos 180 días hiciste {0}12 ventas{1} y tuviste {0}9 problemas.{1} Revisa los consejos sobre cómo mejorar.",
        "placeholders": [
            "",
            ""
        ]
    },
    {
        "order": 1,
        "text": "La experiencia que brinda tu publicación afecta tu exposición y podríamos anularla."
    }
],

Action

{
    "order": uint,
    "text": string,
 }

According to the conditions shown in the items, the possible actions are the following.

Active items

• If the item has score 100 and has no problems: See publication.
• If the item has score 100 with problems or a lower score (excluding score -1, which is when the item has no sales): Modify publication and Pause from the list.

Paused items

• Paused by the seller: Modify publication and View publication.
• Paused by Buying Experience: Modify publication and Reactivate from the list.

Cancelled item

• Overridden by shopping experience: How to provide a good experience.
• Overridden by other moderation: View post.

Reputation

{
    "color": string,
    "text": string,
    "value": int
}

Metrics details

{
    "empty_state_title": string,
    "problems": []problem,
    "distribution": distribution
}

Problem

{
  "order": unit,
  "key": string, // key de L1
  "color": string, // de L1
  "quantity": text, // de L3
  "cancellations": unit, // de l3
  "claims": unit, // de l3
  "tag": string,
    "level_2": level_2,
    "level_3": level_3
}

Level 2

{
    "key": string, // key de L2
    "title": text,
 }

Level 3

{
    "key": string, // key de L3
    "title": text,
    "remedy": text,
}

Distribution

{
    "from": date,
    "to": date,
    "level_1": []level_1
}

Formato date

{"from": "2023-07-04T19:08:56Z",
"to": "2023-11-04T19:08:56Z",
}

Level 1

{
  "key": string, // key de L1
  "title": text,
  "color": string,
  "percentage": float,
  "quantities_level_2": [
        {
            "key": string, // L2 key
            "title": text,
            "quantity": uint
        }
    ]
}

Errors