---
title: "Create a fiscal document of the type invoice"
method: POST
path: "/fiscal-document/v1/fiscal-documents/invoice"
tags: ["Fiscal Documents"]
---

# Create a fiscal document of the type invoice

`POST /fiscal-document/v1/fiscal-documents/invoice`

## Request

- Base URL: `https://api.cloudbeds.com`
- URL: `https://api.cloudbeds.com/fiscal-document/v1/fiscal-documents/invoice`
- Auth: one of:
  - HTTP bearer
  - OAuth 2
    - Authorization code: `https://api.cloudbeds.com/auth/oauth/authorize`
    - Token URL: `https://api.cloudbeds.com/auth/oauth/token` scopes: `write:reservation`

Create a fiscal document of the type invoice.

## Headers

- `X-Property-ID` integer, required

## Request body

- CreateInvoiceRequest
  - `transactionIds` integer[], required: Include transactions with the specified IDs (deprecated, use `includeTransactionIds` instead)
  - `transactionIdToAmount` object, nullable: Map of transaction ID to amount (in major currency units, e.g., 10.50 for $10.50) for partial transaction inclusion
  - `transactionIdToDisplayAmount` object, nullable: Map of transaction ID to amount in the invoice currency (major units, as in displayAmount) for partial transaction inclusion, recorded on the document exactly as given. Takes precedence over transactionIdToAmount for the same transaction. When the invoice currency is the property currency it behaves like transactionIdToAmount.
  - `sourceId` integer, required
  - `sequenceId` integer, nullable
  - `sourceKind` 'GROUP_PROFILE' | 'RESERVATION' | 'HOUSE_ACCOUNT' | 'ACCOUNTS_RECEIVABLE_LEDGER', required: Kind of the source entity
  - `userId` integer, nullable: Ignored. The document is attributed to the authenticated user.
  - `currency` string, nullable: Invoice currency. Selected transactions are converted into this currency at creation using the property's current exchange rate, which is locked on the issued document, and the converted amounts are fiscalized. Defaults to the property currency when omitted.
  - `recipient` RecipientRequest
    - `type` 'GUEST' | 'CONTACT' | 'GROUP' | 'COMPANY' | 'GROUP_PROFILE' | 'GROUP_PROFILE_CONTACT', required: Type of the recipient.
    - `id` integer, required: ID of the recipient, references guestId, contactId, groupId, etc. depending on type.
    - `taxDocumentSource` 'GUEST_TAX_ID' | 'GUEST_DOCUMENT_NUMBER': Source of the tax document number.
  - `manualRecipient` ManualRecipientRequest
    - `type` 'PERSON' | 'COMPANY', required: Type of recipient (person or company)
    - `name` string, required: Name of the recipient
    - `gender` 'M' | 'F' | 'N/A': Gender of the guest
    - `email` string, email, nullable: Email address of the recipient
    - `birthday` string, date, nullable: Birthday of the recipient
    - `phone` string, nullable: Phone number
    - `cellPhone` string, nullable: Cell phone number
    - `taxId` string, required: Tax ID / VAT number
    - `address` object, nullable
      - `country` string, nullable: Country code
      - `state` string, nullable: State or province
      - `city` string, nullable: City
      - `address1` string, nullable: Primary street address
      - `address2` string, nullable: Secondary street address
      - `zip` string, nullable: Zip/postal code
    - `document` object, nullable
      - `type` 'na' | 'driver_licence' | 'student_id' | 'passport' | 'dni' | 'nie': Type of guest identification document
      - `number` string, nullable: Document number
      - `issueDate` string, date, nullable: Document issue date
      - `issuingCountry` string, nullable: Country that issued the document
      - `expirationDate` string, date, nullable: Document expiration date
    - `countryData` object, nullable: Country-specific recipient fields collected from country requirements (e.g. Argentina "ar_iva_condition"), stored on the recipient's countryData.
  - `folioIds` integer[]: Include all transactions from the specified folio IDs
  - `excludeTransactionIds` integer[]: Exclude transactions with the specified IDs
  - `includeTransactionIds` integer[]: Include only the transactions with these IDs. With folioIds they are added on top of the folios' transactions instead. Empty or omitted means every not-yet-invoiced transaction of the source (or of folioIds when given) minus excludeTransactionIds, payments included and pending transactions only when the property allows them. Transactions listed in transactionIdToAmount are added automatically. Ignored when the deprecated transactionIds is set.
  - `simplified` boolean
  - `invoiceType` 'A' | 'B' | 'T', nullable: Argentina RI only — the ARCA invoice class to issue (Factura A/B/T). Determines the ar-arca-doc-type sent to ARCA and the Punto de Venta series used. Ignored for non-RI / non-AR properties (those always issue C).
  - `packageBreakdown` boolean, nullable: Per-document override for package breakdown. Null means use property default.
  - `lineGroupingSelection` LineGroupingSelectionRequest: Per-document grouping chosen in the create modal. Each omitted field keeps the property default. lineGrouping and posGrouping must be inside the property allowed set; otherwise the request is rejected. groupByRoom and groupByBusinessDate are free per-document modifiers: the property has no allowed set for them, only a default. Locked on the document once created.
    - `lineGrouping` 'NONE' | 'TRANSACTION' | 'RATE_PLAN_SHOW_ADDONS' | 'RATE_PLAN_HIDE_ADDONS'
    - `posGrouping` 'NONE' | 'CHECK_NUMBER'
    - `groupByRoom` boolean, nullable
    - `groupByBusinessDate` boolean, nullable
  - `dueDatePropertyTimezone` string, date
  - `note` string, nullable
  - `emails` string[], nullable: Optional list of email addresses to send the document to once it is ready
  - `subject` string, nullable: Optional per-send override for the email subject. When omitted or blank, the subject is resolved from the property's email template, falling back to the service default. Supports the same [Placeholder] tokens as template subjects.
  - `summary` boolean, nullable: When true, marks this as a CFDI global/summary invoice (MX only)
  - `summaryFrequency` 'DAILY' | 'WEEKLY' | 'BIWEEKLY' | 'MONTHLY' | 'BIMONTHLY', nullable: Reporting frequency for summary invoices (MX only)
  - `mxCfdiUse` string, nullable: MX only — SAT c_UsoCFDI code selected in the Create Invoice modal. Overrides the value stored in guest requirements (mx_cfdi_use). A generic RFC (XAXX/XEXX) always forces S01 at issuance time regardless of this value.

