Sign in
Invoices

Update Invoice

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

Creating new clients or items along with the invoice

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.

put/{invoices-type}/{document-id}.json

Path parameters

invoices-type'invoices' | 'invoice_receipts' | 'simplified_invoices' | 'credit_notes' | 'debit_notes' required

The type of the invoice document.

document-idinteger required
Example:1050

The ID of the document.

Query parameters

api_keystring required
Example:YOUR_API_KEY

Your API Key.

Request body

Example request

{
  "invoice": {
    "date": "22/11/2025",
    "due_date": "22/12/2025",
    "reference": "PO-999",
    "observations": "Services rendered",
    "retention": "0",
    "tax_exemption": "M00",
    "sequence_id": "123456",
    "client": {
      "id": 1310176,
      "name": "Client A",
      "code": "CLI-001",
      "email": "client@mail.com",
      "address": "Street A",
      "city": "Lisbon",
      "postal_code": "1000-100",
      "fiscal_id": "500999888",
      "country": "Portugal",
      "website": "www.client-a.com",
      "phone": "912345678",
      "fax": "212345678",
      "observations": "VIP Client"
    },
    "items": [
      {
        "name": "Consulting",
        "description": "IT Services",
        "unit_price": 50,
        "quantity": 2,
        "unit": "hour",
        "tax": {
          "name": "IVA23"
        }
      }
    ],
    "mb_reference": "1",
    "owner_invoice_id": 1049,
    "tax_exemption_reason": "M00",
    "currency_code": "USD",
    "rate": "1.10",
    "plugin_id": "plugin_123",
    "global_discount": {
      "value_type": "percentage",
      "value": 10
    }
  }
}

Response

SUCCESS

Possible values for field atcud:

  • ABCD1234-1 (or similar) - Unique document identifier to the Tax Authority, when the sequence is registered.
  • N/D - The document's sequence is relevant for ATCUD but is not registered in the Tax Authority.
  • N/A - The document's sequence is not relevant for ATCUD and is not registered in the Tax Authority.

Response wrapper key

The parent key shown in the example below as invoice is only an example — it always matches the singular of the requested {invoices-type} path parameter: invoice for invoices, invoice_receipt for invoice_receipts, simplified_invoice for simplified_invoices, credit_note for credit_notes, and debit_note for debit_notes. The nested object shape is identical in every case.

Example response

{
  "invoice": {
    "id": 2137287,
    "status": "final",
    "type": "Invoice",
    "sequence_number": "6/G",
    "inverted_sequence_number": "G/6",
    "atcud": "ABCD1234-6",
    "sequence_id": 12345,
    "tax_exemption": "M01",
    "date": "04/08/2016",
    "due_date": "19/08/2016",
    "reference": "ref123",
    "observations": "Observations",
    "cancel_reason": "API test cancellation",
    "permalink": "https://web.invoicexpress.com/documents/...",
    "saft_hash": "J4ay",
    "sum": 24.39,
    "before_taxes": 24.39,
    "taxes": 5.61,
    "total": 30,
    "currency": "Euro",
    "client": {
      "id": 628535,
      "name": "John Doe",
      "code": "C1",
      "country": "Portugal",
      "email": "john@example.com"
    },
    "items": [
      {
        "name": "Product A",
        "description": "Big Product",
        "unit_price": "100.0",
        "quantity": "1.0",
        "unit": "un",
        "tax": {
          "id": 756700,
          "name": "IVA23",
          "value": 23
        },
        "subtotal": 100,
        "tax_amount": 23,
        "total": 123
      }
    ],
    "mb_reference": {
      "entity": "10611",
      "reference": "123 456 789",
      "value": 123.45
    }
  }
}

Changes