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

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

Example Request:

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

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	Unique key to prevent duplicate creation
`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)

Example: Basic Retention (Dividends)

Example: Retention with Interest Complement (Key 16)

Example: Platform Services Retention (Key 26)

Example: Custom Retention Type (Key 25)

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

Retrieve a specific retention document by its UUID.

Example Request:

Get Retention 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:

Example Response:

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

Cancel Retention

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:

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": "02",
        "nominal_interest": 18500.00,
        "real_interest": 12300.00,
        "loss": 0,
        "withdrawal_aores": null,
        "financial_derivatives": null
    }
}

Field	Type	Required	Description
`financial_system`	string	Yes	Financial system code
`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	AORES withdrawal code
`financial_derivatives`	string	No	Financial derivatives code

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.

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

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

3. Professional Services Withholding

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

4. Bank Interest Payments

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

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.

Use idempotency keys - Prevent duplicate retentions when retrying failed requests.

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

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

{
    "message": "Invalid request body",
    "error": "interest object is required for retention key 16"
}

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

Retentions

Retentions API Guide#

Overview#

Key Features#

Endpoints#

List Retentions#

Create Retention#

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#

Error Handling#

Missing Required Fields#

Invalid Retention Key#

Missing Complement Data#

Retention Not Found#

Already Canceled#

Stamping Error#

Retentions API Guide

Overview

Key Features

Endpoints

List Retentions

Create Retention

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

Error Handling

Missing Required Fields

Invalid Retention Key

Missing Complement Data

Retention Not Found

Already Canceled

Stamping Error