Sign in

v1

latestOpenAPI 3.0.22026-08-061464031.4 MB
Invoices

List invoices

▶️ Usage

With the List Invoices method, you can:

  1. List invoices related to a specific link.id (using the link query parameter).
  2. Get the details of a specific invoice.id (using the id query parameter).
  3. [Not Recommended] List all invoices related to your Belvo account (without using any query parameters).

📖 Pagination

This method returns a paginated response (default: 100 items per page). You can use the page_size query parameter to increase the number of items returned to a maximum of 1000 items. You can use the page query parameter to navigate through the results. For more details on how to navigate Belvo's paginated responses, see our <a href="https://developers.belvo.com/docs/belvo-pagination-tips" target="_blank">Pagination Tips</a> article.

🔦 Filtering Responses

Please see the query list below for a list of fields that you can filter your responses by. For more information on how to use filters, see our <a href="https://developers.belvo.com/docs/searching-and-filtering" target="_blank">Filtering responses</a> article.

🚨 Deprecated Fields

This resource may return deprecated fields. In the response documentation you may see that a field has been marked as deprecated. This means that this field is no longer maintained by the Belvo team. You may still receive data for this field depending on the institution, however, you should not rely on this field.

get/api/invoices/

Query parameters

linkstring uuid
Example:8848bd0c-9c7e-4f53-a732-ec896b11d4c4

The link.id you want to filter by.

ℹ️ We highly recommend adding the link.id filter in order to improve your performance.

pageinteger
Example:1

A page number within the paginated result set.

page_sizeinteger
Example:100

Indicates how many results to return per page. By default we return 100 results per page.

ℹ️ The minimum number of results returned per page is 1 and the maximum is 1000. If you enter a value greater than 1000, our API will default to the maximum value (1000).

link__instring[]

Return results only for these link.ids.

[
  "5722d0ba-69d7-42dc-8ff5-33767b83c5d6"
]
omitstring

Omit certain fields from being returned in the response. For more information, see our <a href="https://developers.belvo.com/docs/searching-and-filtering" target="_blank">Filtering responses</a> DevPortal article.

fieldsstring

Return only the specified fields in the response. For more information, see our <a href="https://developers.belvo.com/docs/searching-and-filtering" target="_blank">Filtering responses</a> DevPortal article.

idstring uuid
Example:24ccab1d-3a86-4136-a6eb-e04bf52b356f

Return information only for this resource id.

id__instring[]

Return information for these resource ids.

[
  "6b3dea0f-be29-49d1-aabe-1a6d588642e6"
]
created_atstring date
Example:2022-05-05

Return items that were last updated in Belvo's database on this date (in YYYY-MM-DD format).

created_at__gtstring date
Example:2022-05-05

Return items that were last updated in Belvo's database after this date (in YYYY-MM-DD format).

created_at__gtestring date
Example:2022-05-04

Return items that were last updated in Belvo's database after or on this date (in YYYY-MM-DD format).

created_at__ltstring date
Example:2022-04-01

Return items that were last updated in Belvo's database before this date (in YYYY-MM-DD format).

created_at__ltestring date
Example:2022-03-30

Return items that were last updated in Belvo's database before or on this date (in YYYY-MM-DD format).

created_at__rangestring[]

Return accounts that were last updated in Belvo's database between two dates (in YYYY-MM-DD format). The first value indicates the start of the range and the second value indicates the end of the range.

[
  "2022-01-01",
  "2022-12-31"
]
invoice_datestring date
Example:2022-05-05

Return invoices issued exactly on this date (YYYY-MM-DD).

invoice_date__ltstring date
Example:2022-03-02

Return balances issued before this date (YYYY-MM-DD).

invoice_date__ltestring date
Example:2022-03-01

Return balances issued on this date or earlier (YYYY-MM-DD).

invoice_date__gtstring date
Example:2022-05-06

Return invoices issued after this date (YYYY-MM-DD).

invoice_date__gtestring date
Example:2022-05-04

Return invoices issued on this date or later (YYYY-MM-DD)

invoice_date__rangestring[]

Return invoices issued within this date range (YYYY-MM-DD). The first value indicates the start of the range and the second value indicates the end of the range.

[
  "2022-01-01",
  "2022-12-31"
]
invoice_identificationstring
Example:862B9918-3K6H-4E0B-NAI9-2BE2D833B840

Return an invoice with this ID (as provided by the insitution).

invoice_identification__instring[]

Return invoices with these IDs (as provided by the institution).

[
  "992B9918-3G6H-4E0B-DAI9-2BE2D833B833"
]
statusstring
Example:Vigente

Return invoices with this status. Can be either Vigente (valid) or Cancelado (cancelled).

status__instring[]

Return invoices with these statuses. Can be either Vigente (valid) or Cancelado (cancelled).

[
  "Cancelado"
]
type'OUTFLOW' | 'INFLOW'
Example:OUTFLOW

Return invoices of this type. Can be either OUTFLOW or INFLOW.

type__instring[]

Return invoices of these types. Can be either OUTFLOW or INFLOW.

[
  "OUTFLOW"
]
total_amountnumber float
Example:1000.02

Return invoices matching exactly this value.

total_amount__ltnumber float
Example:540.02

Return invoices less than this value.

total_amount__ltenumber float
Example:541.02

Return invoices less than or equal to this value.

total_amount__gtnumber float
Example:520.02

Return invoices greater than this value.

total_amount__gtenumber float
Example:519.02

Return invoices greater than or equal to this value.

total_amount__rangenumber[]

Return invoices between these two values. The first value indicates the start of the range and the second value indicates the end of the range.

[
  100,
  5000
]

Response

Ok

countinteger

