Skip to content

InvoiceXpress API (2.0.0)

Endpoints for managing Accounts, Invoices, Estimates, and organization data in InvoiceXpress.

Download OpenAPI description
Overview
InvoiceXpress API Support
Languages
Servers
Mock server
https://docs.invoicexpress.com/_mock/
Production Server
https://{account_name}.app.invoicexpress.com/

Accounts

Create, update and get info about your account.

Operations

Invoices

Create invoices, invoice receipts, simplified invoices, vat moss invoices, credit notes & debit notes and send them to your clients.

Operations

List All

Request

Returns a list of invoices.

Security
apiKeyAuth
Query
api_keystringrequired

Your API Key.

Example: api_key=YOUR_API_KEY
Query Parametersobject(QueryParamns)

Click to expand options.

curl -i -X GET \
  'https://docs.invoicexpress.com/_mock/invoices.json?api_key=YOUR_API_KEY%2CYOUR_API_KEY_HERE&type%5B%5D=Invoice&status%5B%5D=sent&non_archived=true&archived=true&text=string&reference=string&date%5Bfrom%5D=string&date%5Bto%5D=string&due_date%5Bfrom%5D=string&due_date%5Bto%5D=string&total_before_taxes%5Bfrom%5D=0&total_before_taxes%5Bto%5D=0&page=0&per_page=0'

Responses

SUCCESS

Creates a new quote, proforma or fees_note.

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.
Bodyapplication/json
invoicesArray of objects
paginationobject(Pagination)
Response
application/json
{ "invoices": [ {} ], "pagination": { "total_entries": 50, "per_page": 20, "current_page": 1, "total_pages": 3 } }

Create Invoice

Request

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

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.

Security
apiKeyAuth
Path
invoices-typestringrequired

The type of the invoice document.

Enum"invoices""invoice_receipts""simplified_invoices""credit_notes""debit_notes"
Query
api_keystringrequired

Your API Key.

Example: api_key=YOUR_API_KEY
Bodyapplication/jsonrequired
invoiceobject(CreateBody)required

Invoice Body

invoice.​datestringrequired

dd/mm/yyyy

Example: "22/11/2025"
invoice.​due_datestringrequired

dd/mm/yyyy

Example: "22/12/2025"
invoice.​referencestring
Example: "PO-999"
invoice.​observationsstring
Example: "Services rendered"
invoice.​retentionstring
Example: "0"
invoice.​tax_exemptionstring
Example: "M00"
invoice.​sequence_idstring
Example: "123456"
invoice.​manual_sequence_numberstring
invoice.​clientobject(ClientRequest)required

Client Details.

invoice.​client.​namestringrequired
Example: "Client A"
invoice.​client.​codestringrequired
Example: "CLI-001"
invoice.​client.​emailstring
Example: "client@mail.com"
invoice.​client.​addressstring
Example: "Street A"
invoice.​client.​citystring
Example: "Lisbon"
invoice.​client.​postal_codestring
Example: "1000-100"
invoice.​client.​fiscal_idstring
Example: "500999888"
invoice.​client.​countrystring
Example: "Portugal"
invoice.​client.​websitestring
Example: "www.client-a.com"
invoice.​client.​phonestring
Example: "912345678"
invoice.​client.​faxstring
Example: "212345678"
invoice.​client.​observationsstring
Example: "VIP Client"
invoice.​itemsArray of objects(InvoiceItemRequest)required
invoice.​items[].​namestringrequired
Example: "Consulting"
invoice.​items[].​descriptionstringrequired
Example: "IT Services"
invoice.​items[].​unit_pricenumberrequired
Example: 50
invoice.​items[].​quantitynumberrequired
Example: 2
invoice.​items[].​unitstring
Example: "hour"
invoice.​items[].​discountnumber
Example: 0
invoice.​items[].​taxobject(InvoiceTaxRequest)
invoice.​mb_referencestring
Enum"0""1"
Example: "1"
invoice.​owner_invoice_idinteger
Example: 1049
invoice.​tax_exemption_reasonstring
Example: "M00"
invoice.​currency_codestring
Example: "USD"
invoice.​ratestring
Example: "1.10"
invoice.​plugin_idstring
Example: "plugin_123"
invoice.​global_discountobject(GlobalDiscountRequest)
proprietary_uidstring
Example: "uuid-123"
curl -i -X POST \
  'https://docs.invoicexpress.com/_mock/{invoices-type}.json?api_key=YOUR_API_KEY%2CYOUR_API_KEY_HERE' \
  -H 'Content-Type: application/json' \
  -d '{
    "invoice": {
      "date": "22/11/2025",
      "due_date": "22/12/2025",
      "reference": "PO-999",
      "observations": "Services rendered",
      "retention": "0",
      "tax_exemption": "M00",
      "sequence_id": "123456",
      "manual_sequence_number": "string",
      "client": {
        "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",
          "discount": 0,
          "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
      }
    },
    "proprietary_uid": "uuid-123"
  }'

