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 returning400.
Authorizations
Authentication Method: HTTP Bearer token.
The runtime requires the literal Bearer prefix — a bare token in the
Authorization header is rejected with 401 unauthorized.
Header Format: Authorization: Bearer YOUR_API_KEY
Your API key is a JWT. Live keys operate on live data (livemode: true);
test keys operate on isolated test data (livemode: false).
Get your key at: app.gigstack.pro/settings?tab=api
Errors: credential failures are answered by the authentication layer with a raw
{ "message": … } body, not the standardized envelope — 401 for a missing, malformed or
expired token, 403 for a revoked key or a plan without API access. See the Unauthorized
and AuthForbidden responses.
Query Parameters
gigstack Connect: Target team ID for multi-team access.
Requires gigstack Connect enabled on your team and shared billing account.
Also requires the multipleIssuerAccounts feature on your plan. Requests targeting a
team other than the one your API key belongs to return 403 without it.
Only API keys can use it: an OAuth access token sent with another team's id is rejected with
403 Team mismatch with OAuth token.
Optional — omit it entirely unless you are acting on another team. It deliberately
carries no example value so generated snippets do not emit ?team=undefined; when the
parameter is absent, the team is derived from your API key.
Example: ?team=team_xyz789
Body
SAT retention type code (01-26). E.g. "26" for Plataformas Tecnológicas
"26"
Client reference. Same format as invoices/payments. Three modes:
- By ID:
{ id: "client_123" }— looks up existing client - By search:
{ search: { on_key: "tax_id", on_value: "XAXX010101000", auto_create: true } }— finds or creates - Inline:
{ tax_id: "XAXX010101000", legal_name: "EMPRESA SA", address: { zip: "06700" } }— creates on-the-fly
Show child attributes
Show child attributes
Start month (1-12)
1
End month (1-12)
3
Fiscal year
2026
Total operation amount. Taxable amount is auto-calculated as total_operation - total_exempt
93116.98
Retained taxes. Use friendly names (ISR, IVA, IEPS) — SAT codes are mapped automatically
Show child attributes
Show child attributes
Total exempt amount (defaults to 0)
0
Series for folio management (defaults to "RET")
Custom metadata
Optional stored reference. This handler does not claim or replay this key to prevent duplicate issuance. Reconcile an ambiguous result before another request; do not assume retry safety.
Required only for key "25" (Otro tipo de retenciones). Free-text description of the retention type.
Required only for key "16" (Intereses). Financial interest complement data.
Show child attributes
Show child attributes
Required only for key "26" (Plataformas Tecnológicas). Service details for technology platform retentions. Header totals (IVA trasladado, ISR retenido, etc.) are auto-calculated.
Show child attributes
Show child attributes
Response
Retention created and stamped successfully
Standardized success envelope emitted by sendSuccessResponse.
true true
The operation payload.
Server time in epoch milliseconds (Luxon.now().toMillis()).
1767225600000
Human-readable summary. Present only when the handler supplies one.
"Operation completed successfully"