Billing reports

With this functionality you can see the billing reports made by Mercado Libre for sellers. For this, we recommend you request /billing/period to obtain information on the last 12 periods, then with /bills ou will get all the invoices (documents) of a period, and finally, with /summary and /details you access the billing summary of a period and its details respectively.

Contents

→Mercado Pago report
→Get the period
→Get documents from a period
→Billing summary
→Settlement detail
    ↳Optional filters available


Mercado Pago report

Now you can use the society=MP parameter in all the resources to get information about Mercado Pago's billing in order to reconcile invoices. By default, if you don't send it, we will return Mercado Libre billing information.


Example:

curl -X GET  -H 'Authorization: Bearer $ACCESS_TOKEN' https://api.mercadolibre.com/users/123456789/billing/period/20190510/details&society=MP

Response:

{
   "paging":{
      "offset":5,
      "limit":150,
      "total":238618
   },
   "results":[
      {
         "concept":"Pago Comisión MercadoPago",
         "id":878787878787,
         "type":"MP",
         "subtype":"CCMP",
         "detail_type":"CHARGE",
         "date_created":"2021-02-01T04:01:01",
         "prepaid":true,
         "amount":1.47,
         "currency_id":"ARS",
         "site_id":"ARS",
         "document":{
            "id":123456789,
            "date_of_expiration":"2021-03-02",
            "society":"MERCADO-PAGO"
         },
         "mp_info":{
            "id":15454547,
            "ref":"53245543",
            "amount":152,
            "detail":"payment",
            "nickname":"nickname"
         }
      }
   ]
}
Note:
If you send an invalid society or use society=MP together with any of the filters type, order_id, item_id, date_from and/or date_to, the API will return the following errors:

Invalid society error:

{
   "statusCode": 1024,
   "message": "Society parameter is invalid. Possible value: MP"
}

Error using a filter not allowed with society=MP:

{
   "statusCode": 1019,
   "message": "Filter type is not allowed to get Mercado-Pago society details"
}

Get the period

Important:
The billing period may vary depending on the user. Also, you can´t use with TEST users.

To know the period which make the request to Summary and Conciliation Detail resources, you have to GET request:
Request:

curl -X GET -H 'Authorization: Bearer $ACCESS_TOKEN' https://api.mercadolibre.com/users/$USER_ID/billing/period

Example:

curl -X GET -H 'Authorization: Bearer $ACCESS_TOKEN' https://api.mercadolibre.com/users/123456789/billing/period

Response:

{
    "period": [
        {
            "paid": "Y",
            "date_from": "2020-02-05T00:00:00.000-04:00",
            "date_to": "2020-03-04T00:00:00.000-04:00",
            "expiration_date": "2020-03-10T00:00:00.000-04:00",
            "period": "20200310",
            "total_amount": 3440,
            "bills": [
                {
                    "id": 1003544720,
                    "status": "A",
                    "expired_date": "2020-03-10T00:00:00.000-04:00",
                    "amount": 3440,
                    "pending_amount": 0,
                    "pay_status": "Y",
                    "period": {
                        "date_from": "2020-02-05T00:00:00.000-04:00",
                        "date_to": "2020-03-04T00:00:00.000-04:00"
                    },
                    "url_invoice": "https://myaccount.mercadolibre.com.uy/billing/v2/api/billing/user/123456789/invoices/349ac13f-b578?type=pdf"
                }
            ]
        },
        {
            "paid": "Y",
            "date_from": "2020-01-05T00:00:00.000-04:00",
            "date_to": "2020-02-04T00:00:00.000-04:00",
            "expiration_date": "2020-02-10T00:00:00.000-04:00",
            "period": "20200210",
            "total_amount": 3440,
            "bills": [
                {
                    "id": 980292894,
                    "status": "A",
                    "expired_date": "2020-02-10T00:00:00.000-04:00",
                    "amount": 3440,
                    "pending_amount": 0,
                    "pay_status": "Y",
                    "period": {
                        "date_from": "2020-01-05T00:00:00.000-04:00",
                        "date_to": "2020-02-04T00:00:00.000-04:00"
                    }
                }
            ]
        },
        {
            "paid": "Y",
            "date_from": "2019-12-05T00:00:00.000-04:00",
            "date_to": "2020-01-04T00:00:00.000-04:00",
            "expiration_date": "2020-01-10T00:00:00.000-04:00",
            "period": "20200110",
            "total_amount": 3180,
            "bills": [
                {
                    "id": 958238325,
                    "status": "A",
                    "expired_date": "2020-01-10T00:00:00.000-04:00",
                    "amount": 3180,
                    "pending_amount": 0,
                    "pay_status": "Y",
                    "period": {
                        "date_from": "2019-12-05T00:00:00.000-04:00",
                        "date_to": "2020-01-04T00:00:00.000-04:00"
                    },
                    "url_invoice": "https://myaccount.mercadolibre.com.uy/billing/v2/api/billing/user/123456789/invoices/36006403-dc10?type=pdf"
                }
            ]
        },
        {
            "paid": "Y",
            "date_from": "2019-11-05T00:00:00.000-04:00",
            "date_to": "2019-12-04T00:00:00.000-04:00",
            "expiration_date": "2019-12-10T00:00:00.000-04:00",
            "period": "20191210",
            "total_amount": 3180,
            "bills": [
                {
                    "id": 935204108,
                    "status": "A",
                    "expired_date": "2019-12-10T00:00:00.000-04:00",
                    "amount": 3180,
                    "pending_amount": 0,
                    "pay_status": "Y",
                    "period": {
                        "date_from": "2019-11-05T00:00:00.000-04:00",
                        "date_to": "2019-12-04T00:00:00.000-04:00"
                    }
                }
            ]
        },
    ]
}