The total number of results in your Belvo account.

nextstring uri nullable

The URL to next page of results. Each page consists of up to 100 items. If there are not enough results for an additional page, the value is null.

In our documentation example, we use {endpoint} as a placeholder value. In production, this value will be replaced by the actual endpoint you are currently using (for example, accounts or owners).

previousstring uri nullable

The URL to the previous page of results. If there is no previous page, the value is null.

Example response

{
  "count": 130,
  "next": "https://sandbox.belvo.com/api/{endpoint}/?link=1bd948f7-245d-4313-b604-34d1044cb908page=2",
  "results": [
    {
      "id": "0d3ffb69-f83b-456e-ad8e-208d0998d71d",
      "link": "30cb4806-6e00-48a4-91c9-ca55968576c8",
      "collected_at": "2022-02-09T08:45:50.406032Z",
      "created_at": "2022-02-09T08:45:50.406032Z",
      "invoice_identification": "A1A1A1A1-2B2B-3C33-D44D-555555E55EE",
      "invoice_date": "2019-12-01",
      "status": "Vigente",
      "invoice_type": "Ingreso",
      "type": "INFLOW",
      "tax_details": {
        "total_tax_retained": 194.27,
        "total_tax_transferred": 150.4,
        "retained_taxes": [
          {
            "tax_type": "Tasa",
            "tax": "ISR",
            "tax_amount": 94
          }
        ],
        "transferred_taxes": [
          {
            "tax_type": "Tasa",
            "tax": "IVA",
            "tax_percentage": 16,
            "pre_tax_amount": 940,
            "tax_amount": 150.4
          }
        ]
      },
      "sender_id": "AAA111111AA11",
      "sender_fiscal_regime": "601",
      "sender_name": "ACME CORP",
      "sender_tax_fraud_status": "NO_TAX_FRAUD_STATUS",
      "receiver_id": "BBB222222BB22",
      "receiver_postal_code": "11560",
      "receiver_fiscal_regime": "601",
      "receiver_name": "BELVO CORP",
      "receiver_tax_fraud_status": "NO_TAX_FRAUD_STATUS",
      "cancelation_update_date": "2019-12-02",
      "certification_date": "2019-12-01",
      "certification_authority": "CCC333333CC33",
      "payment_type": "99",
      "payment_method": "PUE",
      "usage": "P01",
      "version": "3.3",
      "place_of_issue": "01165",
      "invoice_details": [
        {
          "collected_at": "2022-02-09T08:45:50.406032Z",
          "description": "December 2019 accounting fees",
          "product_identification": "84101600",
          "quantity": 10,
          "unit_code": "E48",
          "unit_description": "Unidad de servicio",
          "unit_amount": 200,
          "discount": 10,
          "tax_subject_code": "02",
          "identifier_number": "PROD-12345",
          "pre_tax_amount": 400,
          "tax_percentage": 16,
          "tax_amount": 64,
          "total_amount": 464,
          "retained_taxes": [
            {
              "collected_at": "2022-02-09T08:45:50.406032Z",
              "tax_type": "Tasa",
              "tax": "ISR",
              "tax_percentage": 10,
              "retained_tax_amount": 209.79
            }
          ],
          "transferred_taxes": [
            {
              "collected_at": "2022-02-09T08:45:50.406032Z",
              "tax_type": "Tasa",
              "tax": "IVA",
              "tax_percentage": 10,
              "transferred_tax_amount": 209.79
            }
          ]
        }
      ],
      "currency": "MXN",
      "subtotal_amount": 400,
      "exchange_rate": 0.052,
      "tax_amount": 64,
      "discount_amount": 10,
      "total_amount": 454,
      "related_invoices": [
        {
          "relationship_type": "01",
          "related_invoice_identification": "INV-123456"
        }
      ],
      "payments": [
        {
          "date": "2020-03-17T12:00:00.000Z",
          "payment_type": "03",
          "currency": "BRL",
          "exchange_rate": "3.75",
          "amount": 8000.5,
          "operation_number": "831840",
          "beneficiary_rfc": "BNM840515VB1",
          "beneficiary_account_number": "12343453245633",
          "payer_rfc": "BKJM840515VB1",
          "payer_account_number": "13343663245699",
          "payer_bank_name": "CITI BANAMEX",
          "related_documents": [
            {
              "invoice_identification": "7EE015F3-6311-11EA-B02A-00155D014007",
              "currency": "MXN",
              "payment_method": "PPD",
              "partiality_number": 1,
              "previous_balance": 18877.84,
              "amount_paid": 8000,
              "outstanding_balance": 10877.84
            }
          ]
        }
      ],
      "payroll": {
        "days": 30,
        "type": "O",
        "amount": 20400.1,
        "version": "1.2",
        "date_from": "2018-07-01",
        "date_to": "2018-07-31",
        "collected_at": "2022-02-09T08:45:50.406032Z",
        "payment_date": "2018-07-16",
        "periodicity": "MONTHLY",
        "earnings_breakdown": [
          {
            "type": "CHRISTMAS_BONUS",
            "taxable_amount": 1505
          }
        ],
        "tax_deductions": [
          {
            "type": "UNION_FEES",
            "amount": 1505
          }
        ],
        "other_payments": [
          {
            "type": "EMPLOYMENT_SUBSIDY",
            "amount": 1505
          }
        ]
      },
      "folio": "26",
      "series": "A",
      "export_type": "01",
      "warnings": {
        "code": "sat_xml_limit_reached",
        "message": "The daily limit for XML downloads set by SAT was reached so this invoice\nmight be missing data. Please check https://tinyurl.com/yydzhy5d for more\ninformation on this error.\n"
      }
    }
  ]
}