Retentions API Guide

Create, manage, and cancel CFDI retention documents (Constancias de Retenciones e Informacion de Pagos) with full SAT compliance. The Retentions API handles the complete lifecycle of withholding tax certificates required by Mexican tax law.

Overview

Retentions are CFDI documents that certify taxes withheld by a payer on behalf of a recipient. They are required in scenarios such as interest payments, technology platform services, dividends, royalties, and other transactions where the payer is legally obligated to withhold taxes (ISR, IVA, IEPS) and report them to SAT. Unlike standard invoices, retentions have a distinct structure: they are organized by retention key (type of operation), fiscal period, and withheld tax amounts rather than line items.

Key Features

SAT Retention Keys - Support for all 26 retention types (01-26)
Automatic Tax Mapping - Friendly names (ISR, IVA, IEPS) mapped to SAT codes
Auto-Calculated Totals - Taxable, exempt, and retained amounts computed automatically
Complement Support - Built-in handling for Intereses (key 16), Plataformas Tecnologicas (key 26), and Otro tipo (key 25)
Folio Management - Automatic folio generation and stamping
File Generation - PDF and XML files generated on stamp
Cancellation - SAT-compliant cancellation with motive codes

Endpoints

List Retentions

GET /retentions

Retrieve a paginated list of retention documents with filtering capabilities. Query Parameters:

Parameter	Type	Description
`limit`	integer (1-100)	Number of results per page (default: 10)
`next`	string	Pagination cursor for next page
`team`	string	gigstack Connect: Target team ID
`order_by`	string	Field to sort by (default: `created_at`)
`sort`	string	Sort direction: `asc` or `desc`
`created_gte`	integer	Filter by creation date (greater than or equal, unix timestamp ms)
`created_lte`	integer	Filter by creation date (less than or equal, unix timestamp ms)
`status`	string	Filter by status: `valid` or `canceled`
`retention_key`	string	Filter by retention type key (e.g., `14`, `16`, `26`)
`client_id`	string	Filter by client ID (retentions created before this field was added won’t match)
`tax_id`	string	Filter by the client’s tax ID / RFC (e.g., `tax_id=PEGJ800101ABC`)

Example Request:

curl -X GET "https://api.gigstack.io/v2/retentions?status=valid&retention_key=14&limit=20" \
  -H "Authorization: Bearer YOUR_TOKEN"

Example Response:

{
    "message": "Retentions retrieved successfully",
    "data": [
        {
            "id": "ret_abc123",
            "uuid": "12345678-1234-1234-1234-123456789012",
            "status": "valid",
            "document_type": "retenciones",
            "retention_key": "14",
            "folio_number": "1",
            "series": "RET",
            "receiver": {
                "legal_name": "Juan Perez Garcia",
                "tax_id": "PEGJ800101ABC",
                "nationality": "Nacional"
            },
            "period": {
                "start": 1,
                "end": 12,
                "year": 2025
            },
            "totals": {
                "total_operation": 100000.00,
                "total_taxable": 100000.00,
                "total_exempt": 0,
                "total_retained": 10000.00,
                "tax_retained": [
                    {
                        "tax": "ISR",
                        "base": 100000.00,
                        "amount": 10000.00,
                        "payment_type": "03"
                    }
                ]
            },
            "stamp": {
                "uuid": "12345678-1234-1234-1234-123456789012",
                "stamped_at": "2025-06-15T10:30:00Z"
            },
            "livemode": true,
            "created_at": 1718451000000
        }
    ],
    "has_more": false,
    "total_results": 1
}

Create Retention

POST /retentions

Create and stamp a new retention CFDI document. The retention is normalized, stamped with SAT, and saved in a single operation. Request Body:

