Invoices API Guide

Create, manage, and cancel CFDI 4.0 compliant invoices with full SAT integration. The Invoices API handles the complete invoice lifecycle including creation, stamping, cancellation, and payment complements.

Overview

The Invoices API provides comprehensive invoicing capabilities with Mexican tax compliance. Create PUE (single payment) or PPD (partial payments) invoices, manage payment complements, and handle cancellations with SAT.

Key Features

CFDI 4.0 Compliance - Full SAT specification support

Automatic Stamping - Real-time SAT integration

Payment Complements - PPD invoice management

Cancellation Support - SAT-compliant cancellation process

Global Invoices - Monthly global invoice generation

File Generation - Automatic PDF and XML creation

Draft Invoices - Prepare, preview, and approve invoices before stamping

Automation Options - Flexible workflow automation

Endpoints

List CFDI Errors

Retrieve a comprehensive catalog of CFDI error codes with descriptions, explanations, and solutions. This endpoint is essential for implementing proper error handling and providing meaningful feedback when invoice operations fail.

Query Parameters:

code (string) - Filter by exact error code (e.g., CFDI140223)

q (string) - Search across code, description, explanation, and solution

type (string) - Filter by error type: invoice, receiver, sender, unknown

limit (integer, 1-100) - Number of results per page (default: 50)

page (integer) - Page number for pagination (default: 1)

Example Request:

Example Response:

{
    "success": true,
    "data": [
        {
            "code": "CFDI140223",
            "description": "El campo Rfc del receptor no es valido",
            "explanation": "The RFC (tax ID) provided for the receiver does not meet the validation requirements or format specified by SAT",
            "solution": "Verify that the receiver's RFC is correct, properly formatted (13 characters for individuals, 12 for legal entities), and matches SAT's registered information",
            "type": "receiver"
        }
    ],
    "total": 1,
    "page": 1,
    "limit": 20,
    "message": "CFDI errors retrieved successfully",
    "timestamp": "2025-12-19T10:30:00.000Z"
}

For complete documentation on the CFDI errors endpoint, see the CFDI Errors Reference.

List Income Invoices

Retrieve a paginated list of income invoices 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 (e.g., `created_at`)
`sort`	string	Sort direction (`asc`, `desc`)
`created_gte`	integer	Filter by creation date (greater than or equal to timestamp)
`created_lte`	integer	Filter by creation date (less than or equal to timestamp)
`metadata.{key}`	string	Filter by metadata field using dot notation (e.g., `metadata.order_id=ORD-123`)
`metadata_{key}`	string	Filter by metadata field using underscore notation (e.g., `metadata_order_id=ORD-123`)
`page`	integer	Page number for pagination when using metadata filters (default: 1)

Metadata Filtering:

You can filter invoices by any metadata key using either dot notation or underscore notation. Both formats are equivalent:

Metadata filtering uses Typesense search for efficient querying without requiring Firestore indexes. When using metadata filters, pagination is controlled via the page parameter instead of the next cursor.

Example Requests:

Example Response:

{
    "message": "Invoices retrieved successfully",
    "data": [
        {
            "uuid": "invoice_1234567890",
            "client": {
                "id": "client_1234567890",
                "name": "Juan Perez Garcia",
                "tax_id": "PEGJ800101ABC"
            },
            "folio_number": 123,
            "series": "A",
            "invoice_type": "I",
            "total": 1160.0,
            "subtotal": 1000.0,
            "taxes": 160.0,
            "currency": "MXN",
            "payment_method": "PUE",
            "status": "valid",
            "created_at": 1677651234,
            "stamp": {
                "stamp_at": 1677651234,
                "sello": "ABC123..."
            }
        }
    ],
    "has_more": false,
    "total_results": 1
}

Create Income Invoice

Create a new income invoice with optional automation.

Automation Types:

payment - Create invoice with payment automation

none - No automation, create invoice only

Request Body:

{
    "automation_type": "payment",
    "client": {
        "id": "client_1234567890"
    },
    "currency": "MXN",
    "exchange_rate": 1.0,
    "items": [
        {
            "description": "Consulting services",
            "quantity": 2,
            "unit_price": 1000.0,
            "product_key": "80141503",
            "unit_key": "E48",
            "unit_name": "Servicio",
            "taxes": [
                {
                    "type": "IVA",
                    "rate": 0.16,
                    "factor": "Tasa",
                    "withholding": false
                }
            ]
        }
    ],
    "use": "P01",
    "payment_form": "03",
    "payment_method": "PUE",
    "series": "A",
    "folio_number": 123,
    "send_email": true,
    "emails": ["client@example.com"]
}

