Invoices

Create New Invoice

post /businesses/:urlKey/invoices

This endpoint allows you to create an invoice

Request

Path Params

urlKey - will be provided by us

Headers

Name	Type	Value Description
Content-Type *	string	application-json
Authorization *	string	Bearer <jwt>

Body

Name	Type	Value Description
invoiceTitle	string	Invoice Title
invoiceSubTitle	string	Invoice Subtitle
contact	object	Contact Details
contact.phone	string	phone of contact
contact.email	string	email of contact
invoiceNumber	string	Invoice number - must be unique among your invoices. If not passed in the API call, invoice number will auto-incremented from the last invoice. If the last number is APP-2020-0004 next will be APP-2020-0005
invoiceDate	string	ISO 8601 Formatted Date String. If not provided, current timestamp will be used.
dueDate	string	ISO 8601 Formatted Date String
invoiceType	string (enum)	INVOICE -> Tax Invoice BOS -> Invoice/Bill without tax
currency	string	ISO 4217 Currency Code -> Default INR
billedTo *	object	Customer's billing details
billedTo.name *	string	Customer's Name
billedTo.street	string	Customer's String Address
billedTo.pincode	string	Customer's Zip/Postal code
billedTo.gstState	string	(Required Only for India) Vendor's gst state code
billedTo.state	string	Customer's State or province (Ignored for India)
billedTo.country *	string	ISO 3166-1 alpha-2 Country code
billedTo.panNumber	string	PAN (India Only)
billedTo.gstin	string	GSTIN Number (India Only)
billedTo.phone	string	Customer's Phone in international format, example - +91 97394 32668
billedTo.email	email	Customer's email
billedTo.emailShowInInvoice	boolean	Show the customer's email on the invoice
billedTo.phoneShowInInvoice	boolean	Show the customer's phone on the invoice
billedBy	object	Vendor's billing details -> In same format as billedTo, including emailShowInInvoice and phoneShowInInvoice
shippedTo	object	Shipping recipient's details -> In same format as billedTo
shippedFrom	object	Shipping sender's details -> In same format as billedTo
transportDetails	object	Required for EWB generation in India
transportDetails.vehicleNumber	string	Vehicle number
transportDetails.vehicleType	string (enum)	REGULAR, OVERDIMENSIONALCARGO
transportDetails.transportMode	string (enum)	ROAD, RAIL, AIR, SHIP -- required when passing vehicleNumber
transportDetails.transporter	object	Transporter details
transportDetails.transporter.name	string	Required when passing transporter.transporterId
transportDetails.transporter.transporterId	string	Transporter GSTIN (15 chars) or TransId
transportDetails.challanNumber	string	Challan number
transportDetails.challanDate	string	ISO 8601 formatted date string
transportDetails.subSupplyType	string	For example, supply
items *	array[object]	Invoice line items array
items[].name *	string	Line item name
items[].rate *	number	unit price of line item
items[].quantity *	number	total quantity sold of line item
items[].gstRate or items[].taxRate	number	tax rate if applicable
additionalCharges	array[object]	Additional charges or invoice-level discounts. Applied after tax, on the post-tax amount.
additionalCharges[].label	string	Charge/Discount Label
additionalCharges[].amount	number	Charge/Discount amount
additionalCharges[].type	string (enum)	PERCENTAGE, FIXED_AMOUNT
additionalCharges[].multiplier	number	1 = additional charge; -1 = discount
terms	array[object]	Invoice terms
terms[].label	string	Terms label
terms[].terms	array[string]	List of term strings
tags	array[string]	Pass tag IDs. Contact Support to get IDs for tags created in your business.
email	object	Add if email should be sent after invoice creation to specified recipients
email.to	object	Main recipient of email
email.to.name	string	Name of main recipient
email.to.email	email	Email of main recipient
email.cc	array[object]	email CC list
email.cc[].name	string	Name of recipient
email.cc[].email	email	Email of recipient

Response

200: OK

Successful auth

