Shipping compensations

From now on, the carriers will inform Mercado Libre about the measurements of the shipping package. With these measurements, we recalculate the shipping cost and then charge the difference to the seller based on what we previously charged at checkout. This surplus to the shipping cost is called shipping compensation. See more about Shipping fees.

Recommended technical flow:

1. See if your shipping cost has a shipping compensation in the senders section.
2. If it does, call the get shipment compensation endpoint for more information about declared and validated costs and dimensions.
3. For free shipping items, you can take a look at how much your cost changed since we validated your declared dimensions.

Shipping costs

You can see the new array named compensations included in the Shipment cost response.

Response:

[...] 
"senders": [
      {
          "user_id": 456789,
          "cost": 177.85,
          "compensations":[
            {
              "amount": 173.27,
              "reason": "incorrect_dimensions",
              "comment": "Incorrect package dimensions"
            }
          ],
          "save": 76.22,
          "discounts": [
              {
                  "rate": 0.3,
                  "type": "mandatory",
                  "promoted_amount": 76.22
              }
          ],
      "compensation": 0
      }
  ]
}

compensations: compensations calculated based on reason (i.e. incorrect dimensions).

Get shipment compensation

Consult the shipping compensation generated for a specific shipment ID.

Parameters

shipment_id: the shipment unique identifier.
weight_unit: the weight unit (g, kg, lb or oz) to be considered by the response. If not parameterized, we will consider the default units defined by the seller’s country.
dimensions_unit: the dimensions unit (mm, cm, m, in or ft) to be considered by the response. If not parameterized, we will consider the default units defined by the seller’s country.

Request:

curl -H 'Authorization: Bearer $ACCESS_TOKEN' -X GET https://api.mercadolibre.com/marketplace/shipments/$SHIPMENT_ID/compensation_costs?weight_unit=$WEIGHT_UNIT&dimensions_unit=$DIMENSIONS_UNIT

Example:

curl -H 'Authorization: Bearer $ACCESS_TOKEN' -X GET https://api.mercadolibre.com/marketplace/shipments/12345/compensation_costs?weight_unit=g&dimensions_unit=cm

Response:

{
    "dimension_by": "seller",
    "package": {
        "declared": {
            "weight": {
                "net": 900,
                "billable": 900,
                "volumetric": 900,
                "unit": "g"
            },
            "dimensions": {
                "length": 15,
                "width": 10,
                "height": 30,
                "unit": "cm"
            },
            "bucket": {
                "min": 501,
                "max": 1000,
                "unit": "g"
            }
        },
        "validated": {
            "weight": {
                "net": 1200,
                "billable": 1200,
                "volumetric": 20,
                "unit": "g"
            },
            "dimensions": {
                "length": 10,
                "width": 5,
                "height": 2,
                "unit": "cm"
            },
            "bucket": {
                "min": 1001,
                "max": 1500,
                "unit": "g"
            }
        }
    },
    "costs": {
        "currency_id": "USD",
        "compensation": 25,
        "declared": {
           "sender": {
               "cost": 15,
           },
           "receiver": {
               "cost": 0,
           }
        },
        "validated": {
           "sender": {
               "cost": 40,
           },
           "receiver": {
               "cost": 0,
           }
        }
    }
}

Response fields

dimension_by: contains information about who declared the dimensions used at checkout. The declared dimensions can either be by the seller or by meli (when validated by Mercado Libre).
package: data about the declared and validated package’s weight and dimensions, alongside in which bucket (weight range) the billable weight fell into at charge time. The weight and dimension units can be parameterized according to preference.
costs: contains information about declared and validated sender and receiver costs, calculated based on the package’s declared and validated measurements, respectively. Furthermore, we use these costs to determine the final compensation cost to be charged on the seller’s behalf.
bucket: the bucket refers to the weight range on the shipping cost tables that determines the base shipping cost for the package.

Free shipping compensation

Search the free shipping compensation that is generated based on the difference between declared dimensions versus Mercado Libre's validated dimensions. These dimensions can generate a shipment compensation if they are different enough to end up in another shipping cost bucket.

Parameters:

item_id: the item unique identifier.
weight_unit: the weight unit (g, kg, lb or oz) to be considered by the response. If not parameterized, we will consider the default units defined by the seller’s country.
dimensions_unit: the dimensions unit (mm, cm, m, in or ft) to be considered by the response. If not parameterized, we will consider the default units defined by the seller’s country.

Request:

curl -H 'Authorization: Bearer $ACCESS_TOKEN' -X GET https://api.mercadolibre.com/marketplace/items/$ITEM_ID/shipping_compensation?weight_unit=$WEIGHT_UNIT&dimensions_unit=$DIMENSIONS_UNIT

Example:

curl -H 'Authorization: Bearer $ACCESS_TOKEN' -X GET https://api.mercadolibre.com/marketplace/items/MLM1234567/shipping_compensation?weight_unit=kg&dimensions_unit=cm

{
    "dimension_by": "seller",
    "package": {
        "declared": {
            "weights": {
                "net": 1.2,
                "billable": 1.2,
                "volumetric": 0.2,
                "unit": "kg"
            },
            "dimensions": {
                "length": 10,
                "width": 10,
                "height": 10,
                "unit": "cm"
            },
            "bucket": {
                "min": 1,
                "max": 1.5,
                "unit": "kg"
            }
        },
        "validated": {
            "weights": {
                "net": 1.8,
                "billable": 1.8,
                "volumetric": 0.6,
                "unit": "kg"
            },
            "dimensions": {
                "length": 20,
                "width": 15,
                "height": 10,
                "unit": "cm"
            },
            "bucket": {
                "min": 1.5,
                "max": 2.0,
                "unit": "kg"
            }
        }
    },
    "costs": {
        "currency_id": "USD",
        "compensation": 25,
        "declared": {
           "sender": {
               "cost": 15,
           }
        },
        "validated": {
           "sender": {
               "cost": 40
           }
        }
    }
}

dimension_by: contains information about who declared the dimensions used at checkout. The declared dimensions can either be by the seller or by meli (when validated by Mercado Libre).
package: data about the declared and validated package’s weight and dimensions, alongside in which bucket (weight range) the billable weight fell into at charge time. The weight and dimension units can be parameterized according to preference.
costs: contains information about declared and validated sender and receiver costs, calculated based on the package’s declared and validated measurements, respectively. Furthermore, we use these costs to determine the final compensation cost to be charged on the seller’s behalf.
bucket: the bucket refers to the weight range on the shipping cost tables that determines the base shipping cost for the package.