--- title: "Create quote" description: "Creates a draft quote from customer, line-item, pricing, settlement, and optional invoicing data." language: en canonical_url: "https://exac.mx/docs/en/api/documents/quotes/create-quote" md_url: "https://exac.mx/docs/en/api/documents/quotes/create-quote.md" --- # Create quote Creates a draft quote from customer, line-item, pricing, settlement, and optional invoicing data. ## Request `POST /v1/quotes` - **Authorization:** Required permission: `quotes:manage`. - **Environments:** Production and sandbox - **Idempotency:** Required ## Canonical machine contract This fragment is generated from the canonical operation and Zod contracts used by the route. ```json { "method": "POST", "path": "/v1/quotes", "operation": { "operationId": "createQuote", "tags": [ "Quotes" ], "summary": "Create quote", "description": "Creates a draft quote from customer, line-item, pricing, settlement, and optional invoicing data.", "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": true, "schema": { "type": "string", "minLength": 1, "maxLength": 200 }, "description": "Unique retry key for this exact operation. Reuse it only when retrying the same request." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "customerId": { "type": "string", "minLength": 1 }, "customerName": { "type": "string", "minLength": 1, "description": "Recipient name when no stored customer is selected." }, "customerEmail": { "type": "string", "format": "email", "pattern": "^(?!\\.)(?!.*\\.\\.)([A-Za-z0-9_'+\\-\\.]*)[A-Za-z0-9_+-]@([A-Za-z0-9][A-Za-z0-9\\-]*\\.)+[A-Za-z]{2,}$" }, "locationId": { "type": "string", "minLength": 1 }, "validUntil": { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}$" }, "items": { "minItems": 1, "maxItems": 50, "type": "array", "items": { "oneOf": [ { "type": "object", "properties": { "kind": { "type": "string", "const": "product" }, "productId": { "type": "string", "minLength": 1 }, "quantity": { "type": "number", "exclusiveMinimum": 0 }, "discount": { "type": "number", "minimum": 0 } }, "required": [ "kind", "productId", "quantity" ], "additionalProperties": false }, { "type": "object", "properties": { "kind": { "type": "string", "const": "custom" }, "description": { "type": "string", "minLength": 1 }, "quantity": { "type": "number", "exclusiveMinimum": 0 }, "unitPrice": { "type": "number", "exclusiveMinimum": 0 }, "discount": { "type": "number", "minimum": 0 }, "satProductCode": { "type": "string", "minLength": 1 }, "satUnitCode": { "type": "string", "minLength": 1 }, "unitName": { "type": "string", "minLength": 1 }, "taxIncluded": { "type": "boolean" }, "taxability": { "type": "string", "enum": [ "standard", "zero", "exempt" ] }, "taxRate": { "type": "number", "minimum": 0, "maximum": 1 } }, "required": [ "kind", "description", "quantity", "unitPrice", "satProductCode" ], "additionalProperties": false } ] } }, "notes": { "type": "string" }, "settlementTerms": { "type": "object", "properties": { "installmentCount": { "type": "integer", "minimum": 1, "maximum": 60 }, "firstDue": { "oneOf": [ { "type": "object", "properties": { "kind": { "type": "string", "const": "transaction_date" } }, "required": [ "kind" ], "additionalProperties": false }, { "type": "object", "properties": { "kind": { "type": "string", "const": "months_after_transaction" }, "months": { "type": "integer", "minimum": 1, "maximum": 60 } }, "required": [ "kind", "months" ], "additionalProperties": false }, { "type": "object", "properties": { "kind": { "type": "string", "const": "fixed_date" }, "date": { "type": "string" } }, "required": [ "kind", "date" ], "additionalProperties": false } ] }, "recurrence": { "oneOf": [ { "type": "object", "properties": { "kind": { "type": "string", "const": "anchor_day" } }, "required": [ "kind" ], "additionalProperties": false }, { "type": "object", "properties": { "kind": { "type": "string", "const": "day_of_month" }, "day": { "type": "integer", "minimum": 1, "maximum": 31 } }, "required": [ "kind", "day" ], "additionalProperties": false }, { "type": "object", "properties": { "kind": { "type": "string", "const": "last_day" } }, "required": [ "kind" ], "additionalProperties": false } ] } }, "required": [ "installmentCount", "firstDue", "recurrence" ], "additionalProperties": false } }, "required": [ "validUntil", "items" ], "additionalProperties": false }, "example": { "customerId": "customer-example", "validUntil": "2026-08-03", "items": [ { "kind": "custom", "description": "Consultoría mensual", "quantity": 1, "unitPrice": 2500, "satProductCode": "80101500", "satUnitCode": "E48", "taxIncluded": false, "taxability": "standard", "taxRate": 0.16 } ] } } } }, "responses": { "201": { "description": "Operation completed.", "headers": { "Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/Quote" } }, "required": [ "data" ], "additionalProperties": false }, "example": { "data": { "folioNumber": 42, "currency": "MXN", "customerId": "customer-example", "customerName": "Estudio Jacaranda", "customerEmail": "administracion@jacaranda.example", "documentRef": "quote:quote-example", "category": "quote", "status": "draft", "items": [ { "lineRef": "quote-line-1", "description": "Consultoría mensual", "quantity": 1, "unitPrice": 2500, "taxIncluded": false, "taxability": "standard", "taxRate": 0.16, "satProductCode": "80101500", "satUnitCode": "E48" } ], "totals": { "subtotal": 2500, "taxes": 400, "total": 2900, "taxBreakdown": [ { "type": "IVA", "factor": "Tasa", "rate": 0.16, "withholding": false, "base": 2500, "amount": 400, "label": "IVA 16%" } ] }, "issueDate": "2026-07-19", "validUntil": "2026-08-03", "createdAt": "2026-08-01T12:00:00.000Z", "updatedAt": "2026-08-01T12:00:00.000Z" } } } } }, "400": { "description": "Invalid request.\n\n`validation_error`", "headers": { "Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "401": { "description": "Missing or invalid credential.\n\n`unauthenticated`", "headers": { "Request-Id": { "$ref": "#/components/headers/RequestId" }, "WWW-Authenticate": { "$ref": "#/components/headers/WWWAuthenticate" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "403": { "description": "The credential does not include the `quotes:manage` permission.\n\n`forbidden`", "headers": { "Request-Id": { "$ref": "#/components/headers/RequestId" }, "WWW-Authenticate": { "$ref": "#/components/headers/WWWAuthenticate" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "404": { "description": "Resource not found.\n\n`not_found`", "headers": { "Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "405": { "description": "Method not allowed.\n\n`method_not_allowed`", "headers": { "Request-Id": { "$ref": "#/components/headers/RequestId" }, "Allow": { "$ref": "#/components/headers/Allow" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "409": { "description": "The operation conflicts with its current state or idempotency key.\n\nPossible codes: `conflict`, `idempotency_conflict`, `operation_in_progress`, `recovery_required`.", "headers": { "Request-Id": { "$ref": "#/components/headers/RequestId" }, "Retry-After": { "$ref": "#/components/headers/RetryAfter" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "429": { "description": "Too many requests.\n\n`rate_limited`", "headers": { "Request-Id": { "$ref": "#/components/headers/RequestId" }, "Retry-After": { "$ref": "#/components/headers/RetryAfter" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "500": { "description": "Internal server error.\n\n`internal`", "headers": { "Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "503": { "description": "Service temporarily unavailable.\n\n`provider_unavailable`", "headers": { "Request-Id": { "$ref": "#/components/headers/RequestId" }, "Retry-After": { "$ref": "#/components/headers/RetryAfter" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } }, "x-exac-environments": [ "production", "sandbox" ] }, "components": { "schemas": { "ApiError": { "type": "object", "properties": { "error": { "$ref": "#/components/schemas/ProgrammaticError" } }, "required": [ "error" ], "additionalProperties": false }, "ProgrammaticError": { "type": "object", "properties": { "code": { "type": "string", "enum": [ "validation_error", "unauthenticated", "forbidden", "not_found", "method_not_allowed", "conflict", "idempotency_conflict", "operation_in_progress", "recovery_required", "rate_limited", "provider_unavailable", "internal" ], "description": "Recommended action by code:\n\n- `validation_error` — Correct each details.issues entry using its path and stable issue code.\n- `unauthenticated` — Provide a valid API key or OAuth access token.\n- `forbidden` — Use a credential with the required permission.\n- `not_found` — Check the organization-scoped resource identifier.\n- `method_not_allowed` — Use the documented HTTP method.\n- `conflict` — Refresh the resource and resolve its current state.\n- `idempotency_conflict` — Use a new idempotency key for a changed request.\n- `operation_in_progress` — Wait for Retry-After, then repeat the exact request.\n- `recovery_required` — Do not retry automatically; reconcile the provider outcome.\n- `rate_limited` — Wait for Retry-After before retrying.\n- `provider_unavailable` — Retry only when the response marks the failure as retryable.\n- `internal` — Retry later and contact support if the error persists." }, "message": { "type": "string" }, "details": { "type": "object", "properties": { "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 } }, "additionalProperties": false }, "status": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 } }, "required": [ "code", "message", "status" ], "additionalProperties": false }, "Quote": { "type": "object", "properties": { "folioNumber": { "type": "number" }, "currency": { "type": "string", "const": "MXN" }, "customerId": { "type": "string" }, "customerName": { "type": "string" }, "customerEmail": { "type": "string" }, "locationId": { "type": "string" }, "locationName": { "type": "string" }, "notes": { "type": "string" }, "settlementTerms": { "type": "object", "properties": { "installmentCount": { "type": "integer", "minimum": 1, "maximum": 60 }, "firstDue": { "oneOf": [ { "type": "object", "properties": { "kind": { "type": "string", "const": "transaction_date" } }, "required": [ "kind" ], "additionalProperties": false }, { "type": "object", "properties": { "kind": { "type": "string", "const": "months_after_transaction" }, "months": { "type": "integer", "minimum": 1, "maximum": 60 } }, "required": [ "kind", "months" ], "additionalProperties": false }, { "type": "object", "properties": { "kind": { "type": "string", "const": "fixed_date" }, "date": { "type": "string" } }, "required": [ "kind", "date" ], "additionalProperties": false } ] }, "recurrence": { "oneOf": [ { "type": "object", "properties": { "kind": { "type": "string", "const": "anchor_day" } }, "required": [ "kind" ], "additionalProperties": false }, { "type": "object", "properties": { "kind": { "type": "string", "const": "day_of_month" }, "day": { "type": "integer", "minimum": 1, "maximum": 31 } }, "required": [ "kind", "day" ], "additionalProperties": false }, { "type": "object", "properties": { "kind": { "type": "string", "const": "last_day" } }, "required": [ "kind" ], "additionalProperties": false } ] } }, "required": [ "installmentCount", "firstDue", "recurrence" ], "additionalProperties": false }, "receivablePlanId": { "type": "string" }, "revisionNumber": { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991 }, "documentRef": { "type": "string", "pattern": "^quote:.+$" }, "category": { "type": "string", "const": "quote" }, "status": { "type": "string", "enum": [ "draft", "sent", "accepted", "converted", "expired", "canceled" ] }, "items": { "type": "array", "items": { "type": "object", "properties": { "lineRef": { "type": "string" }, "productId": { "type": "string" }, "description": { "type": "string" }, "quantity": { "type": "number" }, "unitPrice": { "type": "number" }, "discount": { "type": "number" }, "taxIncluded": { "type": "boolean" }, "taxability": { "type": "string", "enum": [ "standard", "zero", "exempt" ] }, "taxRate": { "type": "number" }, "satProductCode": { "type": "string" }, "satUnitCode": { "type": "string" }, "unitName": { "type": "string" } }, "required": [ "description", "quantity", "unitPrice" ], "additionalProperties": false } }, "totals": { "type": "object", "properties": { "subtotal": { "type": "number" }, "discount": { "type": "number" }, "taxes": { "type": "number" }, "total": { "type": "number" }, "taxBreakdown": { "type": "array", "items": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "IVA", "ISR" ] }, "factor": { "type": "string", "enum": [ "Tasa", "Exento" ] }, "rate": { "type": "number" }, "withholding": { "type": "boolean" }, "base": { "type": "number" }, "amount": { "type": "number" }, "label": { "type": "string" } }, "required": [ "type", "factor", "rate", "withholding", "base", "amount", "label" ], "additionalProperties": false } } }, "required": [ "subtotal", "taxes", "total", "taxBreakdown" ], "additionalProperties": false }, "issueDate": { "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])))$" }, "validUntil": { "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])))$" }, "sentAt": { "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)))$" }, "lastPublishedAt": { "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)))$" }, "acceptance": { "type": "object", "properties": { "acceptedAt": { "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)))$" }, "invoiceRequested": { "type": "boolean" }, "fiscalTreatment": { "type": "string", "enum": [ "public_general", "specific_counterparty" ] }, "fiscalTotals": { "type": "object", "properties": { "subtotal": { "type": "number" }, "discount": { "type": "number" }, "taxes": { "type": "number" }, "total": { "type": "number" }, "taxBreakdown": { "type": "array", "items": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "IVA", "ISR" ] }, "factor": { "type": "string", "enum": [ "Tasa", "Exento" ] }, "rate": { "type": "number" }, "withholding": { "type": "boolean" }, "base": { "type": "number" }, "amount": { "type": "number" }, "label": { "type": "string" } }, "required": [ "type", "factor", "rate", "withholding", "base", "amount", "label" ], "additionalProperties": false } } }, "required": [ "subtotal", "taxes", "total", "taxBreakdown" ], "additionalProperties": false }, "fiscalCustomer": { "type": "object", "properties": { "rfc": { "type": "string" }, "legalName": { "type": "string" }, "taxSystem": { "type": "string" }, "postalCode": { "type": "string" }, "cfdiUse": { "type": "string" }, "email": { "type": "string" } }, "required": [ "rfc", "legalName", "taxSystem", "postalCode", "cfdiUse", "email" ], "additionalProperties": false } }, "required": [ "acceptedAt", "invoiceRequested", "fiscalTreatment", "fiscalTotals" ], "additionalProperties": false }, "createdAt": { "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)))$" }, "updatedAt": { "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)))$" }, "receiptDocumentRef": { "type": "string", "pattern": "^sales_receipt:.+$" }, "payment": { "type": "object", "properties": { "paymentId": { "type": "string" }, "source": { "type": "string", "enum": [ "manual", "online" ] }, "amount": { "type": "number" }, "currency": { "type": "string", "const": "MXN" }, "paymentForm": { "type": "string" }, "applicationStatus": { "type": "string", "enum": [ "pending", "processing", "applied", "failed", "conflict" ] }, "applicationErrorCode": { "type": "string", "enum": [ "payment_form_required", "fiscal_drift", "location_resolution_required", "duplicate_payment", "application_failed" ] }, "invoiceStatus": { "type": "string", "enum": [ "pending", "processing", "issued", "failed" ] }, "salesReceiptDocumentRef": { "type": "string", "pattern": "^sales_receipt:.+$" }, "cfdiDocumentRef": { "type": "string", "pattern": "^cfdi:.+$" }, "paidAt": { "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)))$" } }, "required": [ "paymentId", "source", "amount", "currency", "applicationStatus", "paidAt" ], "additionalProperties": false } }, "required": [ "folioNumber", "currency", "customerName", "documentRef", "category", "status", "items", "totals", "issueDate", "validUntil", "createdAt", "updatedAt" ], "additionalProperties": false } } } } ``` [OpenAPI 3.1](/openapi.json) ## Equivalent MCP tools - [`save_quote`](/docs/en/mcp/tools/save_quote.md) Complete documentation: https://exac.mx/docs/en.md Agent documentation index: https://exac.mx/docs/en/llms.txt