Sign in

v1

latestOpenAPI 3.0.3Proprietaryraw.githubusercontent.com2026-03-067260437.0 KB
Invoices

Create income invoice

Create a new income invoice with CFDI 4.0 compliance.

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

post/invoices/income

Query parameters

teamstring

gigstack Connect: Target team ID for multi-team access.

Requires gigstack Connect enabled on your team and shared billing account.

Example: ?team=team_xyz789

Request body

automation_type'payment' | 'none' required

Invoice automation type:

  • payment: Create invoice with payment automation
  • none: No automation, create invoice only
client_idstring nullable

Optional client ID, if provided will use this client instead of creating/searching

currencystring required
exchange_ratenumber nullable

Exchange rate for currency conversion. If not provided, the latest rate from our rates collection will be used automatically.

folio_numbernumber
seriesstring
idempotency_keystring nullable

Optional idempotency key to prevent duplicate invoices

usestring required
exports'01' | '02' | '03' | '04'
payment_formstring required
payment_methodstring required
invoice_pdf_notesstring
addendastring
return_filesboolean

Return base64 encoded PDF and XML files in response

metadataobject
send_emailboolean
emailsstring[]

Example request

{
  "automation_type": "payment",
  "client_id": "client_1234567890",
  "client": {
    "id": "client_1234567890",
    "search": {
      "on_key": "tax_id",
      "on_value": "PEGJ800101ABC",
      "auto_create": true
    },
    "address": {
      "country": "MEX",
      "street": "Av. Insurgentes Sur",
      "zip": "03100",
      "city": "Ciudad de México",
      "state": "CDMX",
      "exterior": "123",
      "interior": "4B",
      "municipality": "Benito Juárez",
      "neighborhood": "Del Valle"
    },
    "name": "Juan Pérez García",
    "company": "Empresa SA de CV",
    "phone": "+52 55 1234 5678",
    "email": "juan.perez@ejemplo.com",
    "legal_name": "Juan Pérez García",
    "tax_id": "PEGJ800101ABC",
    "use": "P01",
    "tax_system": "601"
  },
  "complements": [
    {
      "type": "custom",
      "data": "<xml>...</xml>"
    }
  ],
  "currency": "MXN",
  "exchange_rate": 1,
  "folio_number": 123,
  "series": "A",
  "idempotency_key": "unique_key_123",
  "items": [
    {
      "id": "service_1234567890",
      "search": {
        "on_key": "sku",
        "on_value": "CONS-001",
        "auto_create": true
      },
      "description": "Consulting services",
      "sku": "CONS-001",
      "product_key": "80141503",
      "unit_key": "E48",
      "unit_name": "Servicio",
      "unit_price": 1000,
      "taxes": [
        {
          "factor": "Tasa",
          "rate": 0.16,
          "type": "IVA"
        }
      ],
      "taxability": "02",
      "third_party": {
        "tax_system": "601",
        "legal_name": "Third Party SA",
        "zip": "03100",
        "tax_id": "TPR800101ABC"
      }
    }
  ],
  "use": "P01",
  "related_documents": [
    {
      "relationship": "04",
      "documents": [
        "12345678-1234-1234-1234-123456789012"
      ]
    }
  ],
  "global": {
    "periodicity": "04",
    "months": "01",
    "year": 2024
  },
  "exports": "01",
  "payment_form": "03",
  "payment_method": "PUE",
  "invoice_pdf_notes": "Additional notes for PDF",
  "addenda": "<addenda>...</addenda>",
  "return_files": true,
  "send_email": true,
  "emails": [
    "client@example.com"
  ]
}

Response

Invoice created successfully

messagestring

Example response

{
  "message": "Invoice created successfully",
  "data": {
    "uuid": "invoice_1234567890",
    "client": {
      "id": "client_1234567890",
      "address": {
        "country": "MEX",
        "street": "Av. Insurgentes Sur",
        "zip": "03100",
        "city": "Ciudad de México",
        "state": "CDMX",
        "exterior": "123",
        "interior": "4B",
        "municipality": "Benito Juárez",
        "neighborhood": "Del Valle"
      },
      "name": "Juan Pérez García",
      "company": "Empresa SA de CV",
      "phone": "+52 55 1234 5678",
      "email": "juan.perez@ejemplo.com",
      "bcc": [
        "admin@empresa.com"
      ],
      "metadata": {
        "custom_field": "value"
      },
      "is_valid": true,
      "from": "api",
      "legal_name": "Juan Pérez García",
      "livemode": true,
      "owner": "user_1234567890",
      "tax_id": "PEGJ800101ABC",
      "use": "P01",
      "tax_system": "601",
      "team": "team_1234567890",
      "created_at": 1677651234,
      "efos": {
        "is_valid": true
      },
      "defaults": {
        "issue_invoiceable_receipts": true
      }
    },
    "created_at": 1677651234,
    "currency": "MXN",
    "exchange_rate": 1,
    "total": 1160,
    "subtotal": 1000,
    "taxes": 160,
    "series": "A",
    "folio_number": 123,
    "invoice_type": "I",
    "use": "P01",
    "payment_form": "03",
    "payment_method": "PUE",
    "status": "stamped",
    "livemode": true,
    "owner": "user_1234567890",
    "from": "api",
    "items": [
      {
        "id": "item_1234567890",
        "description": "Professional consulting services",
        "product_key": "80141503",
        "quantity": 1,
        "unit_price": 1000,
        "unit_key": "E48",
        "unit_name": "Servicio",
        "sku": "CONS-001",
        "taxability": "01",
        "taxes": [
          {
            "factor": "Tasa",
            "rate": 0.16,
            "type": "IVA"
          }
        ]
      }
    ],
    "payments": [
      "payment_1234567890"
    ],
    "invoices": [],
    "stamp": {
      "sello": "ABC123...",
      "stamp_at": 1677651234
    },
    "cancellation": {
      "cancellation_status": "cancelled",
      "cancelled_at": 1677651234,
      "motive": "02",
      "code": "201"
    },
    "verification_url": "https://verificacfdi.facturaelectronica.sat.gob.mx/default.aspx",
    "exports": "01",
    "invoice_pdf_notes": "Additional notes for PDF",
    "files": {
      "pdf": "JVBERi0xLjQKJeLjz9MKMSAwIG9ia...",
      "xml": "PD94bWwgdmVyc2lvbj0iMS4wIiBlbmNvZGluZz0idXRmLTgiPz4..."
    }
  }
}