# Create Invoice

Creates a new invoice, simplified_invoice, invoice_receipt, credit_note or debit_note.

### Idempotency
Send a proprietary_uid (at the top level or inside the root object) to make the request safe to retry:
* If a document with that proprietary_uid was already created, the API returns 201 with the original document instead of creating a new one.
* If another request with the same proprietary_uid is still being saved, the API returns 422 with This document is being saved by another request. Please try again.

English text shown; the message follows the account language.



### Creating new clients or items along with the documents
This method also allows to create a new client and/or new items in the same request with the following behavior:
* If the client name does not exist, a new one is created.
* If items do not exist with the given names, new ones will be created.
* If item name already exists, the item is updated with the new values.

### Taxes
Regarding item taxes, if the tax name is not found, the default tax is applyed to that item. Portuguese accounts should also send the IVA exemption reason if the invoice contains exempt items (IVA 0%).

> Note: Simplified Invoices are only available in Portugal.

Endpoint: POST /{invoices-type}.json
Version: 2.0.0
Security: apiKeyAuth

## Query parameters:

  - `api_key` (string, required)
    Your API Key.
    Example: "YOUR_API_KEY"

## Path parameters:

  - `invoices-type` (string, required)
    The type of the invoice document.
    Enum: "invoices", "invoice_receipts", "simplified_invoices", "credit_notes", "debit_notes"

## Request fields (application/json):

  - `invoice` (object, required)
    Invoice Body. The root key can be invoice or the singular of the requested {invoices-type} (invoice_receipt, simplified_invoice, credit_note, debit_note).

  - `invoice.date` (string, required)
    dd/mm/yyyy
    Example: "22/11/2025"

  - `invoice.due_date` (string)
    dd/mm/yyyy. Defaults to date when omitted.
    Example: "22/12/2025"

  - `invoice.reference` (string)
    Example: "PO-999"

  - `invoice.observations` (string)
    No enforced character limit.
    Example: "Services rendered"

  - `invoice.retention` (string)
    Example: "0"

  - `invoice.tax_exemption` (string)
    Maximum length is the database default, not a business rule — the value is effectively an AT exemption code.
    Example: "M00"

  - `invoice.sequence_id` (string)
    Example: "123456"

  - `invoice.manual_sequence_number` (string)
    Maximum length is the database default, not a business rule.

  - `invoice.client` (object)
    Client Details. To identify an existing client, send id, code, or name — not all three are required. Resolution priority: if id is sent and matches a client on the account, that client is used and name/code are ignored. Without id, if code matches an existing client, that client is used and name is not needed. Without an id/code match, name is used to find or create the client. Creating a brand-new client (no id/code match) still requires name; code is always optional and is never generated automatically by InvoiceXpress.

  - `invoice.client.id` (integer)
    Internal client ID. Preferred way to identify an existing client — see schema description.
    Example: 1310176

  - `invoice.client.name` (string)
    Example: "Client A"

  - `invoice.client.code` (string)
    Maximum length is the database default, not a business rule.
    Example: "CLI-001"

  - `invoice.client.email` (string)
    Example: "client@mail.com"

  - `invoice.client.address` (string)
    No enforced character limit.
    Example: "Street A"

  - `invoice.client.city` (string)
    Maximum length is the database default, not a business rule.
    Example: "Lisbon"

  - `invoice.client.postal_code` (string)
    Maximum length is the database default, not a business rule.
    Example: "1000-100"

  - `invoice.client.fiscal_id` (string)
    Maximum length is the database default, not a business rule.
    Example: "500999888"

  - `invoice.client.country` (string)
    Maximum length is the database default, not a business rule.
    Example: "Portugal"

  - `invoice.client.website` (string)
    Example: "www.client-a.com"

  - `invoice.client.phone` (string)
    Example: "912345678"

  - `invoice.client.fax` (string)
    Example: "212345678"

  - `invoice.items` (array, required)

  - `invoice.items.name` (string, required)
    Maximum 60 characters. The V2 API silently truncates longer values to 60; the V3 API rejects them with 422.
    Example: "Consulting"

  - `invoice.items.description` (string)
    Maximum 200 characters and 20 lines. The V2 API silently truncates longer values to 200; the V3 API rejects them with 422.
    Example: "IT Services"

  - `invoice.items.unit_price` (number, required)
    Example: 50

  - `invoice.items.quantity` (number, required)
    Example: 2

  - `invoice.items.unit` (string)
    Not a length limit — constrained to a fixed set of unit values.
    Example: "hour"

  - `invoice.items.discount` (number)

  - `invoice.items.tax` (object)

  - `invoice.items.tax.name` (string)
    Maximum length is the database default, not a business rule.
    Example: "IVA23"

  - `invoice.items.tax.value` (number)
    Tax rate (%). Alternative to name.
    Example: 23

  - `invoice.items.retention` (number)
    Item retention rate (%).
    Example: 25

  - `invoice.mb_reference` (string)
    Enum: "0", "1"

  - `invoice.owner_invoice_id` (integer)
    Example: 1049

  - `invoice.tax_exemption_reason` (string)
    Maximum 210 characters. Enforced by model validation — longer values are rejected with 422 even though the underlying column would accept more.
    Example: "M00"

  - `invoice.currency_code` (string)
    Example: "USD"

  - `invoice.rate` (string)
    Example: "1.10"

  - `invoice.plugin_id` (string)
    Example: "plugin_123"

  - `invoice.global_discount` (object)

  - `invoice.global_discount.value_type` (string)
    Enum: "percentage", "absolute"

  - `invoice.global_discount.value` (number)
    Example: 10

  - `invoice.proprietary_uid` (string)
    Idempotency key, same as the top-level proprietary_uid.
    Example: "uuid-123"

  - `invoice.tax_exemption_code` (string)
    Tax exemption code.
    Example: "M07"

  - `invoice.tax_exemption_message` (string)
    Tax exemption message.
    Example: "Isento artigo 9.º do CIVA"

  - `invoice.discount` (number)
    Document discount.

  - `invoice.raw_owner_invoice` (any)
    Credit and debit notes only. Reference to an original document issued outside InvoiceXpress. Send a string, or an object with document_type, document_serie and document_number. Cannot be combined with owner_invoice_id.

  - `proprietary_uid` (string)
    Idempotency key. Can also be sent inside the root object.
    Example: "uuid-123"

