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
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.
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.
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
https://api.regate.io/v1/customers. If the customer does not exist, create one via a
POSTrequest 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.
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
https://api.regate.io/v1/products. Otherwise, you need to create a new product with a
POSTrequest 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
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.
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.
Draft invoices cannot have file attachments, as file attachments require the invoice to be issued and an invoice number to be set.
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
- 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.
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_numbervalue is mandatory!
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
receivedstate 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.
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 23 days ago