## Response `200`

OK

- FiscalDocumentSummaryResponse
  - `id` string
  - `kind` 'INVOICE' | 'CREDIT_NOTE' | 'RECEIPT' | 'RECTIFY_INVOICE' | 'PRO_FORMA_INVOICE' | 'REFUND_RECEIPT' | 'INVOICE_RECEIPT' | 'ADVANCE_INVOICE' | 'SETTLEMENT_INVOICE' | 'TAX_WITHHOLDING': Kind of fiscal document
  - `status` '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': Status of the fiscal document
  - `governmentIntegration` GovernmentIntegration
    - `number` string
    - `series` string
    - `invoiceType` string, nullable: 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.
    - `status` string
    - `qr` object
      - `url` string, uri
      - `string` string
    - `url` string, uri
    - `officialId` string
    - `externalId` string
    - `rectifyingInvoiceType` string
    - `cancellationFailedFallbackStatus` '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': Status of the fiscal document
    - `cancellationStatus` 'PENDING' | 'CANCELLED' | 'FAILED': Outcome of the latest cancellation request sent to the tax authority.
    - `pdfFileBase64` string, byte: Base64-encoded PDF file content. Only allowed when status is COMPLETED_INTEGRATION.
    - `handwritten` boolean: Indicates this is a handwritten receipt created during POS unavailability.
    - `signatures` IntegrationSignature[]: Array of semantic signatures/response data from the government integration.
      - `type` string: Semantic type (JWT_TOKEN, QR_CODE_DATA, TRANSACTION_ID, COMPLIANCE_CHECK, etc.)
      - `label` string: Human-readable display label.
      - `value` string: The actual signature data/value.
      - `format` 'TEXT' | 'BASE64' | 'HEX' | 'URL' | 'UNKNOWN': Format of the value.
      - `source` string: Source integration (FISKALTRUST_FR, FISKALTRUST_IT, etc.)
      - `rawMetadata` object: Original integration-specific codes for debugging/auditing.
    - `folioFiscal` string: MX SAT UUID (Folio Fiscal) — populated after CFDI acceptance by Fonoa.
    - `satQrCode` string: MX SAT validation URL used to verify a CFDI at verificacfdi.facturaelectronica.sat.gob.mx.
    - `ext` object: 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.
    - `connectionId` integer: 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.
  - `linkedTo` string

---

[API](https://skmtc.dev/cloudbeds/apis/fiscal-document-service-api.md) - [All operations](https://skmtc.dev/cloudbeds/apis/fiscal-document-service-api/llms.txt) - [OpenAPI document](https://skmtc.dev/cloudbeds/apis/fiscal-document-service-api/revisions/9c2a47775e5e?raw)