Skip to content

InvoiceXpress API (3.1.0)

The InvoiceXpress v3 API: invoicing documents (invoices, guides, estimates) and their series, clients, items, taxes, schedules and favorites; account, user, AT-communication and payment-service settings; batch CSV imports of invoices, products and clients; dashboard KPIs, reports, SAF-T export, digital signatures, EDI (CIUS-PT), Social Security declarations, and reference lists (currencies, tax countries, phone calling codes).

What changed between versions of this reference is listed under Changelog, at the end of the navigation.

Authentication

Send your api_key as a query parameter on JSON (or XML) requests. A request with no valid api_key answers 401. The Authorization: Bearer and X-Account headers authenticate the InvoiceXpress web app only; they are not meant for API clients. Endpoints marked as public need no key.

Download OpenAPI description
Overview
InvoiceXpress API Support
Languages
Servers
Production Server
https://api-v3.app.invoicexpress.com/

Invoices

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

Operations

Guides

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

Operations

Estimates

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

Operations

Sequences

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

Operations

Clients

A Client is an entity you send invoices to.

Operations

Accounts

Manage your InvoiceXpress account settings, users, AT communication, and billing.

Operations

Account Credentials

Manage AT communication credentials for your account.

Operations

Collection Alerts

Configure automated payment collection alerts sent to clients.

Operations

Batch Invoices

Bulk-create invoices from a CSV file. Flow — GET batch → upload → process → mapping → configure_options → configure → validate → validation → available_docs → POST create → status. DELETE to discard.

Operations

Batch Products

Bulk import products from a CSV file. Flow — GET index (optional) → upload → process → GET/PUT mapping → validate → validation → POST create → status. DELETE to discard.

Operations

Batch Clients

Bulk import clients from a CSV file. Flow — GET index (optional) → upload → process → GET/PUT mapping → validate → validation → POST create → status. DELETE to discard. No configure step.

Operations

Items

An Item is the product or service you invoice.

Operations

List Items

Request

Returns a paginated list of all items (products/services) in the account.

Security
apiKeyAuth
Query
api_keystringrequired

Your API Key.

Example: api_key=YOUR_API_KEY
pageinteger

Page number (default 1).

Default 1
Example: page=1
per_pageinteger

Results per page (default 10). items_per_page and page_items are accepted as aliases.

Default 10
Example: per_page=10
termstring

Search text. Matches items whose name (code) or description contains it.

Example: term=Consult
sortstring

Field to sort by (default products.name).

Default "products.name"
Enum"products.name""description""unit_price""rrp""unit""created_at"
Example: sort=unit_price
sort_orderstring

Sort direction (default ASC).

Default "ASC"
Enum"ASC""DESC""asc""desc"
curl -X GET "https://api-v3.app.invoicexpress.com/api/v3/items?api_key=YOUR_API_KEY&page=1&per_page=10&term=Consult&sort=name&sort_order=ASC"

Responses

SUCCESS

Bodyapplication/json
itemsArray of objects(V3ItemObject)
paginationobject
Response
application/json
{ "items": [ { … } ], "pagination": { "total_entries": 1, "current_page": 1, "total_pages": 1, "per_page": 10 } }

Create Item

Request

Creates a new item (product or service). When omitted, unit defaults to service, the tax defaults to the account's default tax and rrp is computed from unit_price and the tax.

Security
apiKeyAuth
Query
api_keystringrequired

Your API Key.

Example: api_key=YOUR_API_KEY
Bodyapplication/jsonrequired
itemobjectrequired

Item fields accepted on create and update. Any other key inside item is ignored.

item.​codestring<= 60 charactersrequired

