Sales invoices
In-depth guide on the specifics of sales invoices
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 aGET
request tohttps://api.regate.io/v1/customers
. If the customer does not exist, create one via aPOST
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 aGET
request tohttps://api.regate.io/v1/products
. Otherwise, you need to create a new product with aPOST
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 thereceived
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
Updated 9 months ago