Invoices

On this page, we'll dive into the different invoice endpoints you can use to manage invoices programmatically. We'll look at how to query, create, update, and delete invoices.

Invoice Numbers & Sequencing

In most countries, invoices have to, by law, follow a numbering sequence without any gaps or duplicate numbers. The invoice API supports multiple sequences, which enables you to create invoices for different organizations or organizational units.

For example, you could create two separate invoice sequences by specifying a different sequence_id when creating the invoice. That way, invoices with sequence_id=org_a will have their sequence, and invoices with sequence_id=org_b will have their sequence.

Sequences are created when a new sequence_id is specified in a Create Invoice request and they always start at 1. If you want to set a new sequence to a specific number, then set the doc_number to the number you want, and send the doc_number together with a new sequence_id in the create request.

Setting a Sequence Number

Download Links and Link Expiry

When creating an invoice, both PDF and HTML versions of the invoice are created, encrypted, and stored in the cloud. When using the API to create or lookup an invoice, the download URLs of the pdf and html versions of the invoice are also returned. These download links are only valid for 5 minutes after making the request, which means that if a download link has expired, another link must be retrieved using either the Get Invoice or the Download Invoice requests.

The invoice model

The invoice model contains all the information about your invoices, such as their username, avatar, and phone number. It also contains a reference to the conversation between you and the invoice and information about when they were last active on InvoiceAhoy.

Properties

Name
id
Type
string
Description
Unique identifier for the invoice.
Name
currency
Type
string
Description
Three-letter ISO currency code, in uppercase (e.g. 'USD').
Name
issue_date
Type
date
Description
The Issue Date of the invoice.
Name
due_date
Type
date
Description
The date on which payment for this invoice is due.
Name
notes
Type
string
Description
Any additional notes that needs to be added to the invoice.
Name
footer_text
Type
string
Description
The invoice footer text.
Name
business
Type
Business
Description
The business sending the invoice.
Name
created_at
Type
timestamp
Description
Timestamp of when the invoice was created.

GET/v1/invoices

List invoices

This endpoint allows you to retrieve a paginated list of all your invoices. By default, a maximum of ten invoices are shown per page.

Optional attributes

Name
take
Type
integer
Description
Sets the number of invoices returned.

Name
skip
Type
integer
Description
Skip a set of results, this is used for paginating the results.

Name
order_by
Type
'created_at | doc_number'
Description
Select the field to order the results by.

Request

GET

/v1/invoices

curl -G https://api.invoiceahoy.com/v1/invoices \
  -H "Authorization: Bearer {token}" \
  -d active=true \
  -d limit=10

Response

  {
      "results": 2,
      "skip": 0,
      "data": [
          {
              "id": "clp9bqr2u0000dgmce79wpv8g",
              "doc_number": "3",
              "download_pdf": "https://downloads.invoiceahoy.com/ydaw55trt9/invoices/3.pdf",
              "download_html": "https://downloads.invoiceahoy.com/ydaw55trt9/invoices/3.html",
              "created_at": "2023-11-22T05:28:43.926Z"
          },
          {
              "id": "clp9bwikh0000dg5o9ymszbmu",
              "doc_number": "4",
              "download_pdf": "https://downloads.invoiceahoy.com/ydaw55trt9/invoices/4.pdf",
              "download_html": "https://downloads.invoiceahoy.com/ydaw55trt9/invoices/4.html",
              "created_at": "2023-11-22T05:33:12.834Z"
          }
      ]
  }

POST/v1/invoices

Create Invoice

Create an invoice. The request object contains the invoice data (transaction data), as well as metadata about how the invoice should be formatted, e.g. the invoice template to use, the company logo, language, etc. Default values for the metadata fields can be set in the dashboard.

Required attributes

Name
data
Type
Invoice
Description
The invoice object (transaction data). See the model

Optional attributes

Name
template_id
Type
string
Description
The ID of the invoice template to generate. See templates for a list of the default templates provided by InvoiceAhoy.
Name
doc_number
Type
string
Description
The document number. If not specified then one will be generated using the specified (or default) sequence.
If both doc_number and sequence_id is specified, then the value of the Sequence will be set to doc_number.
Name
sequence_id
Type
string
Description
The Sequence to use to generate the document number. If not specified, then the default sequence is used. If the specified sequence doesn't exist, then one is created.
Name
timezone
Type
string
Description
Set the timezone. All dates are formatted to this timezone.

