---
title: "List tax retentions"
method: GET
path: "/api/tax-retentions/"
tags: ["Tax retentions"]
---

# List tax retentions

`GET /api/tax-retentions/`

## ▶️ Usage

 With the List Tax Retentions method, you can:

  1. List tax retentions related to a specific `link.id` (using the `link` query parameter).
  2. Get the details of a specific `tax-retention.id` (using the `id` query parameter).
  3. **[Not Recommended]** List all tax retentions 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.

## Query parameters

- `link` string, uuid
- `page_size` integer
- `page` integer
- `omit` string
- `fields` string
- `link__in` string[]
- `created_at` string, date
- `created_at__gt` string, date
- `created_at__gte` string, date
- `created_at__lt` string, date
- `created_at__lte` string, date
- `created_at__range` string[]

## Response `200`

Ok

- object
  - `count` integer — The total number of results in your Belvo account.
  - `next` string, 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`).
  - `previous` string, uri, nullable — The URL to the previous page of results. If there is no previous page, the value is `null`.
  - `results` TaxRetentions[] — Array of tax retentions objects.
    - `id` string, uuid — Belvo's unique identifier for the current item.
    - `link` string, uuid, nullable — The `link.id` the data belongs to.
    - `collected_at` string, date-time, required — The ISO-8601 timestamp when the data point was collected.
    - `created_at` string, date-time — The ISO-8601 timestamp of when the data point was created in Belvo's database.
    - `invoice_identification` string, uuid, nullable, required — The fiscal institution's unique ID for the invoice that the tax retention relates to.
    - `version` string, nullable, required — The CFDI version of the tax retentions.
    - `code` integer, 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_at` string, date-time, nullable, required — The ISO-8601 timestamp of when the tax retention was issued.
    - `certified_at` string, date-time, nullable, required — The ISO-8601 timestamp of when the tax retention was certified.
    - `cancelled_at` string, date-time, nullable, required — The ISO-8601 timestamp of when the tax retention was canceled (if applicable).
    - `sender_id` string, nullable, required — The fiscal ID of the invoice sender.
    - `sender_name` string, 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_id` string, nullable, required — The fiscal ID of the invoice receiver.
    - `receiver_name` string, nullable, required — The name of the invoice receiver.
    - `total_invoice_amount` number, float, nullable, required — The total amount of the invoice that the tax retention relates to.
    - `total_exempt_amount` number, float, nullable, required — Total amount that is exempt from taxation.
    - `total_retained_amount` number, float, nullable, required — Total tax retained.
    - `total_taxable_amount` number, float, nullable, required — The total amount that can be taxed. Calculated as `total_invoice_amount` - `total_exempt_amount`.
    - `retention_breakdown` RetentionBreakdown[], nullable, required — A breakdown of the retained taxes.
      - `base_amount` number, float, nullable, required — The base amount that was used to calculate the tax retention.
      - `tax_type` string, nullable, required — Optional attribute to indicate the type of tax withheld for the period or year according to the <a href="https://developers.belvo.com/docs/sat-catalogs#retention-code" target="_blank">SAT catalog</a>.
      - `retained_amount` number, float, nullable, required — The amount retained.
      - `payment_status` 'PAID' | 'PROVISIONED', nullable, required — Indicates whether or not the tax has been paid or not. Can be either: - `PAID` - `PROVISIONED`
    - `xml` string, nullable, required — The tax retention document in XML form.

## Other responses

- `401` — Unauthorized
- `403` — Access to Belvo API denied
- `404` — Not Found Error
- `408` — Request Timeout
- `428` — MFA Token Required
- `500` — Unexpected Error

---

[API](https://skmtc.net/belvo/apis/belvo-api-docs.md) · [All operations](https://skmtc.net/belvo/apis/belvo-api-docs/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/belvo/belvo-api-docs/revisions/e82dca4a4b97/schema)