Create Invoice

Create a new invoice on your Terraswitch account.

POST {{ BASE_URL }}/v1/corporate/invoice

Body Parameters

Property	Data Type	Description	Example	Required
name	string	The name of the invoice.	"Quick Invoice"	Yes
number	string	The invoice number. Ensure this contain no spaces and special characters. underscore or hyphen can be used to separate characters	"QINK_00018"	Yes
dueAt	string	The invoice due date and time. Format is yyyy/mm/dd hh:mm:ss OR yyyy-mm-dd hh:mm:ss	"2024/01/28 00:30:45"	Yes
description	string	Invoice description	"New quick invoice"	No
recipient	object	An object that holds the invoice recipient's data and informaion.	N/A	Yes
recipient.type	string	Recipient type. This can be individual or business. Defaulted to business	"business"	Yes
recipient.businessName	string	Recipient business name. This required only if recipient type is business	"NANST Solutions"	Yes if type is business
recipient.firstName	string	Recipient first name	"Oluwatobi"	Yes
recipient.lastName	string	Recipient last name	"Immanuel"	Yes
recipient.email	string	Recipient email address	"[e-mail]"	Yes
recipient.phoneNumber	string	Recipient's 11-digit phone number	"08137031202"	Yes
recipient.phoneCode	string	Country phoneCode for the phoneNumber provided. Use the List Countries endpoint to get phoneCode.	"+234"	Yes
recipient.countryCode	string	Country code of the recipient's nationality. Use the List Countries endpoint to get code2 of the country.	"NG"	Yes
recipient.address	string	Address of the recipient	"New NANST address"	Yes
recipient.city	string	City of the recipient	"Ikeja"	Yes
recipient.state	string	State of the recipient	"Lagos"	Yes
items	array[object]	An array of objects that holds the invoice items.	N/A	Yes
items.name	string	item name	"Brown D&G bag"	Yes
items.price	number	Item price	1500.99	Yes
items.quantity	number	Item quantity	2	Yes
vat	object	An object that holds the VAT data of the invoice	N/A	No
vat.title	string	VAT title	"Tax"	Yes
vat.type	string	VAT type. This can be percentage or flat	"percentage"	Yes
vat.value	number	VAT value	5	Yes
partial	number	If specified, this indicates that a part of the total amount due has been paid already.	2000	No
isLink	boolean	This indicates if a payment link should be generated when the invoice is created	true	No

Node.js

import Axios from 'axios';

// set the api url
const API_URL = `${BASE_URL}/v1/corporate/invoice`;

// define request body
const data = {
    name: "NANST-INV",
    dueAt: "2024/01/28 00:30:45", 
    number: "NANST-00124", 
    description: "Invoice for nanst limited", 
    partial: 0,
    isLink: false,
    vat: {
        title: "TAX",
        type: "percentage",
        value: 5
    },
    recipient: {
        type: "business",
        businessName: "NANST Solutions Limited",
        firstName: "Oluwatobi",
        lastName: "Immanuel",
        email: "[e-mail]",
        phoneNumber: "08137031202",
        phoneCode: "+234",
        countryCode: "NG",
        address: "Alausa, Ikeja Lagos.",
        city: "Ikeja",
        state: "Lagos"
    },
    items: [
        {
            name: "Brown D&G Bag",
            price: 2000.99,
            quantity: 2
        }
    ]
}

// make request using axios
Axios({
    method: "POST",
    url: `${API_URL}`,
    headers: {
        lg: 'en',
        ch: 'web'
        Authorization: `Bearer ${API_KEY}`,
        'Content-Type': 'application/json',
    },
    data: data
}).then((resp) => {
    console.log(resp)
}).catch((err) => {
    console.log(err)
})

Response

{
    "error": false,
    "errors": [],
    "data": {
        "code": "VPIB3E319FB",
        "name": "NANST-INV",
        "number": "NANST-00124",
        "status": "pending",
        "link": "https://staging-web.terraswitch.com/invoice/VPIB3E319FB",
        "VAT": {
            "title": "TAX",
            "type": "percentage",
            "value": 5
        },
        "summary": {
            "subtotal": 4001.98,
            "partialAmount": 0,
            "totalAmount": 4202.08
        },
        "description": "Invoice for nanst limited",
        "isEnabled": true,
        "inflow": {
            "value": 0,
            "count": 0
        },
        "items": [
            {
                "label": "ITMKFMFWS",
                "name": "Brown D&G Bag",
                "price": 2000.99,
                "quantity": 2,
                "total": 4001.98
            }
        ],
        "dueAt": {
            "date": "2024-01-28",
            "time": "00:30:45",
            "ISO": "2024-01-28T00:30:45.000Z"
        },
        "issuedAt": {
            "date": "2024-01-13",
            "time": "18:31:23",
            "ISO": "2024-01-13T18:31:23.094Z"
        },
        "paymentLink": "",
        "recipient": {
            "type": "business",
            "businessName": "NANST Solutions Limited",
            "firstName": "Oluwatobi",
            "lastName": "Immanuel",
            "email": "[e-mail]",
            "phoneNumber": "08137031202",
            "phoneCode": "+234",
            "countryCode": "NG",
            "address": "Alausa, Ikeja Lagos.",
            "city": "Ikeja",
            "state": "Lagos"
        },
        "createdAt": "2024-01-13T18:31:23.061Z",
        "updatedAt": "2024-01-13T18:31:23.113Z"
    },
    "message": "successful",
    "status": 200
}