Request

POST

/v1/invoices

curl https://api.invoiceahoy.com/v1/invoices \
  -H "Authorization: Bearer {token}" \
    -H 'Content-Type: application/json'
    -d '{...input_data}'

Response

  {
      "id": "inv_acbcdeeae1730a75fb830bc26939cfa7",
      "doc_number": "3",
      "download_pdf": "https://downloads.invoiceahoy.com/ydaw55trt9/invoices/3.pdf",
      "download_html": "https://downloads.invoiceahoy.com/ydaw55trt9/invoices/3.html",
      "created_at": "2023-11-22T05:28:43.926Z"
  }

GET/v1/invoices/:id

Retrieve invoice

This endpoint allows you to retrieve an invoice by providing their InvoiceAhoy id. Refer to the list at the top of this page to see which properties are included with invoice objects.

Request

GET

/v1/invoices/WAz8eIbvDR60rouK

curl https://api.invoiceahoy.com/v1/invoices/WAz8eIbvDR60rouK \
  -H "Authorization: Bearer {token}"

Response

  {
      "id": "clp9bwikh0000dg5o9ymszbmu",
      "doc_number": "4",
      "download_pdf": "https://downloads.invoiceahoy.com/ydaw55trt9/invoices/4.pdf",
      "download_html": "https://downloads.invoiceahoy.com/ydaw55trt9/invoices/4.html",
      "created_at": "2023-11-22T05:33:12.834Z"
  }

PUT/v1/invoices/:id

Update invoice

Updates an non-issued invoice.

If the doc_number is updated, the new value is used in the invoice, but no changes are made to the Sequence to which the invoice belongs.

Required attributes

Name
data
Type
Invoice
Description
The invoice object (transaction data). See the model

Optional attributes

Name
template_id
Type
string
Description
The ID of the invoice template to generate. See templates for a list of the default templates provided by InvoiceAhoy.
Name
doc_number
Type
string
Description
The document number. If not specified then the existing doc_number is used.
Name
timezone
Type
string
Description
Set the timezone. All dates are formatted to this timezone.

Request

PUT

/v1/invoices/WAz8eIbvDR60rouK

curl -X PUT https://api.invoiceahoy.com/v1/invoices/WAz8eIbvDR60rouK \
  -H "Authorization: Bearer {token}" \
  -d display_name="UncleFrank"

Response

  {
      "id": "clp9bwikh0000dg5o9ymszbmu",
      "doc_number": "4",
      "download_pdf": "https://downloads.invoiceahoy.com/ydaw55trt9/invoices/4.pdf",
      "download_html": "https://downloads.invoiceahoy.com/ydaw55trt9/invoices/4.html",
      "created_at": "2023-11-22T05:33:12.834Z"
  }

DELETE/v1/invoices/:id

Delete invoice

This endpoint allows you to delete invoices from InvoiceAhoy. This also removes the stored artifacts.

Request

DELETE

/v1/invoices/WAz8eIbvDR60rouK

curl -X DELETE https://api.invoiceahoy.com/v1/invoices/WAz8eIbvDR60rouK \
  -H "Authorization: Bearer {token}"

GET/v1/invoices/download/:id

Download invoice

This endpoint allows you to download an invoices from InvoiceAhoy. The API returns a redirect to the secure download link, so the client making the request must be able to follow 302 redirects.

Optional attributes

Name
format
Type
'pdf'|'html'
Description
Specifies the format of the invoice to download. The default is pdf.

Request

GET

/v1/invoices/download/WAz8eIbvDR60rouK

curl -X GET https://api.invoiceahoy.com/v1/invoices/download/WAz8eIbvDR60rouK \
  -H "Authorization: Bearer {token}"

POST/v1/invoices/:id/send

Send invoice

Sends an invoice to a customer via email.

Optional attributes

Name
subject
Type
string
Description
Overrides the default email subject.
Name
to
Type
email
Description
Overrides the destination. If not specified, the email from the customer object in the invoice data is used.
Name
cc
Type
string[]
Description
A list of email addresses to add as CC.

Request

POST

/v1/invoices/WAz8eIbvDR60rouK/send

curl -X POST https://api.invoiceahoy.com/v1/invoices/WAz8eIbvDR60rouK/send \
  -H "Authorization: Bearer {token}"