Credit Notes

Credit notes are an important financial document used in invoicing. They are essentially the opposite of an invoice and are issued to correct or nullify a previously issued invoice. Here are the key aspects of credit notes:

Correction of Errors: If an invoice contains an error, such as overcharging or billing for goods or services not delivered, a credit note is issued to correct this mistake.
Return of Goods: If a customer returns goods due to damage, dissatisfaction, or other reasons, a credit note is issued to account for the value of the returned goods.
Discounts or Rebates: Sometimes, post-invoice discounts or rebates may be offered. A credit note can be used to adjust the original invoice amount to reflect these discounts.
Document Format: A credit note usually mirrors the format of an invoice and includes details such as the amount being credited, the original invoice number, and specific reasons for the issuance.
Accounting Adjustments: In accounting terms, credit notes adjust the accounts receivable in the seller's books and the accounts payable in the buyer's books, ensuring accurate financial records.
Tax Implications: Credit notes also have tax implications. They adjust the sales and VAT (or equivalent) reported on the original invoice, which is essential for accurate tax reporting.
Legal Evidence: They serve as legal evidence of the cancellation or alteration of the original sales transaction, which can be important in case of disputes or audits.

In summary, credit notes are a crucial part of financial management and help maintain accurate and fair accounting and billing practices between businesses and their customers.

The Credit Note model

The credit note model is identical to the invoice model, the only difference being that the type of the document is a credit_note instead of an invoice.

GET/v1/credit-notes

List

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

Optional attributes

Name
take
Type
integer
Description
Sets the number of credit notes 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/credit-notes

curl -G https://api.invoiceahoy.com/v1/credit notes \
  -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/credit-notes

Create

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
Credit Note
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/credit-notes

curl https://api.invoiceahoy.com/v1/credit-notes \
  -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/credit-notes/:id

Retrieve

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/credit-notes/WAz8eIbvDR60rouK

curl https://api.invoiceahoy.com/v1/credit-notes/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/credit-notes/:id

Update

Updates an non-issued credit note.

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
Credit Note
Description
The Credit Note 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/credit-notes/WAz8eIbvDR60rouK

curl -X PUT https://api.invoiceahoy.com/v1/credit-notes/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/credit-notes/:id

Delete

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

Request

DELETE

/v1/credit-notes/WAz8eIbvDR60rouK

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

GET/v1/credit-notes/:id/download

Download

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/credit-notes/download/WAz8eIbvDR60rouK

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

GET/v1/credit-notes/:id/send

Send

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/credit-notes/WAz8eIbvDR60rouK/send

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