Item name/code. Values longer than 60 characters are rejected with HTTP 422 (Code for the item is too long (maximum should be 60 characters)) — they are not truncated. On update, it cannot be changed once the item is used in a non-draft document (HTTP 422 Code can't be changed because it is already associated with invoices).

Example: "Item name"
item.​descriptionstring or null<= 200 characters

Values longer than 200 characters are rejected with HTTP 422 (Description is too long (maximum is 200 characters)) — they are not truncated.

Example: "Item description"
item.​unit_pricenumber>= 0required

A missing or non-numeric value is rejected with HTTP 422 (Price is not valid. Check the decimal mark and if you are inserting only numbers.).

Example: 9.99
item.​rrpnumber>= 0

Recommended retail price. On create, when omitted, it is computed as unit_price plus the item's tax. On update, an omitted value is left unchanged.

Example: 12.29
item.​unitstring

One of: hour, day, month, unit, service, tax, other, product, article. On create, defaults to service when omitted; on update, an omitted unit is left unchanged.

Example: "service"
item.​taxobject

Tax of the item, by name. When omitted, create uses the account's default tax and update keeps the current tax. An unknown name is rejected on create with HTTP 422 (Tax must exist); on update it is ignored and the current tax is kept.

item.​retentionnumber

Retention rate (%). Defaults to 0 when omitted.

Example: 2
curl -X POST "https://api-v3.app.invoicexpress.com/api/v3/items?api_key=YOUR_API_KEY" -H "Content-Type: application/json" --data '{}'

Responses

SUCCESS

Bodyapplication/json
itemobject(V3ItemObject)
Response
application/json
{ "item": { "id": 1, "code": "Item name", "description": "Item description", "unit_price": 9.99, "rrp": 12.29, "unit": "service", "tax": { … }, "retention": 2 } }

Get Item

Request

Returns a specific item with detailed sales statistics.

Security
apiKeyAuth
Path
idstringrequired

Item id

Query
api_keystringrequired

Your API Key.

Example: api_key=YOUR_API_KEY
curl -X GET "https://api-v3.app.invoicexpress.com/api/v3/items/1?api_key=YOUR_API_KEY"

Responses

SUCCESS

Bodyapplication/json
itemobject(V3ItemDetailObject)
Response
application/json
{ "item": { "id": 1, "code": "Item name", "description": "Item description", "unit_price": 9.99, "rrp": 12.29, "unit": "service", "unit_sold": 16, "total_sold": 196.8, "total_sold_before_taxes": 160, "currency": { … }, "tax": { … }, "retention": 2 } }

Update Item

Request

Updates an existing item. Partial update — only the keys sent inside item are changed, except retention, which is reset to 0 when omitted. An unknown tax.name is ignored (the current tax is kept).

Security
apiKeyAuth
Path
idstringrequired

Item id

Query
api_keystringrequired

Your API Key.

Example: api_key=YOUR_API_KEY
Bodyapplication/jsonrequired
itemobject(V3ItemWritableFields)required

Item fields accepted on create and update. Any other key inside item is ignored.

item.​codestring<= 60 characters

Item name/code. Values longer than 60 characters are rejected with HTTP 422 (Code for the item is too long (maximum should be 60 characters)) — they are not truncated. On update, it cannot be changed once the item is used in a non-draft document (HTTP 422 Code can't be changed because it is already associated with invoices).

Example: "Item name"
item.​descriptionstring or null<= 200 characters

Values longer than 200 characters are rejected with HTTP 422 (Description is too long (maximum is 200 characters)) — they are not truncated.

Example: "Item description"
item.​unit_pricenumber>= 0

A missing or non-numeric value is rejected with HTTP 422 (Price is not valid. Check the decimal mark and if you are inserting only numbers.).

Example: 9.99
item.​rrpnumber>= 0

Recommended retail price. On create, when omitted, it is computed as unit_price plus the item's tax. On update, an omitted value is left unchanged.

Example: 12.29
item.​unitstring

One of: hour, day, month, unit, service, tax, other, product, article. On create, defaults to service when omitted; on update, an omitted unit is left unchanged.

Example: "service"
item.​taxobject

Tax of the item, by name. When omitted, create uses the account's default tax and update keeps the current tax. An unknown name is rejected on create with HTTP 422 (Tax must exist); on update it is ignored and the current tax is kept.

item.​retentionnumber

Retention rate (%). Defaults to 0 when omitted.

Example: 2
curl -X PUT "https://api-v3.app.invoicexpress.com/api/v3/items/1?api_key=YOUR_API_KEY" -H "Content-Type: application/json" --data '{}'

Responses

SUCCESS

Bodyapplication/json
itemobject(V3ItemObject)
Response
application/json
{ "item": { "id": 1, "code": "Item name", "description": "Item description", "unit_price": 9.99, "rrp": 12.29, "unit": "service", "tax": { … }, "retention": 2 } }

Delete Item

Request

Deletes one or more items. This is a soft delete (the items are marked as deleted, not removed). Ids that are not undeleted items of the account are skipped.

Security
apiKeyAuth
Path
idstringrequired

Item id, or a comma-separated list of item ids.

Example: 1,2,3
Query
api_keystringrequired

Your API Key.

Example: api_key=YOUR_API_KEY
curl -X DELETE "https://api-v3.app.invoicexpress.com/api/v3/items/1?api_key=YOUR_API_KEY"

Responses

NO CONTENT

Response
No content

Schedules

Create and manage recurring document schedules.

Operations

Taxes

Manage tax rates for your account.

Operations

Current User

Manage the currently authenticated user's own profile, API key, linked accounts, and password recovery.

Operations

Currencies

List supported currencies and look up exchange rates between them.

Operations

Dashboard

Retrieve dashboard KPIs and analytics about your clients and invoicing activity.

Operations

Favorites

Save and reuse custom filter presets for documents and other list views.

Operations

Payment Services

Configure and manage the payment service integration used to collect payments for your invoices.

Operations

Phone Calling Codes

List all phone country calling codes.

Operations

Reports

Reporting endpoints — currently covers the balance-per-client report, its summary, and XLSX export.

Operations

SAF-T

Generate the SAF-T (Standard Audit File for Tax) export for your account.

Operations

Tax Countries

List all tax countries.

Operations

Digital signatures

Allows opt-in for available digital signature providers, manage its credentials, and sign invoices.

Operations

EDI

Manage electronic invoice (CIUS-PT) generation and its additional customs/delivery fields. Note these endpoints are served under /api/v1/edi/ on the v3 host, and address documents by a bare id with no document-type segment.

Operations

Social Security

Helps self-employed accounts (trabalhadores independentes and ENI) fill in the quarterly income declaration for Segurança Social. InvoiceXpress calculates the quarter's totals from your invoices and an estimate of the monthly contribution; you record what you reported.

This feature submits nothing to Segurança Social. You type the figures into Segurança Social Direta yourself. It only calculates and records.

Authentication is api_key only, and every endpoint is JSON only. The declaration endpoints are served under /services/v1/social_security/... and the settings and report endpoints under /api/v3/accounts/..., all on the v3 host.

Operations

Changelog

Changes to the documented contract of the InvoiceXpress API v3: endpoints, fields, enum values, status codes and behaviour you can observe as an integrator. The newest version is at the top.

The version number is the one shown at the top of this reference, and it follows these rules:

  • Minor (3.1.0): something was added, such as a new endpoint, field or enum value. Existing integrations keep working.
  • Patch (3.0.1): the documentation was corrected and now describes what the API already did. No behaviour changed.
  • The major version stays at 3. A change that would break existing integrations is released as a new API version, not as 4.0.0 of this one.