Response fields

paid: field that indicate if the ticket was payed.
date_from: document´s start date.
date_to: it is the last day date.
expiration_date: the deadline date of the document.
period: period number to use in the next resources.
total_amount: total amount of all documents for that period.
bills: returns a list with all the existing documents in the searched period.

  • id: document id.
  • status: document status, whether it is active or inactive.
  • expired_date: document expiration date.
  • amount: amount of the document header.
  • pending_amount: remaining amount to pay.
  • pay_status: if the document is paid or unpaid (Y or N).
  • period: period in which their charges enter.
  •       date_from: creation date of the first charge of the period.
          date_to: creation date of the last charge of the period.

  • url_invoice: URL of the generated legal invoice.
Notes:
- The paid field may not appear for all accounts. This resource returns a maximum of the last 12 periods.
- The url_invoice field may not appear if at the time of the consultation, there is no legal invoice for that document.

Get documents from a period

Request:

curl -X GET -H 'Authorization: Bearer $ACCESS_TOKEN' https://api.mercadolibre.com/users/$USER_ID/billing/period/$PERIODO/bills?$FI LTROS_OPCIONALES

Example:

curl -X GET -H 'Authorization: Bearer $ACCESS_TOKEN' https://api.mercadolibre.com/users/443033562/period/20210101/bills?offset=150

Response:

{
   "paging":{
      "offset":150,
      "limit":150,
      "total":238618
   },
   "results":[
      {
         "id":1003544720,
         "expired_date":"2020-03-10T00:00:00.000-04:00",
         "amount":3440,
         "pending_amount":0,
         "pay_status":"Y",
         "period":{
            "date_from":"2020-02-05T00:00:00.000-04:00",
            "date_to":"2020-03-04T00:00:00.000-04:00"
         }
      }
   ]
}

available filters

document_id: Allows you to search by the invoice id. I.e: document_id=987046992
offset: Allows you to search from a result number onwards I.e: offset=100 (returns from result number 100)
limit: limit the number of results. By default the minimum is 150. Maximum allowed value: 1000.
I.e: limit=300 (returns until 300 results).


Billing summary

To know a summary of the charges and compensations that you had as a seller within a period of time, you must GET the Summary resource.

Request:

curl -X GET  -H 'Authorization: Bearer $ACCESS_TOKEN' https://api.mercadolibre.com/users/$USER_ID/billing/period/$PERIODO/summary

Example:

curl -X GET  -H 'Authorization: Bearer $ACCESS_TOKEN' https://api.mercadolibre.com/users/443033562/billing/period/20190510/summary

Response:

{
  "user": {
    "nickname": "TESTING123"
  },
  "period": {
    "date_from": "2019-04-05T00:00:00.000-04:00",
    "date_to": "2019-05-04T00:00:00.000-04:00",
    "date_of_expiration": "2019-05-10T00:00:00.000-04:00"
  },
  "summary": {
    "amount": 4141767.47,
    "credit_note": 43111.7,
    "tax": 492483.66,
    "bonuses": [
      {
        "label": "Bonificación del cargo por venta",
        "amount": 71007.49
      },
    ],
    "charges": [
      {
        "label": "Cargo por venta",
        "amount": 2784300.73
      },
      {
        "label": "Cargo por Mercado Envíos",
        "amount": 605717.77
      },
       {
        "label": "Percepción IIBB Com. Electrónico",
        "amount": 15529.9
      }
     ]
  }
}

