Package grouping for Pickup

Documentation Mercado Libre

Check out all the necessary information about APIs Mercado Libre.

Last update 12/03/2026

Package grouping for Pickup

This feature allows you to optimize shipment pickup by enabling the seller to declare in advance the packages they will deliver and generate virtual containerization. From this declaration, packages can be grouped into bags, boxes or pallets, generating a new label for the group, which allows the driver to perform a single scan per created group, reducing operational friction and significantly improving the performance and speed of the pickup process.

In this guide, we show the step-by-step to manage the entire process of creating and editing groups and packages (technically bundles and volumes).

Get ready to take your pickups to the next level of efficiency and agility.

1. Validate user

Before you can create a bundle, you need to verify that the user is enabled with this feature.
This resource allows you to validate sellers enabled to use the package grouping feature for pickups.

Call:

curl -X GET "https://api.mercadolibre.com/soe/bundles/users/validate" \
-H "Content-Type: application/json" \
-H "Authorization: Bearer $ACCESS_TOKEN"

Example:

curl -X GET "https://api.mercadolibre.com/soe/bundles/users/validate" \
-H "Content-Type: application/json" \
-H "Authorization: Bearer {ACCESS_TOKEN}"

// Respuesta:
// 200 OK
{
  "active": true,
  "init_date": 2026-03-12T13:09:00Z
}

// 200 OK
{
  "active": false,
  "reason": "FEATURE_DISABLED"
}

Response fields

active: Boolean field indicating whether the integrator has the experience active.
init_date: Field indicating the activation date of the feature.
reason: Field indicating the reason why the feature is NOT active. This means that if active is true, the field returns null. Otherwise, it returns the value FEATURE_DISABLED.

Errors

Http Code	Message	Solution
403	At least one policy returned UNAUTHORIZED	The integrator is missing read/write permissions for Shipments and Sales or does not have the grouping feature enabled
424	An external dependency has failed	External service error.
500	Internal server error	Internal server error.

2. Create Bundle

This resource allows you to create a shipment bundle from the virtual containerization defined by the seller, associating multiple packages with a single containerized unit. When generating the bundle, you obtain a bundle identifier ID and a hash calculated from the ID, the name, the creation date, and the client_id received in the token. This hash must then be passed as a mandatory parameter (acting as authorization for the bundle) when adding or removing shipments. This ensures that accounts other than the seller's can group items into the same bundle.

Note:

We only allow the grouping of packages (shipments) after the label has been printed, ideally in the following statuses:

ready_to_ship

with sub-statuses:

ready_for_pickup
printed

Call:

curl -X POST -H 'Authorization: Bearer $ACCESS_TOKEN' \
https://api.mercadolibre.com/soe/bundles

Required query parameters

Variable	Description
N/A	All parameters go in the body

Body

Field	Description
name	Bundle name
volumes	List of shipment IDs (optional)

Example:

curl -X POST -H 'Authorization: Bearer $ACCESS_TOKEN' \
-H 'Content-Type: application/json' \
-d '{"name": "{bundle_name}", "volumes": ["123", "234"]}' \
https://api.mercadolibre.com/soe/bundles

// Response:
{
  "id": 2073,
  "name": "{bundle_name}",
  "status": "OPENED",
  "service_type": "XD",
  "create_date": "2025-11-05T16:13:02.710912202",
  "update_date": "2025-11-05T16:13:02.710912202",
  "scan_code_id": "",
  "volumes": ["{reference_id}", ...]
  "hash": "abcd1234"
}

Response fields

name: String field with the bundle name (Type: String, Size: 15, Required: Yes)
service_type: Constant field (Type: Constant, Required: No, Values: XD)
reference_id: Shipment IDs (Type: String, Size: 12, Required: No)

Error response when validating volume 409:

{
  "volume_id": "{volume_id}",
  "bundle_name": "(depends on the use case)",
  "reason": "{reason}"
}

Errors

