MCP serverAvailable tools
Refund sales receipt
Register a sales receipt refund and, when applicable, create a CFDI credit note.
MCP tool
refund_sales_receiptPurpose
- Use when
- A customer refund has been approved.
- Do not use when
- The transaction should be voided before settlement or is not a receipt refund.
- Required permissions
- Side effects
- Destructive and external
- Idempotency
- Idempotent
Input schema
JSON Schema{ "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": { "type": "object", "properties": { "amount": { "type": "number", "exclusiveMinimum": 0 }, "reason": { "enum": [ "commercial_refund", "resico_reconciliation" ] }, "settlementMethod": { "enum": [ "cash", "transfer", "original_method", "customer_credit" ] }, "allocations": { "minItems": 1, "type": "array", "items": { "anyOf": [ { "type": "object", "properties": { "kind": { "const": "original_line" }, "lineRef": { "type": "string", "minLength": 1 }, "adjustmentMode": { "const": "quantity" }, "quantity": { "type": "number", "exclusiveMinimum": 0 } }, "required": [ "kind", "lineRef", "adjustmentMode", "quantity" ], "additionalProperties": false }, { "type": "object", "properties": { "kind": { "const": "original_line" }, "lineRef": { "type": "string", "minLength": 1 }, "adjustmentMode": { "const": "amount" }, "amount": { "type": "number", "exclusiveMinimum": 0 } }, "required": [ "kind", "lineRef", "adjustmentMode", "amount" ], "additionalProperties": false }, { "type": "object", "properties": { "kind": { "const": "custom" }, "description": { "type": "string", "minLength": 1 }, "quantity": { "type": "number", "exclusiveMinimum": 0 }, "amount": { "type": "number", "exclusiveMinimum": 0 }, "productKey": { "type": "string", "minLength": 1 }, "unitKey": { "type": "string", "minLength": 1 }, "taxability": { "enum": [ "standard", "zero", "exempt" ] }, "taxRate": { "type": "number", "minimum": 0, "maximum": 1 }, "taxIncluded": { "type": "boolean" } }, "required": [ "kind", "description", "quantity", "amount", "productKey", "unitKey", "taxability", "taxRate", "taxIncluded" ], "additionalProperties": false } ] } }, "note": { "type": "string" }, "documentRef": { "type": "string", "pattern": "^sales_receipt:.+$" } }, "required": [ "amount", "reason", "settlementMethod", "documentRef" ], "additionalProperties": false } }, "required": [ "idempotencyKey", "input" ], "$schema": "http://json-schema.org/draft-07/schema#", "additionalProperties": false}Output schema
JSON Schema{ "type": "object", "properties": { "data": { "type": "object", "properties": { "documentRef": { "type": "string", "pattern": "^sales_receipt_refund:.+$" }, "status": { "enum": [ "pending", "processing", "completed", "failed", "recovery_required", "canceled" ] } }, "required": [ "documentRef", "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" ] } ]}