Developers

Documentation Mercado Libre

Check out all the necessary information about APIs Mercado Libre.

Last update 05/08/2025

Working with Clips

When posting a new listing, we all know that high-quality images can make a big difference in attracting buyers—but video can be even more effective. This guide shows you how to upload, get info, and delete Clips via API, making the process more integrated and automated than ever before. Until now, this was only possible through the Global Selling interface.

Considerations for Uploading Clips

Clips can only be uploaded for active items.
Clips can only be uploaded on the seller's local sites.

The video file must meet the following requirements:

Format: MP4, MOV, MPEG, or AVI.
Duration: minimum 10 seconds, maximum 61 seconds.
Maximum file size: 280 MB.
Minimum resolution: 360x640 pixels.
Vertical video.

Upload a Clip

Allows you to upload a clip for a CBT item and specify the sites where you want it to be available.

Call:

curl -X POST -H 'Authorization: Bearer $ACCESS_TOKEN' https://api.mercadolibre.com/marketplace/items/{cbt_item_id}/clips/upload
-H 'Content-Type: multipart/form-data' \
-F 'file=@{path_to_video_file}' \
-F 'sites=[
{
"site_id":"{site_id_1}",
"logistic_type":"{logistic_type_1}"
},
{
"site_id":"{site_id_2}",
"logistic_type":"{logistic_type_2}"
},
{
"site_id":"{site_id_3}",
"logistic_type":"{logistic_type_3}"
}
]' \

Example:

curl -X POST -H 'Authorization: Bearer $ACCESS_TOKEN' https://api.mercadolibre.com/marketplace/items/{cbt_item_id}/clips/upload
-H 'Content-Type: multipart/form-data' \
-F 'file=@"/Users/karacuna/Downloads/2lkKvX.mp4"' \
-F 'sites=[
{
"site_id":"MLM",
"logistic_type":"remote"
},
{
"site_id":"MCO",
"logistic_type":"remote"
}
]' \

Important:

If "Sites" is left empty, the clip will be uploaded to all available sites.

Response:

{
    "status": "accepted",
    "clip_uuid": "550e8400-e29b-41d4-a716-446655440000",
    "site_ids": [
        {
            "site_id": "MLM",
            "logistic_type": "remote"
        },
        {
            "site_id": "MCO",
            "logistic_type": "remote"
        }
    ]
}

Example of an error response:

{
    "message": "Video resolution is lower than 360x640 pixels.",
    "error_status": "bad_request",
    "status": 400
}

Important:

Uploading clips is subject to a limit set by the daily review capacity of the moderation team, which is capped at 1,000 clips per day.

Get Clips info of an item

Returns all clips for a CBT item and their status by site.

Call:

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

Example:

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

Response:

{
    "parent_item_id": "CBT2215534590",
    "parent_user_id": "757729744",
    "clips": [
        {
            "clip_uuid": "46875e1b-4210-4fdc-b189-e9cc144bd211",
            "metadata": [
                {
                    "site_id": "MCO",
                    "logistic_type": "remote",
                    "item_id": "MCO2753472790",
                    "user_id": 798579194,
                    "moderation_status": "PUBLISHED"
                },
                {
                    "site_id": "MLM",
                    "logistic_type": "remote",
                    "item_id": "MLM2193219951",
                    "user_id": 757732742,
                    "moderation_status": "REJECTED",
                    "moderation_reasons": {
                        "VIDEO_PROCESSING_ERROR": "It was not possible to process your video file. Please try uploading a new one.",
                        "DUPLICATED_VIDEO": "This video had already been uploaded before."
                    }
                }
            ]
        },
        {
            "clip_uuid": "b56847e2-0d0e-4770-84fe-4141814e6fd7",
            "metadata": [
                {
                    "site_id": "MCO",
                    "logistic_type": "remote",
                    "item_id": "MCO2753472790",
                    "user_id": 798579194,
                    "moderation_status": "UNDER_REVIEW"
                }
            ]
        },
        {
            "clip_uuid": "9705bf50-0ceb-435c-b5c9-010e0a8914af",
            "metadata": [
                {
                    "site_id": "MLC",
                    "logistic_type": "remote",
                    "item_id": "MLC2789734556",
                    "user_id": 757732112,
                    "moderation_status": "UNDER_REVIEW"
                }
            ]
        },
        {
            "clip_uuid": "4e737ded-5d48-472f-8c6e-9c9ac9a87d53",
            "metadata": [
                {
                    "site_id": "MLM",
                    "logistic_type": "remote",
                    "item_id": "MLM2193219951",
                    "user_id": 757732742,
                    "moderation_status": "UNDER_REVIEW"
                },
                {
                    "site_id": "MLC",
                    "logistic_type": "remote",
                    "item_id": "MLC2789734556",
                    "user_id": 757732112,
                    "moderation_status": "UNDER_REVIEW"
                }
            ]
        },
        {
            "clip_uuid": "c69658ac-f1f8-4860-b56b-be9f285a9edf",
            "metadata": [
                {
                    "site_id": "MCO",
                    "logistic_type": "remote",
                    "item_id": "MCO2753472790",
                    "user_id": 798579194,
                    "moderation_status": "UNDER_REVIEW"
                },
                {
                    "site_id": "MLM",
                    "logistic_type": "remote",
                    "item_id": "MLM2193219951",
                    "user_id": 757732742,
                    "moderation_status": "UNDER_REVIEW"
                }
            ]
        }
    ]
}

Example of an error response:

{
    "message": "Item not found: CBT999",
    "error_status": "not_found",
    "status": 404
}

Possible Statuses:

UNDER_REVIEW: Moderation ongoing.
REJECTED: Rejected due to content or technical specifications.
PUBLISHED: Approved and published.
TRANSCODING_REJECTED, PAUSED: Technical or commercial status.

Important:

Changing the "moderation_status" from UNDER_REVIEW to any other status, as well as publishing the video if it passes moderation, takes between 24 and 48 hours. This is the estimated timeframe needed to complete the moderation review process.

Delete a Clip

Deletes a clip from a CBT item on one or more sites.

Call:

curl -X DELETE -H 'Authorization: Bearer $ACCESS_TOKEN' https://api.mercadolibre.com/marketplace/items/$cbt_item_id/clips/$clip_relation_id
-H 'Content-Type: multipart/form-data' \
-F 'file=@{path_to_video_file}' \
-F 'sites=[
{
"site_id":"{site_id_1}",
"logistic_type":"{logistic_type_1}"
},
{
"site_id":"{site_id_2}",
"logistic_type":"{logistic_type_2}"
},
{
"site_id":"{site_id_3}",
"logistic_type":"{logistic_type_3}"
}
]' \

Example:

curl -X DELETE -H 'Authorization: Bearer $ACCESS_TOKEN' https://api.mercadolibre.com/marketplace/items/CBT2215534590/clips/c69658ac-f1f8-4860-b56b-be9f285a9edf
-H 'Content-Type: multipart/form-data' \
-F 'file=@{path_to_video_file}' \
-F 'sites=[
{
"site_id":"MLM",
"logistic_type":"remote"
},
{
"site_id":"MLC",
"logistic_type":"remote"
},
{
"site_id":"MLB",
"logistic_type":"remote"
}
]' \

Important:

If "Sites" is left empty, the clip will be deleted from all available sites.

Response:

[
    {
        "status": "DELETED",
        "site_id": "MLM",
        "logistic_type": "remote"
    },
    {
        "status": "NOT_FOUND",
        "site_id": "MLC",
        "logistic_type": "remote"
    },
    {
        "status": "NOT_FOUND",
        "site_id": "MLB",
        "logistic_type": "remote"
    },
    {
        "status": "ERROR",
        "site_id": "MCO",
        "logistic_type": "remote"
    }
]

Example of an error response:

{
    "message": "Item not found: CBT999",
    "error_status": "not_found",
    "status": 404
}

Important:

Clips can be deleted regardless of their assigned 'moderation_status' category.

Errors

