Co-funded campaigns

Check campaign details

Retrieve the details of a specific co-funded campaign, including dates, status, and benefit distribution between seller and Mercado Libre.

Request:

curl -X GET 'https://api.mercadolibre.com/marketplace/seller-promotions/promotions/$PROMOTION_ID?promotion_type=MARKETPLACE_CAMPAIGN&user_id=$USER_ID' \
  -H 'Authorization: Bearer $ACCESS_TOKEN' \
  -H 'version: v2' \
  -H 'X-Client-Id: $CLIENT_ID' \
  -H 'X-Caller-Id: $CALLER_ID'

Example:

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

Response:

{
    "id": "P-MLM1806015",
    "type": "MARKETPLACE_CAMPAIGN",
    "status": "started",
    "start_date": "2023-04-20T02:00:00Z",
    "finish_date": "2023-08-01T02:00:00Z",
    "deadline_date": "2023-08-01T01:00:00Z",
    "name": "Test Campaign v2",
    "benefits": {
        "type": "REBATE",
        "meli_percent": 5,
        "seller_percent": 25
    }
}

Response fields

• id: unique campaign identifier.
• type: campaign type. Value: MARKETPLACE_CAMPAIGN.
• status: current campaign status. See status table below.
• start_date: campaign start date in ISO 8601 format.
• finish_date: campaign end date in ISO 8601 format.
• deadline_date: last date to add items to the campaign.
• name: campaign display name.
• benefits: object containing discount distribution details.
  • type: benefit type. Value: REBATE.
  • meli_percent: percentage of discount contributed by Mercado Libre.
  • seller_percent: percentage of discount contributed by the seller.

Status

Find below the different co-funded campaign statuses:

Check campaign Items

Retrieve the list of candidate items and/or items already included in a co-funded campaign.

Request:

curl -X GET 'https://api.mercadolibre.com/marketplace/seller-promotions/promotions/$PROMOTION_ID/items?user_id=$USER_ID' \
  -H 'Authorization: Bearer $ACCESS_TOKEN' \
  -H 'version: v2' \
  -H 'X-Client-Id: $CLIENT_ID' \
  -H 'X-Caller-Id: $CALLER_ID'

Example:

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

Response:

{
    "results": [
        {
            "id": "MLM3293401659",
            "status": "started",
            "price": 700,
            "original_price": 1000,
            "offer_id": "OFFER-MLM3293401659-177366",
            "meli_percentage": 5,
            "seller_percentage": 25,
            "start_date": "2023-04-23T23:06:53Z",
            "end_date": "2023-08-01T02:00:00Z",
            "net_proceeds": {
                "amount": 20.68,
                "currency": "USD"
            }
        }
    ],
    "paging": {
        "offset": 0,
        "limit": 50,
        "total": 1
    }
}

Response fields

• results: array of items in the campaign.
  • id: item ID.
  • status: item participation status. See item status table below.
  • price: current discounted price.
  • original_price: original price before discount.
  • offer_id: unique offer identifier assigned when item is added to campaign.
  • meli_percentage: percentage contributed by Mercado Libre for this item.
  • seller_percentage: percentage contributed by the seller for this item.
  • start_date: date when the item started participating in the campaign.
  • end_date: date when the item's participation ends.
  • net_proceeds: object containing the seller's net earnings information.
    • amount: net amount the seller will receive.
    • currency: currency code (e.g., USD).
• paging: pagination information.
  • offset: current offset position.
  • limit: maximum items per page.
  • total: total number of items.

Item status

Submit an item to a campaign

Once you are invited to participate in a co-funded campaign, you can specify the products to be included.

Request:

curl -X POST 'https://api.mercadolibre.com/marketplace/seller-promotions/items/$ITEM_ID?user_id=$USER_ID' \
  -H 'Authorization: Bearer $ACCESS_TOKEN' \
  -H 'version: v2' \
  -H 'X-Client-Id: $CLIENT_ID' \
  -H 'X-Caller-Id: $CALLER_ID' \
  -H 'Content-Type: application/json' \
  -d '{
    "promotion_id": "$PROMOTION_ID",
    "promotion_type": "MARKETPLACE_CAMPAIGN"
  }'

Example:

curl -X POST 'https://api.mercadolibre.com/marketplace/seller-promotions/items/MLM3293401659?user_id=1317418851' \
  -H 'Authorization: Bearer $ACCESS_TOKEN' \
  -H 'version: v2' \
  -H 'X-Client-Id: 1317417907' \
  -H 'X-Caller-Id: 1317417907' \
  -H 'Content-Type: application/json' \
  -d '{
    "promotion_id": "P-MLM1806015",
    "promotion_type": "MARKETPLACE_CAMPAIGN"
  }'

Response:

{
    "offer_id": "OFFER-MLM3293401659-177366",
    "price": 700,
    "original_price": 1000
}

Response fields

• offer_id: unique offer identifier for the item in the campaign.
• price: discounted price applied to the item.
• original_price: original item price before discount.

Request body parameters

• promotion_id: campaign identifier.
• promotion_type: must be MARKETPLACE_CAMPAIGN.

Modify items

Since prices cannot be changed directly, follow the steps below to change the price of an item included in a co-funded campaign.

Steps:

• Delete the item from the campaign.
• Change item price just like regular price synchronization.
• Add the item back to the campaign.

Delete items

Remove an item from a co-funded campaign.

Request:

curl -X DELETE 'https://api.mercadolibre.com/marketplace/seller-promotions/items/$ITEM_ID?promotion_type=MARKETPLACE_CAMPAIGN&promotion_id=$PROMOTION_ID&offer_id=$OFFER_ID&user_id=$USER_ID' \
  -H 'Authorization: Bearer $ACCESS_TOKEN' \
  -H 'version: v2' \
  -H 'X-Client-Id: $CLIENT_ID' \
  -H 'X-Caller-Id: $CALLER_ID'

Example:

curl -X DELETE 'https://api.mercadolibre.com/marketplace/seller-promotions/items/MLM3293401659?promotion_type=MARKETPLACE_CAMPAIGN&promotion_id=P-MLM1806015&offer_id=OFFER-MLM3293401659-177366&user_id=1317418851' \
  -H 'Authorization: Bearer $ACCESS_TOKEN' \
  -H 'version: v2' \
  -H 'X-Client-Id: 1317417907' \
  -H 'X-Caller-Id: 1317417907'

Response: HTTP 200 OK

Next: Pre-negotiated Discount per Item