{
  "_id": "60cc8cc6aa3024abd4bef447",
  "invoiceNumber": "APP-2020-0004",
  "invoiceDate": "2021-06-18T12:08:38.000Z",
  "currency": "INR",
  "billType": "INVOICE",
  "status": "UNPAID",
  "billedBy": {
    "name": "Vendor Name",
    "street": "Vendor street line",
    "city": "Bangalore",
    "pincode": "560100",
    "gstState": "29",
    "country": "IN"
  },
  "billedTo": {
    "name": "Customer Name",
    "street": "Customer street line",
    "city": "Bangalore",
    "pincode": "560100",
    "gstState": "29",
    "country": "IN"
  },
  "invoiceTitle": "Invoice",
  "discount": {
    "discountType": "PERCENTAGE"
  },

  "items": [
    {
      "discount": {
        "discountType": "PERCENTAGE"
      },
      "images": [],
      "_id": "60cc8cc6aa3024abd4bef448",
      "rate": 100,
      "quantity": 2,
      "gstRate": 18,
      "name": "Item one name",
      "igst": 36,
      "cgst": 18,
      "sgst": 18,
      "subTotal": 200,
      "amount": 200,
      "total": 236
    },
    {
      "discount": {
        "discountType": "PERCENTAGE"
      },
      "images": [],
      "_id": "60cc8cc6aa3024abd4bef449",
      "rate": 200,
      "quantity": 6,
      "gstRate": 12,
      "name": "Item two name",
      "igst": 144,
      "cgst": 72,
      "sgst": 72,
      "subTotal": 1200,
      "amount": 1200,
      "total": 1344
    }
  ],
  "client": "60cc8cc6aa3024abdsdf23dsf",
  "igst": false,
  "createdAt": "2021-06-18T12:08:38.606Z",
  "updatedAt": "2021-06-18T12:08:38.606Z",
  "finalTotal": {
    "total": 1580,
    "amount": 1400,
    "subTotal": 1400,
    "igst": 180,
    "cgst": 90,
    "sgst": 90,
    "discount": 0
  },
  "share": {
    "link": "<view link>",
    "pdf": "<pdf link>"
  },
  "terms": [],
  "attachments": [],
  "isExpenditure": false,
  "taxType": "INDIA",
  "locale": "en-IN",
  "tags": []
}

401: Unauthorized

Successful auth

{
  "name": "NotAuthenticated",
  "message": "Invalid login",
  "code": 401,
  "className": "not-authenticated",
  "data": {
    "message": "Invalid login"
  },
  "errors": {}
}

---

Find Invoices

get /businesses/:urlKey/invoices

This endpoint allows you to find created invoices

Request

Path Params

urlKey - will be provided by us

Headers

Name	Type	Value Description
Content-Type *	string	application-json
Authorization *	string	Bearer <jwt>

Query Prams

Optional - Can be used for limiting results

Name	Type	Value Description
$limit	number	will return only the number of results you specify
$skip	number	will skip the specified number of results.
$sort	object	will sort based on the object you provide.
$sort[createdAt]	number	sort order on created date (1 ascending, -1 descending)
$sort[invoiceNumber]	number	sort order on invoice number (1 ascending, -1 descending)
$sort[invoiceDate]	number	sort order on invoice date (1 ascending, -1 descending)

Response

200: OK

Successful auth

{
  total:20,
  limit: 10,
  skip: 0,
  data: [
    {...invoices}
  ]
}

401: Unauthorized

Successful auth

{
  "name": "NotAuthenticated",
  "message": "Invalid login",
  "code": 401,
  "className": "not-authenticated",
  "data": {
    "message": "Invalid login"
  },
  "errors": {}
}

Get Invoice

get /businesses/:urlKey/invoices/:invoiceId

This endpoint allows you to get a invoice via invoiceId (_id)

Request

Path Params

urlKey - will be provided by us

invoiceId - unique id of an invoice. (_id returned in create response or find response)

Headers

Name	Type	Value Description
Content-Type *	string	application-json
Authorization *	string	Bearer <jwt>

Response

200: OK

Successful auth

