Zoho Books: Get Invoice Payment Terms via API

: Joel Lipman; Zoho; 06 July 2023; Hits: 2213

What?
A quick article on getting the payment terms in Zoho Books along with their IDs.

Why?
I often need to send through an automatic payment term on the creation of an invoice but lots of my clients set their due dates differently.

How?
The following snippet of code will query the metadata api in Zoho Books and return a JSON of what the payment terms are.

copy raw

void fn_ReturnCurrentPaymentTerms()
{
	v_BooksOrgID = "12345678901";
	r_PaymentTerms = invokeurl
	[
		url :"https://books.zoho.com/api/v3/settings/paymentterms?organization_id=" + v_BooksOrgID
		type :GET
		connection:"abzohobooks"
	];
	info r_PaymentTerms;
}

void fn_ReturnCurrentPaymentTerms()
{
v_BooksOrgID = "12345678901";
r_PaymentTerms = invokeUrl
[
url :"https://books.zoho.com/api/v3/settings/paymentterms?organization_id=" + v_BooksOrgID
type :GET
connection:"abzohobooks"
];
info r_PaymentTerms;
}

This should yield something as follows:

copy raw

{
  "code": 0,
  "message": "success",
  "data": {
    "payment_terms": [
      {
        "payment_terms_id": "123456000000000123",
        "payment_terms": 15,
        "is_default": false,
        "payment_terms_label": "Net 15"
      },
      {
        "payment_terms_id": "123456000000000124",
        "payment_terms": 30,
        "is_default": false,
        "payment_terms_label": "Net 30"
      },
      {
        "payment_terms_id": "123456000000000125",
        "payment_terms": 45,
        "is_default": false,
        "payment_terms_label": "Net 45"
      },
      {
        "payment_terms_id": "123456000000000126",
        "payment_terms": 60,
        "is_default": false,
        "payment_terms_label": "Net 60"
      },
      {
        "payment_terms_id": "",
        "is_mandatory": true,
        "payment_terms": -2,
        "payment_terms_label": "Due end of the month"
      },
      {
        "payment_terms_id": "",
        "is_mandatory": true,
        "payment_terms": -3,
        "payment_terms_label": "Due end of next month"
      }
    ]
  }
}

{
"code": 0,
"message": "success",
"data": {
"payment_terms": [
{
"payment_terms_id": "123456000000000123",
"payment_terms": 15,
"is_default": false,
"payment_terms_label": "Net 15"
},
{
"payment_terms_id": "123456000000000124",
"payment_terms": 30,
"is_default": false,
"payment_terms_label": "Net 30"
},
{
"payment_terms_id": "123456000000000125",
"payment_terms": 45,
"is_default": false,
"payment_terms_label": "Net 45"
},
{
"payment_terms_id": "123456000000000126",
"payment_terms": 60,
"is_default": false,
"payment_terms_label": "Net 60"
},
{
"payment_terms_id": "",
"is_mandatory": true,
"payment_terms": -2,
"payment_terms_label": "Due end of the month"
},
{
"payment_terms_id": "",
"is_mandatory": true,
"payment_terms": -3,
"payment_terms_label": "Due end of next month"
}
]
}
}

Usage:
This is just a snippet of usage and obviously not the whole function to generate an invoice. Please refer to the Zoho Books API documentation for what fields are required to complete a request within your system.

copy raw

m_InvoiceDetails = Map();
m_InvoiceDetails.put("customer_id",m_BooksSO.get("customer_id"));
m_InvoiceDetails.put("payment_terms",-3);
// adding label because -3 often displays "Net 56" instead.
m_InvoiceDetails.put("payment_terms_label","Due end of next month");
//
// loop through line items and populate
for each m_SOLineItem in l_SalesOrderLineItems
{
    m_InvoiceLineItem = Map();
    m_InvoiceLineItem.put("item_id", m_SOLineItem.get("item_id"));
    m_InvoiceLineItem.put("rate", m_SOLineItem.get("rate"));
    m_InvoiceLineItem.put("quantity", m_SOLineItem.get("quantity"));
    l_InvoiceLineItems.add(m_NewLineItem);
}
m_InvoiceDetails.put("line_items",l_InvoiceLineItems);
//
// create or update
if(v_BooksInvoiceID != 0)
{
    r_InvoiceSO = zoho.books.updateRecord("invoices",v_BooksOrgID,v_BooksInvoiceID.toString(),m_InvoiceDetails,"abzohobooks");
}
else 
{
    r_InvoiceSO = zoho.books.createRecord("invoices",v_BooksOrgID,m_InvoiceDetails,"abzohobooks");
}

m_InvoiceDetails = Map();
m_InvoiceDetails.put("customer_id",m_BooksSO.get("customer_id"));
m_InvoiceDetails.put("payment_terms",-3);
// adding label because -3 often displays "Net 56" instead.
m_InvoiceDetails.put("payment_terms_label","Due end of next month");
//
// loop through line items and populate
for each m_SOLineItem in l_SalesOrderLineItems
{
m_InvoiceLineItem = Map();
m_InvoiceLineItem.put("item_id", m_SOLineItem.get("item_id"));
m_InvoiceLineItem.put("rate", m_SOLineItem.get("rate"));
m_InvoiceLineItem.put("quantity", m_SOLineItem.get("quantity"));
l_InvoiceLineItems.add(m_NewLineItem);
}
m_InvoiceDetails.put("line_items",l_InvoiceLineItems);
//
// create or update
if(v_BooksInvoiceID != 0)
{
r_InvoiceSO = zoho.books.updateRecord("invoices",v_BooksOrgID,v_BooksInvoiceID.toString(),m_InvoiceDetails,"abzohobooks");
}
else
{
r_InvoiceSO = zoho.books.createRecord("invoices",v_BooksOrgID,m_InvoiceDetails,"abzohobooks");
}

Note(s):

There are 2 other payment terms which is by setting payment terms to 0 which will result in a "Due on Receipt".
copyrawstyler
```
m_InvoiceDetails.put("payment_terms",0);
m_InvoiceDetails.put("payment_terms_label","Due on Receipt");
```
1. m_InvoiceDetails.put("payment_terms",0);
2. m_InvoiceDetails.put("payment_terms_label","Due on Receipt");