Upload errors (POST /marketplace/items/{cbt_item_id}/clips/upload)

HTTP Code	Error	Message	Details	Solution
404	not_found	Item not found: {cbt_item_id}	The CBT item id was not found	Enter a valid CBT item id
401	unauthorized	invalid access token	Invalid token	Make sure your application scopes are "read" and "write". Update the token.
401	unauthorized	User does not have permission to access this resource	The user does not have permissions to upload clips.	The user is a test user not whitelisted, or the CBT user was not found or does not exist.
400	bad_request	INVALID_EXTENSION	File type not allowed.	Upload a video file with mp4, mov, mpeg, or avi extensions.
400	bad_request	Invalid JSON format for 'sites'	JSON format for the "sites" field does not meet the required structure.	Check the JSON format, make sure to include "site_id" and "logistic_type".
400	bad_request	INVALID_MIN_VIDEO_DURATION	The video duration is shorter than allowed.	Make sure the video duration is longer than 10 seconds.
400	bad_request	INVALID_MAX_VIDEO_DURATION	The video duration is longer than allowed.	Make sure the video does not exceed 61 seconds.
400	not_found	The itemId does not exist, is invalid, inactive, or does not belong to the seller	The Cbt item is not active or does not belong to the seller.	Make sure the CBT item is active and belongs to the CBT user making the request.
400	bad_request	The 'file' field is required.	The request does not include the 'file' field.	Add the "file" field in the request.
400	bad_request	REQUIRED_VIDEO	The request does not include a video file.	Attach a video file in the "file" field of the request.
400	bad_request	Request Entity Too Large	The video file size exceeds the limit (280MB).	Upload a video that does not exceed 280 MB.
400	bad_request	Error processing video file.	An I/O error occurred while trying to read the video properties.	The file may be slightly damaged or was exported in a non-standard format. Preprocess the video in tools like HandBrake and save it as a new file. Open the file in a video editor and make sure to use common export settings, like 'MP4' with the 'H.264' video codec and 'AAC' audio codec.
400	bad_request	La calidad del video es menor a 360x640 pixeles.	The video resolution is lower than the required minimum.	Rescale the video to a higher resolution using editing tools (HandBrake). Set the resolution to at least 360x640 pixels.
500	internal_server_error	(Any error from server)	Error associated with saving information in databases or connections.	Retry the request.

Get errors (GET /items/{cbt_item_id}/clips)

HTTP Code	Error	Message	Details	Solution
404	not_found	Item not found: {cbt_item_id}	The CBT item id was not found	Enter a valid CBT item id
401	authentication_error	Authentication Error	Invalid token	Make sure your application scopes are "read" and "write". Update the token.
401	unauthorized	User does not have permission to access this resource	The user does not have permissions to query clips.	The user is a test user not whitelisted, or the CBT user was not found or does not exist.
404	not_found	No clips found for itemId: {cbt_item_id}	The CBT item exists, but has no associated clips.	Make sure to verify that the correct CBT item exists.
500	internal_server_error	Unexpected error: The itemId does not exist...	Error associated with saving information in databases or the connection.	Retry the request.

Delete errors (DELETE /items/{cbt_item_id})

HTTP Code	Error	Message	Details	Solution
404	not_found	Item not found: {cbt_item_id}	The CBT item id was not found	Enter a valid CBT item id
401	authentication_error	Authentication Error	Invalid token	Make sure your application scopes are "read" and "write". Update the token.
403	unauthorized	User does not have permission to access this resource	The user does not have permissions to delete clips.	The user is a test user not whitelisted, or the CBT user was not found or does not exist.
404	not_found	No valid sites found for itemId: {cbt_item_id}	The sites provided in the request are not found	Make sure the sites are correct and exist for the CBT item.
404	not_found	The clipUuid: {clip_uuid} was not found in the clips of itemId: {cbt_item_id}	The clip was not found.	Make sure the clip_relation_id is correct.
500	internal_server_error	Unexpected error: The itemId does not exist...	Error associated with saving information in databases or the connection.	Retry the request.