## Response 201 fields (application/json):

  - `invoice` (object)

  - `invoice.id` (integer)
    Example: 2137287

  - `invoice.status` (string)
    Example: "final"

  - `invoice.archived` (boolean)

  - `invoice.type` (string)
    Example: "Invoice"

  - `invoice.sequence_number` (string)
    Example: "6/G"

  - `invoice.inverted_sequence_number` (string)
    Example: "G/6"

  - `invoice.atcud` (string)
    Example: "ABCD1234-6"

  - `invoice.sequence_id` (integer,null)
    Example: 12345

  - `invoice.tax_exemption` (string)
    Example: "M01"

  - `invoice.date` (string)
    Example: "04/08/2016"

  - `invoice.due_date` (string)
    Example: "19/08/2016"

  - `invoice.reference` (string,null)
    Example: "ref123"

  - `invoice.observations` (string,null)
    No enforced character limit (text column).
    Example: "Observations"

  - `invoice.retention` (string,null)

  - `invoice.cancel_reason` (string,null)
    Present after the document has been canceled. No enforced character limit (text column).
    Example: "API test cancellation"

  - `invoice.permalink` (string)
    Example: "https://web.invoicexpress.com/documents/..."

  - `invoice.saft_hash` (string)
    Server-generated. No enforced character limit (text column).
    Example: "J4ay"

  - `invoice.sum` (number)
    Example: 24.39

  - `invoice.discount` (number,null)

  - `invoice.before_taxes` (number)
    Example: 24.39

  - `invoice.taxes` (number)
    Example: 5.61

  - `invoice.total` (number)
    Example: 30

  - `invoice.currency` (string)
    Example: "Euro"

  - `invoice.client` (object)
    id and name are always present. The other fields are only returned when they have a value.

  - `invoice.client.name` (string)
    Example: "John Doe"

  - `invoice.client.code` (string)
    Example: "C1"

  - `invoice.client.country` (string)
    Example: "Portugal"

  - `invoice.client.email` (string)
    Example: "john@example.com"

  - `invoice.client.address` (string)
    Example: "Avenida da República"

  - `invoice.client.postal_code` (string)
    Example: "1050-555"

  - `invoice.client.city` (string)
    Example: "Lisboa"

  - `invoice.client.fiscal_id` (string)
    Example: "508025338"

  - `invoice.client.website` (string)
    Example: "www.example.com"

  - `invoice.client.phone` (string)
    Example: "910000000"

  - `invoice.client.fax` (string)
    Example: "210000000"

  - `invoice.client.observations` (string)
    Example: "VIP client"

  - `invoice.items` (array)

  - `invoice.items.description` (string,null)
    Example: "Big Product"

  - `invoice.items.unit_price` (string)
    Example: "100.0"

  - `invoice.items.quantity` (string)
    Example: "1.0"

  - `invoice.items.unit` (string)
    Example: "un"

  - `invoice.items.tax` (object)

  - `invoice.items.tax.value` (number)
    Example: 23

  - `invoice.items.subtotal` (number)
    Example: 100

  - `invoice.items.tax_amount` (number)
    Example: 23

  - `invoice.items.discount_amount` (number)

  - `invoice.mb_reference` (object)

  - `invoice.mb_reference.entity` (string)
    Example: "10611"

## Response 401 fields (application/json):

  - `errors` (array)

  - `errors.error` (string)
    Example: "Authentication Error"

## Response 422 fields (application/json):

  - `errors` (array)
    Example: [{"error":"Date can't be blank"},{"error":"This document is being saved by another request. Please try again."}]

  - `errors.error` (string)