Field	Type	Required	Description
`retention_key`	string	Yes	SAT retention type code (01-26)
`client`	object	Yes	Client reference (by ID, search, or inline data)
`period_start`	number	Yes	Start month of the fiscal period (1-12)
`period_end`	number	Yes	End month of the fiscal period (1-12)
`period_year`	number	Yes	Fiscal year
`total_operation`	number	Yes	Total operation amount
`taxes`	array	Yes	Array of retained taxes
`total_exempt`	number	No	Exempt amount (default: 0)
`series`	string	No	Invoice series (default: “RET”)
`metadata`	object	No	Custom metadata key-value pairs
`idempotency_key`	string	No	Accepted identifier; do not assume income-invoice replay/locking guarantees apply to retentions
`retention_description`	string	No	Required for key “25” (Otro tipo de retenciones)
`interest`	object	No	Required for key “16” (Intereses)
`platform_services`	object	No	Required for key “26” (Plataformas Tecnologicas)

Tax Object:

{
    "tax": "ISR",
    "base": 100000.00,
    "amount": 10000.00,
    "payment_type": "03"
}

tax (string, required) - Tax type: ISR, IVA, or IEPS. Mapped automatically to SAT codes (001, 002, 003).
base (number, required) - Taxable base amount.
amount (number, required) - Amount retained.
payment_type (string, optional) - SAT payment type code. Defaults to 03 (provisional) for ISR and 01 (definitivo) for IVA/IEPS.

Common Retention Keys:

Key	Description	Complement Required
`01`	Servicios profesionales	No
`02`	Renta de inmuebles	No
`06`	Enajenacion de acciones	No
`14`	Dividendos o utilidades	No
`16`	Intereses	Yes (`interest` object)
`25`	Otro tipo de retenciones	Yes (`retention_description`)
`26`	Plataformas tecnologicas	Yes (`platform_services` object)

Required combinations per retention key

A miss is a hard 400. Three retention keys carry a complement, and the API validates the combination before anything is sent to the PAC. Nothing is stamped, nothing is charged, and the response is 400 with the exact message below in error.message:

If `retention_key` is	You must also send	Message when you don’t
`"16"` (Intereses)	`interest` object	`interest object is required for retention key 16 (Intereses)`
`"25"` (Otro tipo de retenciones)	`retention_description` string	`retention_description is required for retention key 25 (Otro tipo de retenciones)`
`"26"` (Plataformas Tecnológicas)	`platform_services` object	`platform_services object is required for retention key 26 (Plataformas Tecnológicas)`
`"26"` (Plataformas Tecnológicas)	and at least one tax in `taxes` whose `tax` is not `IVA` — i.e. `ISR` or `IEPS`	`At least one non-IVA tax (ISR or IEPS) is required for Plataformas Tecnológicas`

Notes that catch people out:

retention_key is a string, not a number. "16" matches; 16 does not, and the complement check silently does not apply.
The extra rule on key 26 is easy to miss: an IVA-only taxes array passes the schema and is then rejected by the validator. A Plataformas Tecnológicas retention is expected to retain ISR (and may also retain IVA), so send both.
These three fields are schema-optional at the top level precisely because they are conditional — the schema will not catch a missing one, only this validator will.
Every other key (01, 02, 06, 14, …) needs no complement; sending one anyway is simply ignored for that key.

Worked examples for all three follow: key 16, key 25, key 26.

Example: Basic Retention (Dividends)

curl -X POST https://api.gigstack.io/v2/retentions \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "retention_key": "14",
    "client": {
      "id": "client_1234567890"
    },
    "period_start": 1,
    "period_end": 12,
    "period_year": 2025,
    "total_operation": 500000.00,
    "total_exempt": 0,
    "taxes": [
      {
        "tax": "ISR",
        "base": 500000.00,
        "amount": 50000.00
      }
    ],
    "metadata": {
      "dividend_resolution": "ACT-2025-001"
    }
  }'

Example: Retention with Interest Complement (Key 16)

curl -X POST https://api.gigstack.io/v2/retentions \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "retention_key": "16",
    "client": {
      "id": "client_1234567890"
    },
    "period_start": 1,
    "period_end": 6,
    "period_year": 2025,
    "total_operation": 250000.00,
    "taxes": [
      {
        "tax": "ISR",
        "base": 250000.00,
        "amount": 25000.00
      }
    ],
    "interest": {
      "financial_system": "SI",
      "nominal_interest": 18500.00,
      "real_interest": 12300.00,
      "loss": 0
    }
  }'

