Documentação do Mercado Shops

Confira todas as informações necessárias sobre as APIs Mercado Shops.
circulos azuis em degrade

Documentação do

Última atualização em 21/03/2023

Guest users sales

Important:
This functionality will be available from June 2022, on the sites where Mercado Shops is enabled (Argentina, Brazil, Mexico, Chile and Colombia).

We will allow guest users to make purchases in the stores without needing to have a Mercado Libre account, simplifying the shopping experience so that sellers can sell more. Therefore, in the stores it will be possible to buy with guest users by entering little information such as name, surname and email. Take into account the considerations per site.

Considerations

The data that we will request to the guest user besides the name and surname by site will be:

  • MLM: e-mail
  • MLB: e-mail + CPF o CNPJ
  • MLA: e-mail + DNI
  • MLC: e-mail + RUT

The guest users:

  • Will not have a protected purchase,
  • will not have a password and will not be able to enter Mercado Libre or Mercado Pago,
  • will not have messaging in Mercado Libre flows,
  • and will have a brand to be will have a brand to be identified as such, which will be lite and an ID.

For this type of user we create a new session type to authorize access only to guest flows. Note that:

  • One user per store and email will be created for each purchase.
  • The sales of these users will not affect the seller's reputation.

Each guest user will be able to track his purchase by accessing the information available in his email and will be able to view each purchase individually.


Cases in which the seller will receive an e-mail of a guest purchase:


Status E-mail buyer E-mail seller
PAYMENT DECLINED Yes No
IN PROCESS No No
PACKAGE IN PREPARATION No Yes
PACKAGE IN PREPARATION DELAYED No Yes
PACKAGE ON THE WAY Yes No
PACKAGE ON THE ROAD DELAYED Yes Yes
PACKAGE AT PICK-UP POINT Yes No
PACKAGE DELIVERED Yes No

Identify guest users

Currently, orders will have a new array that will allow knowing the context with which the orders were created, saving the type of customer that creates the purchase, allowing a better reading and interpretation of the information.

To find out if the order was made by a guest user, they should review the new context node that will have detailed information to identify if the purchase was made by a guest user. For this you will have to check the flows field, inside the context array, checking that its value is lite and that the channel corresponds to mshops. For more information on sales management read more.


Request:

curl -X GET -H 'Authorization: Bearer $ACCESS_TOKEN' https://api.mercadolibre.com/orders/$ORDER_ID

Example:

curl -X GET -H 'Authorization: Bearer $ACCESS_TOKEN' https://api.mercadolibre.com/orders/2000003509333216

Response:

{
    "id": 2000003509333216,
    "date_created": "2022-04-28T09:25:08.000-04:00",
    "date_closed": "2022-04-28T09:25:10.000-04:00",
    "last_updated": "2022-04-28T09:27:11.000-04:00",
    "manufacturing_ending_date": "2022-06-12T09:25:10.000-04:00",
    "comment": null,
    "pack_id": null,
    "pickup_id": null,
    "order_request": {
        "return": null,
        "change": null
    },
    "fulfilled": null,
    "application_id": "3606760543142028",
    "hidden_for_seller": false,
    "buying_mode": "buy_equals_pay",
    "shipping_cost": 1504.99,
    "mediations": [],
    "total_amount": 20000,
    "paid_amount": 21504.99,
    "coupon": {
        "id": null,
        "amount": 0
    },
    "expiration_date": "2022-07-10T09:25:10.000-04:00",
    "order_items": [
        {
            "item": {
                "id": "MLA924971996",
                "title": "Maceta De Plastico (item De Prueba No Ofertar)",
                "category_id": "MLA11034",
                "variation_id": 87620137218,
                "seller_custom_field": null,
                "variation_attributes": [
                    {
                        "id": "COLOR",
                        "name": "Color",
                        "value_id": "52049",
                        "value_name": "Negro"
                    }
                ],
                "warranty": "Sin garantía",
                "condition": "new",
                "seller_sku": null,
                "global_price": null,
                "net_weight": null
            },
            "quantity": 1,
            "requested_quantity": {
                "value": 1,
                "measure": "unit"
            },
            "picked_quantity": null,
            "unit_price": 20000,
            "full_unit_price": 22000,
            "currency_id": "ARS",
            "manufacturing_days": 45,
            "sale_fee": 3800,
            "listing_type_id": "gold_pro",
            "base_exchange_rate": null,
            "base_currency_id": null,
            "element_id": null,
            "bundle": null,
            "discounts": null
        }
    ],
    "currency_id": "ARS",
    "payments": [
        {
            "id": 21926289045,
            "order_id": 2000003509333216,
            "payer_id": 1109579510,
            "collector": {
                "id": 660948237
            },
            "card_id": null,
            "site_id": "MLA",
            "reason": "Maceta De Plastico (item De Prueba No Ofertar)",
            "payment_method_id": "visa",
            "currency_id": "ARS",
            "installments": 1,
            "issuer_id": "1",
            "atm_transfer_reference": {
                "company_id": null,
                "transaction_id": null
            },
            "coupon_id": null,
            "activation_uri": null,
            "operation_type": "regular_payment",
            "payment_type": "credit_card",
            "available_actions": [
                "refund"
            ],
            "status": "approved",
            "status_code": null,
            "status_detail": "accredited",
            "transaction_amount": 20000,
            "transaction_amount_refunded": 0,
            "taxes_amount": 0,
            "shipping_cost": 1504.99,
            "coupon_amount": 0,
            "overpaid_amount": 0,
            "total_paid_amount": 21504.99,
            "installment_amount": 21504.99,
            "deferred_period": null,
            "date_approved": "2022-04-28T09:25:10.000-04:00",
            "authorization_code": "301299",
            "transaction_order_id": null,
            "date_created": "2022-04-28T09:25:09.000-04:00",
            "date_last_modified": "2022-04-28T09:25:26.000-04:00",
            "marketplace_fee": 3800
        }
    ],
    "shipping": {
        "id": 41336716357
    },
    "status": "paid",
    "status_detail": null,
    "tags": [
        "mshops",
        "not_delivered",
        "test_order",
        "paid"
    ],
    "internal_tags": [],
    "feedback": {
        "buyer": null,
        "seller": null
    },
    "context": {
        "channel": "mshops",
        "site": "MLA",
        "flows": [
            "lite"
        ]
    },
    "seller": {
        "id": 660948237
    },
    "buyer": {
        "id": 1109579510
    },
    "taxes": {
        "amount": null,
        "currency_id": null,
        "id": null
    }
}

