npm:easyinvoice

README

Build for Web and Backend 💪

If this package helped you out please star us on Github!
Much appreciated!

Important

Easy Invoice v1.x is deprecated and will stop working from the 1st of April 2022.
Please upgrade to v2.x before this time.

EASY products

Package	Description	Link
Easy PDF	Easy PDF Creator
Easy Invoice	Easy Invoice Creator

Platform support

Platform	Repository	Supported
PHP	Composer	Yes!
Javascript	NPM	Yes!
Python	PIP	Yes!
Java	Maven	In progress...

Sample

JSON Configs used for above samples:

Demo

JS Fiddle: Plain Javascript
JS Fiddle: Vue
JS Fiddle: React
JS Fiddle: Angular

Step-by-step guide

Read our step-by-step guide on Medium. Click here!

Installing

Using npm:

$ npm install easyinvoice --save

Using yarn:

$ yarn add easyinvoice

CDN

Using unkpg CDN:


<script src="https://unpkg.com/easyinvoice/dist/easyinvoice.min.js"></script>

Using jsDelivr CDN:


<script src="https://cdn.jsdelivr.net/npm/easyinvoice/dist/easyinvoice.min.js"></script>

Import

CommonJS

var easyinvoice = require('easyinvoice');

ES6 =<

import easyinvoice from 'easyinvoice';

Direct REST API access

# HTTPS POST 
https://api.easyinvoice.cloud/v2/free/invoices

# POST Data
Format: JSON
Structure: {"data":{"products":[]}} # Parent object must be 'data'

Getting Started - Basic Example

NodeJS

// Import the library into your project
var easyinvoice = require('easyinvoice');

// Create your invoice! Easy!
var data = {};
easyinvoice.createInvoice(data, function (result) {
    // The response will contain a base64 encoded PDF file
    console.log('PDF base64 string: ', result.pdf);

    // Now this result can be used to save, download or render your invoice
    // Please review the documentation below on how to do this
});

Web


<html>
<head>
    // Import the library into your project
    <script src="https://unpkg.com/easyinvoice/dist/easyinvoice.min.js"></script>
</head>
<body>
<script>
    // Create your invoice! Easy!
    var data = {};
    easyinvoice.createInvoice(data, function (result) {
        // The response will contain a base64 encoded PDF file
        console.log('PDF base64 string: ', result.pdf);

        // Now this result can be used to save, download or render your invoice
        // Please review the documentation below on how to do this
    });
</script>
</body>
</html>

Complete Example (NodeJS)

//Import the library into your project
var easyinvoice = require('easyinvoice');

var data = {
    // Customize enables you to provide your own templates
    // Please review the documentation for instructions and examples
    "customize": {
        //  "template": fs.readFileSync('template.html', 'base64') // Must be base64 encoded html 
    },
    "images": {
        // The logo on top of your invoice
        "logo": "https://public.easyinvoice.cloud/img/logo_en_original.png",
        // The invoice background
        "background": "https://public.easyinvoice.cloud/img/watermark-draft.jpg"
    },
    // Your own data
    "sender": {
        "company": "Sample Corp",
        "address": "Sample Street 123",
        "zip": "1234 AB",
        "city": "Sampletown",
        "country": "Samplecountry"
        //"custom1": "custom value 1",
        //"custom2": "custom value 2",
        //"custom3": "custom value 3"
    },
    // Your recipient
    "client": {
        "company": "Client Corp",
        "address": "Clientstreet 456",
        "zip": "4567 CD",
        "city": "Clientcity",
        "country": "Clientcountry"
        // "custom1": "custom value 1",
        // "custom2": "custom value 2",
        // "custom3": "custom value 3"
    },
    "information": {
        // Invoice number
        "number": "2021.0001",
        // Invoice data
        "date": "12-12-2021",
        // Invoice due date
        "due-date": "31-12-2021"
    },
    // The products you would like to see on your invoice
    // Total values are being calculated automatically
    "products": [
        {
            "quantity": 2,
            "description": "Product 1",
            "tax-rate": 6,
            "price": 33.87
        },
        {
            "quantity": 4.1,
            "description": "Product 2",
            "tax-rate": 6,
            "price": 12.34
        },
        {
            "quantity": 4.5678,
            "description": "Product 3",
            "tax-rate": 21,
            "price": 6324.453456
        }
    ],
    // The message you would like to display on the bottom of your invoice
    "bottom-notice": "Kindly pay your invoice within 15 days.",
    // Settings to customize your invoice
    "settings": {
        "currency": "USD", // See documentation 'Locales and Currency' for more info. Leave empty for no currency.
        // "locale": "nl-NL", // Defaults to en-US, used for number formatting (See documentation 'Locales and Currency')
        // "tax-notation": "gst", // Defaults to 'vat'
        // "margin-top": 25, // Defaults to '25'
        // "margin-right": 25, // Defaults to '25'
        // "margin-left": 25, // Defaults to '25'
        // "margin-bottom": 25, // Defaults to '25'
        // "format": "A4" // Defaults to A4, options: A3, A4, A5, Legal, Letter, Tabloid
    },
    // Translate your invoice to your preferred language
    "translate": {
        // "invoice": "FACTUUR",  // Default to 'INVOICE'
        // "number": "Nummer", // Defaults to 'Number'
        // "date": "Datum", // Default to 'Date'
        // "due-date": "Verloopdatum", // Defaults to 'Due Date'
        // "subtotal": "Subtotaal", // Defaults to 'Subtotal'
        // "products": "Producten", // Defaults to 'Products'
        // "quantity": "Aantal", // Default to 'Quantity'
        // "price": "Prijs", // Defaults to 'Price'
        // "product-total": "Totaal", // Defaults to 'Total'
        // "total": "Totaal" // Defaults to 'Total'
    },
};

