Developers

Documentación Mercado Libre

Descubre toda la información que debes conocer sobre las APIs de Mercado Libre.

Última actualización 01/02/2024

Billing reports

With this resource, you can get the billing reports made by Mercado Libre and Mercado Pago for sellers. Querying /billing/monthly/periods will give you information on the last 12 periods. Then, with /documents you will get all the invoices (documents) for a period, and finally, with /summary and /details you can access the billing summary for a period and, respectively, the details.

Mercado Libre and Mercado Pago billing

Each of the endpoints allows us to obtain billing information from both Mercado Libre and Mercado Pago. Through the mandatory query group parameter we can specify from which billing group we want to obtain the information.

Notes:

- It is not mandatory to consult the period endpoint first since the key required to consume the rest of the endpoints is the first day of the month. For example: 2023-06-01.

- Parameter document_type is required in /monthly/periods and optional in /documents.

- Parameter limit accepts 12 at most in /monthly/periods.

Get the period

Important:

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

Allows you to obtain information on the billing periods for the indicated billing group (Mercado Libre or Mercado Pago). By default, the last 6 periods are returned, with the possibility of consulting older periods using the offset and limit pagination.

Note:

Through the parameter document_type parameter, you can filter the type of document you want to obtain BILL | CREDIT_NOTE .

Request for MLM:

curl -X GET -H 'Authorization: Bearer $ACCESS_TOKEN' https://api.mercadolibre.com/billing/integration/periods

Request for MLA, MLB MCO, MLC, MLU, MPE, MLV and MCR sites:

curl -X GET -H 'Authorization: Bearer $ACCESS_TOKEN' https://api.mercadolibre.com/billing/integration/monthly/periods

Example for MLA, MLB MCO, MLC, MLU, MPE, MLV and MCR sites:

curl -X GET  -H 'Authorization: Bearer $ACCESS_TOKEN' https://api.mercadolibre.com/billing/integration/monthly/periods?group=MP&document_type=BILL&offset=1&limit=2

Response:

{
  "offset": 1,
  "limit": 2,
  "total": 27,
  "results": [{
      "amount": 30.46000027656555,
      "unpaid_amount": 0.0,
      "period": {
        "date_from": "2020-02-19",
        "date_to": "2020-03-18"
      },
      "key": "2020-03-01" 
      "expiration_date": "2020-03-24",
      "debt_expiration_date": "2020-03-24",
      "debt_expiration_date_move_reason": null,
      "debt_expiration_date_move_reason_description": null,
      "period_status": "CLOSED"
    },
    {
      "amount": 477888.1484375,
      "unpaid_amount": 0.0,
      "period": {
        "date_from": "2020-01-19",
        "date_to": "2020-02-18"
      },
      "expiration_date": "2020-02-24",
      "debt_expiration_date": "2020-03-23",
      "debt_expiration_date_move_reason": "PAYMENT_ANNULMENT",
      "debt_expiration_date_move_reason_description": "Anulación de pago",
      "period_status": "CLOSED"
    }
  ]
}

Response fields

amount: total amount for the period.
unpaid_amount: total amount pending payment.
period: date range of the period.

date_from: start date of the period.
date_to: period end date.

key: is the date of the first day of the month. For MLA, MLB, MCO, MLC, MLU, MPE, MLV and MCR sites it is the value used to consume the documents, details and summary endpoints.

expiration_date: is the period closing date. It is always reported when the period status is closed. For the rest of the sites (MLM) it is the value used to consume the documents, details and summary endpoints.

debt_expiration_date: is the debt expiration date. In case the expiration date is not moved this field will be equal to expiration_date.

debt_expiration_date_move_reason: motivoreason for debt expiration date change. In case the expiration date is not moved this field will be null.

Valores posibles: : AUTOMATIC_DOCUMENT_CLOSURE_PROCES | RECEIPT_ANNULMENT_PROCESS_UNRECORDED | RECEIPT_ANNULMENT_PROCESS | PERIOD_EXTENDED_BY_ADMIN | PAYMENT_ANNULMENT

debt_expiration_date_move_reason_description: internationalized description of debt_expiration_date_move_reason. In case the expiration date is not moved this field will be null.

period_status: indicates whether the period is open or closed. Possible values:OPEN | CLOSED .

Get documents from a period

Allows you to obtain information on the documents (Invoices and Credit Notes) for a particular billing period for the indicated billing group (Mercado Libre or Mercado Pago).

Request for MLM sites:

curl -X GET -H 'Authorization: Bearer $ACCESS_TOKEN' https://api.mercadolibre.com/billing/integration/periods/$EXPIRATION_DATE/documents

Request for MLA, MLB, MCO, MLC, MLU, MPE, MLV and MCR sites:

curl -X GET -H 'Authorization: Bearer $ACCESS_TOKEN' https://api.mercadolibre.com/billing/integration/periods/key/$key/documents

Example for MLA, MLB, MCO, MLC, MLU, MPE, MLV and MCR sites:

curl -X GET -H 'Authorization: Bearer $ACCESS_TOKEN' https://api.mercadolibre.com/billing/integration/periods/key/2021-06-01/documents?group=MP&document_type=BILL&limit=1

Response:

{
  "offset": 0,
  "limit": 1,
  "total": 2,
  "results": [{
    "id": 987654321,
    "user_id": 1234,
    "document_type": "BILL",
    "expiration_date": "2021-06-02",
    "associated_document_id": null,
    "amount": 3.86,
             "unpaid_amount": 0.0,
    "document_status": "BILLED",
    "site_id": "MLM",
    "period": {
      "date_from": "2021-05-03",
      "date_to": "2021-05-03"
    },
    "currency_id": "MXN",
    "count_details": 1,
     "files": [
               {
                   "file_id": "1234_FE_MEPF00869625_pdf",
                   "reference_number": "MEPF00999999"
               },
               {
                   "file_id": "1234_FE_MEPF00869625_xml",
                   "reference_number": "MEPF00999999"
               }
           ]
  }]
}

Optional filters

