Developer resources

Getting Started.

The Invoice Ninja API is built on top of the Laravel Framework, this is a hugely popular PHP framework with extensive high quality documentation and tutorials all over the web. To get started customizing and/or extending Invoice Ninja you will need to be acquainted with the latest version of Laravel and all of its features. The URL namespace for the api is /api/v1 The Client Portal is a traditional web application also built with Laravel along with Livewire and Tailwind components. The URL namespace for client facing URLs is /client/

If you are planning to build new functionality in Invoice Ninja, for example a Inventory Module, rather than integrate this directly into the codebase, we highly recommend using the Laravel Modules library. This library is already part of the Invoice Ninja core, so you can dive straight in and start building.

If you plan to contribute your code back to the official Invoice Ninja repository, please ensure you have test coverage for your functionality. We use Phpunit for our API testing, and Cypress for our UI testing of the client portal.

API Definition

Our full API definition can be found on swagger here

Migrating from v4

Invoice Ninja v4 was initially built as a web application with an API added on later to support common uses cases and the limited functionality of the v4 mobile app. With v5 we’ve instead built an API first application, all features in the web/mobile/desktop apps are powered by the API.

For example v4 client includes are limited to contacts, invoices, credits and activities, whereas in v5 where all options are available. This includes: contacts, documents, gateway_tokens, documents, gateway_tokens, activities, ledger and system_logs.

Another major shortcoming of the v4 API is the docs, even though the functionality is limited, what is available isn’t necessarily documented. In v5 we’ve made sure to document every aspect of the API.

The v4 and v5 APIs are mostly the same but there are some key changes which are important to be aware of.

::: warning The header name for the API token has changed from X-Ninja-Token in v4 to X-API-Token in v5. :::

The data type of the id fields has changes from integer to string to support the new id format.

The route for uploading documents has changed, here's a v5 cURL example:

curl -X POST<invoice_id> \
  -H 'Content-Type: multipart/form-data' \
  -H 'X-Requested-With: XMLHttpRequest' \
  -F _method=PUT \
  -F 'documents[]=@filename.png'

Adding payment gateways

Payment Driver Template.

So you want to make a payment driver for invoice ninja, but don't know where to start? The first step would be to reach out to us directly on Slack and have a chat to us in real time so that we can help you hit the ground running and build your driver in the most efficient way possible. Contacting us prior will also ensure that your code can be merged back into the official repository as we will be maintaining this code into the future.

Ready? Lets go!

Step 1. Setup environment

You should update your code to be up to date with the v5-develop branch.

You will then want to create your own branch for for your driver ie.

git branch my_payment_driver

Step 2. Adding the gateway into the gateways table

Lets create a migration file which will insert a record identifying the gateway.

php artisan make:migration my_new_gateway

Let open this file and in the up() method create our new gateway record

Init a new gateway instance

$gateway = new Gateway;
$gateway->name = 'Fancy Gateway'; 
$gateway->key = Str::lower(Str::random(32)); 
$gateway->provider = ‘FancyGateway’;
$gateway->is_offsite = true;
$gateway->fields = new \stdClass;
$gateway->visible = true;
$gateway->site_url = ‘’;
$gateway->default_gateway_type_id = 1;

Gateway Properties

    const CREDIT_CARD = 1;
    const BANK_TRANSFER = 2;
    const PAYPAL = 3;
    const CRYPTO = 4;
    const CUSTOM = 5;
    const ALIPAY = 6;
    const SOFORT = 7;
    const APPLE_PAY = 8;
    const SEPA = 9;
    const CREDIT = 10;
Want to contribute? Edit this page on GitHub!