Introduction
Billit API gives you the ability to connect to your billit.io account, retrieve your clients and suppliers, check your invoice's status, see your balance and create OCP (One click payment) links. You can of course generate new invoices from any kind of application by using a set of callable API endpoints. To perform an action using the API, you need to send a request to its endpoint specifying a method and some arguments, and you will receive a formatted response.
In case you're a Greek company, invoices are also compatible with MYDATA and can be forwarded automatically to the authorities (A.A.D.E).
Sandbox
- Web app: https://app.sandbox-billit.xyz
- API endpoints: https://api.sandbox-billit.xyz
Production
- Web app: https://app.billit.io
- API endpoints: https://api.billit.io
The API has a limit of 60 requests per minute per user account (all your tokens share it). Every response carries
X-RateLimit-LimitandX-RateLimit-Remaining. Over the limit you get status 429 with aRetry-Afterheader: wait that many seconds, then retry.
How to start
For your convinience, Billit provides you a Sandbox environment. This way you can test your API implementation and watch the end result at all times in your web app space. The steps you must take in order to use the API is as follow:
-
You need to register first in order to have a sandbox account.
-
After logging in to your app section of your Sandbox account, you need to navigate to settings > API (tab) and generate a token

Use that generated token to your requests by hitting the sandbox endpoints. If you want to check the UI after your API request, visit the Sandbox web app url as well.
In case you use PHP, we provide an opensource package you can use to make things very easy. Special addons included if you use the Laravel Framework
Make sure to test your implementation thoroughly using the Sandbox account first. When you're ready for production we will give you full write access to all resources the same day.
Authentication
This API uses a Bearer Token for authentication, To Generate a token follow the instructions as seen in the "How to start" section of this documentation.
Example Header
Code
If you want to test your credentials, make a GET request with the Authorization header to https://api.sandbox-billit.xyz/v1. You will receive a 200 OK response like this:
Code
Token abilities
When you create a token you choose its abilities: read, write, or both. GET requests need read; POST, PUT, PATCH and DELETE need write. A token without the needed ability gets 403 with {"msg": "This token does not have the 'write' ability."}.
A token belongs to the company it was created in. If you lose access to that company, its token gets 403 and you need a new token from that company's settings.
The "Try it out" feature
The API documentation includes an HTTP client that you can use to make realy quickly requests and see the responses. To use the Authentication, send an "Authorization" header with value of your token with an appended "Bearer" string, like this:

Using the "My Account" endpoint
The /account endpoint response is important. The reason is that except the expected information regarding the user, the setup and subscription details it also contains the account's Vat details, Payment methods and Biller information. This information doesn't change often so you can safely cache it as long as you need or even hard code the Ids from those objects when you need them to your requests.
As an example, if you'll use the /invoices endpoint to create a new invoice, you will definitely need the billerId, paymentmethodId and the vatId (for each product row). This kind of information lives in the /account endpoint response, no need to make extra queries to other endpoints just to fetch those.
Where each id comes from:
| You need | Read it from |
|---|---|
vatId, products[].vatId, taxes[].taxId | GET /account → data.relations.vats[].id |
paymentMethod, paymentMethods | GET /account → data.relations.paymentMethods[].id |
invoiceTypeId | GET /account → data.relations.invoiceTypes[].id |
billerId | GET /account → data.relations.biller.id |
customerId, supplierId | GET /contacts → data[].id |
productId | GET /products → data[].id |
correlatedIds (credit notes) | GET /invoices → data[].id (the numeric id, not the uuid) |
Choosing the invoice type
Each invoice type in GET /account → data.relations.invoiceTypes has a mydataDefaultType: its myDATA category. Send an invoiceTypeId whose category covers the mydataInvoiceType code you send:
mydataDefaultType | myDATA codes |
|---|---|
| Τιμολόγιο Πώλησης | 1.1, 1.2, 1.3 |
| Τιμολόγιο Παροχής Υπηρεσιών | 2.1, 2.2, 2.3 |
| Τίτλος Κτήσης | 3.1, 3.2 |
| Πιστωτικό Τιμολόγιο | 5.1, 5.2 |
| Στοιχείο Αυτοπαράδοσης | 6.1 |
| Ενοίκια - Έσοδο | 8.1 |
| Τέλος ανθεκτικότητας στη κλιματική κρίση (older types: Eιδικό Στοιχείο – Απόδειξης Eίσπραξης Φόρου Διαμονής) | 8.2, stay tax: these types have a stayTax object with the price per room and night; see "Stay tax (8.2)" in POST /invoices |
| Δελτίο Αποστολής | 9.3 |
| Δελτίο Αποστολής Συσχετιζόμενο | 9.1 |
| Συγκεντρωτικό Δελτίο Αποστολής | 9.2 |
| Δελτίο Ποσοτικής Παραλαβής Συσχετιζόμενο | 10.1 |
| Δελτίο Ποσοτικής Παραλαβής Μη Συσχετιζόμενο | 10.2 |
| ΑΛΠ (Απόδειξη Λιανικής Πώλησης) | 11.1 |
| ΑΠΥ (Απόδειξη Παροχής Υπηρεσιών) | 11.2 |
| Πιστωτικό στοιχείο Λιανικής | 11.4 |
| Πιστωτικό Στοιχ. Λιανικής ημεδαπής / αλλοδαπής | 13.31 |
Several types can share a category (for example one per numbering series); choose among them by name and series. Credit-note types have pistosi: true.
myDATA classifications: ask your accountant
Greek invoices sent to myDATA (AADE) carry, on every row, an income classification and, on 0% VAT rows, a VAT exemption reason. Which ones are correct depends on what you sell and to whom, and it has tax consequences, so ask your accountant before you start issuing invoices. The values in our examples only show the format.
You don't need to send them with every invoice. Set them once in the web app under Settings → myData → "Εξ ορισμού χαρακτηρισμοί προϊόντων": for each invoice type, map each contact type (domestic, EU, outside the EU) to a classification and to the exemption reason for 0% VAT. A product can override these with its own mapping. Rows you send without a classification then get the product's mapping, or else the account default for the customer's type. A value you send in the row always wins.
Pagination
List endpoints are paginated. Send per_page (an integer, maximum 250) to choose the page size and page to choose the page.
The default page size depends on the endpoint:
| Endpoint | Default per_page |
|---|---|
/invoices, /contacts | 25 |
/products | 50 |
/payments, /purchases, /tags | 20 |
/ocps | 15 |
Each list response has data, links and meta. To read every page, follow links.next until it is null, or compare meta.current_page with meta.last_page.
HTTP Methods
This API uses HTTP verbs (methods) as following:
GET- Read - used to read (or retrieve) a representation of a resource,POST- Create - used to create new resources. In particular, it's used to create subordinate resources.PUT- Update/Replace - used for update capabilities, PUT-ing to a known resource URI with the request body containing the newly-updated representation of the original resource. On successful request, replaces identified resource with the request body.PATCH- Partial update - available for contacts (PATCH /contacts/{id}): only the fields you send change.DELETE- Delete - used to delete a resource identified by a URI.
PUTreplaces the whole resource. Fields you leave out are cleared or reset (for example tags are removed and notes emptied), they are not kept. Read the resource first and send it back complete. To change only a few fields of a contact, usePATCH.
Media Type
Where applicable this API MUST use the JSON media-type. Requests with a message-body are using plain JSON to set or update resource states.
Content-type: application/json and Accept: application/json headers SHOULD be set on all requests if not stated otherwise.
Representation of Date and Time
All exchange of date and time-related data MUST be done according to ISO 8601 standard and stored in UTC.
When you send a date as input to create a new resource or to filter results, you need to send it formatted as "Y-m-d" ( Year - Month - day Ex: 2021-05-28).
Status Codes and Errors
This API uses HTTP status codes to communicate with the API consumer.
200 OK- Response to a successful GET, PUT, PATCH or DELETE.201 Created- Response to a POST that results in a creation.204 No Content- Response to a successful request that won't be returning a body (like a DELETE request). | Status | Meaning | What to do | | --- | --- | --- | |200 OK| Successful GET, PUT or PATCH. | — | |201 Created| Successful POST that created a resource. | — | |204 No Content| Successful DELETE. | — | |400 Bad Request|Account Restriction: your plan's invoice limit is reached.Bad Request: an unexpected error was logged. | Upgrade the plan, or contact support withdata.insidentId. | |401 Unauthorized|Authorization Required: missing or invalid token.Restricted Access: the account is blocked, suspended or expired, or the user lacks the permission. | Send a valid token. ForRestricted Access, retrying will not help. | |403 Forbidden| Writes not yet approved in Production, the token lacks theread/writeability, or the token's company is no longer yours. Body:{"msg": "..."}. | Test in the Sandbox and contact us; or create a token with the right ability or company. | |404 Not Found|This resource is not found: no such record in your account.Not found: unknown URL. | Check the id and the path. | |405 Method Not Allowed| The URL does not accept this HTTP method. | Use the documented method. | |409 Conflict| Only on invoice updates that sendloaded_at: the invoice changed after that time. | Read the invoice again, then resend your update. | |422 Unprocessable Entity| Validation failed.errorslists each invalid field. | Fix the listed fields and resend. | |429 Too Many Requests| Over 60 requests per minute. | WaitRetry-Afterseconds, then retry. | |500 Internal Server Error| Unexpected server error, logged withdata.insidentId. | Contact support with the id. Before resending a create, list the resource to check it was not created. |
Error messages are always in English.
Error response
This API returns both, machine-readable error codes and human-readable error messages in response body when an error is encountered.
Examples
Resource not found
Code
Validation Error
Code
Generic Error
Code