Responses

SUCCESS

Creates a new quote, proforma or fees_note.

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.
Bodyapplication/json
invoiceobject(FullDocumentObject)
Response
application/json
{ "invoice": { "id": 2137287, "status": "final", "archived": false, "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", "retention": "0", "permalink": "https://www.app.invoicexpress.com/documents/...", "saft_hash": "J4ay", "sum": 24.39, "discount": 0, "before_taxes": 24.39, "taxes": 5.61, "total": 30, "currency": "Euro", "client": {}, "items": [], "mb_reference": {} } }

Get Invoice

Request

Security
apiKeyAuth
Path
document-idintegerrequired

The ID of the document.

Example: 1050
invoices-typestringrequired

The type of the invoice document.

Enum"invoices""invoice_receipts""simplified_invoices""credit_notes""debit_notes"
Query
api_keystringrequired

Your API Key.

Example: api_key=YOUR_API_KEY
curl -i -X GET \
  'https://docs.invoicexpress.com/_mock/{invoices-type}/1050.json?api_key=YOUR_API_KEY%2CYOUR_API_KEY_HERE'

Responses

SUCCESS

Creates a new quote, proforma or fees_note.

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.
Bodyapplication/json
invoiceobject(FullDocumentObject)
Response
application/json
{ "invoice": { "id": 2137287, "status": "final", "archived": false, "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", "retention": "0", "permalink": "https://www.app.invoicexpress.com/documents/...", "saft_hash": "J4ay", "sum": 24.39, "discount": 0, "before_taxes": 24.39, "taxes": 5.61, "total": 30, "currency": "Euro", "client": {}, "items": [], "mb_reference": {} } }

Update Invoice

Request

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.

Security
apiKeyAuth
Path
invoices-typestringrequired

The type of the invoice document.

Enum"invoices""invoice_receipts""simplified_invoices""credit_notes""debit_notes"
document-idintegerrequired

The ID of the document.

Example: 1050
Query
api_keystringrequired

Your API Key.

Example: api_key=YOUR_API_KEY
Bodyapplication/jsonrequired
invoiceobject(CreateBody)required

Invoice Body

invoice.​datestringrequired

dd/mm/yyyy

Example: "22/11/2025"
invoice.​due_datestringrequired

dd/mm/yyyy

Example: "22/12/2025"
invoice.​referencestring
Example: "PO-999"
invoice.​observationsstring
Example: "Services rendered"
invoice.​retentionstring
Example: "0"
invoice.​tax_exemptionstring
Example: "M00"
invoice.​sequence_idstring
Example: "123456"
invoice.​manual_sequence_numberstring
invoice.​clientobject(ClientRequest)required

Client Details.

invoice.​client.​namestringrequired
Example: "Client A"
invoice.​client.​codestringrequired
Example: "CLI-001"
invoice.​client.​emailstring
Example: "client@mail.com"
invoice.​client.​addressstring
Example: "Street A"
invoice.​client.​citystring
Example: "Lisbon"
invoice.​client.​postal_codestring
Example: "1000-100"
invoice.​client.​fiscal_idstring
Example: "500999888"
invoice.​client.​countrystring
Example: "Portugal"
invoice.​client.​websitestring
Example: "www.client-a.com"
invoice.​client.​phonestring
Example: "912345678"
invoice.​client.​faxstring
Example: "212345678"
invoice.​client.​observationsstring
Example: "VIP Client"
invoice.​itemsArray of objects(InvoiceItemRequest)required
invoice.​items[].​namestringrequired
Example: "Consulting"
invoice.​items[].​descriptionstringrequired
Example: "IT Services"
invoice.​items[].​unit_pricenumberrequired
Example: 50
invoice.​items[].​quantitynumberrequired
Example: 2
invoice.​items[].​unitstring
Example: "hour"
invoice.​items[].​discountnumber
Example: 0
invoice.​items[].​taxobject(InvoiceTaxRequest)
invoice.​mb_referencestring
Enum"0""1"
Example: "1"
invoice.​owner_invoice_idinteger
Example: 1049
invoice.​tax_exemption_reasonstring
Example: "M00"
invoice.​currency_codestring
Example: "USD"
invoice.​ratestring
Example: "1.10"
invoice.​plugin_idstring
Example: "plugin_123"
invoice.​global_discountobject(GlobalDiscountRequest)
curl -i -X PUT \
  'https://docs.invoicexpress.com/_mock/{invoices-type}/1050.json?api_key=YOUR_API_KEY%2CYOUR_API_KEY_HERE' \
  -H 'Content-Type: application/json' \
  -d '{
    "invoice": {
      "date": "22/11/2025",
      "due_date": "22/12/2025",
      "reference": "PO-999",
      "observations": "Services rendered",
      "retention": "0",
      "tax_exemption": "M00",
      "sequence_id": "123456",
      "manual_sequence_number": "string",
      "client": {
        "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",
          "discount": 0,
          "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
      }
    }
  }'

