Invoices

Create, manage, and send invoices to customers with line items and tax calculations.

Create Invoice

POST https://api.invoiless.com/v1/invoices

Create a new invoice with customer information and line items.

Example 1:

{
  "customer": {
    "internalId": "INTERNAL_USER_ID",
    "billTo": {
      "company": "Invoiless"
    }
  },
  "items": [
    {
      "name": "Demo product",
      "quantity": 1,
      "price": 42
    }
  ]
}

Example 2:

{
  "customer": "CUSTOMER_ID",
  "items": [
    {
      "name": "Demo product",
      "quantity": 1,
      "price": 42
    }
  ]
}

Header Parameters

Name	Type	Description	Required
scope-id	string	Scope id	No

Body Parameters

Name	Type	Description	Required
slug	string	Invoice slug (max 50 characters)	No
header	string	Invoice header text (max 20 characters)	No
number	string	Invoice number (max 20 characters). For e-invoicing, set it only on a draft: issuing the invoice assigns its number	No
date	date	Invoice date	No
dueDate	date	Invoice due date (must be >= date)	No
currency	string	ISO 4217 currency code	No
lang	string	Invoice language, possible values are en, fr, de, nl, es, bg, ro, ja, mn, da, sv, lt, fi, hu, cs, it, et, lv, pt, pl, sk, zh, or vi	No, default is en
status	string	Invoice status, possible values are Draft, Pending, Unpaid, Canceled, Partial, Paid, or Refunded. For e-invoicing, only Draft, Pending, or Paid can be set: other statuses are derived from payments, credit notes, and cancellations	No, default is Draft
customer	string, object	Customer id or customer details with your internal user id	Yes
shipTo	bool	Show or hide the ship to address	No, default is false
items	array	Invoice line items (min 1 item required)	Yes
extraCharges	object	Invoice extra charges	No
discount	object	Invoice discount	No
extraFields	array	Invoice extra fields (max 3 fields)	No
taxes	array	Invoice taxes (max 3 taxes). Not supported for e-invoicing: set the tax on each item instead	No
taxIncluded	bool	Tax is included in prices	No, default is false
terms	string	Invoice terms (max 1000 characters, HTML sanitized)	No
notes	string	Invoice notes (max 1000 characters, HTML sanitized)	No
tags	array[string]	Invoice tags (max 10 tags, each max 50 characters)	No
isRetainer	bool	Mark invoice as a retainer	No

Customer Parameters

Name	Type	Description	Required
id	string	Customer id	Yes

Name	Type	Description	Required
internalId	string	The internal id is used to identify an individual customer in your application	Yes
billTo	object	Bill to address	Yes
shipTo	object	Ship to address	No

Bill To / Ship To Parameters

Either firstName and lastName, or company, is required.

Name	Type	Description	Required
firstName	string	First name	No
lastName	string	Last name	No
company	string	Company name	No
email	string	Email	No
phone	string	Phone	No
address	string	Address	No
legal	string	Legal info (e.g. Company number)	No

Items Parameters

Name	Type	Description	Required
item	string	Item id that refers to a global item	No
name	string	Item name (max 100 characters)	Yes
url	string	Item url	No
description	string	Item description (max 1000 characters, HTML sanitized)	No
quantity	number	Item quantity (must be > 0)	Yes
unit	string	Item unit (max 20 characters)	No
price	number	Item unit price (must be >= 0)	Yes
discount	object	Item discount	No
taxes	array	Item taxes (max 3 taxes). For e-invoicing, exactly 1 tax per item	No

Item Discount Parameters

Name	Type	Description	Required
name	string	Discount name (max 15 characters)	No
value	number	Discount value (cannot exceed item total)	Yes

Item Taxes Parameters

Name	Type	Description	Required
name	string	Tax name (max 15 characters)	Yes
value	number	Tax value	Yes
exemption	string	VAT treatment used for e-invoices, possible values are Standard, ZeroRated, ReverseCharge, IntraCommunity, Export, Exempt, or OutsideScope. All values except Standard require a value of 0	No, default is Standard when value > 0
exemptionReason	string	Exemption reason shown on the e-invoice (max 1000 characters). Only kept when exemption is Exempt	Yes, if exemption is Exempt for e-invoicing