Example Request with Client Search:

Get Income Invoice

Retrieve a specific income invoice by ID.

Example Request:

List Egress Invoices

Retrieve a paginated list of egress invoices (credit notes) 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 (e.g., `created_at`)
`sort`	string	Sort direction (`asc`, `desc`)
`created_gte`	integer	Filter by creation date (greater than or equal to timestamp)
`created_lte`	integer	Filter by creation date (less than or equal to timestamp)
`metadata.{key}`	string	Filter by metadata field using dot notation (e.g., `metadata.order_id=ORD-123`)
`metadata_{key}`	string	Filter by metadata field using underscore notation (e.g., `metadata_order_id=ORD-123`)
`page`	integer	Page number for pagination when using metadata filters (default: 1)

Metadata Filtering:

You can filter egress invoices by any metadata key using either dot notation or underscore notation. Both formats are equivalent:

Example Requests:

Get Invoice Files

Retrieve XML and PDF files for an invoice.

Query Parameters:

file_type (string) - Type of file: "pdf", "xml" (optional, returns both if not specified)

team (string) - gigstack Connect: Target team ID

Example Request:

Example Response:

{
    "message": "Invoice files retrieved successfully",
    "data": {
        "pdf": "https://storage.gigstack.io/invoices/invoice_1234567890.pdf",
        "xml": "https://storage.gigstack.io/invoices/invoice_1234567890.xml"
    }
}

Cancel Invoice

Cancel an invoice with SAT.

Request Body:

{
    "motive": "02",
    "substitution_uuid": "12345678-1234-1234-1234-123456789012"
}

Cancellation Motives:

01 - Comprobante emitido con errores con relacion (requires substitution_uuid)

02 - Comprobante emitido con errores sin relacion

03 - No se llevo a cabo la operacion

04 - Operacion nominativa relacionada en una factura global

Example Request:

Draft Invoices (Pre-Facturas)

Draft invoices allow you to prepare and review an invoice before stamping it with SAT. This is useful for approval workflows, client review, or building invoices incrementally over time.

A draft follows this lifecycle:

Create a draft with partial or complete data.

Update the draft as needed (add items, set client, change payment method).

Preview the draft to generate a PDF with a "Sin Validez Fiscal" watermark.

Stamp the draft to finalize it into a real CFDI invoice.

Drafts are stored in the invoices collection with a draft: true flag and do not consume credits until stamped.

Create Draft

Create a new draft invoice. Only invoice_type is required at creation; all other fields can be added later via update.

Request Body:

{
    "invoice_type": "I",
    "client": {
        "id": "client_1234567890"
    },
    "currency": "MXN",
    "items": [
        {
            "description": "Consulting services",
            "quantity": 1,
            "unit_price": 1000.00,
            "product_key": "80141503",
            "unit_key": "E48",
            "taxes": [{"type": "IVA", "rate": 0.16}]
        }
    ],
    "use": "G03",
    "payment_form": "03",
    "payment_method": "PUE"
}

Minimal Request (just the type):

{
    "invoice_type": "I"
}

Example Request:

Response (201):

{
    "message": "Draft created successfully",
    "data": {
        "id": "draft_abc123",
        "draft": true,
        "invoice_type": "I",
        "client": {
            "id": "client_1234567890",
            "name": "Juan Perez Garcia"
        },
        "currency": "MXN",
        "items": [...],
        "status": "draft",
        "created_at": 1709090576567
    }
}

List Drafts

Retrieve a paginated list of draft invoices.

Query Parameters:

Parameter	Type	Description
`limit`	integer (1-100)	Number of results per page (default: 10)
`next`	string	Pagination cursor for next page
`invoice_type`	string	Filter by invoice type: `I` (income) or `E` (egress)
`client_id`	string	Filter by client ID

Example Request:

Get Draft

Retrieve a specific draft by ID. If a preview PDF has been generated, it is included in the response.

Example Request:

Update Draft

Update an existing draft. Only the fields included in the request body are merged; omitted fields remain unchanged.

Example Request:

Delete Draft

Permanently delete a draft and its associated preview files.

Example Request:

Stamp Draft (Finalize)

Finalize a draft into a real CFDI invoice. This stamps the invoice with SAT, assigns a folio, and removes the draft document.

The draft must have all required fields before stamping:

client with valid fiscal data

At least one item

use (CFDI use code)

payment_form

payment_method

currency

Optional Request Body:

{
    "send_email": true,
    "return_files": true
}

