---
updatedAt: 2026-04-24T16:39:54.000Z
agentTools:
  projectIndex: https://developers.cloudbeds.com/llms.txt
---

# Update a fiscal document by id

Update a fiscal document status, government integration details, or failure reason.
Used by integration partners to update document lifecycle and government processing status.

**Common Updates:**
- Update status (PENDING_INTEGRATION, COMPLETED_INTEGRATION, FAILED, etc.)
- Set government integration details (series, number, external ID, QR codes)
- Record failure reasons for failed integrations

**Invoice Cancellation:**
- Set status to CANCEL_REQUESTED to cancel invoices
- Only invoices in OPEN, PAID, PARTIALLY_PAID or CORRECTION_NEEDED status can be canceled
- Invoices with rectifying documents cannot be canceled
- Integration partners must handle CANCEL_REQUESTED and update to CANCELED (success) or revert to previous status (failure)
- For a fiscalized Mexico invoice (CFDI tipo I), provide `reason` as SAT motivo "02" or "03"; it defaults to "03"
- For a Mexico invoice fiscalized through Fonoa, the service sends the cancellation to SAT itself: the invoice
  stays CANCEL_REQUESTED until SAT's verdict, then becomes CANCELED or returns to its previous status, and
  setting CANCELED manually is rejected
- Such an invoice cannot be canceled while it has active payment complements or credit notes


# OpenAPI definition

