Packs management

Entities relationship

The diagram illustrates how the key components are interrelated within a pack:

• Pack: It becomes a mandatory component in all purchases, as all orders will be associated with a pack_id.
• Relationship with Order: There is a 1 to N relationship between a pack and one or more orders. This means that a pack can contain multiple orders, which reflects situations where several orders are grouped into a single pack.
• Relationship with Shipping: There is a 0 to 1 relationship, which suggests that a pack may or may not be linked to a shipping process. This case is common, especially in sales of not_specified items, where a shipment_id is not always required.
• Relationship with Payments: There is a 1 to N relationship between an order and one or more payments. This implies that an order may require multiple payments, such as in the case of installment payments or when an order is associated with various different transactions.

This diagram provides a clear view of the flow of packs, orders, shipping, and payments, highlighting the flexibility and possible variations in each component.

Learn more about:

• How do I use the extended warranty?
• How do I extend a product's warranty?
• How do I cancel the extended warranty?

Consult pack orders

Represents a purchase package, it can have one or several orders from the same or different sellers.

This endpoint allows you to consult information about the orders of a pack.

Request:

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

Example:

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

Response:

{
    "shipment": {
        "id": 43729529445
    },
    "orders": [
        {
            "id": 2000009047722568
        },
        {
            "id": 2000009047707726
        }
    ],
    "id": 2000006181551917,
    "status": "released",
    "status_detail": null,
    "family_pack_id": null,
    "buyer": {
        "id": 1944693439
    },
    "date_created": "2024-08-15T17:38:30.000-0400",
    "last_updated": "2024-08-15T17:42:52.000-0400"
}

Response parameters:

• shipment.id: Unique identifier of the shipment.
• orders.id: Unique identifiers of the orders associated with a pack.
• id: Unique identifier of the pack.
• status: Current status of the pack. It may take the following values:
  • Released: the orders and shipment are paid.
  • Error: Something failed in the process and could be recovered.
  • Pending_cancel: an unrecoverable error occurred.
  • Cancelled: the orders and shipment are canceled.
• status_detail: Provides additional details about the pack's status, such as the reasons for a cancellation or any other specific issue affecting the shipment (in this case, null indicates there are no additional details).
• buyer.id: Unique identifier of the buyer associated with the pack.
• date_created: Date and time the pack was created.
• last_updated: Date and time of the last update of the pack.

Response status codes:

Consult orders

An order represents the purchase of an item-variation in the marketplace. The order is always for a single item, but there can be multiple units of the same item.

This endpoint allows you to retrieve details about a specific order.

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/2000008779458474