Example: Platform Services Retention (Key 26)

curl -X POST https://api.gigstack.io/v2/retentions \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "retention_key": "26",
    "client": {
      "search": {
        "on_key": "tax_id",
        "on_value": "PEGJ800101ABC",
        "auto_create": true
      },
      "name": "Juan Perez Garcia",
      "email": "juan@example.com",
      "tax_id": "PEGJ800101ABC",
      "tax_system": "625"
    },
    "period_start": 3,
    "period_end": 3,
    "period_year": 2025,
    "total_operation": 45000.00,
    "taxes": [
      {
        "tax": "ISR",
        "base": 45000.00,
        "amount": 4500.00
      },
      {
        "tax": "IVA",
        "base": 45000.00,
        "amount": 7200.00
      }
    ],
    "platform_services": {
      "periodicity": "04",
      "services": [
        {
          "payment_form": "03",
          "service_type": "01",
          "service_date": "2025-03-15",
          "price_without_tax": 25000.00,
          "tax_rate": 0.16,
          "commission": 2500.00
        },
        {
          "payment_form": "04",
          "service_type": "01",
          "service_date": "2025-03-22",
          "price_without_tax": 20000.00,
          "tax_rate": 0.16,
          "commission": 2000.00
        }
      ]
    }
  }'

Example: Custom Retention Type (Key 25)

curl -X POST https://api.gigstack.io/v2/retentions \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "retention_key": "25",
    "client": {
      "id": "client_1234567890"
    },
    "period_start": 1,
    "period_end": 12,
    "period_year": 2025,
    "total_operation": 120000.00,
    "taxes": [
      {
        "tax": "ISR",
        "base": 120000.00,
        "amount": 12000.00
      }
    ],
    "retention_description": "Retencion por servicios de asesoria fiscal especializada"
  }'

Response (201):

{
    "message": "Retention created successfully",
    "data": {
        "id": "ret_xyz789",
        "uuid": "98765432-1234-1234-1234-123456789012",
        "status": "valid",
        "document_type": "retenciones",
        "retention_key": "14",
        "folio_number": "1",
        "series": "RET",
        "issuer": {
            "legal_name": "Mi Empresa SA de CV",
            "tax_id": "MEM200101ABC",
            "tax_system": "601"
        },
        "receiver": {
            "legal_name": "Juan Perez Garcia",
            "tax_id": "PEGJ800101ABC",
            "nationality": "Nacional"
        },
        "period": {
            "start": 1,
            "end": 12,
            "year": 2025
        },
        "totals": {
            "total_operation": 500000.00,
            "total_taxable": 500000.00,
            "total_exempt": 0,
            "total_retained": 50000.00,
            "tax_retained": [
                {
                    "tax": "ISR",
                    "base": 500000.00,
                    "amount": 50000.00,
                    "payment_type": "03"
                }
            ]
        },
        "stamp": {
            "uuid": "98765432-1234-1234-1234-123456789012",
            "stamped_at": "2025-06-15T10:30:00Z"
        },
        "verification_url": "https://verificacfdi.facturaelectronica.sat.gob.mx/...",
        "livemode": true,
        "created_at": 1718451000000,
        "metadata": {
            "dividend_resolution": "ACT-2025-001"
        }
    }
}

Get Retention

GET /retentions/{id}

Retrieve a specific retention document by its UUID. Example Request:

curl -X GET https://api.gigstack.io/v2/retentions/98765432-1234-1234-1234-123456789012 \
  -H "Authorization: Bearer YOUR_TOKEN"

Get Retention Files

GET /retentions/{id}/files

Retrieve the PDF and XML files for a stamped retention. Query Parameters:

file_type (string, optional) - Filter by file type: pdf or xml. Returns both if omitted.
team (string, optional) - gigstack Connect: Target team ID.

