Billit API Docs

Introduction

Billit API gives you the ability to connect to your billit.io account, retrieve your clients, check your invoice status, see your balance and your Tax obligations. 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.

A few links that will be handy:

Sandbox

Production

The API has a limit of 120 requests/minute.

If you hit that limit you get an error with status code 429 "Too Many Requests"

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 Sandbox,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.

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

Authorization: Bearer dAmj16gJe0YNrjw6x9EBpMm7IAahs0M5ZQGiNZ7rnfRBAG5oN3ocTjnwidmd

If you want to test your credentials just make a POST request with the Authorization Header to https://api.sandbox-billit.xyz and you will receive a 200OK response with the following json body

{'msg' : 'Hello from the Billit API'}

The '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 /invoice 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.

Pagination

This API uses pagination when retrieves a lot of results. The default (per page ) but you can choose anything you want by sending a parameter of "per_page" with an INT.

  • Default is 25

  • Max is 250

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.

  • DELETE - Delete - used to delete a resource identified by a URI.

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 in your account settings. You can check the date format if you make a get request to /account endpoint. You can alter this only from your app dashboard settings as always.

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).

  • 400 Bad Request - Malformed request; form validation errors.

  • 401 Unauthorized - When no or invalid authentication details are provided.

  • 403 Forbidden - When authentication succeeded but authenticated user doesn't have access to the resource.

  • 404 Not Found - When a non-existent resource is requested.

  • 405 Method Not Allowed - Method not allowed.

  • 406 Not Acceptable - Could not satisfy the request Accept header.

  • 415 Unsupported Media Type - Unsupported media type in request.

  • 422 Validation error - You should check your input again.

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
{
    "statusCode": 404,
    "error": "This resource is not found",
    "message": "",
    "data": []
}
Validation Error
{
  "statusCode": 422
  "error": "Validation Failed"
  "message": "Your input had some validation errors."
  "errors": {
    "company": [
      0 => "The 'Company' field is required."
    ]
  }
}
Generic Error
{
    "statusCode": 400,
    "error": "Bad Request",
    "message": "Request was logged for investigation.",
    "data": {
        "insidentId": "8dc6e605-dd53-4180-9026-db9316a87967"
    }
}

Customers

List customers

GET /customers Customers list

Example URI

GET https://api.sandbox-billit.xyz/customers

URI Parameters

Parameter Description
q

string  (optional)  Example: Testing S.A.

If you want to list customers by a search term. Lookup is on Company name, VatID, Telephone,Email.

unpaid

string  (optional)  Example: 1

If you want to list only customer with unpaid invoices

tagid

string  (optional)  Example: 24

If you want to filter by a Tag, fill in the Tag ID

withRelations

string  (optional)  Example: 1

If you want to load model relationships as well with one call.

per_page

string  (optional)  Example: 100

Set the results per page limit. Default is 25.

Examples

Click on Request/Response to expand an example and Schema Details.

Create customer

POST /customers Create customer

Create a new customer to your billit account.

Example URI

POST https://api.sandbox-billit.xyz/customers

Examples

Click on Request/Response to expand an example and Schema Details.

Show customer

GET /customers/{id} Show customer

Retrieves a specific customer by ID.

Example URI

GET https://api.sandbox-billit.xyz/customers/1312

URI Parameters

Parameter Description
id

string  (optional)  Example: 1312

ID of the customer

Examples

Click on Request/Response to expand an example and Schema Details.

Update customer

PUT /customers/{id} Update customer

Update a customer.

Example URI

PUT https://api.sandbox-billit.xyz/customers/1312

URI Parameters

Parameter Description
id

string  (optional)  Example: 1312

ID of the customer

Examples

Click on Request/Response to expand an example and Schema Details.

Delete customer

DELETE /customers/{id} Delete customer

Delete a customer.

Example URI

DELETE https://api.sandbox-billit.xyz/customers/1312

URI Parameters

Parameter Description
id

string  (optional)  Example: 1312

ID of the customer

Examples

Click on Request/Response to expand an example and Schema Details.

Invoices

List Invoices

GET /invoices Invoices list

You can fetch a list of your invoices with pagination. Optionally you can search/filter the results of your query by using any of the following parameters in your request.

Example URI

GET https://api.sandbox-billit.xyz/invoices

URI Parameters

Parameter Description
q

