Create retention

Create and stamp a new tax retention document (CFDI Retenciones 2.0).

The API accepts a simplified format — the backend handles:

Client lookup by ID (fetches RFC, legal name, address automatically)

Nationality detection from client's country

Tax code mapping (ISR → 001, IVA → 002, IEPS → 003)

Payment type defaults per tax (ISR → provisional, IVA/IEPS → definitivo)

Totals auto-calculation (taxable = operation − exempt, retained = sum of taxes)

Folio auto-generation

SAT stamping, PDF and XML generation

gigstack Connect: Create retentions for other teams using the team parameter.

Conditional requirements per `retention_key`

retention_key is validated as a free-form string — any SAT key is accepted — but three
keys carry extra requirements enforced before the document is stamped. A violation
returns 400 with error.code: invalid_request_body and the message quoted below.

`retention_key`	additional requirement	error message on violation
`16` — Intereses	`interest` object is required	`interest object is required for retention key 16 (Intereses)`
`25` — Otro tipo de retenciones	`retention_description` is required and non-empty	`retention_description is required for retention key 25 (Otro tipo de retenciones)`
`26` — Plataformas Tecnológicas	`platform_services` object is required and `taxes` must contain at least one entry whose `tax` is not `IVA` (i.e. `ISR` or `IEPS`)	`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`

Every other key requires only the base fields (retention_key, client,
period_start, period_end, period_year, total_operation, taxes).

Within interest, financial_system, nominal_interest and real_interest are
required. Within platform_services, periodicity and services are required, and
each entry in services requires payment_form, service_type, service_date and
price_without_tax.

Unlike the other modules, this endpoint strips unknown keys instead of rejecting
them (stripUnknown: true), so an undeclared field is silently discarded rather than
returning 400.

curl --location 'https://api.gigstack.io/v2/retentions?team=undefined' \ --header 'Authorization: <api-key>' \ --header 'Content-Type: application/json' \ --data '{ "retention_key": "26", "client": { "id": "abc123clientId" }, "period_start": 1, "period_end": 1, "period_year": 2026, "total_operation": 93116.98, "total_exempt": 0, "taxes": [ { "tax": "ISR", "base": 93116.98, "amount": 2327.92 }, { "tax": "IVA", "base": 14898.71, "amount": 7449.35 } ], "platform_services": { "periodicity": "04", "services": [ { "payment_form": "02", "service_type": "01", "service_date": "2026-01-10", "price_without_tax": 46558.49, "tax_rate": 0.16, "commission": 11639.62 }, { "payment_form": "02", "service_type": "01", "service_date": "2026-01-20", "price_without_tax": 46558.49, "tax_rate": 0.16, "commission": 11639.62 } ] } }'

{ "message": "Retention created successfully", "data": { "id": "9d9b0e5b-034c-42f7-bd21-3a868a57c13e", "uuid": "9d9b0e5b-034c-42f7-bd21-3a868a57c13e", "status": "valid", "document_type": "retenciones", "retention_key": "26", "folio_number": "1", "series": "RET", "issuer": { "legal_name": "MI EMPRESA SA DE CV", "tax_id": "MEE200101ABC", "tax_system": "601" }, "receiver": { "legal_name": "GRUPO JINIM", "tax_id": "GJI180508GM9", "nationality": "Nacional" }, "period": { "start": 1, "end": 1, "year": 2026 }, "totals": { "total_operation": 93116.98, "total_taxable": 93116.98, "total_exempt": 0, "total_retained": 9777.27, "tax_retained": [ { "tax": "001", "base": 93116.98, "amount": 2327.92, "payment_type": "03" }, { "tax": "002", "base": 14898.71, "amount": 7449.35, "payment_type": "01" } ] }, "stamp": { "uuid": "9d9b0e5b-034c-42f7-bd21-3a868a57c13e", "stamped_at": "2026-01-15T10:30:45.000Z" }, "verification_url": "https://verificacfdi.facturaelectronica.sat.gob.mx/default.aspx?id=9d9b0e5b-034c-42f7-bd21-3a868a57c13e&re=MEE200101ABC&rr=GJI180508GM9&tt=93116.98&fe=abcd1234", "livemode": true, "created_at": 1736942445000, "metadata": null }, "success": true, "timestamp": 1767225600000 }

Conditional requirements per `retention_key`

Request

Responses

Create retention

Conditional requirements per retention_key#

Request

Responses

Conditional requirements per `retention_key`