Variable	Description	Values	Detail
volume_id	ID of the volume in error	String
		ERR_SHIPMENT_INVALID	occurs when the shipment is invalid for the operation.
		ERR_SHIPMENT_CANCELLED	occurs when a shipment was cancelled.
		ERR_SHIPMENT_NOT_FOUND	occurs when the shipment does not exist.
reason	Error description	ERR_LOGISTIC	occurs when the logistics is invalid.
		ERR_NOT_READY_FOR_PICKUP_OR_NOT_PRINTED	occurs when the shipment is not in the correct state and substate.
		ERR_SHIPMENT_EXIST_IN_OTHER_BUNDLE	occurs when the shipment exists in another bundle.
		ERR_SHIPMENT_DUPLICATED	duplicate validation error
		ERR_BUNDLE_LIMIT_EXCEEDED_SHIPMENT	The shipment limit exceeded the maximum limit of 450.

Errors

Http Code	Message	Solution
201	Created	-
400	Bad arguments	Validate the JSON format
401	User is not authorized into the application	User does not have access to the application
409	The request generates conflict with existing data	A bundle with similar characteristics already exists. Verify data uniqueness
424	An external dependency has failed	External bundle management service error
500	Internal server error	Internal server error

3.1. Bundle search by ID

This resource allows you to obtain the information of an existing bundle from its identifier. Through the search by bundle_id, you can query the bundle summary, including the data associated with the containerized unit, the packages that comprise it and their status, facilitating traceability and validation of the grouping during the logistics process.

Call:

curl -X GET -H 'Authorization: Bearer $ACCESS_TOKEN' \
https://api.mercadolibre.com/soe/bundles/{bundle_id}/summary

Required query parameters

Variable	Description
bundle_id	Bundle ID to search for

Example

curl -X GET -H 'Authorization: Bearer $ACCESS_TOKEN' \
https://api.mercadolibre.com/soe/bundles/12345/summary

Response fields for all searches

Bundle Summary

id: Bundle ID
bundle_name: Bundle name
service_type: Service/logistics type with which the bundle will be operated
status: Current status of the bundle
created_date: Bundle creation date
last_updated: Date of last bundle update
scan_code_id: Bundle label ID

Volume

id: Volume ID
bundle_id: Bundle ID
reference_id: Volume ID in the MELI network
status: Current status of the volume in the kitting context
create_date: Volume creation date
update_date: Date of last volume update

Errors

Http Code	Message	Solution
401	User is not authorized into the application	Verify that the authorization token is valid and present in the header
404	Bundle data not found for given user and ID	The specified user or bundle does not exist in the system
424	An external dependency has failed	External service error.
500	Internal server error	Internal server error.

3.2. Bundle search by reference

This resource allows you to search for bundles from a partial reference, either by name or by the scannable code associated with the bundle. The search by bundle_reference facilitates the identification of containerized units when the exact ID is not available, returning a list of matching bundles to improve traceability and operational management during pickup and subsequent logistics processes.

Call:

curl -X GET -H 'Authorization: Bearer $ACCESS_TOKEN' \
https://api.mercadolibre.com/soe/bundles/search

Required query parameters

Variable	Description
bundle_reference	Part of the bundle name or scannable code

Example

curl -X GET -H 'Authorization: Bearer $ACCESS_TOKEN' \
https://api.mercadolibre.com/soe/bundles/search?bundle_reference=ABCD1234

curl -X GET -H 'Authorization: Bearer $ACCESS_TOKEN' \
https://api.mercadolibre.com/soe/bundles/search?bundle_reference=bund_1

Errors

Http Code	Message	Solution
400	One or more of the given parameters is invalid	Verify that bundle_reference is valid. bundle_reference cannot be empty or null
401	User is not authorized into the application	Verify that the authorization token is valid and present in the header
404	Bundle data not found for given user	The specified user or bundle does not exist in the system
424	An external dependency has failed	External service error.
500	Internal server error	Internal server error.

3.3. Volume search by Bundle ID