string  (optional)  Example: Testing S.A.

If you want to list customers by a search term. Lookup is on Company name, VatID, Telephone,Email.

unpaid

string  (optional)  Example: 1

If you want to list only customer with unpaid invoices

startdate

string  (optional)  Example: 01-10-2019

If you want to filter from a certain Date (lookup in dateIssued field). Please note that the date format can be set in your settings options in your app account.

enddate

string  (optional)  Example: 30-10-2019

If you want to filter until a certain Date (lookup in dateExpires field). Please note that the date format can be set in your settings options in your app account.

invcat

string  (optional)  Example: 101

If you want to list only a certain Invoice type

tagid

string  (optional)  Example: 24

If you want to filter by a Tag, fill in the Tag ID

scheduled

string  (optional)  Example: 1

If you want to list only scheduled invoices

withRelations

string  (optional)  Example: 1

If you want to load model relationships as well with one call.

per_page

string  (optional)  Example: 100

Set the results per page limit. Default is 25.

Examples

Click on Request/Response to expand an example and Schema Details.

Create invoice

POST /invoices Create invoice

Create a new invoice to your billit account.

Example URI

POST https://api.sandbox-billit.xyz/invoices

Examples

Click on Request/Response to expand an example and Schema Details.

Show invoice

GET /invoices/{uuid} Show invoice

Retrieves an invoice

Example URI

GET https://api.sandbox-billit.xyz/invoices/30922f91-2245-4b12-93eb-44e2f50a13a0

URI Parameters

Parameter Description
uuid

string  (required)  Example: 30922f91-2245-4b12-93eb-44e2f50a13a0

Unique identifier of invoice

Examples

Click on Request/Response to expand an example and Schema Details.

Update invoice

PUT /invoices/{uuid} Update invoice

Update an existing invoice. Be really carefull with this option as your client may have already forwarded the invoice to the TaxOffice. Always make sure this is not the case.

Example URI

PUT https://api.sandbox-billit.xyz/invoices/30922f91-2245-4b12-93eb-44e2f50a13a0

URI Parameters

Parameter Description
uuid

string  (required)  Example: 30922f91-2245-4b12-93eb-44e2f50a13a0

Unique identifier of invoice

Examples

Click on Request/Response to expand an example and Schema Details.

Delete invoice

DELETE /invoices/{uuid} Delete invoice

Delete an invoice.

Example URI

DELETE https://api.sandbox-billit.xyz/invoices/30922f91-2245-4b12-93eb-44e2f50a13a0

URI Parameters

Parameter Description
uuid

string  (required)  Example: 30922f91-2245-4b12-93eb-44e2f50a13a0

Unique identifier of invoice

Examples

Click on Request/Response to expand an example and Schema Details.

Products

List products

GET /products Products list

Example URI

GET https://api.sandbox-billit.xyz/products

URI Parameters

Parameter Description
has_stock

string  (optional)  Example: true

Show only products that their stock is tracked.

stock_less

string  (optional)  Example: 5

Show only products that their stock is less thank this number.

stock_greater

string  (optional)  Example: 10

Show only products that their stock is less thank this number.

tag_id

string  (optional)  Example: 100

Show only products that are using a certain tag.

per_page

string  (optional)  Example: 100

Set the results per page limit. Default is 25.

Examples

Click on Request/Response to expand an example and Schema Details.

Create product

POST /products Create product

Create a new product to your billit account.

Example URI

POST https://api.sandbox-billit.xyz/products

Examples

Click on Request/Response to expand an example and Schema Details.

Show product

GET /products/{id} Show product

Retrieves a specific product by ID.

Example URI

GET https://api.sandbox-billit.xyz/products/1001

URI Parameters

Parameter Description
id

string  (optional)  Example: 1001

ID of the product

Examples

Click on Request/Response to expand an example and Schema Details.

Update product

PUT /products/{id} Update product

Update a product.

Example URI

PUT https://api.sandbox-billit.xyz/products/1312

URI Parameters

Parameter Description
id

string  (optional)  Example: 1312

ID of the customer

Examples

Click on Request/Response to expand an example and Schema Details.

Delete product

DELETE /products/{id} Delete product

Delete a product.

Example URI

DELETE https://api.sandbox-billit.xyz/products/2412

URI Parameters

Parameter Description
id

string  (optional)  Example: 2412

ID of the customer

