v1

latestOpenAPI 3.0.22026-08-061464031.4 MB

Tax retentions

Retrieve tax retentions for a link

Retrieve tax retention information from a specific link. The maximum number of tax retentions that can be returned for a period is 500.

post/api/tax-retentions/

Query parameters

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.

Request body

linkstring uuid required

The link.id you want to retrieve information for.

date_fromstring date required

The date from which you want to start getting data for, in YYYY-MM-DD format.

⚠️ The value of date_from cannot be greater than date_to.

date_tostring date required

The date you want to stop getting data for, in YYYY-MM-DD format.

⚠️ The value of date_to cannot be greater than today's date (in other words, no future dates).

type'OUTFLOW' | 'INFLOW' required

The type of tax retention in relation to the invoice (from the perspective of the Link owner).

OUTFLOW relates to a tax retention for a sent invoice.
INFLOW related to a tax retention for a received invoice.

attach_xmlboolean

When set to true, you will receive the XML invoice in the response.

save_databoolean

Indicates whether or not to persist the data in Belvo. By default, this is set to true and we return a 201 Created response.

When set to false, the data won't be persisted and we return a 200 OK response.

Example request

{
  "link": "c81a1dea-6dd6-4999-8b9f-541ee8197058",
  "date_from": "2020-08-05",
  "date_to": "2020-10-05",
  "type": "INFLOW",
  "save_data": true
}

Response

Ok (when save_data=false)

idstring uuid

Belvo's unique identifier for the current item.

linkstring uuid nullable

The link.id the data belongs to.

collected_atstring date-time required

The ISO-8601 timestamp when the data point was collected.

created_atstring date-time

The ISO-8601 timestamp of when the data point was created in Belvo's database.

invoice_identificationstring uuid nullable required

The fiscal institution's unique ID for the invoice that the tax retention relates to.

versionstring nullable required

The CFDI version of the tax retentions.

codeinteger nullable required

The tax retention code. For more information, see our <a href="https://developers.belvo.com/docs/sat-catalogs#retention-code" target="_blank">SAT Catalogs DevPortal article</a>.

issued_atstring date-time nullable required

The ISO-8601 timestamp of when the tax retention was issued.

certified_atstring date-time nullable required

The ISO-8601 timestamp of when the tax retention was certified.

cancelled_atstring date-time nullable required

The ISO-8601 timestamp of when the tax retention was canceled (if applicable).

sender_idstring nullable required

The fiscal ID of the invoice sender.

sender_namestring nullable required

The name of the invoice sender.

receiver_nationality'NATIONAL' | 'FOREIGN' nullable required

Whether the invoice receiver is a Mexican national or not. If the receiver is not considered a Mexican national, the retained taxes can be calculated differently. Possible values:

NATIONAL
FOREIGN

receiver_idstring nullable required

The fiscal ID of the invoice receiver.

receiver_namestring nullable required

The name of the invoice receiver.

total_invoice_amountnumber float nullable required

The total amount of the invoice that the tax retention relates to.

total_exempt_amountnumber float nullable required

Total amount that is exempt from taxation.

total_retained_amountnumber float nullable required

Total tax retained.

total_taxable_amountnumber float nullable required

The total amount that can be taxed. Calculated as total_invoice_amount - total_exempt_amount.

xmlstring nullable required

The tax retention document in XML form.

Example response

[
  {
    "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": "def404af-5eef-4112-aa99-d1ec8493b89a",
    "version": "1.0",
    "code": 25,
    "issued_at": "2019-01-03T21:10:40.000Z",
    "certified_at": "2019-01-03T21:10:41.000Z",
    "sender_id": "JKUF980404P0",
    "sender_name": "Roberto Nunez Batman",
    "receiver_nationality": "NATIONAL",
    "receiver_id": "GYGK3207809L1",
    "receiver_name": "ACME LTD",
    "total_invoice_amount": 53249.8,
    "total_exempt_amount": 1000.8,
    "total_retained_amount": 1550.7,
    "total_taxable_amount": 43249,
    "retention_breakdown": [
      {
        "base_amount": 0.03,
        "tax_type": "01",
        "payment_status": "PAID"
      }
    ],
    "xml": "=XML-STRING="
  }
]