This resource allows you to obtain the list of volumes associated with a specific bundle from its identifier. Through the search by bundle_id, you can query the individual packages that make up the containerized unit, accessing their detailed information to facilitate traceability, operational validation and content control during pickup and the subsequent stages of the logistics flow.

Call:

curl -X GET -H 'Authorization: Bearer $ACCESS_TOKEN' \
https://api.mercadolibre.com/soe/bundles/{bundle_id}/volumes

Required query parameters

Variable	Description
bundle_id	ID of the bundle whose volumes are to be retrieved

Example

curl -X GET -H 'Authorization: Bearer $ACCESS_TOKEN' \
https://api.mercadolibre.com/soe/bundles/12345/volumes

Errors

Http Code	Message	Solution
400	One or more of the given parameters is invalid	Verify that bundle_id is valid. bundle_id cannot be empty or null
401	User is not authorized into the application	Verify that the authorization token is valid and present in the header
404	Management data not found for given user	The specified user does not exist in the system
424	An external dependency has failed	External service error.
500	Internal server error	Internal server error.

3.4. Volume search by reference and Bundle ID

This resource allows you to search for specific volumes within a given bundle, combining the bundle ID with a partial volume reference. Through the volume_reference parameter, you can identify one or more packages within the containerized unit when the full identifier is not available, facilitating precise location, traceability and operational validation of the associated volumes.

Call:

curl -X GET -H 'Authorization: Bearer $ACCESS_TOKEN' \
https://api.mercadolibre.com/soe/bundles/{bundle_id}/volumes/search

Required query parameters

Variable	Description
bundle_id	ID of the bundle whose volumes are to be retrieved
volume_reference	Part of the shipment ID to search for within the bundle

Example

curl -X GET -H 'Authorization: Bearer $ACCESS_TOKEN' \
https://api.mercadolibre.com/soe/bundles/12345/volumes/search?volume_reference=451235132

Errors

Http Code	Message	Solution
400	One or more of the given parameters is invalid	Verify that bundle_id and volume_reference are valid. bundle_id and volume_reference cannot be empty or null
401	User is not authorized into the application	Verify that the authorization token is valid and present in the header
404	Volume data not found for given user	The specified user or volume does not exist in the system
424	An external dependency has failed	External service error.
500	Internal server error	Internal server error.

4. Update Bundle

This resource allows you to update the information of an existing bundle from its identifier. Through this operation you can modify the name and/or status of the bundle, reflecting changes in the containerized unit throughout its lifecycle.

Variable	Description
bundleId	ID of the bundle to update (path parameter)

Call:

curl -X PUT "https://api.mercadolibre.com/soe/bundles/{bundleId}" \
-H "Content-Type: application/json" \
-H "Authorization: Bearer $ACCESS_TOKEN" \
-d '{"name": "name", "status": "status"}'

Body

Field	Description
name	Updated bundle name
status	Bundle status

Example:

curl -X PUT -H 'Authorization: Bearer $ACCESS_TOKEN' \
-H 'Content-Type: application/json' \
-d '{"name": "Updated bundle", "status": "CLOSED"}' \
https://api.mercadolibre.com/soe/bundles/789

Response fields

bundle_id: Long field with the bundle ID (Type: Long, Required: Yes)
name: Updated bundle name (Type: String, Size: 15, Required: No)
status: Constant field (Type: Constant, Required: No, Values: CLOSED, DELETED)

Validation errors

Variable	Description	Values	Detail
status	bundle status	String
bundle_name	bundle name	String
		ERR_USER_WITH_FEATURE_DISABLED	occurs when the user does not have the experience enabled
		ERR_BUNDLE_FINISHED	occurs when a bundle is finished and you try to delete it.
		ERR_DELETING_BUNDLE	Occurs when group deletion fails.
		ERR_DATA_NOT_FOUND	occurs when a bundle is not found
		ERR_BUNDLE_IS_DELETED	occurs when trying to delete a bundle that is already deleted
