Overview

This guide will help you understand the specifics of the sales invoice objects in the Regate API. This includes:

• How to retrieve specific attribute values needed for invoice creation
• Differences between the options available in the Regate API and the Regate app when creating an invoice
• Invoice states and what they represent

What is a sales invoice

A sales invoice is a document sent to a customer with a list of products or services they have bought and their prices, any sales tax, the total amount, and the date before which the customer must pay. The invoice serves as a key financial document for both parties, aiding in accurate bookkeeping, tracking revenue, and facilitating timely payment reconciliation.

In the Regate app, the list of sales invoices can be seen in the "Accounts receivable" section.

Create a sales invoice

In the Regate API, a sales invoice is created by making a POST request to https://api.regate.io/v1/sales_invoices. See the API Reference for full details and an option to try out the request.

Required attributes

The required attributes for the request body are as follows:

• currency - The currency for this invoice.
• customer_id - The ID of the customer linked to this invoice. The list of customers and their IDs be retrieved by making a GET request to https://api.regate.io/v1/customers. If the customer does not exist, create one via a POST request to the same endpoint URL. The information linked to this customer ID will be displayed in the response body.
• due_date - Due date for this invoice, i.e. the date by which the customer is expected to make the payment for the goods or services outlined in the invoice.
• payment_method - The method used to make the payment.
• lines - An array of objects containing information about the lines in the invoice - what type of product is included, the quantity, discounts, etc.
• vat_paid - Indicates when the VAT is paid. It can either be paid on receipts or compensated for sales.

{
  "currency": "EUR",
  "customer_id": "9876543a-bc21-0def-98g7-6543hij21kl0",
  "due_date": "2023-01-31",
  "payment_method": "bank_transfer",
  "lines": [
    {
      "product_id": "1a234567-89b0-123c-45d6-e78fg90h1234",
      "quantity": 1000
    }
  ],
  "vat_paid": "receipts"
}

Optional line values

For each invoice line you are only required to specify two attributes:

• product_id - ID of the product for this line. If the product already exists, you can retrieve the product via a GET request to https://api.regate.io/v1/products. Otherwise, you need to create a new product with a POST request to the same endpoint URL.
• quantity - The amount or number of units of this product that the customer has purchased. The quantity shown is multiplied by 100 to avoid a decimal separator, so it needs to be divided by 100 to get the actual amount.

Based on the product_id, additional information will be retrieved - its external reference, price for a single unit, VAT tax account linked to it.

However, when creating an invoice you can select specific values for the product lines by adding the reference, unit_price_cents and sales_vat_account_id attributes to the line object. These will NOT update the product object itself, but will instead override the values of those same product attributes for this invoice only.

Create a draft invoice

By default when making a POST /sales_invoices request, the invoice is created in an received state - meaning that it has already been issued and an invoice_number value is returned for it. Invoice and customer information for issued invoices cannot be edited and the invoice cannot be deleted.

However, if in the request body you set the value of the draft attribute to true, the invoice will remain in a draft state and be visible under "Drafts" in the Regate app. Draft invoices do not have an invoice number and the invoice information to be edited prior to it being issued. Also, a draft invoice can be deleted if needed.

🚧

Warning

Draft invoices cannot have file attachments, as file attachments require the invoice to be issued and an invoice number to be set.

File attachments

When creating an invoice, a PDF copy of the invoice can be attached to it. There are two ways to do this:

• adding a public link to the required file as the value of the file_url attribute
• adding the Base64 encoded content of the file to the request body

The string of the Base64-encoded file information needs to be set as the value of the file attribute in the request body. The value of the invoice_number attribute will be used as file name, and the extension will be PDF, as only PDF files are allowed for upload.

📘

Info

The file is used only for reference. The information on the file will not affect any attribute values, regardless of whether the it matches the one submitted in the request body. Additionally, if a file is attached to a request payload, adding an invoice_number value is mandatory!

Invoice states

When making a GET request to https://api.regate.io/v1/sales_invoices, a list of all invoices is retrieved. In the invoice objects, the state attribute indicates the current state of the invoice:

• draft - An invoice draft that has not yet been issued and can be edited. In the Regate app, these are displayed under "Accounts receivable" >> "Draft".
• received - The invoice has been issued, but not yet recorded. In the Regate app, these are displayed under "Accounts receivable" >> "New".
• excluded - Excluded invoices. Only invoices in the received state can be excluded. In the Regate app, these are displayed under "Accounts receivable" >> "Archives" >> "Excluded".
• recorded - Recorded invoices, which are not yet paid. In the Regate app, these are displayed under "Accounts receivable" >> "Recorded".
• paid - Paid invoices. In the Regate app, these are displayed under "Accounts receivable" >> "Paid".
• reconciled - Reconciled invoices.

Limitations

Due to the current stage of development of the Regate API, not all actions available in the Regate app are possible via the Regate API. The most important include:

• Invoices cannot be transitioned from one state to another via an API call
• It is currently not possible to upload an invoice file via the API, thus creating an invoice by extracting the information from the file