Invoice & credit note templates
Update organisation invoice template
Updates organisation-level invoice template (global default). Request body uses boolean flags for grouping: show subsection header, show subtotal in subsection, show VAT and quantity total in subsection and in bottom subtotals; line description formula with placeholders from GET line-item-description-fields (use returned id in curly braces); optional lineDescriptionTagGroupId when formula uses a placeholder with requiresTagGroup; attachment strategy.
PUT
/
finance
/
invoice-template
Update organisation invoice template
curl --request PUT \
--url https://api.sandbox.flowpayroll.ai/v1/billing/finance/invoice-template \
--header 'Content-Type: application/json' \
--header 'X-Auth-Token: <api-key>' \
--data '
{
"showSubsectionHeader": true,
"showSubtotalInSubsection": true,
"showSubtotalVatInSubsection": true,
"showQuantitySumInSubsection": true,
"showBottomSubtotals": true,
"showVatInBottomSubtotals": true,
"showQuantitySumInBottomSubtotals": true,
"lineDescriptionFormula": "<string>",
"lineDescriptionTagGroupId": "<string>",
"includeAttachmentsWithOnlineInvoice": true
}
'import requests
url = "https://api.sandbox.flowpayroll.ai/v1/billing/finance/invoice-template"
payload = {
"showSubsectionHeader": True,
"showSubtotalInSubsection": True,
"showSubtotalVatInSubsection": True,
"showQuantitySumInSubsection": True,
"showBottomSubtotals": True,
"showVatInBottomSubtotals": True,
"showQuantitySumInBottomSubtotals": True,
"lineDescriptionFormula": "<string>",
"lineDescriptionTagGroupId": "<string>",
"includeAttachmentsWithOnlineInvoice": True
}
headers = {
"X-Auth-Token": "<api-key>",
"Content-Type": "application/json"
}
response = requests.put(url, json=payload, headers=headers)
print(response.text)const options = {
method: 'PUT',
headers: {'X-Auth-Token': '<api-key>', 'Content-Type': 'application/json'},
body: JSON.stringify({
showSubsectionHeader: true,
showSubtotalInSubsection: true,
showSubtotalVatInSubsection: true,
showQuantitySumInSubsection: true,
showBottomSubtotals: true,
showVatInBottomSubtotals: true,
showQuantitySumInBottomSubtotals: true,
lineDescriptionFormula: '<string>',
lineDescriptionTagGroupId: '<string>',
includeAttachmentsWithOnlineInvoice: true
})
};
fetch('https://api.sandbox.flowpayroll.ai/v1/billing/finance/invoice-template', options)
.then(res => res.json())
.then(res => console.log(res))
.catch(err => console.error(err));<?php
$curl = curl_init();
curl_setopt_array($curl, [
CURLOPT_URL => "https://api.sandbox.flowpayroll.ai/v1/billing/finance/invoice-template",
CURLOPT_RETURNTRANSFER => true,
CURLOPT_ENCODING => "",
CURLOPT_MAXREDIRS => 10,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST => "PUT",
CURLOPT_POSTFIELDS => json_encode([
'showSubsectionHeader' => true,
'showSubtotalInSubsection' => true,
'showSubtotalVatInSubsection' => true,
'showQuantitySumInSubsection' => true,
'showBottomSubtotals' => true,
'showVatInBottomSubtotals' => true,
'showQuantitySumInBottomSubtotals' => true,
'lineDescriptionFormula' => '<string>',
'lineDescriptionTagGroupId' => '<string>',
'includeAttachmentsWithOnlineInvoice' => true
]),
CURLOPT_HTTPHEADER => [
"Content-Type: application/json",
"X-Auth-Token: <api-key>"
],
]);
$response = curl_exec($curl);
$err = curl_error($curl);
curl_close($curl);
if ($err) {
echo "cURL Error #:" . $err;
} else {
echo $response;
}package main
import (
"fmt"
"strings"
"net/http"
"io"
)
func main() {
url := "https://api.sandbox.flowpayroll.ai/v1/billing/finance/invoice-template"
payload := strings.NewReader("{\n \"showSubsectionHeader\": true,\n \"showSubtotalInSubsection\": true,\n \"showSubtotalVatInSubsection\": true,\n \"showQuantitySumInSubsection\": true,\n \"showBottomSubtotals\": true,\n \"showVatInBottomSubtotals\": true,\n \"showQuantitySumInBottomSubtotals\": true,\n \"lineDescriptionFormula\": \"<string>\",\n \"lineDescriptionTagGroupId\": \"<string>\",\n \"includeAttachmentsWithOnlineInvoice\": true\n}")
req, _ := http.NewRequest("PUT", url, payload)
req.Header.Add("X-Auth-Token", "<api-key>")
req.Header.Add("Content-Type", "application/json")
res, _ := http.DefaultClient.Do(req)
defer res.Body.Close()
body, _ := io.ReadAll(res.Body)
fmt.Println(string(body))
}HttpResponse<String> response = Unirest.put("https://api.sandbox.flowpayroll.ai/v1/billing/finance/invoice-template")
.header("X-Auth-Token", "<api-key>")
.header("Content-Type", "application/json")
.body("{\n \"showSubsectionHeader\": true,\n \"showSubtotalInSubsection\": true,\n \"showSubtotalVatInSubsection\": true,\n \"showQuantitySumInSubsection\": true,\n \"showBottomSubtotals\": true,\n \"showVatInBottomSubtotals\": true,\n \"showQuantitySumInBottomSubtotals\": true,\n \"lineDescriptionFormula\": \"<string>\",\n \"lineDescriptionTagGroupId\": \"<string>\",\n \"includeAttachmentsWithOnlineInvoice\": true\n}")
.asString();require 'uri'
require 'net/http'
url = URI("https://api.sandbox.flowpayroll.ai/v1/billing/finance/invoice-template")
http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
request = Net::HTTP::Put.new(url)
request["X-Auth-Token"] = '<api-key>'
request["Content-Type"] = 'application/json'
request.body = "{\n \"showSubsectionHeader\": true,\n \"showSubtotalInSubsection\": true,\n \"showSubtotalVatInSubsection\": true,\n \"showQuantitySumInSubsection\": true,\n \"showBottomSubtotals\": true,\n \"showVatInBottomSubtotals\": true,\n \"showQuantitySumInBottomSubtotals\": true,\n \"lineDescriptionFormula\": \"<string>\",\n \"lineDescriptionTagGroupId\": \"<string>\",\n \"includeAttachmentsWithOnlineInvoice\": true\n}"
response = http.request(request)
puts response.read_body{
"message": {
"token": "<string>",
"text": "<string>",
"tokenArguments": [
{
"name": "<string>",
"value": null
}
],
"textId": "<string>",
"textParameters": [
{
"key": "<string>",
"value": "<string>"
}
]
},
"content": {
"data": {
"showSubsectionHeader": true,
"showSubtotalInSubsection": true,
"showSubtotalVatInSubsection": true,
"showQuantitySumInSubsection": true,
"showBottomSubtotals": true,
"showVatInBottomSubtotals": true,
"showQuantitySumInBottomSubtotals": true,
"lineItemSortOrder": "None",
"lineDescriptionFormula": "<string>",
"lineDescriptionTagGroupId": "<string>",
"attachmentStrategy": "ExcessLost",
"includeAttachmentsWithOnlineInvoice": true
},
"metadata": {
"dateFormat": "<string>",
"dateTimeFormat": "<string>",
"paginationToken": "<string>"
}
},
"validationIssues": [
{
"field": "<string>",
"reason": "<string>",
"reasonToken": "<string>",
"reasonTokenArguments": [
{
"name": "<string>",
"value": null
}
]
}
],
"errors": [
{
"field": "<string>",
"reasonText": "<string>",
"reasonId": "<string>",
"reasonParameters": [
{
"key": "<string>",
"value": "<string>"
}
]
}
],
"metadata": {
"dateFormat": "<string>",
"dateTimeFormat": "<string>",
"paginationToken": "<string>"
}
}{
"message": {
"token": "<string>",
"text": "<string>",
"tokenArguments": [
{
"name": "<string>",
"value": null
}
],
"textId": "<string>",
"textParameters": [
{
"key": "<string>",
"value": "<string>"
}
]
},
"content": {
"data": "<string>",
"metadata": {
"dateFormat": "<string>",
"dateTimeFormat": "<string>",
"paginationToken": "<string>"
}
},
"validationIssues": [
{
"field": "<string>",
"reason": "<string>",
"reasonToken": "<string>",
"reasonTokenArguments": [
{
"name": "<string>",
"value": null
}
]
}
],
"errors": [
{
"field": "<string>",
"reasonText": "<string>",
"reasonId": "<string>",
"reasonParameters": [
{
"key": "<string>",
"value": "<string>"
}
]
}
],
"metadata": {
"dateFormat": "<string>",
"dateTimeFormat": "<string>",
"paginationToken": "<string>"
}
}{
"message": {
"token": "<string>",
"text": "<string>",
"tokenArguments": [
{
"name": "<string>",
"value": null
}
],
"textId": "<string>",
"textParameters": [
{
"key": "<string>",
"value": "<string>"
}
]
},
"content": {
"data": null,
"metadata": {
"dateFormat": "<string>",
"dateTimeFormat": "<string>",
"paginationToken": "<string>"
}
},
"validationIssues": [
{
"field": "<string>",
"reason": "<string>",
"reasonToken": "<string>",
"reasonTokenArguments": [
{
"name": "<string>",
"value": null
}
]
}
],
"errors": [
{
"field": "<string>",
"reasonText": "<string>",
"reasonId": "<string>",
"reasonParameters": [
{
"key": "<string>",
"value": "<string>"
}
]
}
],
"metadata": {
"dateFormat": "<string>",
"dateTimeFormat": "<string>",
"paginationToken": "<string>"
}
}{
"message": {
"token": "<string>",
"text": "<string>",
"tokenArguments": [
{
"name": "<string>",
"value": null
}
],
"textId": "<string>",
"textParameters": [
{
"key": "<string>",
"value": "<string>"
}
]
},
"content": {
"data": "<string>",
"metadata": {
"dateFormat": "<string>",
"dateTimeFormat": "<string>",
"paginationToken": "<string>"
}
},
"validationIssues": [
{
"field": "<string>",
"reason": "<string>",
"reasonToken": "<string>",
"reasonTokenArguments": [
{
"name": "<string>",
"value": null
}
]
}
],
"errors": [
{
"field": "<string>",
"reasonText": "<string>",
"reasonId": "<string>",
"reasonParameters": [
{
"key": "<string>",
"value": "<string>"
}
]
}
],
"metadata": {
"dateFormat": "<string>",
"dateTimeFormat": "<string>",
"paginationToken": "<string>"
}
}Authorizations
Authentication token for API access
Body
application/json
Document (invoice or credit note) template: grouping, sort order, line description formula, attachment strategy. Same shape for org default and per-client override. Grouping is driven by booleans (subsection header, subtotal row, VAT and quantity total in subsection and in bottom subtotals).
When true, emit group header lines (e.g. "--- Pay Element ---") when client uses subtotal grouping.
When true (and showSubsectionHeader is true), emit a subtotal row after each group with amount and optionally VAT and quantity total.
When true, include VAT in each subsection subtotal row description.
When true, include quantity total (sum of quantities/units in the group) in each subsection subtotal row description.
When true, emit a bottom block listing all group subtotals after the lines.
When true, include VAT in each bottom subtotal line description.
When true, include quantity total in each bottom subtotal line description.
Sort order for line items when subsection/grouping is not used (e.g. as stored, by employee A–Z, by pay element then employee).
Available options:
None, ByEmployee, ByPayElementThenEmployee Template string with placeholders (e.g. "{description} - {employeeName} - {poNumber}"). Use ids from GET /finance/line-item-description-fields in curly braces. When null, use line Description only.
Optional tag group key when formula uses {tagValue}. Required when a placeholder with requiresTagGroup is used. Stored as a normalised key.
How to handle attachments when over provider limit (e.g. excess lost vs merge on integration).
Available options:
ExcessLost, MergeOnIntegration When true, the customer can see the attached files on their own copy of the document rather than them being an internal record only.
Response
OK
Billing's response envelope: the platform's (message.text + message.token,
content.data + content.metadata, validationIssues) plus the fields billing
sent before it (PRODLAUNCH-416). Those are deprecated, removed on 31 December 2026, and are
projections of their replacements so the two cannot disagree.
What happened, as English text and a stable snake_case token to translate from.
Show child attributes
Show child attributes
Show child attributes
Show child attributes
Show child attributes
Show child attributes
Deprecated: the same issues as validationIssues (reasonText is reason, reasonId is reasonToken, reasonParameters is reasonTokenArguments). Read validationIssues; this will be removed.
Show child attributes
Show child attributes
Deprecated: the same values as content.metadata. Read that; this will be removed.
Show child attributes
Show child attributes
Was this page helpful?
⌘I
Update organisation invoice template
curl --request PUT \
--url https://api.sandbox.flowpayroll.ai/v1/billing/finance/invoice-template \
--header 'Content-Type: application/json' \
--header 'X-Auth-Token: <api-key>' \
--data '
{
"showSubsectionHeader": true,
"showSubtotalInSubsection": true,
"showSubtotalVatInSubsection": true,
"showQuantitySumInSubsection": true,
"showBottomSubtotals": true,
"showVatInBottomSubtotals": true,
"showQuantitySumInBottomSubtotals": true,
"lineDescriptionFormula": "<string>",
"lineDescriptionTagGroupId": "<string>",
"includeAttachmentsWithOnlineInvoice": true
}
'import requests
url = "https://api.sandbox.flowpayroll.ai/v1/billing/finance/invoice-template"
payload = {
"showSubsectionHeader": True,
"showSubtotalInSubsection": True,
"showSubtotalVatInSubsection": True,
"showQuantitySumInSubsection": True,
"showBottomSubtotals": True,
"showVatInBottomSubtotals": True,
"showQuantitySumInBottomSubtotals": True,
"lineDescriptionFormula": "<string>",
"lineDescriptionTagGroupId": "<string>",
"includeAttachmentsWithOnlineInvoice": True
}
headers = {
"X-Auth-Token": "<api-key>",
"Content-Type": "application/json"
}
response = requests.put(url, json=payload, headers=headers)
print(response.text)const options = {
method: 'PUT',
headers: {'X-Auth-Token': '<api-key>', 'Content-Type': 'application/json'},
body: JSON.stringify({
showSubsectionHeader: true,
showSubtotalInSubsection: true,
showSubtotalVatInSubsection: true,
showQuantitySumInSubsection: true,
showBottomSubtotals: true,
showVatInBottomSubtotals: true,
showQuantitySumInBottomSubtotals: true,
lineDescriptionFormula: '<string>',
lineDescriptionTagGroupId: '<string>',
includeAttachmentsWithOnlineInvoice: true
})
};
fetch('https://api.sandbox.flowpayroll.ai/v1/billing/finance/invoice-template', options)
.then(res => res.json())
.then(res => console.log(res))
.catch(err => console.error(err));<?php
$curl = curl_init();
curl_setopt_array($curl, [
CURLOPT_URL => "https://api.sandbox.flowpayroll.ai/v1/billing/finance/invoice-template",
CURLOPT_RETURNTRANSFER => true,
CURLOPT_ENCODING => "",
CURLOPT_MAXREDIRS => 10,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST => "PUT",
CURLOPT_POSTFIELDS => json_encode([
'showSubsectionHeader' => true,
'showSubtotalInSubsection' => true,
'showSubtotalVatInSubsection' => true,
'showQuantitySumInSubsection' => true,
'showBottomSubtotals' => true,
'showVatInBottomSubtotals' => true,
'showQuantitySumInBottomSubtotals' => true,
'lineDescriptionFormula' => '<string>',
'lineDescriptionTagGroupId' => '<string>',
'includeAttachmentsWithOnlineInvoice' => true
]),
CURLOPT_HTTPHEADER => [
"Content-Type: application/json",
"X-Auth-Token: <api-key>"
],
]);
$response = curl_exec($curl);
$err = curl_error($curl);
curl_close($curl);
if ($err) {
echo "cURL Error #:" . $err;
} else {
echo $response;
}package main
import (
"fmt"
"strings"
"net/http"
"io"
)
func main() {
url := "https://api.sandbox.flowpayroll.ai/v1/billing/finance/invoice-template"
payload := strings.NewReader("{\n \"showSubsectionHeader\": true,\n \"showSubtotalInSubsection\": true,\n \"showSubtotalVatInSubsection\": true,\n \"showQuantitySumInSubsection\": true,\n \"showBottomSubtotals\": true,\n \"showVatInBottomSubtotals\": true,\n \"showQuantitySumInBottomSubtotals\": true,\n \"lineDescriptionFormula\": \"<string>\",\n \"lineDescriptionTagGroupId\": \"<string>\",\n \"includeAttachmentsWithOnlineInvoice\": true\n}")
req, _ := http.NewRequest("PUT", url, payload)
req.Header.Add("X-Auth-Token", "<api-key>")
req.Header.Add("Content-Type", "application/json")
res, _ := http.DefaultClient.Do(req)
defer res.Body.Close()
body, _ := io.ReadAll(res.Body)
fmt.Println(string(body))
}HttpResponse<String> response = Unirest.put("https://api.sandbox.flowpayroll.ai/v1/billing/finance/invoice-template")
.header("X-Auth-Token", "<api-key>")
.header("Content-Type", "application/json")
.body("{\n \"showSubsectionHeader\": true,\n \"showSubtotalInSubsection\": true,\n \"showSubtotalVatInSubsection\": true,\n \"showQuantitySumInSubsection\": true,\n \"showBottomSubtotals\": true,\n \"showVatInBottomSubtotals\": true,\n \"showQuantitySumInBottomSubtotals\": true,\n \"lineDescriptionFormula\": \"<string>\",\n \"lineDescriptionTagGroupId\": \"<string>\",\n \"includeAttachmentsWithOnlineInvoice\": true\n}")
.asString();require 'uri'
require 'net/http'
url = URI("https://api.sandbox.flowpayroll.ai/v1/billing/finance/invoice-template")
http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
request = Net::HTTP::Put.new(url)
request["X-Auth-Token"] = '<api-key>'
request["Content-Type"] = 'application/json'
request.body = "{\n \"showSubsectionHeader\": true,\n \"showSubtotalInSubsection\": true,\n \"showSubtotalVatInSubsection\": true,\n \"showQuantitySumInSubsection\": true,\n \"showBottomSubtotals\": true,\n \"showVatInBottomSubtotals\": true,\n \"showQuantitySumInBottomSubtotals\": true,\n \"lineDescriptionFormula\": \"<string>\",\n \"lineDescriptionTagGroupId\": \"<string>\",\n \"includeAttachmentsWithOnlineInvoice\": true\n}"
response = http.request(request)
puts response.read_body{
"message": {
"token": "<string>",
"text": "<string>",
"tokenArguments": [
{
"name": "<string>",
"value": null
}
],
"textId": "<string>",
"textParameters": [
{
"key": "<string>",
"value": "<string>"
}
]
},
"content": {
"data": {
"showSubsectionHeader": true,
"showSubtotalInSubsection": true,
"showSubtotalVatInSubsection": true,
"showQuantitySumInSubsection": true,
"showBottomSubtotals": true,
"showVatInBottomSubtotals": true,
"showQuantitySumInBottomSubtotals": true,
"lineItemSortOrder": "None",
"lineDescriptionFormula": "<string>",
"lineDescriptionTagGroupId": "<string>",
"attachmentStrategy": "ExcessLost",
"includeAttachmentsWithOnlineInvoice": true
},
"metadata": {
"dateFormat": "<string>",
"dateTimeFormat": "<string>",
"paginationToken": "<string>"
}
},
"validationIssues": [
{
"field": "<string>",
"reason": "<string>",
"reasonToken": "<string>",
"reasonTokenArguments": [
{
"name": "<string>",
"value": null
}
]
}
],
"errors": [
{
"field": "<string>",
"reasonText": "<string>",
"reasonId": "<string>",
"reasonParameters": [
{
"key": "<string>",
"value": "<string>"
}
]
}
],
"metadata": {
"dateFormat": "<string>",
"dateTimeFormat": "<string>",
"paginationToken": "<string>"
}
}{
"message": {
"token": "<string>",
"text": "<string>",
"tokenArguments": [
{
"name": "<string>",
"value": null
}
],
"textId": "<string>",
"textParameters": [
{
"key": "<string>",
"value": "<string>"
}
]
},
"content": {
"data": "<string>",
"metadata": {
"dateFormat": "<string>",
"dateTimeFormat": "<string>",
"paginationToken": "<string>"
}
},
"validationIssues": [
{
"field": "<string>",
"reason": "<string>",
"reasonToken": "<string>",
"reasonTokenArguments": [
{
"name": "<string>",
"value": null
}
]
}
],
"errors": [
{
"field": "<string>",
"reasonText": "<string>",
"reasonId": "<string>",
"reasonParameters": [
{
"key": "<string>",
"value": "<string>"
}
]
}
],
"metadata": {
"dateFormat": "<string>",
"dateTimeFormat": "<string>",
"paginationToken": "<string>"
}
}{
"message": {
"token": "<string>",
"text": "<string>",
"tokenArguments": [
{
"name": "<string>",
"value": null
}
],
"textId": "<string>",
"textParameters": [
{
"key": "<string>",
"value": "<string>"
}
]
},
"content": {
"data": null,
"metadata": {
"dateFormat": "<string>",
"dateTimeFormat": "<string>",
"paginationToken": "<string>"
}
},
"validationIssues": [
{
"field": "<string>",
"reason": "<string>",
"reasonToken": "<string>",
"reasonTokenArguments": [
{
"name": "<string>",
"value": null
}
]
}
],
"errors": [
{
"field": "<string>",
"reasonText": "<string>",
"reasonId": "<string>",
"reasonParameters": [
{
"key": "<string>",
"value": "<string>"
}
]
}
],
"metadata": {
"dateFormat": "<string>",
"dateTimeFormat": "<string>",
"paginationToken": "<string>"
}
}{
"message": {
"token": "<string>",
"text": "<string>",
"tokenArguments": [
{
"name": "<string>",
"value": null
}
],
"textId": "<string>",
"textParameters": [
{
"key": "<string>",
"value": "<string>"
}
]
},
"content": {
"data": "<string>",
"metadata": {
"dateFormat": "<string>",
"dateTimeFormat": "<string>",
"paginationToken": "<string>"
}
},
"validationIssues": [
{
"field": "<string>",
"reason": "<string>",
"reasonToken": "<string>",
"reasonTokenArguments": [
{
"name": "<string>",
"value": null
}
]
}
],
"errors": [
{
"field": "<string>",
"reasonText": "<string>",
"reasonId": "<string>",
"reasonParameters": [
{
"key": "<string>",
"value": "<string>"
}
]
}
],
"metadata": {
"dateFormat": "<string>",
"dateTimeFormat": "<string>",
"paginationToken": "<string>"
}
}