send_email (boolean) - Set to false to suppress email delivery. Default: true.

return_files (boolean) - Set to true to include base64-encoded XML and PDF in the response.

Example Request:

Response (200):

{
    "message": "Invoice created from draft",
    "data": {
        "uuid": "12345678-1234-1234-1234-123456789012",
        "folio_number": 456,
        "series": "A",
        "total": 29000.00,
        "status": "valid",
        "stamp": {
            "stamp_at": 1709090576567,
            "sello": "ABC123..."
        },
        "files": {
            "xml": "PD94bWwgdmVyc2lvbj...",
            "pdf": "JVBERi0xLjQK..."
        }
    }
}

Error: Incomplete draft (400):

{
    "message": "Draft is incomplete — a client and at least one item are required to stamp"
}

Error: Credit limit reached (429):

{
    "message": "Team credit limit reached",
    "error": "No remaining credits",
    "credit_limit": 100,
    "used_credits": 100
}

Preview Draft

Generate a preview PDF for the draft. The PDF includes a "Sin Validez Fiscal" watermark and uses a placeholder UUID (PREFACTURA-0000-0000-0000-SINVALIDEZ). The preview is saved to the draft's files subcollection.

The draft must have at least a client and one item.

Example Request:

Response (200):

{
    "message": "Preview generated successfully",
    "data": {
        "pdf_base64": "JVBERi0xLjQK...",
        "draft_id": "draft_abc123",
        "watermark": true
    }
}

Draft Workflow Example

A typical approval workflow using drafts:

Invoice Structure

Invoice Types

I - Ingreso (Income)

E - Egreso (Expense / Credit note)

P - Pago (Payment complement)

N - Nomina (Payroll)

Payment Methods

PUE - Pago en Una sola Exhibicion (Single payment)

PPD - Pago en Parcialidades o Diferido (Partial or deferred payment)

Payment Forms (Formas de Pago)

Code	Description
01	Efectivo
02	Cheque nominativo
03	Transferencia electronica de fondos
04	Tarjeta de credito
28	Tarjeta de debito
99	Por definir

Complex Invoice Examples

Invoice with Multiple Items and Taxes

{
    "automation_type": "payment",
    "client": {
        "id": "client_1234567890"
    },
    "currency": "MXN",
    "exchange_rate": 1.0,
    "items": [
        {
            "description": "Consulting services - Phase 1",
            "quantity": 10,
            "unit_price": 1000.0,
            "product_key": "80141503",
            "unit_key": "HUR",
            "taxes": [
                {
                    "type": "IVA",
                    "rate": 0.16,
                    "withholding": false
                }
            ]
        },
        {
            "description": "Software license",
            "quantity": 1,
            "unit_price": 5000.0,
            "product_key": "81111500",
            "unit_key": "H87",
            "taxes": [
                {
                    "type": "IVA",
                    "rate": 0.16,
                    "withholding": false
                }
            ]
        }
    ],
    "use": "G03",
    "payment_form": "03",
    "payment_method": "PUE"
}

Invoice with Withholding Taxes

{
    "automation_type": "payment",
    "client": {
        "id": "client_1234567890"
    },
    "currency": "MXN",
    "exchange_rate": 1.0,
    "items": [
        {
            "description": "Professional services",
            "quantity": 1,
            "unit_price": 10000.0,
            "product_key": "80141503",
            "unit_key": "E48",
            "taxes": [
                {
                    "type": "IVA",
                    "rate": 0.16,
                    "withholding": false
                },
                {
                    "type": "ISR",
                    "rate": 0.1,
                    "withholding": true
                },
                {
                    "type": "IVA",
                    "rate": 0.106667,
                    "withholding": true
                }
            ]
        }
    ],
    "use": "G03",
    "payment_form": "03",
    "payment_method": "PUE"
}

PPD Invoice (Partial Payments)

{
    "automation_type": "none",
    "client": {
        "id": "client_1234567890"
    },
    "currency": "MXN",
    "exchange_rate": 1.0,
    "items": [
        {
            "description": "Large project - Total amount",
            "quantity": 1,
            "unit_price": 100000.0,
            "product_key": "80141503",
            "unit_key": "E48",
            "taxes": [
                {
                    "type": "IVA",
                    "rate": 0.16
                }
            ]
        }
    ],
    "use": "G03",
    "payment_form": "99",
    "payment_method": "PPD"
}

Global Invoice

