Create retention

POST

https://api.gigstack.io/v2/retentions

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.

Request

Authorization

API Key

Add parameter in header

Authorization

Example:

Authorization: ********************

Query Params

Body Params application/jsonRequired

Examples

Responses

🟢201Created

application/json

Retention created and stamped successfully

Body

🟠400Bad Request

🟠401Unauthorized

Request Example

Shell

JavaScript

Java

Swift

cURL

Plataformas Tecnológicas (key 26) — with services complementIntereses (key 16) — with interest complementHonorarios profesionales (key 01) — ISR onlyArrendamiento (key 02) — ISR + IVAWith exempt amount, series, and metadataOtro tipo de retenciones (key 25) — with descriptionISR with custom payment type override

curl --location --request POST 'https://api.gigstack.io/v2/retentions?team' \
--header 'Authorization: <api-key>' \
--header 'Content-Type: application/json' \
--data-raw '{
    "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
            }
        ]
    }
}'

Response Example

201 - Retention stamped successfully

{
    "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",
            "provider": "prodigia"
        },
        "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
    }
}

Modified at 2026-03-06 19:07:26

List retentions

Get retention