Responses

SUCCESS

Creates a new quote, proforma or fees_note.

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.
Bodyapplication/json
invoiceobject(FullDocumentObject)
Response
application/json
{ "invoice": { "id": 2137287, "status": "final", "archived": false, "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", "retention": "0", "permalink": "https://www.app.invoicexpress.com/documents/...", "saft_hash": "J4ay", "sum": 24.39, "discount": 0, "before_taxes": 24.39, "taxes": 5.61, "total": 30, "currency": "Euro", "client": {}, "items": [], "mb_reference": {} } }

Change Invoice State

Request

Changes the state of invoice documents.

FromToState on Request BodyNotes
draftfinalfinalizedAll documents.
draftsettledfinalizedOnly invoice_receipt.
draftdeleteddeletedAll documents.
finalcanceledcanceledAll documents.
settledcanceledcanceledOnly invoice_receipt.
finalsettledsettledAll documents.
settledfinalunsettledOnly credit_note and debit_note.
Security
apiKeyAuth
Path
invoices-typestringrequired

The type of the invoice document.

Enum"invoices""invoice_receipts""simplified_invoices""credit_notes""debit_notes"
document-idintegerrequired

The ID of the document.

Example: 1050
Query
api_keystringrequired

Your API Key.

Example: api_key=YOUR_API_KEY
Bodyapplication/jsonrequired
invoiceobjectrequired
invoice.​statestringrequired
Enum"finalized""canceled""deleted""accepted""refused""settled"
Example: "finalized"
invoice.​messagestring
Example: "Wrong value"
curl -i -X PUT \
  'https://docs.invoicexpress.com/_mock/{invoices-type}/1050/change-state.json?api_key=YOUR_API_KEY%2CYOUR_API_KEY_HERE' \
  -H 'Content-Type: application/json' \
  -d '{
    "invoice": {
      "state": "finalized",
      "message": "Wrong value"
    }
  }'

Responses

SUCCESS

Creates a new quote, proforma or fees_note.

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.
Bodyapplication/json
invoiceobject(FullDocumentObject)
Response
application/json
{ "invoice": { "id": 2137287, "status": "final", "archived": false, "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", "retention": "0", "permalink": "https://www.app.invoicexpress.com/documents/...", "saft_hash": "J4ay", "sum": 24.39, "discount": 0, "before_taxes": 24.39, "taxes": 5.61, "total": 30, "currency": "Euro", "client": {}, "items": [], "mb_reference": {} } }

Send Invoice by Email

Request

Security
apiKeyAuth
Path
invoices-typestringrequired

The type of the invoice document.

Enum"invoices""invoice_receipts""simplified_invoices""credit_notes""debit_notes"
document-idintegerrequired

The ID of the document.

Example: 1050
Query
api_keystringrequired

Your API Key.

Example: api_key=YOUR_API_KEY
Bodyapplication/jsonrequired
messageobjectrequired
message.​clientobjectrequired
message.​client.​emailstringrequired
Example: "dest@mail.com"
message.​client.​savestringrequired
Enum"0""1"
Example: "1"
message.​subjectstring
Example: "Invoice"
message.​bodystring
Example: "Attached."
message.​ccstring
Example: "cc@mail.com"
message.​bccstring
Example: "bcc@mail.com"
message.​logostring
Enum"0""1"
Example: "1"
curl -i -X PUT \
  'https://docs.invoicexpress.com/_mock/{invoices-type}/1050/email-document.json?api_key=YOUR_API_KEY%2CYOUR_API_KEY_HERE' \
  -H 'Content-Type: application/json' \
  -d '{
    "message": {
      "client": {
        "email": "dest@mail.com",
        "save": "1"
      },
      "subject": "Invoice",
      "body": "Attached.",
      "cc": "cc@mail.com",
      "bcc": "bcc@mail.com",
      "logo": "1"
    }
  }'

Responses

SUCCESS

Response
No content

Generate PDF

Request

Security
apiKeyAuth
Path
document-idintegerrequired

The ID of the document.

Example: 1050
Query
api_keystringrequired

Your API Key.