{
    "automation_type": "none",
    "client": {
        "id": "client_publico_general"
    },
    "currency": "MXN",
    "exchange_rate": 1.0,
    "global": {
        "periodicity": "04",
        "months": "01",
        "year": 2024
    },
    "items": [
        {
            "description": "Ventas del periodo",
            "quantity": 1,
            "unit_price": 50000.0,
            "product_key": "01010101",
            "unit_key": "ACT",
            "taxes": [
                {
                    "type": "IVA",
                    "rate": 0.16
                }
            ]
        }
    ],
    "use": "P01",
    "payment_form": "03",
    "payment_method": "PUE"
}

{
    "related_documents": [
        {
            "relationship": "04",
            "documents": ["12345678-1234-1234-1234-123456789012"]
        }
    ]
}

Relationship Types:

01 - Nota de credito de los documentos relacionados

02 - Nota de debito de los documentos relacionados

03 - Devolucion de mercancia sobre facturas o traslados previos

04 - Sustitucion de los CFDI previos

07 - CFDI por aplicacion de anticipo

Common Scenarios

1. Simple Sale Invoice

2. Service Invoice with Email

3. USD Invoice with Exchange Rate

Best Practices

Use idempotency keys - Prevent duplicate invoices by including unique identifiers.

Validate clients first - Ensure the client's fiscal data (RFC, tax system, address) is correct before creating an invoice.

Configure email settings - Set up BCC addresses for your accounting department.

Use correct payment methods - Use PUE for immediate single payments and PPD for partial or deferred payments.

Include all required taxes - Apply IVA, ISR, and IEPS as applicable to each line item.

Set proper CFDI use - Match the CFDI use code to the client's tax requirements.

Keep series organized - Use different series for different invoice types or business units.

Use drafts for review - For high-value invoices, use the draft workflow to generate a preview before stamping.

CFDI Errors Reference - Comprehensive error code catalog

Clients API - Manage invoice recipients

Services API - Configure invoice items

Payments API - Process invoice payments

Teams API - Configure invoice settings

Error Handling

When working with invoices, you may encounter various CFDI-specific error codes. Use the CFDI Errors endpoint to look up detailed explanations and solutions for any error codes you receive.

Missing Required Fields

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

Invalid Tax Configuration

{
    "message": "Tax validation failed",
    "error": "IVA rate must be 0.16 for standard rate"
}

Stamping Error

{
    "message": "Failed to stamp invoice",
    "error": "Stamping service unavailable"
}

Cancellation Error

{
    "message": "Cannot cancel invoice",
    "error": "Invoice has dependent payment complements"
}

For additional help with invoice management, refer to the support documentation or contact support@gigstack.io.

Invoices API Guide

Invoices API Guide#

Overview#

Key Features#

Endpoints#

List CFDI Errors#

List Income Invoices#

Create Income Invoice#

Get Income Invoice#

List Egress Invoices#

Get Invoice Files#

Cancel Invoice#

Draft Invoices (Pre-Facturas)#

Create Draft#

List Drafts#

Get Draft#

Update Draft#

Delete Draft#

Stamp Draft (Finalize)#

Preview Draft#

Draft Workflow Example#

Invoice Structure#

Invoice Types#

Payment Methods#

Payment Forms (Formas de Pago)#

Complex Invoice Examples#

Invoice with Multiple Items and Taxes#

Invoice with Withholding Taxes#

PPD Invoice (Partial Payments)#

Global Invoice#

Related Documents#

Creating Related Invoices#

Common Scenarios#

1. Simple Sale Invoice#

2. Service Invoice with Email#

3. USD Invoice with Exchange Rate#

Best Practices#

Related Resources#

Error Handling#

Missing Required Fields#

Invalid Tax Configuration#

Stamping Error#

Cancellation Error#

Invoices API Guide

Overview

Key Features

Endpoints

List CFDI Errors

List Income Invoices

Create Income Invoice

Get Income Invoice

List Egress Invoices

Get Invoice Files

Cancel Invoice

Draft Invoices (Pre-Facturas)

Create Draft

List Drafts

Get Draft

Update Draft

Delete Draft

Stamp Draft (Finalize)

Preview Draft

Draft Workflow Example

Invoice Structure

Invoice Types

Payment Methods

Payment Forms (Formas de Pago)

Complex Invoice Examples

Invoice with Multiple Items and Taxes

Invoice with Withholding Taxes

PPD Invoice (Partial Payments)

Global Invoice

Related Documents

Creating Related Invoices

Common Scenarios

1. Simple Sale Invoice

2. Service Invoice with Email

3. USD Invoice with Exchange Rate

Best Practices

Related Resources

Error Handling

Missing Required Fields

Invalid Tax Configuration

Stamping Error

Cancellation Error