Response:

    {
        "id": 2000009047691488,
        "date_created": "2024-08-15T17:36:41.000-04:00",
        "last_updated": "2024-08-15T17:42:10.000-04:00",
        "expiration_date": "2024-09-12T17:36:43.000-04:00",
        "date_closed": "2024-08-15T17:36:43.000-04:00",
        "pack_id": null,
        "fulfilled": true,
        "buying_mode": "buy_equals_pay",
        "shipping_cost": null,
        "mediations": [],
        "total_amount": 1000.00,
        "paid_amount": 4784.99,
        "coupon": {
            "amount": 0.00,
            "id": null
        },
        "order_items": [
            {
                "item": {
                    "id": "MLA1443455161",
                    "title": "Lápiz Labial Love Me De Batom Mac You, 431, Color Rojo",
                    "category_id": "MLA29883",
                    "variation_id": 181369367530,
                    "seller_custom_field": null,
                    "variation_attributes": [
                        {
                            "name": "Color",
                            "id": "COLOR",
                            "value_id": "51993",
                            "value_name": "Rojo"
                        }
                    ],
                    "warranty": "Garantía del vendedor: 30 días",
                    "condition": "new",
                    "seller_sku": null,
                    "global_price": null,
                    "net_weight": null,
                    "user_product_id": "MLAU458107282",
                    "release_date": null
                },
                "quantity": 1,
                "requested_quantity": {
                    "value": 1,
                    "measure": "unit"
                },
                "picked_quantity": null,
                "unit_price": 1000.00,
                "full_unit_price": 1000.00,
                "currency_id": "ARS",
                "manufacturing_days": null,
                "sale_fee": 1290.00,
                "listing_type_id": "gold_pro",
                "base_exchange_rate": null,
                "base_currency_id": null,
                "element_id": null,
                "discounts": null,
                "bundle": null,
                "compat_id": null,
                "stock":  {
                      "store_id": "54936888", // New attributes of Distributed Stock and Multi-Origin
                      "node_id": "MXP10000665555", // New attributes of Distributed Stock and Multi-Origin
                    }
            }
        ],
        "currency_id": "ARS",
        "payments": [
            {
                "id": 85100978297,
                "order_id": 2000009047691488,
                "payer_id": 1944693439,
                "collector": {
                    "id": 1947296464
                },
                "card_id": null,
                "reason": "Lápiz Labial Love Me De Batom Mac You, 431, Color Rojo",
                "site_id": "MLA",
                "payment_method_id": "master",
                "currency_id": "ARS",
                "installments": 1,
                "issuer_id": "3",
                "atm_transfer_reference": {
                    "transaction_id": null,
                    "company_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": 1000.00,
                "transaction_amount_refunded": 0.00,
                "taxes_amount": 0.00,
                "shipping_cost": 3784.99,
                "coupon_amount": 0.00,
                "overpaid_amount": 0.00,
                "total_paid_amount": 4784.99,
                "installment_amount": 4784.99,
                "deferred_period": null,
                "date_approved": "2024-08-15T17:36:43.000-04:00",
                "transaction_order_id": null,
                "date_created": "2024-08-15T17:36:42.000-04:00",
                "date_last_modified": "2024-08-15T17:36:49.000-04:00",
                "marketplace_fee": 0.00,
                "reference_id": null,
                "authorization_code": "301299"
            }
        ],
        "shipping": {
            "id": 43729693454
        },
        "status": "paid",
        "status_detail": null,
        "tags": [
            "paid",
            "delivered",
            "test_order"
        ],
        "feedback": {
            "seller": null,
            "buyer": null
        },
        "context": {
            "channel": "marketplace",
            "site": "MLA",
            "flows": []
        },
        "seller": {
            "id": 1947296464,
            "user_type": null,
            "tags": [],
            "status": null,
            "buy_restrictions": []
        },
        "buyer": {
            "id": 1944693439,
            "nickname": "TESTUSER559713256",
            "first_name": "Test",
            "last_name": "Test",
            "user_type": null,
            "tags": [],
            "status": null,
            "buy_restrictions": []
        },
        "taxes": {
            "amount": null,
            "currency_id": null,
            "id": null
        },
        "cancel_detail": null,
        "manufacturing_ending_date": null,
        "order_request": {
            "change": null,
            "return": null
        }
    }
    

Response parameters:

• id: Unique order identifier.
• date_created: Date and time the order was created.
• last_updated: Date and time of the last update of the order.
• expiration_date: Date and time the order expires.
• date_closed: Date and time the order was closed.
• pack_id: Identifier of the pack to which the order belongs, if associated with a pack.
• fulfilled: Indicates whether the order has been fulfilled or completed (boolean value).
• buying_mode: Buying mode used, in this case, "buy_equals_pay" (buy equals pay).
• shipping_cost: Shipping cost associated with the order. It may be null if it is part of a pack_id. Otherwise, the shipping cost paid by the buyer for their order will be shown.
• mediations: Array of mediations associated with the order (can be empty).
• total_amount: Total amount of the order.
• paid_amount: Amount paid for the order.
• order_items: Array that contains the details of the products included in the order, such as title, quantity, unit price, etc.
• order_items.stock: This attribute represents a structure that groups information related to the availability and location of an item’s stock.
  • order_items.stock.store_id: This field identifies the store or specific physical location where an item's stock is stored.
  • order_items.stock.node_id: This attribute represents the seller's node or the specific physical location from which an item originates.
• currency_id: Identifier of the currency used in the transaction.
• payments: Array of payments associated with the order, including details such as the payment method, transaction amount, payment status, etc.
• shipping: Information about the shipment, including the shipment id.
• status: Current status of the order (e.g., "paid").
• status_detail: Additional details about the order status (can be null).
• tags: Array of tags associated with the order.
• feedback: Information about the seller and buyer feedback (can be null).
• context: Contextual information about the order, including channel and country.
• seller: Information about the seller, including their "id", user type, and purchasing restrictions.
• buyer: Information about the buyer, including their "id", nickname, first name, last name, user type, and purchasing restrictions.
• taxes: Information about the taxes applied to the order, including the amount and currency (can be null).
• cancel_detail: Details about the cancellation of the order (can be null).
• manufacturing_ending_date: Date of completion of manufacturing, if applicable (can be null).
• order_request: Information about requests for changes or returns associated with the order (can be null).

Response status codes:

Considerations

• The pack_order tag is generated automatically to identify if the order is associated with a pack. This tag cannot be removed by the buyer or the seller.
• Sometimes, it may happen that, even though there is an order, the shipment takes time to be created. In these cases, the shipping ID will be null until the shipment is created, and you will receive a notification once it is generated.
• The delivered/not delivered tags will no longer be added automatically. If you need these tags to be present, the integrator will have to perform a PUT with the corresponding tag.
• Orders in paid status will be canceled if the payment is refunded. When this happens, you will receive a notification to keep you informed of the order's status change.
• Although the order will still display the seller_custom_field field, the information displayed in this field will follow certain criteria to select SKU information, such as:
  • seller_sku of variation attributes
  • seller_custom_field of variation
  • seller_sku of item attributes
  • seller_custom_field of item
• If the order is not associated with a pack and the transaction is under the "to be agreed" mode, you will no longer receive a to be agreed status. Instead, the shipping ID will come as null. This will signal that you need to contact the buyer to coordinate the shipping method.

I have the product

This endpoint allows the seller to mark the stock availability or "I have the product", allowing them to dispatch the product when it's ready.

Request:

curl -X POST -H 'Authorization: Bearer $ACCESS_TOKEN' https://api.mercadolibre.com/shipments/$SHIPMENT_ID/process/ready_to_ship

Example:

curl -X POST -H 'Authorization: Bearer $ACCESS_TOKEN' https://api.mercadolibre.com/shipments/43664723386/process/ready_to_ship

Response:

{                                                                                                              
    "status": 200                                                                                              
}

Response Status Codes:

Considerations:

• Keep in mind that this functionality can only be used for ME2 orders.
• Consider that it is enabled in countries that have the functionality of manufacturing_time and ME2.