Documentation Mercado Libre

Check out all the necessary information about APIs Mercado Libre.
circulos azuis em degrade

Documentation

Last update 26/02/2024

Pre-negotiated Discount per Item

Importante:
Sellers are regularly invited to participate in different website campaigns. In this type of campaign the seller previously negotiated with Mercado Libre commercial representatives a discount for certain items, setting price, offered discount and granted benefit.
If you received an invitation and want to join, use the resources below.

Seller view






Check details about a pre-negotiated campaign

Example:

curl -X GET -H 'Authorization: Bearer $ACCESS_TOKEN' 'https://api.mercadolibre.com/marketplace/seller-promotions/promotions/P-MLM13773008?promotion_type=PRE_NEGOTIATED&user_id=1317418851' \
  --header 'version: v2' \
  --header 'X-Client-Id: 1317417907' \
  --header 'X-Caller-Id: 1317417907' \

Response:

{
  "id": "P-MLM13773008",
  "type": "PRE_NEGOTIATED",
  "status": "started",
  "start_date": "2024-02-01T06:00:00Z",
  "finish_date": "2024-03-01T06:00:00Z",
  "deadline_date": "2024-03-01T00:00:00Z",
  "name": "Commercial Shared Discounts"
}

Specific campaign fields


Offers: detail of pre-negotiated discount

  • id: offer identification.
  • type: PRE_NEGOTIATED
  • status: promotion status.
  • start_date: start date of offer in promotion.
  • end_date: end date of offer in promotion.

  • Status campaign description

    pending: promotion approved but not yet started.
    started: active promotion.
    finished: finished promotion.


    Check items in a pre-negotiated campaign

    Request:

    curl -X GET -H 'Authorization: Bearer $ACCESS_TOKEN' 'https://api.mercadolibre.com/marketplace/seller-promotions/promotions/P-MLM13773008/items?user_id=1317418851' \
      --header 'versio: v2' \
      --header 'X-Client-Id: 1317417907' \
      --header 'X-Caller-Id: 1317417907' \

    Response:

    {
      "results": [
          {
              "id": "MLM2184798066",
              "status": "candidate",
              "price": 30,
              "original_price": 0,
              "currency_id": "USD",
              "offer_id": "CANDIDATE-MLM2184798066-70509424924",
              "meli_percentage": 6.7,
              "seller_percentage": 26.7,
              "start_date": "2024-02-02T06:00:00Z",
              "end_date": "2024-02-29T05:59:59Z"
          },
          {
              "id": "MLM2184694464",
              "status": "candidate",
              "price": 100,
              "original_price": 0,
              "currency_id": "USD",
              "offer_id": "CANDIDATE-MLM2184694464-70509424935",
              "meli_percentage": 20,
              "start_date": "2024-02-02T06:00:00Z",
              "end_date": "2024-02-29T05:59:59Z"
          },
          {
              "id": "MLM2184616078",
              "status": "candidate",
              "price": 130,
              "original_price": 0,
              "currency_id": "USD",
              "offer_id": "CANDIDATE-MLM2184616078-70509424939",
              "meli_percentage": 15.4,
              "seller_percentage": 7.7,
              "start_date": "2024-02-02T06:00:00Z",
              "end_date": "2024-02-29T05:59:59Z"
          }
      ],
      "paging": {
          "offset": 0,
          "limit": 50,
          "total": 3,
          "searchAfter": ""
      }
    }

    When a new campaign is created, all applicable items are selected. The initial item (status) is "candidate" with a unique "offer_id". When the seller adds an item to the campaign, item status changes and goes to programmed or active.



    Status item description

    candidate: candidate item to participate in the promotion.
    programmed: approved and programmed promotion item.
    active: campaign active item.


    Accept a pre-negotiated discount per item

    Once a discount has been negotiated for an item, the seller can accept the pre-negotiation with the following resource.

    Request:

    curl -X POST -H 'Authorization: Bearer $ACCESS_TOKEN' -d 
      {
         "promotion_id": "$PROMOTION_ID",
         "promotion_type": "$PROMOTION_TYPE",
         "offer_id": "$OFFER_ID"
      }
      https://api.mercadolibre.com/marketplace/seller-promotions/items/$ITEM_ID?user_id=$USER_ID

    Example:

    curl -X POST -H 'Authorization: Bearer $ACCESS_TOKEN' -d 
      '{
         "promotion_id":"P-MLM13773008",
          "offer_id":"CANDIDATE-MLM2184798066-70509424924",
         "promotion_type":"PRE_NEGOTIATED"
      }
      'https://api.mercadolibre.com/marketplace/seller-promotions/items/MLM2184798066?user_id=1317418851' \
      --header 'version: v2' \
      --header 'X-Client-Id: 1317417907' \
      --header 'X-Caller-Id: 1317417907' \

    Response:

    {
      "price": 20,
      "original_price": 30,
      "currency_id": "USD",
      "offer_id": "OFFER-MLM2184798066-10194569987"
    }

    Parameters

    deal_id: promotion identification.
    offer_id: negotiated offer identification.
    promotion_type: type of promotion (PRE_NEGOTIATED).



    Remove pre-negotiated discount

    Use this resource to Pre-negotiated Discount per Item

    Request:

    curl -X DELETE -H 'Authorization: Bearer $ACCESS_TOKEN' https://api.mercadolibre.com/marketplace/seller-promotions/items/$ITEM_ID?user_id=$USER_ID&promotion_type=PRE_NEGOTIATED&promotion_id=$PROMOTION_ID&offer_id=$OFFER_ID

    Example:

    curl -X DELETE -H 'Authorization: Bearer $ACCESS_TOKEN'
      'https://api.mercadolibre.com/marketplace/seller-promotions/items/MLM2184798066?user_id=1317418851&promotion_type=PRE_NEGOTIATED&promotion_id=P-MLM13773008&offer_id=OFFER-MLM2184798066-10194569987' \
      --header 'version: v2' \
      --header 'X-Client-Id: 1317417907' \
      --header 'X-Caller-Id: 1317417907
    Nota:
    Remember that if an item pre-negotiated discount is removed, the item will no longer be a candidate.

    Next: Unhealthy Stock Campaign