Example: api_key=YOUR_API_KEY
second_copyboolean
Example: second_copy=false
curl -i -X GET \
  'https://docs.invoicexpress.com/_mock/api/pdf/1050.json?api_key=YOUR_API_KEY%2CYOUR_API_KEY_HERE&second_copy=false'

Responses

SUCCESS

Bodyapplication/json
outputobject
Response
application/json
{ "output": { "pdfUrl": "url.pdf" } }

Get QR Code

Request

Security
apiKeyAuth
Path
document-idintegerrequired

The ID of the document.

Example: 1050
Query
api_keystringrequired

Your API Key.

Example: api_key=YOUR_API_KEY
curl -i -X GET \
  'https://docs.invoicexpress.com/_mock/api/qr_codes/1050.json?api_key=YOUR_API_KEY%2CYOUR_API_KEY_HERE'

Responses

SUCCESS

Bodyapplication/json
qr_codeobject
Response
application/json
{ "qr_code": { "url": "url.png" } }

Related Documents

Request

Security
apiKeyAuth
Path
document-idintegerrequired

The ID of the document.

Example: 1050
Query
api_keystringrequired

Your API Key.

Example: api_key=YOUR_API_KEY
curl -i -X GET \
  'https://docs.invoicexpress.com/_mock/document/1050/related_documents.json?api_key=YOUR_API_KEY%2CYOUR_API_KEY_HERE'

Responses

SUCCESS

Creates a new quote, proforma or fees_note.

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.
Bodyapplication/json
documentsArray of objects
Response
application/json
{ "documents": [ {} ] }

Generate Payment

Request

Security
apiKeyAuth
Path
document-idintegerrequired

The ID of the document.

Example: 1050
Query
api_keystringrequired

Your API Key.

Example: api_key=YOUR_API_KEY
Bodyapplication/jsonrequired
partial_paymentobjectrequired
partial_payment.​amountnumberrequired
Example: 10
partial_payment.​payment_mechanismstring
Enum"TB""MB""CC"
Example: "TB"
partial_payment.​notestring
Example: "Transfer"
partial_payment.​seriestring
partial_payment.​payment_datestring
Example: "22/11/2025"
curl -i -X POST \
  'https://docs.invoicexpress.com/_mock/documents/1050/partial_payments.json?api_key=YOUR_API_KEY%2CYOUR_API_KEY_HERE' \
  -H 'Content-Type: application/json' \
  -d '{
    "partial_payment": {
      "amount": 10,
      "payment_mechanism": "TB",
      "note": "Transfer",
      "serie": "string",
      "payment_date": "22/11/2025"
    }
  }'

Responses

SUCCESS

Creates a new quote, proforma or fees_note.

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.
Bodyapplication/json
receiptobject(FullDocumentObject)
Response
application/json
{ "receipt": { "id": 2137287, "status": "final", "archived": false, "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", "retention": "0", "permalink": "https://www.app.invoicexpress.com/documents/...", "saft_hash": "J4ay", "sum": 24.39, "discount": 0, "before_taxes": 24.39, "taxes": 5.61, "total": 30, "currency": "Euro", "client": {}, "items": [], "mb_reference": {} } }

Cancel Payment

Request

Security
apiKeyAuth
Path
receipt-idintegerrequired
Example: 42
Query
api_keystringrequired

Your API Key.

Example: api_key=YOUR_API_KEY
Bodyapplication/jsonrequired
receiptobjectrequired
receipt.​statestringrequired
Value"canceled"
Example: "canceled"
receipt.​messagestringrequired
Example: "Error"
curl -i -X PUT \
  'https://docs.invoicexpress.com/_mock/receipts/42/change-state.json?api_key=YOUR_API_KEY%2CYOUR_API_KEY_HERE' \
  -H 'Content-Type: application/json' \
  -d '{
    "receipt": {
      "state": "canceled",
      "message": "Error"
    }
  }'

Responses

SUCCESS

Bodyapplication/json
receiptobject(FullDocumentObject)
Response
application/json
{ "receipt": { "id": 2137287, "status": "final", "archived": false, "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", "retention": "0", "permalink": "https://www.app.invoicexpress.com/documents/...", "saft_hash": "J4ay", "sum": 24.39, "discount": 0, "before_taxes": 24.39, "taxes": 5.61, "total": 30, "currency": "Euro", "client": {}, "items": [], "mb_reference": {} } }

Estimates

Create quotes, proformas or fees notes and send them to your clients.

Operations

Guides

Create shippings, transports & devolutions and send them to your clients.

Operations

Sequences

A Sequence is used to group invoices in a sequential order.

Operations

Taxes

A Tax is applied to invoice items when creating invoices.

Operations

SAFT

Export the Standard Audit File for Tax (SAF-T PT) required by the Portuguese Tax Authority.

SAF-T

Operations