--- title: "Create invoice draft" description: "Create a CFDI draft with canonical tax validation. Payment complements accept automatic taxes for known CFDIs or caller-provided taxObject and payment-level tax entries for external CFDIs. This tool never stamps." language: en canonical_url: "https://exac.mx/docs/en/mcp/tools/create_invoice_draft" md_url: "https://exac.mx/docs/en/mcp/tools/create_invoice_draft.md" --- # Create invoice draft Create a CFDI draft with canonical tax validation. Payment complements accept automatic taxes for known CFDIs or caller-provided taxObject and payment-level tax entries for external CFDIs. This tool never stamps. Tool: `create_invoice_draft` ## Purpose Create a tax-validated CFDI draft for income, credit note, transfer, or payment-complement flows. ### Use when You need to author a CFDI before SAT stamping. ### Do not use when The document is payroll, a withholding, or a sales receipt. | Detail | Value | | --- | --- | | Permissions | invoices:manage | | Side effects | External side effect | | Idempotency | Idempotent | ## Input schema ```json { "type": "object", "properties": { "idempotencyKey": { "type": "string", "minLength": 1, "maxLength": 200, "description": "Unique retry key for this exact operation. Reuse it only when retrying the same request." }, "input": { "oneOf": [ { "type": "object", "properties": { "pdfCustomSection": { "$ref": "#/definitions/__schema1" }, "emissionDate": { "$ref": "#/definitions/__schema2" }, "currency": { "$ref": "#/definitions/__schema4" }, "customerId": { "$ref": "#/definitions/__schema5" }, "items": { "$ref": "#/definitions/__schema6" }, "kind": { "const": "income" }, "exchangeRate": { "$ref": "#/definitions/__schema25" }, "inventoryImpact": { "description": "Optional stock deduction on issuance; null disables. Location must hold every location-assigned product.", "allOf": [ { "anyOf": [ { "type": "object", "properties": { "locationId": { "type": "string", "minLength": 1 } }, "additionalProperties": false }, { "type": "null" } ] } ] }, "cfdiUse": { "enum": [ "CN01", "CP01", "D01", "D02", "D03", "D04", "D05", "D06", "D07", "D08", "D09", "D10", "G01", "G02", "G03", "I01", "I02", "I03", "I04", "I05", "I06", "I07", "I08", "S01" ], "description": "Known SAT CFDI-use code.", "x-exac-sat-catalog": "cfdi-uses" }, "payment": { "oneOf": [ { "type": "object", "properties": { "timing": { "const": "single_payment" }, "formCode": { "$ref": "#/definitions/__schema31" }, "conditions": { "type": "string", "maxLength": 1000 } }, "required": [ "timing", "formCode" ], "additionalProperties": false }, { "type": "object", "properties": { "timing": { "const": "deferred_or_installments" }, "formCode": { "const": "99" }, "dueDate": { "type": "string", "format": "date", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))$", "description": "Calendar date in YYYY-MM-DD format" }, "settlementTerms": { "type": "object", "properties": { "installmentCount": { "type": "integer", "minimum": 1, "maximum": 60 }, "firstDue": { "oneOf": [ { "type": "object", "properties": { "kind": { "const": "transaction_date" } }, "required": [ "kind" ], "additionalProperties": false }, { "type": "object", "properties": { "kind": { "const": "months_after_transaction" }, "months": { "type": "integer", "minimum": 1, "maximum": 60 } }, "required": [ "kind", "months" ], "additionalProperties": false }, { "type": "object", "properties": { "kind": { "const": "fixed_date" }, "date": { "type": "string" } }, "required": [ "kind", "date" ], "additionalProperties": false } ] }, "recurrence": { "oneOf": [ { "type": "object", "properties": { "kind": { "const": "anchor_day" } }, "required": [ "kind" ], "additionalProperties": false }, { "type": "object", "properties": { "kind": { "const": "day_of_month" }, "day": { "type": "integer", "minimum": 1, "maximum": 31 } }, "required": [ "kind", "day" ], "additionalProperties": false }, { "type": "object", "properties": { "kind": { "const": "last_day" } }, "required": [ "kind" ], "additionalProperties": false } ] } }, "required": [ "installmentCount", "firstDue", "recurrence" ], "additionalProperties": false }, "conditions": { "type": "string", "maxLength": 1000 } }, "required": [ "timing", "formCode" ], "additionalProperties": false } ] } }, "required": [ "customerId", "items", "kind", "cfdiUse", "payment" ], "additionalProperties": false, "title": "CFDI I · income" }, { "type": "object", "properties": { "pdfCustomSection": { "$ref": "#/definitions/__schema1" }, "emissionDate": { "$ref": "#/definitions/__schema2" }, "currency": { "$ref": "#/definitions/__schema4" }, "customerId": { "$ref": "#/definitions/__schema5" }, "items": { "$ref": "#/definitions/__schema6" }, "kind": { "const": "credit_note" }, "exchangeRate": { "$ref": "#/definitions/__schema25" }, "formCode": { "$ref": "#/definitions/__schema31" }, "methodCode": { "enum": [ "PPD", "PUE" ], "description": "Known SAT payment-method code. Defaults to PUE when omitted.", "x-exac-sat-catalog": "payment-methods" }, "relatedDocuments": { "minItems": 1, "type": "array", "items": { "type": "object", "properties": { "relationship": { "enum": [ "01", "02", "03", "04", "05", "06", "07" ], "description": "Known SAT CFDI relationship-type code.", "x-exac-sat-catalog": "relationship-types" }, "documents": { "minItems": 1, "type": "array", "items": { "type": "string", "minLength": 1 }, "description": "Related CFDI UUIDs" } }, "required": [ "relationship", "documents" ], "additionalProperties": false } } }, "required": [ "customerId", "items", "kind", "formCode", "relatedDocuments" ], "additionalProperties": false, "title": "CFDI E · credit_note" }, { "type": "object", "properties": { "pdfCustomSection": { "$ref": "#/definitions/__schema1" }, "emissionDate": { "$ref": "#/definitions/__schema2" }, "currency": { "$ref": "#/definitions/__schema4" }, "customerId": { "$ref": "#/definitions/__schema5" }, "items": { "minItems": 1, "type": "array", "items": { "oneOf": [ { "type": "object", "properties": { "kind": { "$ref": "#/definitions/__schema9" }, "productId": { "$ref": "#/definitions/__schema10" }, "quantity": { "$ref": "#/definitions/__schema11" }, "unitPrice": { "type": "number", "const": 0 } }, "required": [ "kind", "productId", "quantity", "unitPrice" ], "additionalProperties": false }, { "type": "object", "properties": { "kind": { "$ref": "#/definitions/__schema17" }, "description": { "$ref": "#/definitions/__schema18" }, "quantity": { "$ref": "#/definitions/__schema19" }, "unitPrice": { "type": "number", "const": 0 }, "satProductCode": { "$ref": "#/definitions/__schema20" }, "satUnitCode": { "$ref": "#/definitions/__schema21" } }, "required": [ "kind", "description", "quantity", "unitPrice", "satProductCode", "satUnitCode" ], "additionalProperties": false } ] } }, "kind": { "const": "transfer" } }, "required": [ "customerId", "items", "kind" ], "additionalProperties": false, "title": "CFDI T · transfer" }, { "type": "object", "properties": { "pdfCustomSection": { "$ref": "#/definitions/__schema1" }, "emissionDate": { "$ref": "#/definitions/__schema2" }, "kind": { "const": "payment_complement" }, "customerId": { "type": "string", "minLength": 1 }, "payments": { "minItems": 1, "type": "array", "items": { "type": "object", "properties": { "formCode": { "$ref": "#/definitions/__schema31" }, "paidLocalDateTime": { "type": "string", "pattern": "^(\\d{4})-(\\d{2})-(\\d{2})T(\\d{2}):(\\d{2}):(\\d{2})(?:\\.(\\d{1,9}))?$" }, "documents": { "minItems": 1, "type": "array", "items": { "type": "object", "properties": { "uuid": { "type": "string", "minLength": 1 }, "amount": { "type": "number", "exclusiveMinimum": 0 }, "installment": { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991, "description": "1-based payment sequence" }, "previousBalance": { "type": "number", "exclusiveMinimum": 0, "description": "Balance before payment; then use prior remaining balance" }, "series": { "type": "string" }, "folio": { "type": "string" }, "currency": { "type": "string", "minLength": 3, "maxLength": 3 }, "exchangeRate": { "description": "Document currency units per MXN.", "allOf": [ { "type": "number", "exclusiveMinimum": 0 } ] }, "taxes": { "anyOf": [ { "const": "auto", "description": "Calculate taxes from this organization's CFDI." }, { "type": "object", "properties": { "taxObject": { "enum": [ "01", "02", "03", "04", "05", "06", "07", "08" ], "description": "SAT ObjetoImpDR from the related CFDI" }, "entries": { "type": "array", "items": { "type": "object", "properties": { "base": { "type": "number", "minimum": 0 }, "type": { "enum": [ "IVA", "ISR", "IEPS" ] }, "rate": { "type": "number", "minimum": 0 }, "factor": { "enum": [ "Tasa", "Cuota", "Exento" ] }, "withholding": { "type": "boolean" } }, "required": [ "base", "type", "rate" ], "additionalProperties": false }, "description": "Payment-level tax rows from the related CFDI" } }, "required": [ "taxObject", "entries" ], "additionalProperties": false, "description": "Taxes for an external CFDI Exac cannot inspect" } ] } }, "required": [ "uuid", "amount", "installment", "previousBalance", "taxes" ], "additionalProperties": false } } }, "required": [ "formCode", "documents" ], "additionalProperties": false } } }, "required": [ "kind", "customerId", "payments" ], "additionalProperties": false, "title": "CFDI P · payment_complement" } ] } }, "required": [ "idempotencyKey", "input" ], "$schema": "http://json-schema.org/draft-07/schema#", "additionalProperties": false, "definitions": { "__schema1": { "type": "string" }, "__schema2": { "description": "Emission instant with UTC offset; validated against the certification window at stamping.", "allOf": [ { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$" } ] }, "__schema4": { "type": "string", "minLength": 3, "maxLength": 3 }, "__schema5": { "type": "string", "minLength": 1 }, "__schema6": { "minItems": 1, "type": "array", "items": { "oneOf": [ { "type": "object", "properties": { "kind": { "$ref": "#/definitions/__schema9" }, "productId": { "$ref": "#/definitions/__schema10" }, "quantity": { "$ref": "#/definitions/__schema11" }, "unitPrice": { "type": "number", "minimum": 0, "description": "Unit price in pesos" }, "discount": { "type": "number", "minimum": 0 }, "taxIncluded": { "type": "boolean" }, "deliveredOutsideBorderRegion": { "$ref": "#/definitions/__schema12" }, "borderOperation": { "$ref": "#/definitions/__schema14" } }, "required": [ "kind", "productId", "quantity", "unitPrice" ], "additionalProperties": false }, { "type": "object", "properties": { "kind": { "$ref": "#/definitions/__schema17" }, "description": { "$ref": "#/definitions/__schema18" }, "quantity": { "$ref": "#/definitions/__schema19" }, "unitPrice": { "type": "number", "minimum": 0, "description": "Unit price in pesos" }, "satProductCode": { "$ref": "#/definitions/__schema20" }, "satUnitCode": { "$ref": "#/definitions/__schema21" }, "discount": { "type": "number", "minimum": 0 }, "taxIncluded": { "type": "boolean" }, "taxRate": { "description": "The IVA rate you expect; the rules in force decide it and refuse another. A credit note keeps a rate its related invoice charged.", "allOf": [ { "type": "number", "minimum": 0, "maximum": 1 } ] }, "taxability": { "enum": [ "standard", "zero", "exempt" ] }, "taxCategory": { "description": "What the concept bills, for withholdings (service: professional fees). Optional: without it the CFDI states only the withholdings every operation type shares.", "allOf": [ { "type": "string", "pattern": "^[a-z][A-Za-z0-9]{0,63}$" } ] }, "deliveredOutsideBorderRegion": { "$ref": "#/definitions/__schema12" }, "borderOperation": { "$ref": "#/definitions/__schema14" } }, "required": [ "kind", "description", "quantity", "unitPrice", "satProductCode", "satUnitCode" ], "additionalProperties": false } ] } }, "__schema9": { "const": "product" }, "__schema10": { "type": "string", "minLength": 1, "description": "Existing Exac product ID" }, "__schema11": { "type": "number", "exclusiveMinimum": 0 }, "__schema12": { "description": "Border issuers: delivered or rendered outside the region, so no border IVA stimulus.", "allOf": [ { "type": "boolean" } ] }, "__schema14": { "description": "Completed operation paid within ten calendar days after the border decree expires.", "allOf": [ { "type": "object", "properties": { "completedOn": { "type": "string", "format": "date", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))$", "description": "Date goods were delivered or services completed in the border region" }, "paidOn": { "type": "string", "format": "date", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))$", "description": "Date the consideration was paid" } }, "required": [ "completedOn", "paidOn" ], "additionalProperties": false } ] }, "__schema17": { "const": "custom" }, "__schema18": { "type": "string", "minLength": 1 }, "__schema19": { "type": "number", "exclusiveMinimum": 0 }, "__schema20": { "type": "string", "minLength": 1, "description": "SAT product/service code" }, "__schema21": { "type": "string", "minLength": 1, "description": "SAT unit code" }, "__schema25": { "description": "MXN per document-currency unit. Use 1 for MXN; this is not the payment document equivalence rate.", "allOf": [ { "type": "number", "exclusiveMinimum": 0 } ] }, "__schema31": { "enum": [ "12", "13", "14", "15", "17", "23", "24", "25", "26", "27", "28", "29", "30", "31", "99", "01", "02", "03", "04", "05", "06", "08" ], "description": "Known SAT payment-form code.", "x-exac-sat-catalog": "payment-forms" } } } ``` ## Output schema ```json { "type": "object", "properties": { "data": { "type": "object", "properties": { "simulated": { "allOf": [ { "type": "boolean", "const": true } ] }, "documentRef": { "type": "string", "pattern": "^invoice:.+$" }, "kind": { "enum": [ "income", "credit_note", "transfer", "payroll", "payment_complement" ] }, "status": { "const": "draft" } }, "required": [ "documentRef", "kind", "status" ], "additionalProperties": false }, "error": { "$schema": "http://json-schema.org/draft-07/schema#", "type": "object", "properties": { "code": { "enum": [ "validation_error", "unauthenticated", "forbidden", "payment_required", "not_found", "method_not_allowed", "conflict", "idempotency_conflict", "operation_in_progress", "recovery_required", "migration_required", "rate_limited", "provider_unavailable", "internal" ] }, "message": { "type": "string" }, "details": { "type": "object", "properties": { "document": { "type": "object", "properties": { "documentRef": { "type": "string", "pattern": "^(invoice|withholding|sales_receipt|declaration|tax_compliance_opinion|sales_receipt_refund):.+$" }, "editable": { "type": "boolean" } }, "required": [ "documentRef", "editable" ], "additionalProperties": false }, "issues": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "array", "items": { "anyOf": [ { "type": "string" }, { "type": "number" } ] } }, "message": { "type": "string" }, "code": { "type": "string" } }, "required": [ "path", "message" ], "additionalProperties": false } }, "retryable": { "type": "boolean" }, "retryAfterSeconds": { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991 }, "reason": { "type": "string" }, "balanceMinor": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "topUpUrl": { "type": "string" } }, "additionalProperties": false } }, "required": [ "code", "message" ], "additionalProperties": false } }, "$schema": "http://json-schema.org/draft-07/schema#", "additionalProperties": false, "oneOf": [ { "required": [ "data" ] }, { "required": [ "error" ] } ] } ``` ## Related tools - [`get_document`](/docs/en/mcp/tools/get_document.md) — **Get document**: Retrieve one document by its public documentRef. Sales receipt details include stable lineRef values and remaining refundable amounts for sales receipt refunds. - [`update_invoice_draft`](/docs/en/mcp/tools/update_invoice_draft.md) — **Update invoice draft**: Fully replace the contents of an existing CFDI draft. The semantic kind must match the draft; changing fiscal kind requires archiving the old draft and creating a new draft. - [`stamp_invoice`](/docs/en/mcp/tools/stamp_invoice.md) — **Stamp invoice**: Irreversibly stamp an existing CFDI draft. Review the draft first with get_document. Safe retries require reusing the same idempotencyKey. ## Related workflow [See the canonical workflows in the introduction](/docs/en.md) ## Equivalent REST operations - [`POST /v1/invoices`](/docs/en/api/documents/invoices/create-invoice-draft.md) Complete documentation: https://exac.mx/docs/en.md Agent documentation index: https://exac.mx/docs/en/llms.txt