reason	Error description	ERR_TRANSITION_BUNDLE_STATUS	occurs when trying to close a bundle that does not have the OPENED status
		ERR_TRANSITION_STATUS_CLOSED_WITH_BUNDLE_EMPTY	occurs when trying to close a bundle that has no shipments added.
		ERR_TRANSITION_BUNDLE_STATUS_WITH_ALL_VOLUMES_CANCELLED	occurs when trying to close a group with all its shipments cancelled
		ERR_CLOSING_BUNDLE	Occurs when bundle closure fails; failure details are omitted.

Errors

Http Code	Message	Solution
400	One or more of the given parameters is invalid	Verify that bundleId is a valid positive number
400	Bad arguments	Validate the JSON body format and that it meets the validations
401	User is not authorized into the application	Verify that the authorization token is valid and present in the header
404	Bundle data not found for given user	The specified bundle does not exist
409	The request generates conflict with existing data	The update conflicts with the current bundle status
424	An external dependency has failed	External service error.
500	Internal server error	Internal server error.

5. Add Volumes to Bundle

This resource allows you to add one or more volumes to an existing bundle, associating individual packages with an already created containerized unit. By sending the list of shipment IDs, you can incorporate new volumes into the bundle, maintaining the consistency of the grouping.

Call:

curl -X PUT "https://api.mercadolibre.com/soe/bundles/{bundle_id}/volumes" \
-H "Content-Type: application/json" \
-H "Authorization: Bearer $ACCESS_TOKEN" \
-d '{"volumes": ["volume_id", "volume_id", ...], "hash": "hashcode"}'

Required query parameters

Variable	Description
bundleId	ID of the bundle that should contain the volumes (path parameter)

Body

Fields	Description
volumes	List of shipment IDs to add
hash	Hash associated with the bundle

Example:

curl -X PUT "https://api.mercadolibre.com/soe/bundles/12345/volumes" \
-H "Content-Type: application/json" \
-H "Authorization: Bearer $ACCESS_TOKEN" \
-d '{"volumes": ["123456789", "987654321", "555666777", "111222333", "444555666"], "hash": "abcd1234"}'

// Response:
// 200 OK

// Response Error:
{
  "status": "CLOSED",
  "reason": "ERR_INVALID_BUNDLE_STATUS",
  "max_limit": 0,
  "bundle_name": "GRUPO 7"
}

// Or:
{
  "status": "OPENED",
  "reason": "ERR_BUNDLE_IS_DELETED",
  "max_limit": 0
}

// Or:
{
  "reason": "ERR_BUNDLE_HASH_MISMATCH",
  "max_limit": 0
}

// Or:
{
  "volume_id": "{volume_id}",
  "bundle_name": "(depends on the use case)",
  "reason": "{reason}"
}

Validation errors (Error response fields)

Variable	Description	Values	Detail
volume_id	ID of the volume in error	String
		ERR_SHIPMENT_INVALID	occurs when the shipment is invalid or does not exist.
		ERR_SHIPMENT_CANCELLED	occurs when a shipment was cancelled.
		ERR_SHIPMENT_NOT_FOUND	occurs when the shipment does not exist.
		ERR_BUNDLE_HASH_MISMATCH	occurs when the body hash does not match the one calculated during bundle creation.
reason	Error description	ERR_LOGISTIC	occurs when the logistics is invalid.
		ERR_NOT_READY_FOR_PICKUP_OR_NOT_PRINTED	occurs when the shipment is not in the correct state and substate.
		ERR_SHIPMENT_ALREADY_EXIST_IN_THE_BUNDLE	occurs when the shipment already exists in the current bundle.
		ERR_SHIPMENT_EXIST_IN_OTHER_BUNDLE	occurs when the shipment exists in another bundle.

Errors

Http Code	Message	Solution
400	One or more of the given parameters is invalid	Verify that bundleId is a valid positive number
400	Bad arguments	Validate the JSON body format with a valid volume list
401	User is not authorized into the application	Verify that the authorization token is valid and present in the header
404	Bundle data not found for given user	The specified bundle does not exist
409	The request generates conflict with existing data	Volumes are already associated with the bundle or there is a status conflict
424	An external dependency has failed	External service error.
500	Internal server error	Internal server error.