Example Request:

curl -X GET "https://api.gigstack.io/v2/retentions/98765432-1234-1234-1234-123456789012/files?file_type=pdf" \
  -H "Authorization: Bearer YOUR_TOKEN"

Example Response:

{
    "message": "Retention files retrieved successfully",
    "data": [
        {
            "content": "JVBERi0xLjQK...",
            "filename": "retention_98765432.pdf",
            "type": "application/pdf"
        }
    ]
}

Cancel Retention

DELETE /retentions/{id}

Cancel a stamped retention with SAT. Requires a cancellation motive. Request Body:

{
    "motive": "02",
    "replace_uuid": null
}

Cancellation Motives:

Code	Description	Requires `replace_uuid`
`01`	Comprobante emitido con errores con relacion	Yes
`02`	Comprobante emitido con errores sin relacion	No
`03`	No se llevo a cabo la operacion	No
`04`	Operacion nominativa relacionada en factura global	No

Example Request:

curl -X DELETE https://api.gigstack.io/v2/retentions/98765432-1234-1234-1234-123456789012 \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "motive": "02"
  }'

Example Response:

{
    "message": "Retention cancelled successfully",
    "data": {
        "id": "ret_xyz789",
        "uuid": "98765432-1234-1234-1234-123456789012",
        "status": "canceled",
        "cancellation": {
            "motive": "02",
            "canceled_at": "2025-06-20T15:00:00Z"
        }
    }
}

Retention Structure

Retention Keys (Types)

The retention_key identifies the type of operation that requires tax withholding. Common keys include:

Key	Description
`01`	Servicios profesionales
`02`	Renta de inmuebles
`03`	Comercio exterior
`04`	Fideicomisos que no realizan actividades empresariales
`05`	Planes de retiro
`06`	Enajenacion de acciones
`07`	Intereses reales hipotecarios
`08`	Interes real por primas de seguro
`09`	Premios
`10`	Otras retenciones por ganancias
`11`	Pagos a extranjeros
`12`	Pagos a extranjeros consolidados
`14`	Dividendos o utilidades
`15`	Remanente distribuido
`16`	Intereses
`17`	Arrendamiento en fideicomiso
`18`	Pagos a FIBRAS
`22`	Enajenacion de FIBRAS
`25`	Otro tipo de retenciones
`26`	Plataformas tecnologicas

Tax Types

Friendly Name	SAT Code	Default Payment Type
`ISR`	001	`03` (Pago provisional)
`IVA`	002	`01` (Pago definitivo)
`IEPS`	003	`01` (Pago definitivo)

Auto-Calculated Fields

When creating a retention, the following fields are computed automatically:

total_taxable = total_operation - total_exempt
total_retained = sum of all taxes[].amount

You do not need to send these values; they are derived from the input.

Complement-Specific Fields

Interest Complement (Key 16)

Required when retention_key is "16". Provides details about financial interest payments.

{
    "interest": {
        "financial_system": "SI",
        "nominal_interest": 18500.00,
        "real_interest": 12300.00,
        "loss": 0,
        "withdrawal_aores": null,
        "financial_derivatives": null
    }
}

Field	Type	Required	Description
`financial_system`	string	Yes	`SI` or `NO`, according to the actual financial-system classification
`nominal_interest`	number	Yes	Nominal interest amount
`real_interest`	number	Yes	Real (inflation-adjusted) interest amount
`loss`	number	No	Loss amount (default: 0)
`withdrawal_aores`	string	No	`SI` or `NO` for the applicable withdrawal flag
`financial_derivatives`	string	No	`SI` or `NO` for the applicable derivatives flag

Platform Services Complement (Key 26)

Required when retention_key is "26". Details technology platform service transactions.

{
    "platform_services": {
        "periodicity": "04",
        "services": [
            {
                "payment_form": "03",
                "service_type": "01",
                "service_date": "2025-03-15",
                "price_without_tax": 25000.00,
                "tax_rate": 0.16,
                "commission": 2500.00,
                "government_contribution": 0
            }
        ]
    }
}