Examples

Click on Request/Response to expand an example and Schema Details.

Payments

List payments

GET /payments Index payments

Example URI

GET https://api.sandbox-billit.xyz/payments

URI Parameters

Parameter Description
per_page

string  (optional)  Example: 100

Set the results per page limit. Default is 25.

Examples

Click on Request/Response to expand an example and Schema Details.

Create payment

POST /payments Create payment

Create a new payment to your billit account.

Example URI

POST https://api.sandbox-billit.xyz/payments

Examples

Click on Request/Response to expand an example and Schema Details.

Delete payment

DELETE /payments/{id} Delete payment

Delete a payment.

Example URI

DELETE https://api.sandbox-billit.xyz/payments/100

URI Parameters

Parameter Description
id

string  (required)  Example: 100

ID of the payment

Examples

Click on Request/Response to expand an example and Schema Details.

Purchases

List purchases

GET /purchases Purchases list

Example URI

GET https://api.sandbox-billit.xyz/purchases

URI Parameters

Parameter Description
per_page

string  (optional)  Example: 100

Set the results per page limit. Default is 25.

Examples

Click on Request/Response to expand an example and Schema Details.

Create purchase

POST /purchases Create purchase

Create a new purchace to your billit account.

Example URI

POST https://api.sandbox-billit.xyz/purchases

Examples

Click on Request/Response to expand an example and Schema Details.

Show purchase

GET /purchases/{id} Show purchase

Retrieves a specific purchase by ID.

Example URI

GET https://api.sandbox-billit.xyz/purchases/1312

URI Parameters

Parameter Description
id

string  (optional)  Example: 1312

ID of the purchase

Examples

Click on Request/Response to expand an example and Schema Details.

Delete purchase

DELETE /purchases/{id} Delete purchase

Delete a purchase.

Example URI

DELETE https://api.sandbox-billit.xyz/purchases/1312

URI Parameters

Parameter Description
id

string  (optional)  Example: 1312

ID of the purchase

Examples

Click on Request/Response to expand an example and Schema Details.

Tags

List tags

GET /tags Tags list

Example URI

GET https://api.sandbox-billit.xyz/tags

URI Parameters

Parameter Description
tag

string  (optional)  Example: tagname

Search by tag name

per_page

string  (optional)  Example: 100

Set the results per page limit. Default is 25.

Examples

Click on Request/Response to expand an example and Schema Details.

Show tag

GET /tags/{id} Show tag

Retrieves a specific tag by ID.

Example URI

GET https://api.sandbox-billit.xyz/tags/1551

URI Parameters

Parameter Description
id

string  (optional)  Example: 1551

ID of the tag

Examples

Click on Request/Response to expand an example and Schema Details.

Delete tag

DELETE /tags/{id} Delete tag

Delete a tag.

Example URI

DELETE https://api.sandbox-billit.xyz/tags/1551

URI Parameters

Parameter Description
id

string  (optional)  Example: 1551

ID of the tag

Examples

Click on Request/Response to expand an example and Schema Details.

Suppliers

List suppliers

GET /suppliers Suppliers list

Example URI

GET https://api.sandbox-billit.xyz/suppliers

URI Parameters

Parameter Description
q

string  (optional)  Example: companyName

Search by company name,email,telephone or Vat ID.

withRelations

string  (optional)  Example: 1

If you want to load model relationships as well with one call.

per_page

string  (optional)  Example: 100

Set the results per page limit. Default is 25.

Examples

Click on Request/Response to expand an example and Schema Details.

Show supplier

GET /suppliers/{id} Show supplier

Retrieves a specific supplier by ID.

Example URI

GET https://api.sandbox-billit.xyz/suppliers/9090

URI Parameters

Parameter Description
id

string  (optional)  Example: 9090

ID of the supplier

Examples

Click on Request/Response to expand an example and Schema Details.

Delete supplier

DELETE /suppliers/{id} Delete supplier

Delete a supplier.

Example URI

DELETE https://api.sandbox-billit.xyz/suppliers/9090

URI Parameters

Parameter Description
id

string  (optional)  Example: 9090

ID of the supplier

Examples

Click on Request/Response to expand an example and Schema Details.

My Account

Show account

GET /account Show my account

Example URI

GET https://api.sandbox-billit.xyz/account

Examples

Click on Request/Response to expand an example and Schema Details.