6. Remove Volumes from Bundle

This resource allows you to remove one or more volumes from an existing bundle, detaching individual packages from the containerized unit. By sending the list of shipment IDs, you can adjust the composition of the bundle, reflecting operational changes and maintaining consistency.

Call:

curl -X DELETE "https://api.mercadolibre.com/soe/bundles/{bundle_id}/volumes" \
-H "Content-Type: application/json" \
-H "Authorization: Bearer $ACCESS_TOKEN" \
-d '{"volumes": ["volume_id", "volume_id", "volume_id"], "hash": "hashcode"}'

Required query parameters

Variable	Description
bundleId	ID of the bundle from which shipments should be removed (path parameter)

Body

Fields	Description
volumes	List of shipment IDs to remove
hash	Hash associated with the bundle

Example:

curl -X DELETE "https://api.mercadolibre.com/soe/bundles/12345/volumes" \
-H "Content-Type: application/json" \
-H "Authorization: Bearer {your_token}" \
-d '{"volumes": ["123456789", "987654321", "555666777"], "hash": "abcd1234"}'

// Response:
// 200 OK

Errors

Http Code	Message	Solution
400	One or more of the given parameters is invalid	Verify that bundleId is a valid positive number
401	User is not authorized into the application	Verify that the authorization token is valid and present in the header
404	Bundle data not found for given user	The specified bundle does not exist
409	The request generates conflict with existing data	Volumes cannot be removed due to their current status
424	An external dependency has failed	External service error.
500	Internal server error	Internal server error.

7. Download File

This resource allows you to download the file associated with a specific bundle from its identifier. With this, you can obtain the CSV file generated with the bundle information and its containerization, facilitating printing, validation and operational use of the documentation required during pickup.

Call:

curl -X GET -H 'Authorization: Bearer $ACCESS_TOKEN' \
https://api.mercadolibre.com/soe/bundles/{bundleId}/file

Required query parameters

Variable	Description
bundleId	Bundle ID to download the file (path parameter)

Example:

curl -X GET -H 'Authorization: Bearer $ACCESS_TOKEN' \
https://api.mercadolibre.com/soe/bundles/789/file

// Response:
// Binary file content (CSV)

Response fields

file: File content

Response headers

content_disposition: Content disposition
content_type: File content type

Errors

Http Code	Message	Solution
400	One or more of the given parameters is invalid	Verify that bundleId is a valid positive number
401	User is not authorized into the application	Verify that the authorization token is valid and present in the header
404	Bundle data not found for given user	The specified bundle or user does not exist
424	An external dependency has failed	External file generation service error
500	Internal server error	Internal server error when generating the file

8. Download Label

This resource allows you to download the label associated with a specific bundle, indicating the desired print format. From the bundle_id, the containerized unit label is generated in the requested format (for example, PDF, ZPL and ZIP), allowing its printing, scanning and operational use.

Call:

curl -X POST -H 'Authorization: Bearer $ACCESS_TOKEN' \
https://api.mercadolibre.com/soe/bundles/label

Body Label Download Request (valid JSON)

Fields	Description
bundle_id	ID of the bundle whose label you want to print
format	Format in which you want to print the label

Example:

curl -X POST -H 'Authorization: Bearer $ACCESS_TOKEN' \
-H 'Content-Type: application/json' \
-d '{"bundle_id": 789, "format": "PDF"}' \
https://api.mercadolibre.com/soe/bundles/label

// Response:
{
  "file": "base64_encoded_data",
  "content_type": "application/pdf",
  "file_name": "ETIQUETA_789"
}

Response fields

file: Label binary
content_type: Content type
file_name: File name

Errors

Http Code	Message	Solution
400	Bad arguments	Validate the JSON body format with valid parameters
401	User is not authorized into the application	Verify that the authorization token is valid and present in the header
404	Management data not found for given user	The specified bundle for generating the label does not exist
424	An external dependency has failed	External label generation service error
500	Internal server error	Internal server error when generating the label