Periodicity Codes:

Code	Description
`01`	Diario
`02`	Semanal
`03`	Quincenal
`04`	Mensual
`05`	Bimestral

Custom Retention Description (Key 25)

Required when retention_key is "25". A free-text description of the retention type.

{
    "retention_description": "Retencion por servicios de asesoria fiscal especializada"
}

Use Cases

1. Dividend Distribution

A company distributes dividends to shareholders and must issue retention certificates for the ISR withheld.

curl -X POST https://api.gigstack.io/v2/retentions \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "retention_key": "14",
    "client": {"id": "client_shareholder_001"},
    "period_start": 1,
    "period_end": 12,
    "period_year": 2025,
    "total_operation": 1000000.00,
    "taxes": [{"tax": "ISR", "base": 1000000.00, "amount": 100000.00}],
    "metadata": {"resolution": "AG-2025-003", "shares": 5000}
  }'

2. Technology Platform (Uber, Rappi, etc.)

A technology platform withholds taxes on behalf of service providers and must issue monthly retention certificates.

curl -X POST https://api.gigstack.io/v2/retentions \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "retention_key": "26",
    "client": {
      "search": {"on_key": "tax_id", "on_value": "GARJ900515ABC", "auto_create": true},
      "name": "Jose Garcia Rodriguez",
      "tax_id": "GARJ900515ABC",
      "tax_system": "625"
    },
    "period_start": 6,
    "period_end": 6,
    "period_year": 2025,
    "total_operation": 35000.00,
    "taxes": [
      {"tax": "ISR", "base": 35000.00, "amount": 3500.00},
      {"tax": "IVA", "base": 35000.00, "amount": 2800.00}
    ],
    "platform_services": {
      "periodicity": "04",
      "services": [
        {"payment_form": "03", "service_type": "01", "service_date": "2025-06-10", "price_without_tax": 18000.00, "tax_rate": 0.16, "commission": 1800.00},
        {"payment_form": "03", "service_type": "01", "service_date": "2025-06-25", "price_without_tax": 17000.00, "tax_rate": 0.16, "commission": 1700.00}
      ]
    }
  }'

3. Professional Services Withholding

A company paying a freelance consultant withholds ISR and IVA as required by law.

curl -X POST https://api.gigstack.io/v2/retentions \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "retention_key": "01",
    "client": {"id": "client_consultant_001"},
    "period_start": 1,
    "period_end": 3,
    "period_year": 2025,
    "total_operation": 150000.00,
    "taxes": [
      {"tax": "ISR", "base": 150000.00, "amount": 15000.00},
      {"tax": "IVA", "base": 150000.00, "amount": 16000.00}
    ]
  }'

4. Bank Interest Payments

A financial institution issues retention certificates for interest paid to account holders.

curl -X POST https://api.gigstack.io/v2/retentions \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "retention_key": "16",
    "client": {"id": "client_account_holder"},
    "period_start": 1,
    "period_end": 12,
    "period_year": 2025,
    "total_operation": 85000.00,
    "taxes": [{"tax": "ISR", "base": 85000.00, "amount": 8500.00}],
    "interest": {
      "financial_system": "SI",
      "nominal_interest": 12750.00,
      "real_interest": 8500.00
    }
  }'

Best Practices

Use the correct retention key - Each type of withholding operation has a specific key. Using the wrong key will cause SAT validation errors.
Provide complement data when required - Keys 16, 25, and 26 require additional fields. The API will reject requests missing required complement data.
Verify client fiscal data - The receiver’s RFC and tax system must be valid and registered with SAT.
Reconcile uncertain issuance - Retention creation accepts idempotency_key, but the reviewed retention stamping path does not perform the income endpoint’s key claim/replay checks. After a timeout or server error, reconcile the retention and provider result before issuing again; a new request can take another folio.
Match fiscal periods accurately - The period_start, period_end, and period_year must correspond to the actual period covered by the retention.
Review before stamping - Unlike draft invoices, retentions are stamped immediately on creation. Verify all data before submitting.
Keep metadata organized - Use metadata to link retentions to internal records (resolutions, contracts, account numbers).