```json
{
  "openapi": "3.0.1",
  "info": {
    "title": "Fiscal document service API",
    "version": "v1"
  },
  "servers": [
    {
      "url": "https://api.cloudbeds.com"
    }
  ],
  "paths": {
    "/fiscal-document/v1/fiscal-documents/{id}": {
      "put": {
        "summary": "Update a fiscal document by id",
        "description": "Update a fiscal document status, government integration details, or failure reason.\nUsed by integration partners to update document lifecycle and government processing status.\n\n**Common Updates:**\n- Update status (PENDING_INTEGRATION, COMPLETED_INTEGRATION, FAILED, etc.)\n- Set government integration details (series, number, external ID, QR codes)\n- Record failure reasons for failed integrations\n\n**Invoice Cancellation:**\n- Set status to CANCEL_REQUESTED to cancel invoices\n- Only invoices in OPEN, PAID, PARTIALLY_PAID or CORRECTION_NEEDED status can be canceled\n- Invoices with rectifying documents cannot be canceled\n- Integration partners must handle CANCEL_REQUESTED and update to CANCELED (success) or revert to previous status (failure)\n- For a fiscalized Mexico invoice (CFDI tipo I), provide `reason` as SAT motivo \"02\" or \"03\"; it defaults to \"03\"\n- For a Mexico invoice fiscalized through Fonoa, the service sends the cancellation to SAT itself: the invoice\n  stays CANCEL_REQUESTED until SAT's verdict, then becomes CANCELED or returns to its previous status, and\n  setting CANCELED manually is rejected\n- Such an invoice cannot be canceled while it has active payment complements or credit notes\n",
        "operationId": "putFiscalDocument",
        "security": [
          {
            "bearerAuth": []
          },
          {
            "oauth2": [
              "write:reservation"
            ]
          }
        ],
        "tags": [
          "Fiscal Documents"
        ],
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "description": "Unique ID of the fiscal document to download.",
            "schema": {
              "type": "integer",
              "format": "int64",
              "minimum": 1
            }
          },
          {
            "$ref": "#/components/parameters/propertyIdHeader"
          }
        ],
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/FiscalDocumentPatchRequest"
              }
            }
          },
          "required": true
        },
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/FiscalDocumentSummaryResponse"
                }
              }
            }
          }
        }
      }
    }
  },
  "components": {
    "securitySchemes": {
      "bearerAuth": {
        "type": "http",
        "scheme": "bearer",
        "bearerFormat": "JWT"
      },
      "oauth2": {
        "type": "oauth2",
        "flows": {
          "authorizationCode": {
            "authorizationUrl": "https://api.cloudbeds.com/auth/oauth/authorize",
            "tokenUrl": "https://api.cloudbeds.com/auth/oauth/token",
            "scopes": {
              "read:reservation": "Read fiscal documents and fiscalization configuration",
              "write:reservation": "Create, update, or void fiscal documents and fiscalization configuration"
            }
          }
        }
      }
    },
    "parameters": {
      "propertyIdHeader": {
        "name": "X-Property-ID",
        "in": "header",
        "required": true,
        "schema": {
          "type": "integer",
          "format": "int64",
          "minimum": 1
        },
        "description": "Property id"
      }
    },
    "schemas": {
      "FiscalDocumentSummaryResponse": {
        "type": "object",
        "properties": {
          "id": {
            "type": "string"
          },
          "kind": {
            "$ref": "#/components/schemas/FiscalDocumentKind"
          },
          "status": {
            "$ref": "#/components/schemas/FiscalDocumentStatus"
          },
          "governmentIntegration": {
            "$ref": "#/components/schemas/GovernmentIntegration"
          },
          "linkedTo": {
            "type": "string"
          }
        }
      },
      "FiscalDocumentPatchRequest": {
        "type": "object",
        "properties": {
          "status": {
            "$ref": "#/components/schemas/FiscalDocumentStatus"
          },
          "reason": {
            "type": "string",
            "description": "SAT cancellation motive when cancelling a fiscalized Mexico invoice (CFDI tipo I): \"02\" (issued with errors, no substitute) or \"03\" (operation not carried out). Defaults to \"03\" when omitted and is ignored elsewhere.\n"
          },
          "failReason": {
            "type": "string"
          },
          "governmentIntegration": {
            "$ref": "#/components/schemas/GovernmentIntegration"
          }
        }
      },
      "GovernmentIntegration": {
        "type": "object",
        "properties": {
          "number": {
            "type": "string"
          },
          "series": {
            "type": "string"
          },
          "invoiceType": {
            "type": "string",
            "nullable": true,
            "description": "AR ARCA invoice class (A/B/C/T) for this document, used to disambiguate documents that share series + number across classes. Null for non-AR documents.\n"
          },
          "status": {
            "type": "string"
          },
          "qr": {
            "type": "object",
            "properties": {
              "url": {
                "type": "string",
                "format": "uri"
              },
              "string": {
                "type": "string"
              }
            }
          },
          "url": {
            "type": "string",
            "format": "uri"
          },
          "officialId": {
            "type": "string"
          },
          "externalId": {
            "type": "string"
          },
          "rectifyingInvoiceType": {
            "type": "string"
          },
          "cancellationFailedFallbackStatus": {
            "$ref": "#/components/schemas/FiscalDocumentStatus"
          },
          "cancellationStatus": {
            "type": "string",
            "readOnly": true,
            "enum": [
              "PENDING",
              "CANCELLED",
              "FAILED"
            ],
            "description": "Outcome of the latest cancellation request sent to the tax authority."
          },
          "pdfFileBase64": {
            "type": "string",
            "format": "byte",
            "description": "Base64-encoded PDF file content. Only allowed when status is COMPLETED_INTEGRATION."
          },
          "handwritten": {
            "type": "boolean",
            "description": "Indicates this is a handwritten receipt created during POS unavailability."
          },
          "signatures": {
            "type": "array",
            "description": "Array of semantic signatures/response data from the government integration.",
            "items": {
              "$ref": "#/components/schemas/IntegrationSignature"
            }
          },
          "folioFiscal": {
            "type": "string",
            "description": "MX SAT UUID (Folio Fiscal) — populated after CFDI acceptance by Fonoa.",
            "example": "9B3E26F4-1234-4A5B-8C9D-ABCDEF012345"
          },
          "satQrCode": {
            "type": "string",
            "description": "MX SAT validation URL used to verify a CFDI at verificacfdi.facturaelectronica.sat.gob.mx."
          },
          "ext": {
            "type": "object",
            "readOnly": true,
            "additionalProperties": {
              "type": "string"
            },
            "description": "Provider-returned extension values for the document, keyed by extension or stamp code (e.g. AR \"ar-arca-doc-type\", and \"arca-cae-expiry\" for the CAE expiry date as YYYY-MM-DD; the CAE itself is in officialId). Read-only.\n",
            "example": {
              "ar-arca-doc-type": "6",
              "arca-cae-expiry": "2026-10-02"
            }
          },
          "connectionId": {
            "type": "integer",
            "format": "int64",
            "readOnly": true,
            "description": "The fiscalization connection this document was dispatched through; its provider and channel are those of the connection. Read-only — a partner reporting an outcome cannot change where the document was routed, and uses this to confirm the document was addressed to it before acting on it.\n"
          }
        }
      },
      "IntegrationSignature": {
        "type": "object",
        "description": "A semantic signature/response item from a government integration.",
        "properties": {
          "type": {
            "type": "string",
            "description": "Semantic type (JWT_TOKEN, QR_CODE_DATA, TRANSACTION_ID, COMPLIANCE_CHECK, etc.)"
          },
          "label": {
            "type": "string",
            "description": "Human-readable display label."
          },
          "value": {
            "type": "string",
            "description": "The actual signature data/value."
          },
          "format": {
            "type": "string",
            "description": "Format of the value.",
            "enum": [
              "TEXT",
              "BASE64",
              "HEX",
              "URL",
              "UNKNOWN"
            ]
          },
          "source": {
            "type": "string",
            "description": "Source integration (FISKALTRUST_FR, FISKALTRUST_IT, etc.)"
          },
          "rawMetadata": {
            "type": "object",
            "additionalProperties": {
              "type": "string"
            },
            "description": "Original integration-specific codes for debugging/auditing."
          }
        }
      },
      "FiscalDocumentStatus": {
        "type": "string",
        "description": "Status of the fiscal document",
        "enum": [
          "COMPLETED",
          "VOIDED",
          "PAID",
          "PENDING_INTEGRATION",
          "PARTIALLY_PAID",
          "COMPLETED_INTEGRATION",
          "FAILED_INTEGRATION",
          "CORRECTION_NEEDED",
          "CANCELED",
          "CANCEL_REQUESTED",
          "OPEN",
          "REQUESTED",
          "VOID_REQUESTED",
          "FAILED",
          "MANUALLY_RECONCILED",
          "REJECTED",
          "ACCEPTED",
          "PENDING_TRANSACTION",
          "ALLOCATED",
          "APPLIED"
        ]
      },
      "FiscalDocumentKind": {
        "type": "string",
        "description": "Kind of fiscal document",
        "enum": [
          "INVOICE",
          "CREDIT_NOTE",
          "RECEIPT",
          "RECTIFY_INVOICE",
          "PRO_FORMA_INVOICE",
          "REFUND_RECEIPT",
          "INVOICE_RECEIPT",
          "ADVANCE_INVOICE",
          "SETTLEMENT_INVOICE",
          "TAX_WITHHOLDING"
        ]
      }
    }
  }
}
```