document_id: allows you to search by invoice id. Ex: document_id=987046992.
document_type: allows you to search by document type: Invoice or Credit Note. Possible values: BILL | CREDIT_NOTE.
offset: allows you to search from one result number onwards e.g. offset=100 (returns from result number 100).
limit: limits the number of results. By default the minimum is 150. Maximum allowed value: 1000. Ex: limit=300 (returns up to 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.

Note:

Through the document_type parameter you can filter the type of document to be obtained BILL | CREDIT_NOTE.

Request for MLM sites:

curl -X GET -H 'Authorization: Bearer $ACCESS_TOKEN' https://api.mercadolibre.com/billing/integration/periods/$EXPIRATION_DATE/summary

Request for MLA, MLB, MCO, MLC, MLU, MPE, MLV and MCR sites:

curl -X GET -H 'Authorization: Bearer $ACCESS_TOKEN' https://api.mercadolibre.com/billing/integration/periods/key/$key/summary

Example for MLA, MLB, MCO, MLC, MLU, MPE, MLV and MCR sites:

curl -X GET -H 'Authorization: Bearer $ACCESS_TOKEN' https://api.mercadolibre.com/billing/integration/periods/key/2021-06 -01/summary?group=MP&document_type=BILL

Response:

{
    "user": {
      "nickname": "TEST"
    },
    "period": {
      "date_from": "2021-05-01",
      "date_to": "2021-06-01",
      "expiration_date": "2021-06-02"
    },
    "summary": {
      "amount": 545562.37,
      "credit_note": 0,
      "tax": 0.00,
      "bonuses": [{
        "label": "Bonificación de MercadoPago",
        "amount": 7354.60
      },
      {
        "label": "Bonificación Impuesto a los Ingresos Brutos Cap. Fed.",
        "amount": 116.43
      },
      {
        "label": "Bonificación Impuesto al Valor Agregado Régimen General",
        "amount": 116.43
      }
      ],
      "charges": [{
          "label": "Cargo de MercadoPago",
          "amount": 524228.80
        },
        {
          "label": "Percepción General IIBB de CABA",
          "amount": 13003.72
        }, {
          "label": "Percepción IVA Régimen General",
          "amount": 13003.72
  
        },
        {
          "label": "Cargo por transferencia de dinero",
          "amount": 2913.59
        }
      ]
    }
  }

Campos de la respuesta

summary: cargos y bonificaciones que tuvo el vendedor.

amout: 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: hey 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.
amout: bonus price.

Request for MLA, MLB, MCO, MLC, MLU, MPE, MLV and MCR sites:

curl -X GET -H 'Authorization: Bearer $ACCESS_TOKEN'https://api.mercadolibre.com/billing/integration/periods/key/$KEY/summary/details

Example for MLA, MLB, MCO, MLC, MLU, MPE, MLV and MCR sites:

curl -X GET -H 'Authorization: Bearer $ACCESS_TOKEN'https://api.mercadolibre.com/billing/integration/periods/key/2023-10-01/summary/details

Note:

Using the optional group parameter, you can filter the information corresponding to Mercado Livre or Mercado Pago. If you don't specify, you'll get the result for both.

{
  "user": {
      "nickname": "TEST"
  },
  "period": {
      "date_from": "2023-06-19",
      "date_to": "2023-07-18",
      "expiration_date": "2023-07-24",
      "key": "2023-07-01"
  },
  "bill_includes": {
      "total_amount": 171070532.64,
      "total_perceptions": 33077380.48,
      "bonuses": [
          {
              "label": "Bonificación cargo por Mercado Envíos",
              "amount": 385261.63,
              "type": "BXD",
              "groupId":  3
          },
          {
              "label": "Bonificación del cargo por venta",
              "amount": 6123337.46,
              "type": "BXD",
              "groupId":  4
          },
          {
              "label": "Bonificación campañas de publicidad -   Product Ads",
              "amount": 12967.5,
              "type": "BXD",
              "groupId":  5
          },
          {
              "label": "Bonificación cargo por Mercado Envíos",
              "amount": 28132.36,
              "type": "BXD",
              "groupId":  6
          }
      ],
      "charges": [
          {
              "label": "Campañas de publicidad - Product Ads",
              "amount": 48600,
              "type": "PADS",
              "groupId":  24
          },
          {
              "label": "Percepción impuesto a los IIBB Rég. General de Salta",
              "amount": 111.18,
              "type": "CXD",
              "groupId":  25
          },
          {
              "label": "Percepción impuesto IIBB Com. Electrónico La Pampa",
              "amount": 178050.01,
              "type": "CXD",
              "groupId":  26
          },
          {
              "label": "Percep. gral. impuesto IIBB CABA Mercado Envíos",
              "amount": 257364.18,
              "type": "CXD",
              "groupId":  27
          },
          {
              "label": "Percepción impuesto IIBB CABA",
              "amount": 2593731.92,
              "type": "CXD",
              "groupId":  25
          },
          {
              "label": "Cargo por Mercado Envíos",
              "amount": 11195255.36
              "type": "CXD",
              "groupId":  24
          },
          {
              "label": "Cargo por venta",
              "amount": 131285530.48,
              "type": "CV",
              "groupId":  28
          },
      ]
  },
  "payment_collected": {
      "operation_discount": 136492738.16,
      "total_payment": 33353689.85,
      "total_credit_note": 1989281,
      "total_collected": 171070532.64,
      "total_debt": 0.00 
  },
  "errors": []
}

Response fields

user

nickname: user name.

period

date_from: start date of the period.
date_to: end date of the period.
expiration_date: expiration date.
key: date of the first day of the month.

bill_includes

total_amount: total amount.
total_perceptions: total amount of payments.
bonuses

label: description of the bonus.
amount: bonus amount.
type: type of bonus.
groupId: bonus group.

charges

label: description of the charge.
amount: amount of the charge.
type: type of charge.
groupId: group of the charge.

payment_collected:

operation_discount: operations discounted from sales.
total_payment: payments made.
total_credit_note: total credit notes.
total_collected: total paid.
total_debt: total debt.

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

Allows you to obtain the details to reconcile invoices and sales charges for a particular period, the billing group (Mercado Libre or Mercado Pago) and the type of document (Invoice or Credit Note). This information is the same that is available through the billing reports section.

Notes:

- If queries with an offset greater than 10,000, we recommend you use the filters and narrow down the results, avoiding delayed responses.
- Through the document_type parameter you can filter the type of document you want to get BILL | CREDIT_NOTE.

Mercado Libre

In the case of Mercado Libre, the details of the invoiced charges, sale information, discounts, shipping and publication information are shown.

Request for MLM sites:

curl -X GET -H 'Authorization: Bearer $ACCESS_TOKEN' https://api.mercadolibre.com/billing/integration/periods/$EXPIRATION_DATE/group/ML/details

Request for MLA, MLB, MCO, MLC, MLU, MPE, MLV and MCR sites:

curl -X GET -H 'Authorization: Bearer $ACCESS_TOKEN' https://api.mercadolibre.com/billing/integration/periods/key/$key/group/ML/details

Example for MLA, MLB, MCO, MLC, MLU, MPE, MLV and MCR sites:

curl -X GET -H 'Authorization: Bearer $ACCESS_TOKEN' https://api.mercadolibre.com/billing/integration/periods/key/2021-06-01/group/ML/details?document_type=BILL&limit=1

Response:

{
     "offset": 0,
     "limit": 150,
     "total": 1,
     "results": [
         {
             "charge_info": {
                 "legal_document_number": "0001A00123456",
                 "legal_document_status": "PROCESSED",
                 "legal_document_status_description": "Procesado",
                 "creation_date_time": "2021-05-13T08:08:24",
                 "detail_id": 123456789,
                 "detail_amount": 342.49,
                 "transaction_detail": "Cargo por Mercado Envíos",
                 "debited_from_operation": "YES",
                 "debited_from_operation_description": "Si",
                 "status": null,
                 "status_description": null,
                 "charge_bonified_id": null,
                 "detail_type": "CHARGE",
                 "detail_sub_type": "CXD",
                 "concept_type": "SHIPPING"
             },
             "discount_info": {
                 "charge_amount_without_discount": 684.99,
                 "discount_amount": 342.5,
                 "discount_reason": "Descuento general"
             },
             "sales_info": [
                 {
                     "order_id": 12345,
                     "operation_id": null,
                     "sale_date_time": "2021-05-13T08:05:10",
                     "sales_channel": "Mercado Libre",
                     "payer_nickname": "ABCD",
                     "state_name": "Neuquén",
                     "transaction_amount": 2499
                 },
              ],
             "shipping_info": {
                 "shipping_id": "123456789",
                 "pack_id": "200000123456789",
                 "receiver_shipping_cost": 0
             },
             "items_info": [
                 {
                     "item_id": "MLA987654321",
                     "item_title": "Fabrica Magdalenas Cup Cake Maker Atma Cm8910e",
                     "item_type": "gold_special",
                     "item_type_description": "Clásica",
  "item_category": "Electrodomésticos y Aires Ac. > Pequeños Electrodomésticos > Para Cocina > Máquinas para Postres > Máquinas de Cupcakes",
                     "inventory_id": null,
                     "item_amount": 1,
                     "item_price": 2499,
                     "order_id": 1234
                 }
             ],
             "document_info": {
                 "document_id": 1615633359
             },
             "marketplace_info": {
                 "marketplace": "SHIPPING"
             },
             "currency_info": {
                 "currency_id": "ARS"
             }
         }
     ],
     errors:[]
  }

Mercado Libre response fields

charge_info: position information.

legal_document_number: document number.
legal_document_status: document generation status. Possible values: PROCESSING | PROCESSED.
legal_document_status_description: internationalized description of the legal document status_document_status.
creation_date_time: date of creation of the position.
detail_id: position identifier.
transaction_detail: position detail.
debited_from_operation: indicates whether it is discounted from the transaction. Possible values: YES | NO | INAPPLICABLE.
debited_from_operation_description: internationalized description of the debited_from_operation field.
status: status of the position. Possible values: BONUS_ON_CREDIT_NOTE | BONUS_PART_ON_CREDIT_NOTE | BONUS_ON_BILL | BONUS_PART_ON_BILL | BONUS_ON | BONUS_PART_ON.
status_description: internationalized status description.
charge_bonified_id: bonus position identifier.
detail_amount: amount of the charge.
detail_type: type of detail.
detail_sub_type: subtypes of details.

discount_info: discount information.

charge_amount_without_discount: value of the charge without discount.
discount_amount: discount value.
discount_reason: reason for the discount.

sales_info: sales information.

order_id: sale identifier.
operation_id: payment identifier.
sale_date_time: date and time of sale.
sales_channel: sales channel.
payer_nickname: customer.
state_name: province.
transaction_amount: total amount of the sale.

shipping_info: shipping information.

shipping_id: shipment identifier.
pack_id: ackage identifier.
receiver_shipping_cost: shipping at customer's expense.

items_info: information on publications.

item_id: publication identifier.
item_title: title of the publication
item_type: type of publication.
item_category: publication category.
inventory_id: code of Mercado Libre.
item_amount: number of items sold.
item_price: unit price of the item.
order_id: order to which the item belongs.

documentInfo: document information.

document_id: Id number of documents.

marketplaceInfo: marketplace information.

marketplace: marketplace name.

currency_info: currency information according to the site_id.

currency_id: currency identifier according to the site_id.

Mercado Pago

For Mercado Pago, the detail of invoiced charges is shown with complementary information on the Mercado Pago operation, such as movements, payment methods, payer, branch, point of sale, among others.

Request for MLM sites:

curl -X GET -H 'Authorization: Bearer $ACCESS_TOKEN' https://api.mercadolibre.com/billing/integration/periods/$EXPIRATION_DATE/group/MP/details

Request for MLA, MLB, MLC, MLU, MPE, MLV and MCR sites:

curl -X GET -H 'Authorization: Bearer $ACCESS_TOKEN' https://api.mercadolibre.com/billing/integration/periods/key/$key/group/MP/details

Example MLA, MLB, MCO, MLC, MLU, MPE, MLV and MCR sites:

curl -X GET -H 'Authorization: Bearer $ACCESS_TOKEN' https://api.mercadolibre.com/billing/integration/periods/key/2021-06-01/group/MP/details?document_type=BILL&limit=1

Response:

{
  "offset": 0,
  "limit": 1,
  "total": 9,
  "results": [
      {
          "charge_info": {
              "legal_document_number": null,
              "legal_document_status": "PROCESSING",
              "legal_document_status_description": "En proceso",
              "concept_id": "12345678",
              "transaction_detail": "Cargo de MercadoPago",
              "creation_date_time": "2021-06-01T17:45:39",
              "detail_amount": 13.8,
      "detail_type": "CHARGE",
      "detail_sub_type": "CCMP"
              
          },
          "operation_info": {
              "operation_type": "BUY",
              "operation_type_description": "Pago",
              "reference_id": 12345678,
              "sales_channel": "Point",
              "store_id": 2222222,
              "store_name": "Store",
              "external_reference": "Venta presencial",
              "payer_nickname": "TEST",
              "transaction_amount": 340
          },
          "perception_info": {
              "aliquot": null,
              "taxable_amount": null
          },
         "document_info": {
      "document_id": 8888899999,
     },
    "market_type_info": {
      "marketplace": "MP"
          },

          "currency_info": {
              "currency_id": "MXN"
          }
      }
  ]
}

Mercado Pago response fields

charge_info: information of the position.

legal_document_number: document number.
detail_id: position identifier.
movement_id: movement number.
transaction_detail: detail.
creation_date_time: date of the position.
detail_amount: amount of the charge.
detail_type: type of detail.
detail_sub_type: subtypes of details.

operation_info: information of the operation to which it applies.

operation_type: type of operation. Possible values BUY | TAX .
operation_type_description: internationalized description of the operation field.
reference_id: related operation number.
sales_channel: type of payment.
store_id: branch number.
store_name: name of the branch.
external_reference: external reference number.
payer_nickname: customer.
transation_amount: amount of the operation.

perception_info: perception information.

aliquot: value of the aliquot.
taxable_amount: taxable income.

documentInfo: document information.

document_id: Id number of documents.

marketplaceInfo: marketplace information.

marketplace: marketplace name.

currency_info: currency information according to site_id.

currency_id: currency identifier according to the site_id.

Mercado Envíos Flex

For Mercado Envíos with Flex logistics, you can see the detail to reconcile Flex credits and cancellations for a particular period, the Mercado Libre billing group and the type of document (debit note or credit note). It also gives you information about the shipment and information about the sale.

Note:

The endpoint Flex is available just for MLA, MLC and MCO sites.

Request:

curl -X GET -H 'Authorization: Bearer $ACCESS_TOKEN' https://api.mercadolibre.com/billing/integration/periods/key/$keyEXPIRATION_DATE/group/ML/flex/details

Example:

curl -X GET -H 'Authorization: Bearer $ACCESS_TOKEN' https://api.mercadolibre.com/billing/integration/periods/key/2023-03-012/group/ML/flex/details?document_type=BILL&limit=1

{
    "offset": 0,
    "limit": 1,
    "total": 100,
    "results": [{
      "charge_info": {
        "legal_document_number": "00AA11AA00",
        "legal_document_status": "PROCESSED",
        "legal_document_status_description": "Procesado",
        "creation_date_time": "2023-02-21T12:35:58",
        "detail_id": 2020202020,
        "detail_associated_id": 4040404040,
        "detail_amount": 163,
        "transaction_detail": "Anulación de bonificación por Mercado Envíos Flex",
        "detail_type": "CHARGE",
        "detail_sub_type": "CFLX",
        "concept_type": "FLEX"
      },
      "shipping_info": {
        "shipping_id": 4444455555,
        "receiver_nickname": "NICKNAME",
        "pack_id": "12345678",
        "receiver_shipping_cost": 814.99,
        "order": {
          "order_id": 9000000008888888,
          "date_created": "2023-02-15T11:54:51",
          "total_amount": 29499,
          "payment_id": 998899889988,
          "buyer_nickname": "NICKNAME"
        }
      },
      "document_info": {
        "document_id": 776677667711
      }
    }],
    "errors": []
  }

Mercado Envíos Flex response fields

charge_info: charge information.

legal_document_number: document number.
legal_document_status: document generation status. Possible values: PROCESSING | PROCESSED
legal_document_status_description: internationalized description of the legal document status_document_status.
creation_date_time: date of creation of the charge.
detail_id: charge ID.
detail_associated_id: charge ID associated (in the case of a cancelation or credit).
detail_amount: charge amount.
transaction_detail: charge detail.
detail_type: detail type.
detail_sub_type: detail subtypes.
concept_type: concept type.

shipping_info: shipping information.

shipping_id: shipping ID.
receiver_nickname: client.
pack_id: package number.
receiver_shipping_cost: shipping cost.

order: sale information.

order_id: sale ID.
date_created: date of origin of the order.
totalAmount: total order amount.
paymentId: payment ID.
buyerNickname: client.

document_info: document information.

document_id: document ID.

Fulfillment

For Mercado Envios with Full logistics, you can see the detail to reconcile the charges and credits for collect and/or storage for a particular period, the Mercado Libre invoicing group and the type of document (invoice or credit note). It also provides information on the product stored or collected. Here are the types of charges available for Fulfillment reporting:

Stock withdrawal charge.
Extended storage charge.
Collection service charge.
Non-compliance charge.
Storage charge.

Note:

The endpoint FULL is available just for MLA, MLB, MLM, MCO and MLC sites.

Request for MLM site:

curl -X GET -H 'Authorization: Bearer $ACCESS_TOKEN' https://api.mercadolibre.com/billing/integration/periods/$EXPIRATION_DATE/group/ML/full/details

Requestfor MLA, MLB, MCO and MLC sites:

curl -X GET -H 'Authorization: Bearer $ACCESS_TOKEN'https://api.mercadolibre.com/billing/integration/periods/key/$key/group/ML/full/details

Example for MLA, MLB, MCO and MLC sites:

curl -X GET -H 'Authorization: Bearer $ACCESS_TOKEN' https://api.mercadolibre.com/billing/integration/periods/key/2023-03-01/group/ML/full/details?document_type=BILL&limit=1

Response:

{
	"offset": 0,
	"limit": 100,
	"total": 634,
	"results": [{
		"charge_info": {
			"legal_document_number": "000AAA00000000",
			"legal_document_status": "PROCESSED",
			"legal_document_status_description": "Procesado",
			"creation_date_time": "2021-07-23T16:37:58",
			"detail_id": 11111111111,
			"detail_amount": 2.54,
			"transaction_detail": "Cargo por servicio de colecta Full",
			"charge_bonified_id": null,
			"detail_type": "CHARGE",
			"detail_sub_type": "CFCB",
			"concept_type": "FULFILLMENT",
			"payment_id": 222222222
		},
		"fulfillment_info": {
			"type": "INBOUND_COLLECT",
			"amount_per_unit": 2.54,
			"amount": 2.54,
			"sku": "3125404000009",
			"ean": "3125404000009",
			"item_id": "MLM788740252",
			"item_title": "VESTIDO CORTO AZUL MARINO BORDADO EN PECHO DEVENDI",
			"variation": "AZUL MARINO | EG",
			"quantity": 1,
			"volume_type": null,
			"inventory_id": "LLLGGKK12",
			"inbound_id": 555555,
			"volume_unit": "m3",
			"amount_per_volume_unit": 500,
			"volume": 0.00507,
			"volume_total": 0.00507
		},
		"document_info": {
			"document_id": 333333333
		}
	}],
	"errors": []
}

Mercado Envíos Fulfillment response fields

charge_info: charge information.

legal_document_number: document number.
legal_document_status: document generation status. Possible values: PROCESSING, PROCESSED
creation_date_time: date of creation of the charge.
detail_id: charge ID.
detail_amount: charge amount.
transaction_detail: charge detail.
charge_bonified_id: ID of the charge that bonified.
detail_type: detail type.
detail_sub_type: detail sub_types.
concept_type: concept type.
payment_id: payment ID.

fulfillment_info: fulfillment information.

type: fulfillment type. Possible values: WITHDRAWAL | AGING | INBOUND_COLLECT | INBOUND_PENALTY | WAREHOUSING
amount_per_unit: amount per unit.
amount: total amount.
sku: stock-keeping-unit.
item_id: listing number.
item_title: listing title.
variation: product variation.
quantity: quantity stored or collected.
volume_type: unit size.
inventory_id: ML inventory code.
withdrawal_id: withdrawal number –TYPE WITHDRAWAL Stock withdrawal charge –
shipment_type: shipment type. –TYPE WITHDRAWAL Stock withdrawal charge –
volume_unit: unit of measure (m3). –TYPE WITHDRAWAL Stock withdrawal charge –
amount_per_volume_unit: amount per m3. –TYPE WITHDRAWAL Stock withdrawal charge –
volume: unit volume (cm3) –TYPE WITHDRAWAL Stock withdrawal charge–
volume_total: total volume. –TYPE WITHDRAWAL Stock withdrawal charge –
months_range: antiquity in months. –TYPE AGING Extended storage charge –
stock_details: stock details. –TYPE AGING Extended storage charge –
quantity: stock quantity. –TYPE AGING Cargo por Extended storage charge–
inventory_status: inventory status. –TYPE AGING Extended storage charge –
inbound_id: shipping number. –TYPE INBOUND_COLLECT Collection service charge –
volume_unit: unit of measure (m3) –TYPE INBOUND_COLLECT Collection service charge –
amount_per_volume_unit: amount per m3. –TYPE INBOUND_COLLECT Collection service charge –
volume: unit volume (cm3) –TYPE INBOUND_COLLECT Collection service charge –
volume_total: total volume. –TYPE INBOUND_COLLECT Collection service charge –
inbound_id: shipping number. –TYPE INBOUND_PENALTY Non-compliance charge -
penalty_type: no-compliance type. –TYPE INBOUND_PENALTY Non-compliance charge –
warehouse_id: warehouse ID.–TYPE WAREHOUSING Non-compliance charge –
size: unit size.–TYPE WAREHOUSING Storage charge–
item_quantity: stored units.–TYPE WAREHOUSING Storage charge –

document_info: document information.

document_id: document ID.

Insurtech

Allows to obtain the detail to reconcile the charges and bonuses of the guarantees applied on the products for a particular period, the Mercado Libre invoicing group and the type of document (invoice or credit note). This is the same information that is available through the billing report section for Insurtech users. The filter options can be used in the same way that we have available for Mercado Libre and Mercado Pago details.

Note:

The endpoint Insurtech is available just for MLA, MLB and MLC sites.

Request:

curl -X GET -H 'Authorization: Bearer $ACCESS_TOKEN' https://api.mercadolibre.com/billing/integration/periods/key/$key/group/ML/insurtech/details

Example:

curl -X GET -H 'Authorization: Bearer $ACCESS_TOKEN' https://api.mercadolibre.com/billing/integration/periods/key/2022-10-01/group/ML/insurtech/details?document_type=BILL&limit=1

Response:


  {
     "offset": 0,
     "limit": 150,
     "total": 1,
     "results": [
         {
             "charge_info": {
                 "legal_document_number": "001112131415",
                 "legal_document_status": "PROCESSED",
                 "legal_document_status_description": "Procesado",
                 "creation_date_time": "2022-10-04T22:24:18",
                 "detail_id": 123456,
                 "detail_amount": 520.01,
                 "transaction_detail": "Cargo por seguro de garantía extendida",
                 "status": null,
                 "status_description": null,
                 "charge_bonified_id": null,
                 "detail_type": "CHARGE",
                 "detail_sub_type": "CEW",
                 "concept_type": "WARRANTY"
             },
             "warranty_info": {
                 "warranty_id": "11111111-43c2-44ea-8436-00000000",
                 "certificate_id": "MLA999999",
                 "warranty_product": "GAREX",
                 "buyer_nickname": "TEST",
                 "buyer_state_name": "Salta",
                 "order": {
                     "order_id": 102030405060,
                     "order_items": [
                         {
                             "unit_price": 10791,
                             "listing_type_id": "gold_special",
                             "item": {
                                 "item_id": "MLA88888888",
                                 "title": "Auriculares Inalámbricos Jbl Tune 510bt Negro",
                                 "category_id": "MLA1234",
                                 "category_name": "Auriculares"
                             }
                         }
                     ]
                 },
                 "quote_model": null,
                 "quote_brand": null,
                 "quote_description": ""
             },
             "prepaid_info": {
                 "operation_id": 55558888,
                 "movement_id": 123456789,
                 "doc_id": 11111111111,
                 "payment": {
                     "payment_id": 5555555555,
                     "date_created": "2022-10-04T22:23:40",
                     "transaction_amount": 736.98,
                     "money_release_date": "2023-03-03T22:23:41"
                 }
             },
             "document_info": {
                 "document_id": 3333333333
             }
         }
  ]

>Insurtech response fields

charge_info: position information.

legal_document_number: document number.
legal_document_status: document generation status. Possible values: PROCESSING | PROCESSED.
legal_document_status_description: internationalized description of the document status legal_document_status.
creation_date_time: date of creation of the position.
detail_id: position identifier.
detail_amount: amount of the charge.
transaction_detail: position detail.
status: status of the position. Possible values: BONUS_ON_CREDIT_NOTE | BONUS_PART_ON_CREDIT_NOTE | BONUS_ON_BILL | BONUS_PART_ON_BILL | BONUS_ON | BONUS_PART_ON.
status_description: internationalized status description.
charge_bonified_id: bonus position identifier.
detail_type: type of detail.
detail_sub_type: subtypes of detail.
concept_type: concept type.

wanrranty_info: warranty information.

wanrranty_id: warranty identifier.
certificate_id: certificate identifier.
waranty_product: type of guarantee. Possible values: CARDS, GAREX, RODA.
buyer_nickname: buyer's number.
buyer_state_name: buyer's state.
order: order information.
order_id: identifier.
order_items: list of items in the order.
unit_price: unit price.
listing_type_id: listing type.
item: item information.
item_id: product identifier.
tittle: product title.
category_id: category identifier.
category_name: category name.
quote_model: product model. Applies to RODA.
quote_brand: product brand. Applies to RODA.
quote_description: additional description. Applies to RODA.

prepaid_info: payment information.

operation_id: operation identifier.
movement_id: payment identifier.
doc_id: document identifier.

payment: payment information.

payment_id: payment identifier.
date_created: payment date.
transaction_amount: payment amount.
money_release_date: money release date.

document_info: document information

document_id: ID document.

Optional filters

date_sort: allows you to sort the search.
asc: sorts results ascending (default value).
desc: sorts the results descendingly.
Ex: date_sort=asc

sort_by: allows you to select by which field to sort. Possible values: DATE

detail_type allows you to search by detail type.
charge: brings only charges.
bonus: retrieves only bonuses.
Ex: det_type=charge

detail_sub_types: allows filtering by detail subtypes. Several can be defined separated by comma.
Ex: detail_sub_types=CV, BV

detail_excluded_sub_types: allows the specified detail subtypes to be excluded from the search. Several subtypes can be defined separated by commas.
Ex: not_subtypes=CXD, BXD

marketplace_type: allows you to search by the marketplace of the detail.
Ex: marketplace_type=SHIPPING

order_ids: allows you to search by one or more order ids. Available for ML.
Ex: order_ids=2294412230.

item_ids: allows you to search by one or more id of the publication.
Ex: item_ids=724159812.

document_ids: allows you to search by one or more invoice ids.
Ex: document_ids=987046992

detail_ids: allows you to search by one or more detail ids.
Ex: detail_ids=724159812

offset: allows searching from one result number onwards. The minimum value allowed is 0 and the maximum value allowed is 10000. The default value is 0. Ex: offset=100 (returns from result number 100).

limit:limits the number of results. By default the minimum is 1 and the maximum allowed value: 1000 . Ex: limit=300 (returns up to 300 results).
Ex: limit=300 (returns up to 300 results).

Payment Report

Allows to obtain the details of the seller's invoices paid in a given period.

Request for MLM:

curl -X GET -H 'Authorization: Bearer $ACCESS_TOKEN' https://api.mercadolibre.com/billing/integration/periods/$expiration_date/group/ML/payment/details

URL parameters:

expiration_date: period in which you want to obtain the detail (Format: YYYY-mm-dd)

Request for MLA, MLB, MCO, MLC, MLU, MPE, MLV and MCR:

curl -X GET -H 'Authorization: Bearer $ACCESS_TOKEN' https://api.mercadolibre.com/billing/integration/periods/key/$key/group/ML/payment/details

URL parameters:

key: date of the first day of the month. (Format: YYYY-mm-dd)

Optional query parameters:

sort_by:

Possible values: DATE,ID.
Default values: DATE.

order_by: Allows you to sort the search.

Possible values: ASC, DESC.
Default values: ASC.

offset: Allows to search from one result number onwards. The minimum allowed value is 0 and the maximum allowed value is 10000. The default value is 0.
limit: Limits the amount of the result. The minimum value allowed is 1 and the maximum value allowed is 1000. Default value is 150.

Response fields

payment_id: Payment number.
credit_note_number: Credit note number (if applicable).
payment_date: Date of payment.
payment_type_description: Description of the payment type.
payment_type: Payment type.
payment_method_description: Description of payment method.
payment_method: Payment method.
payment_status_description: Description of the payment status.
payment_status: Payment status.
payment_amount: Total amount of payment.
amount_in_this_period: Amount applied in this period.
amount_in_other_period: Amount applied in another period.
remaining_amount: Balance in favor for next invoices.

Example:

curl -X GET -H 'Authorization: Bearer $ACCESS_TOKEN' https://api.mercadolibre.com/billing/integration/periods/key/2023-08-01/group/ML/payment/details?limit=1

Response:

"payment_info": {
       "payment_id": 57062878565,
       "credit_note_number": null,      
       "payment_date": "2023-04-19T12:53:24",
       "payment_type": "payment",
       "payment_type_description": "Pagos manuales",
       "payment_method": "amex",
       "payment_method_description": "American Express online",
       "payment_status": "approved",
       "payment_status_description": "Aplicado",
       "payment_amount": 999888,
       "amount_in_this_period": 103985.84,
       "amount_in_other_period": 895902.16,
       "remaining_amount": 0,
     }

Download Legal document

Allows you to download the legal invoices from Mercado Libre and Mercado Pago in PDF format for all sites.

Notes:

- The file_id In some cases the Documents endpoint may return two file_id. Only in these cases note that the file_id corresponding to the PDF must be used.

- If the Document endpoint returns a single file_id. Then you must use that data for the legal document download.

Request:

curl -X GET -H 'Authorization: Bearer $ACCESS_TOKEN' https://api.mercadolibre.com/billing/integration/legal_document/$FILE_ID

Example:

curl -X GET -H 'Authorization: Bearer $ACCESS_TOKEN' https://api.mercadolibre.com/billing/integration/legal_document/1234_FE_MEPF00869625_pdf

Response: Download the file in PDF format..

Download reconciliation report

To download the Mercado Libre, Mercado Envios Flex, Insurtech and Mercado Pago reconciliation reports in XLSX and CSV formats, a report generation process must be followed. The same process applies to the Fulfillment and payment report, which only supports the XLSX download format.
The report generation process consists of three steps: first the reconciliation report is generated, then the report generation status must be consulted until it is generated, and finally it is downloaded.

1. Report generation

This endpoint will be used to create the report.

Request for MLM sites:

curl -X POST -H 'Authorization: Bearer $ACCESS_TOKEN' -H "Content-Type: application/json" -d {...}
  https://api.mercadolibre.com/billing/integration/periods/$EXPIRATION_DATE/reports

Request for MLA, MLB, MCO, MLC, MLU, MPE, MLV and MCR sites:

curl -X POST -H 'Authorization: Bearer $ACCESS_TOKEN' -H "Content-Type: application/json" -d {...}
    https://api.mercadolibre.com/billing/integration/periods/key/$keyEXPIRATION_DATE/reports

Example for MLA, MLB, MCO, MLC, MLU, MPE, MLV and MCR sites:

curl -X POST -H 'Authorization: Bearer $ACCESS_TOKEN'
  -d '{
     "group": "MLP",
     "document_type": "BILL",
     "report_format": "CSV"
  }' 
  https://api.mercadolibre.com/billing/integration/periods/key/2021-08 -014/reports

The value of the group parameter varies according to the report to be generated:

ML for ML report.
MP for MP report.
FLEX for Flex report.
FULL for Fulfillment report.
INSURTECH for Insurtech report.
PAYMENT for the payment report.

Response:

{
  "fileId": "ML-report-BILL-2021-08-014-11119999-CSV-v2"
  }

2. Report generation status

It will allow you to get the status of the creation of a report. The status can be:

PROCESSING: the report is being generated.
READY: the report is finished generating.
ERROR: report generation failed, must be re-consulted.

Request:

curl -X GET -H 'Authorization: Bearer $ACCESS_TOKEN' https://api.mercadolibre.com/billing/integration/reports/$FILE_ID/status

Example:

curl -X GET -H 'Authorization: Bearer $ACCESS_TOKEN' https://api.mercadolibre.com/billing/integration/reports/ML-repo rt-BILL-2021-08-04-11119999-CSV-v2/status?document_type=BILL

Response:

{
"status": "PROCESSING"
}

3. Report download

With this endpoint, you can download the report. This download will be effective once the generation status is Ready.

Request:

curl -X GET -H 'Authorization: Bearer $ACCESS_TOKEN' https://api.mercadolibre.com/billing/integration/reports/$FILE_ID

Example:

curl -X GET -H 'Authorization: Bearer $ACCESS_TOKEN' https://api.mercadolibre.com/billing/integration/reports/ML-repo rt-BILL-2021-08-04-11119999-CSV-v2?document_type=BILL

Summary of perceptions

Important:

Applies only for Argentina.

Allows you to obtain the summary of payments made by the seller for a particular period, the billing group (Mercado Libre or Mercado Pago).

Request:

curl -X GET -H 'Authorization: Bearer $ACCESS_TOKEN' https://api.mercadolibre.com/billing/integration/periods/key/$key/perceptions/summary

Example:

curl -X GET -H 'Authorization: Bearer $ACCESS_TOKEN' https://api.mercadolibre.com/billing/integration/periods/key/2021-08-01/perceptions/summary?group=MP

Response:

{
  "summary": [
         {
          "document_id": 123456789,
          "society": "ML",
          "legal_document_number": "0011A012345678",
          "user_fiscal_condition": "Responsable inscripto sin incumplimientos",
          "amount": 229314.11,
          "regimen_tax_type": "MLA_RE_IVA_N",
          "regimen_tax_type_description": "Percepción de IVA nuevos del régimen 
  especial",
          "taxable_amount": 22931410.96,
          "aliquot": 1.00,
             "coefficient": 1.0000,
             "perception_charge_number": 1123456789,
             "tax_type": "CRGI",
             "tax_type_description": 
  "Percepción Impuesto al Valor Agregado nuevos",
             "bill_date": "2021-11-29",
             "status": "APPLIED",
             "status_description": "Aplicado"
        "tax_ids": [123345678,233455678]  
         }
  ],
  "errors": []
  }

Response fields

summary: summary information.

document_id: document identifier.
society: society. Possible values ML | MP.
legal_document_number: document number.
user_fiscal_condition: tax status of the user.
amount: total payable within the period consulted.
regimen_tax_type: tax rate regime.
regimen_tax_type_description: internationalized description of the tax rate regime.
taxable_amount: taxable income.
aliquot: value of the aliquot.
coefficient: coefficient involved in the calculation of the tax.
perception_charge_number: charge number of perception charge.
tax_type: tax rate.
tax_type_description: internationalized description of the tax rate.
bill_date: billing date.
status: summary status.
status_description: internationalized description of the state.
tax_ids: types of taxes.

Detail of perceptions

Important:

Applies only to Argentina.

Allows you to obtain the details of a specific perception. For Mercado Libre perceptions from the perception code and the document number. For Mercado Pago perceptions from the perception code, the document number and the tax identifier.

Notes:

- Mercado Pago: with the field tax_type, document_id and tax_id you can access the details of the payment and the document indicated in the filters.
- Mercado Libre: with the field tax_type, document_id you can access to the detail of the perception and of the document indicated in the filters.
- These fields are obtained from the Perception Summary endpoint.
- The result fields vary according to the tax_type consulted: General Regime, Special Regime, Tucumán Regime.

Mercado Libre

Request:

curl -X GET -H 'Authorization: Bearer $ACCESS_TOKEN' https://api.mercadolibre.com/billing/integration/group/ML/perceptions/details

Example (General Regime)::

curl -X GET -H 'Authorization: Bearer $ACCESS_TOKEN' https://api.mercadolibre.com/billing/integration/group/ML/perceptions/details?document_id=333555777&tax_type=CIVA&offset=1&limit=2

Response (General Regime)::

{
   "offset": 0,
   "limit": 150,
   "total": 4241,
   "results": [
       {
           "detail_id": 12345678,
           "date_created": "2021-10-30",
           "taxable_amount": 2660.0,
           "aliquot": 3.0,
           "tax_amount": 79.8,
           "transaction_detail": "CV",
           "transaction_detail_description": "Cargo por venta",
           "charge_bonified_id": null,
           "amount": 2660.0,
           "gross_amount": 3218.6,
           "detail_type": "CHARGE",
           "detail_type_description": "Cargo"
       }],
   "errors": []
}

Mercado Pago

Request:

curl -X GET -H 'Authorization: Bearer $ACCESS_TOKEN' https://api.mercadolibre.com/billing/integration/group/MP/perceptions/details

Example (General Regime):

curl -X GET -H 'Authorization: Bearer $ACCESS_TOKEN' https://api.mercadolibre.com/billing/integration/group/MP/perceptions/details?document_id=333555777&tax_type=CIVAMP&tax_id=12345&tax_id=12345&offset=1&limit=2

Response (General Regime):

{
   "offset": 0,
   "limit": 150,
   "total": 5,
   "results": [
       {
           "detail_id": 1114444,
           "date_created": "2021-10-30",
           "taxable_amount": 154.93,
           "aliquot": 3.0,
           "tax_amount": 4.6479,
           "movement_id": "1234567",
           "reference_id": 1234567,
           "transaction_detail": "CCMP",
           "transaction_detail_description": "Cargo de MercadoPago",
           "amount": 154.93,
           "gross_amount": 187.46,
           "detail_type": "CHARGE",
           "detail_type_description": "Cargo"
       }],
   "errors": []
}

Response fields

The following data is returned for Mercado Libre and for a General Regime perception:

detail_id: detail identifier.
date_created: creation date.
taxable_amount: taxable amount.
aliquot: tax rate value.
tax_amount: tax amount.
transaction_detai: transaction detail.
transaction_detail_description: internationalized description of transaction detail.
charge_bonified_id: identifier of the charge that bonifies in case the charge is a bonus. amount: amount of the charge.
amount: gross amount of the charge.
gross_amount: type of detail to which the charge applies.
detail_type: type of detail to which the charge applies.
detail_type_description: description of the type of detail to which the benefit applies.

For Mercado libre and for a Special Regime collection, the following data are also reported:

publish_number: publication number.
publish_title: title of the publication.
sale_date: date of sale.
sale_number: sale number.
buyer_name: buyer number.
buyer_state_name: buyer's state.

For Mercado Libre and for a perception of the Tucumán Regime, the following data is also reported:

coefficient: coefficient with which the amount of the tax is calculated.

For Mercado Pago the following information is also provided:

movement_id: movement number.
reference_id: related operation.

HTTP response code

206 - Partial content: in some cases, the endpoints will return the code 206 - Partial content. This will occur when the request to some of the data (e.g. discount of a detail) fails to inform you that you will receive an incomplete response. Errors can be displayed in the errors field of the endpoint response.

Field structure errors:

"errors": [
       {
           "index": 3,
           "error_type": "PARTIAL_CONTENT",
           "messages": "An error occurred while retrieving the information. Try again"    
       },
]

Field description:

index: position of the object that could not be retrieved.
date_created: error type.
taxable_amount: error description.

Note:

Applies to all endpoints, except for legal document download and reconciliation detail report download in XLSX and CSV format.

Possible Errors

The expected errors that may occur in the application will be returned taking into account the following structure:

{
   "timestamp": string($date-time),
   "status": integer($int32),
   "type": string,
   "message": string,

  "path": string,
   "errors": {

<*>: string }
}

timestamp: reports the date and time at which the error was generated.
status: reports the error code returned.
type: application error code. Possible values:

ABUSE_PREVENTION_ERROR
AUTHENTICATION_ERROR
AUTHORIZATION_ERROR
BAD_REQUEST_ERROR
VALIDATION_ERROR
TYPE_MISMATCH_ERROR
INTERNAL_ERROR
MISSING_PARAMETER_ERROR
METHOD_NOT_ALLOWED_ERROR
NOT_FOUND_ERROR

message: indicates an error message.
path: reports the endpoint that was consumed.
errors: reports the errors that occurred.

Example:

{
   "timestamp": "2021-07-07T21:21:09.72319Z",
   "status": 422,
   "type": "TYPE_MISMATCH_ERROR",
   "message": "Type mismatch error.",
   "path": "/periods",
   "errors": {
       "group": "Invalid format for value "
   }
}