{
  "_id": "60cc8cc6aa3024abd4bef447",
  "invoiceNumber": "APP-2020-0004",
  "invoiceDate": "2021-06-18T12:08:38.000Z",
  "currency": "INR",
  "billType": "INVOICE",
  "status": "UNPAID",
  "billedBy": {
    "name": "Vendor Name",
    "street": "Vendor street line",
    "city": "Bangalore",
    "pincode": "560100",
    "gstState": "29",
    "country": "IN"
  },
  "billedTo": {
    "name": "Customer Name",
    "street": "Customer street line",
    "city": "Bangalore",
    "pincode": "560100",
    "gstState": "29",
    "country": "IN"
  },
  "invoiceTitle": "Invoice",
  "discount": {
    "discountType": "PERCENTAGE"
  },

  "items": [
    {
      "discount": {
        "discountType": "PERCENTAGE"
      },
      "images": [],
      "_id": "60cc8cc6aa3024abd4bef448",
      "rate": 100,
      "quantity": 2,
      "gstRate": 18,
      "name": "Item one name",
      "igst": 36,
      "cgst": 18,
      "sgst": 18,
      "subTotal": 200,
      "amount": 200,
      "total": 236
    },
    {
      "discount": {
        "discountType": "PERCENTAGE"
      },
      "images": [],
      "_id": "60cc8cc6aa3024abd4bef449",
      "rate": 200,
      "quantity": 6,
      "gstRate": 12,
      "name": "Item two name",
      "igst": 144,
      "cgst": 72,
      "sgst": 72,
      "subTotal": 1200,
      "amount": 1200,
      "total": 1344
    }
  ],
  "client": "60cc8cc6aa3024abdsdf23dsf",
  "igst": false,
  "createdAt": "2021-06-18T12:08:38.606Z",
  "updatedAt": "2021-06-18T12:08:38.606Z",
  "finalTotal": {
    "total": 1580,
    "amount": 1400,
    "subTotal": 1400,
    "igst": 180,
    "cgst": 90,
    "sgst": 90,
    "discount": 0
  },
  "share": {
    "link": "<view link>",
    "pdf": "<pdf link>"
  },
  "terms": [],
  "attachments": [],
  "isExpenditure": false,
  "taxType": "INDIA",
  "locale": "en-IN",
  "tags": []
}

401: Unauthorized

Successful auth

{
  "name": "NotAuthenticated",
  "message": "Invalid login",
  "code": 401,
  "className": "not-authenticated",
  "data": {
    "message": "Invalid login"
  },
  "errors": {}
}

---

Cancel Invoice

patch /businesses/:urlKey/invoices/:invoice?cancelPayment=true

This endpoint allows you to update an invoice for a specific business.

Request

Path Params

urlKey - The unique identifier of the business.
invoice - The invoice ID for which the status is to be updated.

Query Params

Name	Type	Value Description
cancelPayment	boolean	Set to true if you want to cancel the associated payments.

Headers

Name	Type	Value Description
Content-Type *	string	application-json
Authorization *	string	Bearer <jwt>

Body

{
  "status": "CANCELED"
}

Response

200: OK

Upon successful execution, the API responds with a status code of 200 and a JSON object containing the updated details of the invoice.

{
  "_id": "60cc8cc6aa3024abd4bef447",
  "invoiceNumber": "APP-2020-0004",
  "status": "CANCELED",
  "currency": "INR",
  "invoiceTitle": "Invoice",
  "billType": "INVOICE",
  "discount": {
    "discountType": "PERCENTAGE"
  },
  "items": [
    {
      "name": "Item one name",
      "rate": 100,
      "quantity": 2,
      "gstRate": 18,
      "amount": 200,
      "total": 236
    }
  ],
  "payments": [],
  "finalTotal": {
    "total": 0,
    "amount": 0,
    "subTotal": 0,
    "igst": 0,
    "cgst": 0,
    "sgst": 0,
    "discount": 0
  },
  "updatedAt": "2024-08-18T12:08:38.000Z"
}

401: Unauthorized

Invalid authentication.

{
  "name": "NotAuthenticated",
  "message": "Invalid login",
  "code": 401,
  "className": "not-authenticated",
  "data": {
    "message": "Invalid login"
  },
  "errors": {}
}