Clients API - Manage retention recipients
Invoices API - Standard CFDI invoicing
Teams API - Configure team SAT certificates
CFDI Errors Reference - Error codes for stamping failures

Retry and outcome checks

HTTP 201 returns the created retention in data. Retain its ID and UUID, then use the get/files routes to retrieve it. If a response is lost after stamping, do not assume the accepted idempotency_key field makes resubmission safe: the current retention path does not implement the income-invoice key claim/replay workflow. Search/list the appropriate team and mode and reconcile with the provider or support before another creation. A validation error returned before provider submission can be corrected without implying that a fiscal document already exists.

Error Handling

Missing Required Fields

{
    "message": "Invalid request body",
    "error": "retention_key is required"
}

Invalid Retention Key

{
    "message": "Invalid request body",
    "error": "retention_key must be a valid SAT retention type (01-26)"
}

Missing Complement Data (400)

Returned by the conditional-requirements check described under Required combinations. The status is always 400 and the offending rule is spelled out verbatim in error.message:

{
    "success": false,
    "error": {
        "code": "invalid_request_body",
        "message": "interest object is required for retention key 16 (Intereses)"
    },
    "timestamp": 1718451000000
}

The other three messages you can get here:

retention_description is required for retention key 25 (Otro tipo de retenciones)
platform_services object is required for retention key 26 (Plataformas Tecnológicas)
At least one non-IVA tax (ISR or IEPS) is required for Plataformas Tecnológicas

What to do: add the missing field and retry with the same idempotency_key — the request never reached the PAC, so no folio was consumed and no document exists.

Retention Not Found

{
    "message": "Resource not found"
}

Already Canceled

{
    "message": "Retention is already canceled"
}

Stamping Error

{
    "message": "An error occurred while creating retention",
    "error": {
        "code": "CFDI33106",
        "message": "El RFC del receptor no es valido"
    }
}

For additional assistance, contact support@gigstack.io

​Overview

​Key Features

​Endpoints

​List Retentions

​Create Retention

​Required combinations per retention key

​Example: Basic Retention (Dividends)

​Example: Retention with Interest Complement (Key 16)

​Example: Platform Services Retention (Key 26)

​Example: Custom Retention Type (Key 25)

​Get Retention

​Get Retention Files

​Cancel Retention

​Retention Structure

​Retention Keys (Types)

​Tax Types

​Auto-Calculated Fields

​Complement-Specific Fields

​Interest Complement (Key 16)

​Platform Services Complement (Key 26)

​Custom Retention Description (Key 25)

​Use Cases

​1. Dividend Distribution

​2. Technology Platform (Uber, Rappi, etc.)

​3. Professional Services Withholding

​4. Bank Interest Payments

​Best Practices

​Related Resources

​Retry and outcome checks

​Error Handling

​Missing Required Fields

​Invalid Retention Key

​Missing Complement Data (400)

​Retention Not Found

​Already Canceled

​Stamping Error

Overview

Key Features

Endpoints

List Retentions

Create Retention

Required combinations per retention key

Example: Basic Retention (Dividends)

Example: Retention with Interest Complement (Key 16)

Example: Platform Services Retention (Key 26)

Example: Custom Retention Type (Key 25)

Get Retention

Get Retention Files

Cancel Retention

Retention Structure

Retention Keys (Types)

Tax Types

Auto-Calculated Fields

Complement-Specific Fields

Interest Complement (Key 16)

Platform Services Complement (Key 26)

Custom Retention Description (Key 25)

Use Cases

1. Dividend Distribution

2. Technology Platform (Uber, Rappi, etc.)

3. Professional Services Withholding

4. Bank Interest Payments

Best Practices

Related Resources

Retry and outcome checks

Error Handling

Missing Required Fields

Invalid Retention Key

Missing Complement Data (400)

Retention Not Found

Already Canceled

Stamping Error