The new array:


    "context": {
        "channel": "mshops",
        "site": "MLA",
        "flows": [
            "lite"
        ] 
}

Parameters

channel: sales channels where the order was generated.

site: sales channels where the order was generated.

flows: is a list of characteristics of the source of the purchase, then the following current tags:

  • cbt
  • subscription
  • contract
  • supermarket
  • 3x_campaign
  • high_concurrency
  • catalog
  • lite (comprador invitado)

Verify guest user information

You will be able to identify buyer information through the /users resource since it will have an ID like a regular user, the information that identifies a guest buyer is through the user_type: lite.


Request:

curl -X GET -H 'Authorization: Bearer $ACCESS_TOKEN' https://api.mercadolibre.com/users/$USER_ID

Example:

curl -X GET -H 'Authorization: Bearer $ACCESS_TOKEN' https://api.mercadolibre.com/users/1109579510

Response:

{
    "id": 1109579510,
    "nickname": "TEST_USER_1109579510",
    "registration_date": "2022-04-19T16:01:57.099-04:00",
    "country_id": "AR",
    "address": {
        "city": "Palermo",
        "state": "AR-C"
    },
    "user_type": "lite",
    "tags": [
        "test_user",
        "lite"
    ],
    "logo": null,
    "points": 0,
    "site_id": "MLA",
    "permalink": "http://perfil.mercadolibre.com.ar/TEST_USER_1109579510",
    "seller_reputation": {
        "level_id": null,
        "power_seller_status": null,
        "transactions": {
            "canceled": 0,
            "completed": 0,
            "period": "historic",
            "ratings": {
                "negative": 0,
                "neutral": 0,
                "positive": 0
            },
            "total": 0
        }
    },
    "buyer_reputation": {
        "tags": null
    },
    "status": {
        "site_status": "active"
    }
}

Cancellations

Note:
Consider that for this type of sales to lite users (guest), they will not have the messaging flows, claims and cancellations by means of feedbacks of not completed.

For this type of sales, the only one who can cancel a sale is the seller, and must do it by making a refund by sending a POST to /v1/payments/{id}/refunds. Learn more about how to make a refund.


Request:

curl -X POST \
    'https://api.mercadopago.com/v1/payments/{id}/refunds' \
    -H 'Authorization: Bearer YOUR_ACCESS_TOKEN' \
    -H 'Content-Type: application/json' \
    -d '{
  "amount": 5
}'

Example:

curl --location --request POST 'https://api.mercadopago.com/v1/payments/23415342519/refunds' \
--header 'Authorization: Bearer APP_USR-2843871569852229-060217-cdc5b8cafba2c1dda4ffeb2235f79b4c-553421365' \
--header 'Content-Type: text/plain' \
--data-raw '{
"amount": 683397.27
}'

Response:

{
    "id": 1150318715,
    "payment_id": 23415342519,
    "amount": 683397.27,
    "metadata": {},
    "source": {
        "id": "553421365",
        "name": "Nitienda Test Test",
        "type": "collector"
    },
    "date_created": "2022-06-23T18:21:49.114-04:00",
    "unique_sequence_number": null,
    "refund_mode": "standard",
    "adjustment_amount": 0,
    "status": "approved",
    "reason": null,
    "labels": [],
    "amount_refunded_to_payer": 683397.27,
    "partition_details": []
}

Next: Campaigns with installments.