Extra Charges Parameters

Name	Type	Description	Required
type	string	Extra charges type, possible values are Flat or Percentage	No, default is Percentage
value	number	Extra charges value (must be >= 0)	Yes

Discount Parameters

Name	Type	Description	Required
type	string	Discount type, possible values are Flat or Percentage	No, default is Percentage
value	number	Discount value (Flat: cannot exceed subtotal, Percentage: max 100)	Yes

Extra Fields Parameters

Name	Type	Description	Required
name	string	Extra field name (max 15 characters)	Yes
type	string	Extra field type, possible values are Flat or Percentage	No, default is Percentage
value	number	Extra field value	Yes

Taxes Parameters

Name	Type	Description	Required
name	string	Tax name (max 15 characters)	No
type	string	Tax type, possible values are Flat or Percentage	No, default is Percentage
value	number	Tax value	Yes

Response HTTP/1.1 201 Created

{
  "id": "invoice_id",
  "url": "https://invoiless.com/i/invoice_id"
}

Response Body

Name	Type	Description
id	string	Invoice id
url	string	Invoice preview url

Update Invoice

PUT https://api.invoiless.com/v1/invoices/:id

PATCH https://api.invoiless.com/v1/invoices/:id

Update an existing invoice. See PUT vs PATCH for details on the differences.

Path Parameters

Name	Type	Description	Required
id	string	Invoice id	Yes

Body Parameters

Accepts the same parameters as Create Invoice.

Get Invoice

GET https://api.invoiless.com/v1/invoices/:id

Retrieve a specific invoice by ID.

Path Parameters

Name	Type	Description	Required
id	string	Invoice id	Yes

Get Invoices

GET https://api.invoiless.com/v1/invoices

Retrieve a paginated list of all invoices.

Query Parameters

Name	Type	Description	Required
page	number	Page number	No, default is 1
limit	number	Page limit	No , default is 50
search	string	Search by invoice number, customer name, or tags	No

Send Invoice

POST https://api.invoiless.com/v1/invoices/:id/send

Send an invoice via email to the customer.

Path Parameters

Name	Type	Description	Required
id	string	Invoice id	Yes

Body Parameters

Name	Type	Description	Required
email	string	Email address	No
subject	string	Email subject	No
body	string	Email body	No
date	date	Schedule send	No

Issue Invoice

POST https://api.invoiless.com/v1/invoices/:id/issue

Issue a draft invoice without sending it. The invoice gets its final number and becomes read-only. Calling it on an issued invoice returns it unchanged.

Only available when e-invoicing is enabled. For e-invoicing, the invoice is validated against its standard first, and the request fails with the list of errors if it isn't valid.

Path Parameters

Name	Type	Description	Required
id	string	Invoice id	Yes

Cancel Invoice

POST https://api.invoiless.com/v1/invoices/:id/cancel

Cancel an issued invoice. This issues a cancellation credit note for the invoice's full amount and sets its status to Canceled. The invoice keeps its number.

Only issued invoices can be canceled (see E-Invoicing). Delete a draft instead. Received payments must be refunded before the invoice can be canceled.

Example:

{
  "reason": "BillingError",
  "notes": "Wrong billing address"
}

Path Parameters

Name	Type	Description	Required
id	string	Invoice id	Yes

Body Parameters

Name	Type	Description	Required
reason	string	Cancellation reason, possible values are Duplicate, CustomerRequest, Cancelled, BillingError, Fraudulent, or Other	No, default is Cancelled
notes	string	Cancellation notes (max 500 characters)	No

Export Invoice

GET https://api.invoiless.com/v1/invoices/:id/export

Export an invoice as PDF. An invoice issued as an e-invoice is exported as a hybrid PDF with the e-invoice XML embedded (ZUGFeRD).

Path Parameters

Name	Type	Description	Required
id	string	Invoice id	Yes

Query Parameters

Name	Type	Description	Required
tz	string	IANA time zone used to render dates, e.g. Europe/Paris	No

Delete Invoice

DELETE https://api.invoiless.com/v1/invoices/:id

Permanently delete an invoice.

Path Parameters

Name	Type	Description	Required
id	string	Invoice id	Yes