Response:

{
  "user": {
    "nickname": "TESTING123"
  },
  "period": {
    "date_from": "2019-04-05T00:00:00.000-04:00",
    "date_to": "2019-05-04T00:00:00.000-04:00",
    "date_of_expiration": "2019-05-10T00:00:00.000-04:00"
  },
  "summary": {
    "amount": 4141767.47,
    "credit_note": 43111.7,
    "tax": 492483.66,
    "bonuses": [
      {
        "label": "Bonificación del cargo por venta",
        "amount": 71007.49
      },
    ],
    "charges": [
      {
        "label": "Cargo por venta",
        "amount": 2784300.73
      },
      {
        "label": "Cargo por Mercado Envíos",
        "amount": 605717.77
      },
    ]
  }
}

Response fields

Summary: Here we will see the Charges and Bonuses that the seller had.
amount: It is the total to pay within the consulted billing period. It is formed with the sum of Charges and Taxes and subtraction of the Bonuses.
credit_note: They are the bonuses of charges generated in other periods. Credit notes are used to pay bills due.
tax: They are the perceptions generated by the different tax regimes.
bonuses:It is the refund of commissions for your sales and services that did not materialize. You will see them discriminated according to the type of bonus.

  • label: Bonus name
  • amount: Bonus price.

The bonuses can be for the following concepts:
Sales and shipping charges: If a sale fails due to a return or mail problems (such as product loss or damage), we refund the sales commission and shipping charge.
Advertising charges: If by mistake you hired the service or there was a problem with the collection, we will refund the difference.
Tax Perceptions Bonuses: When a sales charge is returned, the corresponding refund of the IVA tax collection (either for a new or a used item) and of Gross Income is also included. The same if there were errors in the application of a perception.
charges: They represent the different charges that the seller may have: sales commissions, publication costs, tax receipts, service charges (Example: Mercado Envios, Mercado Shops etc.)
In case of hiring advertising campaigns, they also appear here.


Settlement detail

The settlement detail is a report for settling your Mercado Libre and Mercado Envíos invoices with sales made charges.

Note:
If you query with an offset greater than 10,000, we recommend using the following filters and narrowing down the results, avoiding delayed responses.


Optional filters available

  • date_sort
    asc: sorts the results in ascending order (value by default)
    desc: sorts the results in descending results
    for example: date_sort=asc
  • date_from and date_to: They must be used together and allows searching within a date range. You can also use hours. Remember that the date range must always be within the period start and end dates
    Possible formats: yyyy-MM-dd o yyyy-MM-ddThh:mm:ss.sss.
    For example: only date: date_from=2019-05-09&date_to=2019-05-15
    Date and hour: date_from=2019-05-09T00:00:00.000&date_to=2019-05-15T00:00:00.000.
  • det_id: allows searching for a specific detail id.
    Ej: det_id=8398490328
  • det_type
    charge: returns only charges
    bonus: returns only bonuses
    For example: det_type=charge
  • subtypes: allows filtering by detail subtypes. Multiple can be defined separated by commas.
    For example: subtypes=CV,BV
  • not_subtypes: lets you exclude the specified detail subtypes from the search. Multiple can be defined separated by commas.
    Ej: not_subtypes=CXD,BXD
  • type: allows searching by the detail market.
    For example: type=SHIPPING
  • order_id: allows to search by the order id.
    For example: order_id=2294412230
  • item_id: allows searching by the id of the publication.
    For example: item_id=724159812
  • document_id: allows to search by the invoice id.
    For example: document_id=987046992
  • offset: allows searching from a result number onwards
    For example: offset=100 (devuelve a partir del resultado nro 100)
  • limit: limit the number of results. By default the minimum is 150 and the maximum allowed value: 1000.
    For example: limit=300 (returns up to 300 results)

Request:

curl -X GET -H 'Authorization: Bearer $ACCESS_TOKEN'  https://api.mercadolibre.com/users/$USER_ID/billing/period/$PERIODO/details?$FILTROS_OPCIONALES

Example:

curl -X GET-H 'Authorization: Bearer $ACCESS_TOKEN'  https://api.mercadolibre.com/users/443033562/billing/period/20190510/details

Response:

{
    "paging": {
        "total": 2679,
        "offset": 0,
        "limit": 150
    },
    "results": [
        {
            "concept": "Cargo por Mercado Envíos",
            "id": 5782869395,
            "type": "SHIPPING",
            "subtype": "CFF",
            "date": {
                "billable": "2020-01-21T00:00:00.000-04:00",
                "created": "2020-01-21T00:00:00.000-04:00"
            },
            "prepaid": true,
            "amount": 68.4,
            "currency_id": "MXN",
            "site_id": "MLM",
            "document": {
                "id": 987046992,
                "date_of_expiration": "2020-02-25T00:00:00.000-04:00",
                "society": "ML"
            },
            "order": {
                "id": 2290642081
            },
            "detail_type": "CHARGE",
            "mp_op_id": 28226734621
        },
        {
            "concept": "Cargo por venta",
            "id": 5782859370,
            "type": "CORE",
            "subtype": "CV",
            "date": {
                "billable": "2020-01-21T00:00:00.000-04:00",
                "created": "2020-01-21T00:00:00.000-04:00"
            },
            "prepaid": true,
            "amount": 272.87,
            "currency_id": "MXN",
            "site_id": "MLM",
            "document": {
                "id": 987046992,
                "date_of_expiration": "2020-02-25T00:00:00.000-04:00",
                "society": "ML"
            },
            "order": {
                "id": 2290642081,
                "item_id": 725366950
            },
            "detail_type": "CHARGE",
            "mp_op_id": 5801583834
        },
        {
            "concept": "Cargo por Mercado Envíos",
            "id": 5782887632,
            "type": "SHIPPING",
            "subtype": "CFF",
            "date": {
                "billable": "2020-01-21T00:00:00.000-04:00",
                "created": "2020-01-21T00:00:00.000-04:00"
            },
            "prepaid": true,
            "amount": 50.8,
            "currency_id": "MXN",
            "site_id": "MLM",
            "document": {
                "id": 987046992,
                "date_of_expiration": "2020-02-25T00:00:00.000-04:00",
                "society": "ML"
            },
            "order": {
                "id": 2290649986
            },
            "detail_type": "CHARGE",
            "mp_op_id": 28226824168
        },
        {
            "concept": "Cargo por venta",
            "id": 5782887634,
            "type": "CORE",
            "subtype": "CV",
            "date": {
                "billable": "2020-01-21T00:00:00.000-04:00",
                "created": "2020-01-21T00:00:00.000-04:00"
            },
            "prepaid": true,
            "amount": 285.87,
            "currency_id": "MXN",
            "site_id": "MLM",
            "document": {
                "id": 987046992,
                "date_of_expiration": "2020-02-25T00:00:00.000-04:00",
                "society": "ML"
            },
            "order": {
                "id": 2290649986,
                "item_id": 620189246
            },
            "detail_type": "CHARGE",
            "mp_op_id": 5801916351
        },
        {
            "concept": "Cargo por Mercado Envíos",
            "id": 5782897217,
            "type": "SHIPPING",
            "subtype": "CFF",
            "date": {
                "billable": "2020-01-21T00:00:00.000-04:00",
                "created": "2020-01-21T00:00:00.000-04:00"
            },
            "prepaid": true,
            "amount": 68.4,
            "currency_id": "MXN",
            "site_id": "MLM",
            "document": {
                "id": 987046992,
                "date_of_expiration": "2020-02-25T00:00:00.000-04:00",
                "society": "ML"
            },
            "order": {
                "id": 2290651588
            },
            "detail_type": "CHARGE",
            "mp_op_id": 28226713276
        },
]


Resources fields

concept: They are all sales and operations that you made during your billing period.

type: It is the business unit to which the position belongs.

  • shipment: when the charge is for Mercado Envios.
  • mp_operation: when is the charge for a sale.
  • tax: when is a tax charge.

subtype: It is the concept subtype that will allow you to better identify each operation. There are 1100 subtypes to distinguish charges, subscriptions, packages, perceptions, bonuses, cancellations, services, etc.

date: is the date of the transaction.

prepaid:

  • true: the charge is automatically debited through Mercado Pago.
  • false: the charge is NOT automatically debited.
  • amount: detail amount.

    currency_id: identifier of the currency according to the site_id.

    site_id: site where the detail was generated.

    document:

    • id: document identification number.
    • date_of_expiration: is the expiration date of said document.
    • society: refers to the entity that issues the documents.

    order:

    • id: identification number of the order linked to the concept.
    • item_id: identification number of the product committed in the order.

    detail_type: indicates whether it is a charge or a bonus.

    mp_op_id: is de Mercado Pago´s order number.

or register to recieve the latest news about our API