//Create your invoice! Easy!
easyinvoice.createInvoice(data, function (result) {
    //The response will contain a base64 encoded PDF file
    console.log('PDF base64 string: ', result.pdf);
});

Return values

Key	Value	Data Type
result.pdf	The PDF file as base64 string	String
result.calculations.products	Array of objects reflecting the products used in creation	Array
result.calculations.products[key].subtotal	Rounded price without tax per product	Number
result.calculations.products[key].tax	Rounded tax per product	Number
result.calculations.products[key].total	Rounded price including tax per product	Number
result.calculations.tax	Array of objects containing total calculated tax per unique tax rate	Array
result.calculations.tax[rate]	Total tax for all products with same tax rate	Number
result.calculations.subtotal	Rounded price without tax for all products	Number
result.calculations.total	Rounded price without tax for all products	Number

Locales and Currency

Used for number formatting and the currency symbol:

//E.g. for Germany, prices would look like 123.456,78 €
const data = {settings: {locale: 'de-DE', currency: 'EUR'}};

//E.g. for US, prices would look like $123,456.78
const data = {settings: {locale: 'en-US', currency: 'USD'}};

Formatting and symbols are applied through the ECMAScript Internationalization API

Click here for a list of locale codes
Click here for a list of currency codes

Disclaimer: Not all locales and currency codes found in the above lists might be supported by the ECMAScript Internationalization API.

Logo and Background

The logo and background inputs accept either a URL or a base64 encoded file.

Supported file types:

Logo: image
Background: image, pdf

URL

const data = {
    images: {
        logo: "https://public.easyinvoice.cloud/img/logo_en_original.png",
        background: "https://public.easyinvoice.cloud/img/watermark_draft.jpg",
    }
};

Base64

const data = {
    //Note: Sample base64 string
    //Please use the link below to convert your image to base64
    images: {
        logo: "iVBORw0KGgoAAAANSUhEUgAAAAUAAAAFCAYAAACNbyblAAAAHElEQVQI12P4//8/w38GIAXDIBKE0DHxgljNBAAO9TXL0Y4OHwAAAABJRU5ErkJggg==",
        background: "iVBORw0KGgoAAAANSUhEUgAAAAUAAAAFCAYAAACNbyblAAAAHElEQVQI12P4//8/w38GIAXDIBKE0DHxgljNBAAO9TXL0Y4OHwAAAABJRU5ErkJggg=="
    }
};

Local File (NodeJS only)

//Import fs to be able to read from the local file system
var fs = require("fs");

//Use the code below to read your local file as a base64 string
const data = {
    images: {
        logo: fs.readFileSync('logo.png', 'base64'),
        background: fs.readFileSync('images/background.png', 'base64')
    }
};

Click here for an online tool to convert an image to base64

Async/await support

// Import the library into your project
var easyinvoice = require('easyinvoice');

// Create your invoice! Easy!
var data = {};
const result = await easyinvoice.createInvoice(data);

// The response will contain a base64 encoded PDF file
console.log('PDF base64 string: ', result.pdf);

To store the file locally (NodeJS)

var fs = require('fs');

var data = {};
const result = await easyinvoice.createInvoice(data);
await fs.writeFileSync("invoice.pdf", result.pdf, 'base64');

Download your invoice (browser only)

Using callback

var data = {};
easyinvoice.createInvoice(data, function (result) {
    easyinvoice.download('myInvoice.pdf', result.pdf);
    //	you can download like this as well:
    //	easyinvoice.download();
    //	easyinvoice.download('myInvoice.pdf');   
});

Using async/await

var data = {};
const result = await easyinvoice.createInvoice(data);
easyinvoice.download('myInvoice.pdf', result.pdf);
//	you can download like this as well:
//	easyinvoice.download();
//	easyinvoice.download('myInvoice.pdf');

Render(view) your invoice (browser only)

html

<!-- Only include when rendering is required -->
<script src="https://unpkg.com/pdfjs-dist/build/pdf.min.js"></script>
<script src="https://unpkg.com/pdfjs-dist/build/pdf.worker.min.js"></script>

<!-- Include pdfjs version 2.3.200 for Internet Explorer compatibility, no worker required -->
<!-- <script src="https://unpkg.com/pdfjs-dist@2.3.200/build/pdf.min.js"></script> -->

<!-- The pdf will be rendered within this div -->
<div id="pdf"></div>

css (optional)

#pdf {
    text-align: center;
}

#pdf canvas {
    border: 1px solid black;
    width: 95%;
}

js: Using Callback

var data = {};
var elementId = 'pdf';
easyinvoice.createInvoice(data, function (result) {
    easyinvoice.render(elementId, result.pdf, function () {
        console.log('Invoice rendered!');
    });
});

js: Using async/await

var data = {};
const elementId = 'pdf';
const result = await easyinvoice.createInvoice(data);
await easyinvoice.render(elementId, result.pdf);

Template customization

Download our default template (invoice-v2) here to have an example which you can customize.