Credit note API documentation
The Credit Note Feed API allows merchants to upload credit note data in real-time or in bulk. Credit note data flows automatically and securely into Lovat, enabling businesses to generate, manage, and track credit notes efficiently while maintaining compliance with tax regulations and accounting standards.
Terms and abbreviations
- API – Application Programming Interface. A set of calls provided by the system for integration with external software products.
- Merchant – The owner of an online store or business using the Lovat platform.
- Customer – An individual or business entity who purchases goods or services from the merchant.
- Credit Note – A commercial document issued by a seller to a buyer, indicating a reduction in the amount owed for previously issued invoices.
- Token – A secret string used by the system to identify the merchant and authenticate API requests.
- Line Item – Individual product or service entry in a credit note with quantity, unit price, and total.
Credit note data parameters
Parameter | Type/Example | Description | Validation |
---|---|---|---|
credit_note_number | String/”CN-2024-001″ | Unique credit note identifier | Optional. Maximum 255 characters |
customer_id | Integer/123 | Existing customer ID in system | Optional. Must exist in customer database |
customer_name | String/”Acme Corporation” | Customer business name | Required. Maximum 255 characters. Not empty |
customer_email | String/”contact@acme.com” | Customer email address | Optional. Must contain ‘@’ if provided |
customer_country | String/”USA” | Customer country code | Optional. ISO 3166-1 alpha-3 format (3 characters) |
customer_tax_number | String/”123456789″ | Customer tax/VAT number | Optional. Maximum 25 characters |
customer_address | String/”123 Business St” | Customer address | Optional. Maximum 255 characters |
credit_note_date | String/”2024-01-15″ | Credit note creation date | Required. YYYY-MM-DD format |
due_date | String/”2024-02-15″ | Payment due date | Required. YYYY-MM-DD format |
currency | String/”EUR” | Credit note currency | Optional. Default: “EUR”. Maximum 3 characters |
status | String/”draft” | Credit note status | Required. Values: “draft”, “pending”, “sent”, “paid” |
line_items | Array | List of credit note items | Required. At least one item required |
subtotal | Float/1000.00 | Sum before taxes and discounts | Required. Decimal with 2 places |
total_tax | Float/220.00 | Total tax amount | Required. Decimal with 2 places |
total | Float/1220.00 | Final credit note amount | Required. Decimal with 2 places |
total_discount_amount | Float/50.00 | Total discount amount | Required. Decimal with 2 places |
supplier_tax_number | String/”987654321″ | Supplier tax number | Optional. Maximum 25 characters |
supplier_country | String/”USA” | Supplier country code | Optional. ISO 3166-1 alpha-3 format |
Line item parameters
Parameter | Type/Example | Description | Validation |
---|---|---|---|
description | String/”Web Development” | Item description | Required. Maximum 255 characters |
quantity | Float/2.0 | Item quantity | Required. Positive number |
unit_price | Float/500.00 | Price per unit | Required. Positive number |
is_taxable | Boolean/true | Whether item is taxable | Default: true |
1. Bulk credit note upload
- Description: Upload one or multiple credit notes to the platform in a single request.
- Method: POST
- URL: https://invoice.vatcompliance.co/api/1/app/l_invoice/credit_notes/{access_token}
- Parameters:
Path parameters: access_token (required)
Body parameters: Array of credit note objects (JSON format)
Example requests
Credit note upload
curl -X POST \
"https://invoice.vatcompliance.co/api/1/app/l_invoice/credit_notes/your-access-token" \
-H "Content-Type: application/json" \
-d '[
{
"credit_note_number": "CN-2024-001",
"customer_name": "Acme Corporation",
"customer_email": "contact@acme.com",
"customer_country": "USA",
"customer_tax_number": "123456789",
"customer_address": "123 Business Ave, New York, NY 10001",
"credit_note_date": "2024-01-15",
"due_date": "2024-02-15",
"currency": "USD",
"status": "draft",
"line_items": [
{
"description": "Web Development Services Refund",
"quantity": 10,
"unit_price": 75.00,
"tax": true
},
{
"description": "Domain Registration Refund",
"quantity": 1,
"unit_price": 15.00,
"tax": false
}
],
"subtotal": 765.00,
"total_tax": 168.30,
"total": 933.30,
"total_discount_amount": 0.00,
"supplier_company_name": "Tech Solutions Inc",
"supplier_address": "456 Tech Street, San Francisco, CA 94102",
"supplier_email": "billing@techsolutions.com",
"supplier_tax_number": "987654321",
"supplier_country": "USA"
},
{
"credit_note_number": "CN-2024-002",
"customer_name": "Tech Solutions Ltd",
"customer_email": "info@techsolutions.com",
"customer_country": "GBR",
"customer_tax_number": "GB123456789",
"customer_address": "456 Tech Street, London, SW1A 1AA",
"credit_note_date": "2024-01-16",
"due_date": "2024-02-16",
"currency": "EUR",
"status": "draft",
"line_items": [
{
"description": "Software License Refund",
"quantity": 1,
"unit_price": 299.00,
"tax": true
}
],
"subtotal": 299.00,
"total_tax": 65.78,
"total": 364.78,
"total_discount_amount": 0.00,
"supplier_company_name": "Tech Solutions Inc",
"supplier_address": "456 Tech Street, San Francisco, CA 94102",
"supplier_email": "billing@techsolutions.com",
"supplier_tax_number": "987654321",
"supplier_country": "USA"
}
]'
import requests
import json
url = "https://invoice.vatcompliance.co/api/1/app/l_invoice/credit_notes/your-access-token"
headers = {"Content-Type": "application/json"}
credit_notes = [
{
"credit_note_number": "CN-2024-001",
"customer_name": "Acme Corporation",
"customer_email": "contact@acme.com",
"customer_country": "USA",
"customer_tax_number": "123456789",
"customer_address": "123 Business Ave, New York, NY 10001",
"credit_note_date": "2024-01-15",
"due_date": "2024-02-15",
"currency": "USD",
"status": "draft",
"line_items": [
{
"description": "Web Development Services Refund",
"quantity": 10,
"unit_price": 75.00,
"tax": True
},
{
"description": "Domain Registration Refund",
"quantity": 1,
"unit_price": 15.00,
"tax": False
}
],
"subtotal": 765.00,
"total_tax": 168.30,
"total": 933.30,
"total_discount_amount": 0.00,
"supplier_company_name": "Tech Solutions Inc",
"supplier_address": "456 Tech Street, San Francisco, CA 94102",
"supplier_email": "billing@techsolutions.com",
"supplier_tax_number": "987654321",
"supplier_country": "USA"
}
]
response = requests.post(url, headers=headers, data=json.dumps(credit_notes))
print(response.json())
require 'net/http'
require 'uri'
require 'json'
url = URI("https://invoice.vatcompliance.co/api/1/app/l_invoice/credit_notes/your-access-token")
http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
headers = { "Content-Type" => "application/json" }
credit_notes = [
{
"credit_note_number" => "CN-2024-001",
"customer_name" => "Acme Corporation",
"customer_email" => "contact@acme.com",
"customer_country" => "USA",
"customer_tax_number" => "123456789",
"customer_address" => "123 Business Ave, New York, NY 10001",
"credit_note_date" => "2024-01-15",
"due_date" => "2024-02-15",
"currency" => "USD",
"status" => "draft",
"line_items" => [
{
"description" => "Web Development Services Refund",
"quantity" => 10,
"unit_price" => 75.00,
"tax" => true
},
{
"description" => "Domain Registration Refund",
"quantity" => 1,
"unit_price" => 15.00,
"tax" => false
}
],
"subtotal" => 765.00,
"total_tax" => 168.30,
"total" => 933.30,
"total_discount_amount" => 0.00,
"supplier_company_name" => "Tech Solutions Inc",
"supplier_address" => "456 Tech Street, San Francisco, CA 94102",
"supplier_email" => "billing@techsolutions.com",
"supplier_tax_number" => "987654321",
"supplier_country" => "USA"
}
]
request = Net::HTTP::Post.new(url, headers)
request.body = credit_notes.to_json
response = http.request(request)
puts response.body
<?php
$url = "https://invoice.vatcompliance.co/api/1/app/l_invoice/credit_notes/your-access-token";
$credit_notes = [
[
"credit_note_number" => "CN-2024-001",
"customer_name" => "Acme Corporation",
"customer_email" => "contact@acme.com",
"customer_country" => "USA",
"customer_tax_number" => "123456789",
"customer_address" => "123 Business Ave, New York, NY 10001",
"credit_note_date" => "2024-01-15",
"due_date" => "2024-02-15",
"currency" => "USD",
"status" => "draft",
"line_items" => [
[
"description" => "Web Development Services Refund",
"quantity" => 10,
"unit_price" => 75.00,
"tax" => true
],
[
"description" => "Domain Registration Refund",
"quantity" => 1,
"unit_price" => 15.00,
"tax" => false
]
],
"subtotal" => 765.00,
"total_tax" => 168.30,
"total" => 933.30,
"total_discount_amount" => 0.00,
"supplier_company_name" => "Tech Solutions Inc",
"supplier_address" => "456 Tech Street, San Francisco, CA 94102",
"supplier_email" => "billing@techsolutions.com",
"supplier_tax_number" => "987654321",
"supplier_country" => "USA"
]
];
$options = [
"http" => [
"header" => "Content-Type: application/json\r\n",
"method" => "POST",
"content" => json_encode($credit_notes),
]
];
$context = stream_context_create($options);
$result = file_get_contents($url, false, $context);
if ($result === FALSE) {
die("Error sending request");
}
echo $result;
?>
const fetch = require("node-fetch");
const url = "https://invoice.vatcompliance.co/api/1/app/l_invoice/credit_notes/your-access-token";
const credit_notes = [
{
credit_note_number: "CN-2024-001",
customer_name: "Acme Corporation",
customer_email: "contact@acme.com",
customer_country: "USA",
customer_tax_number: "123456789",
customer_address: "123 Business Ave, New York, NY 10001",
credit_note_date: "2024-01-15",
due_date: "2024-02-15",
currency: "USD",
status: "draft",
line_items: [
{
description: "Web Development Services Refund",
quantity: 10,
unit_price: 75.00,
tax: true
},
{
description: "Domain Registration Refund",
quantity: 1,
unit_price: 15.00,
tax: false
}
],
subtotal: 765.00,
total_tax: 168.30,
total: 933.30,
total_discount_amount: 0.00,
supplier_company_name: "Tech Solutions Inc",
supplier_address: "456 Tech Street, San Francisco, CA 94102",
supplier_email: "billing@techsolutions.com",
supplier_tax_number: "987654321",
supplier_country: "USA"
}
];
fetch(url, {
method: "POST",
headers: { "Content-Type": "application/json" },
body: JSON.stringify(credit_notes),
})
.then(res => res.json())
.then(json => console.log(json))
.catch(err => console.error("Error:", err));
using System;
using System.Net.Http;
using System.Text;
using System.Threading.Tasks;
class Program {
static async Task Main() {
var url = "https://invoice.vatcompliance.co/api/1/app/l_invoice/credit_notes/your-access-token";
var client = new HttpClient();
var credit_notes = new[] {
new {
credit_note_number = "CN-2024-001",
customer_name = "Acme Corporation",
customer_email = "contact@acme.com",
customer_country = "USA",
customer_tax_number = "123456789",
customer_address = "123 Business Ave, New York, NY 10001",
credit_note_date = "2024-01-15",
due_date = "2024-02-15",
currency = "USD",
status = "draft",
line_items = new[] {
new {
description = "Web Development Services Refund",
quantity = 10,
unit_price = 75.00,
tax = true
},
new {
description = "Domain Registration Refund",
quantity = 1,
unit_price = 15.00,
tax = false
}
},
subtotal = 765.00,
total_tax = 168.30,
total = 933.30,
total_discount_amount = 0.00,
supplier_company_name = "Tech Solutions Inc",
supplier_address = "456 Tech Street, San Francisco, CA 94102",
supplier_email = "billing@techsolutions.com",
supplier_tax_number = "987654321",
supplier_country = "USA"
}
};
var json = Newtonsoft.Json.JsonConvert.SerializeObject(credit_notes);
var content = new StringContent(json, Encoding.UTF8, "application/json");
var response = await client.PostAsync(url, content);
string responseBody = await response.Content.ReadAsStringAsync();
Console.WriteLine(responseBody);
}
}
import java.net.http.*;
import java.net.URI;
import java.nio.charset.StandardCharsets;
public class BulkCreditNoteUpload {
public static void main(String[] args) throws Exception {
String url = "https://invoice.vatcompliance.co/api/1/app/l_invoice/credit_notes/your-access-token";
String json = "[{\"credit_note_number\":\"CN-2024-001\",\"customer_name\":\"Acme Corporation\",\"customer_email\":\"contact@acme.com\",\"customer_country\":\"USA\",\"customer_tax_number\":\"123456789\",\"customer_address\":\"123 Business Ave, New York, NY 10001\",\"credit_note_date\":\"2024-01-15\",\"due_date\":\"2024-02-15\",\"currency\":\"USD\",\"status\":\"draft\",\"line_items\":[{\"description\":\"Web Development Services Refund\",\"quantity\":10,\"unit_price\":75.00,\"tax\":true},{\"description\":\"Domain Registration Refund\",\"quantity\":1,\"unit_price\":15.00,\"tax\":false}],\"subtotal\":765.00,\"total_tax\":168.30,\"total\":933.30,\"total_discount_amount\":0.00,\"supplier_company_name\":\"Tech Solutions Inc\",\"supplier_address\":\"456 Tech Street, San Francisco, CA 94102\",\"supplier_email\":\"billing@techsolutions.com\",\"supplier_tax_number\":\"987654321\",\"supplier_country\":\"USA\"}]";
HttpClient client = HttpClient.newHttpClient();
HttpRequest request = HttpRequest.newBuilder()
.uri(URI.create(url))
.header("Content-Type", "application/json")
.POST(HttpRequest.BodyPublishers.ofString(json, StandardCharsets.UTF_8))
.build();
HttpResponse response = client.send(request, HttpResponse.BodyHandlers.ofString());
System.out.println(response.body());
}
}
package main
import (
"bytes"
"encoding/json"
"fmt"
"net/http"
"io/ioutil"
)
func main() {
url := "https://invoice.vatcompliance.co/api/1/app/l_invoice/credit_notes/your-access-token"
credit_notes := []map[string]interface{}{
{
"credit_note_number": "CN-2024-001",
"customer_name": "Acme Corporation",
"customer_email": "contact@acme.com",
"customer_country": "USA",
"customer_tax_number": "123456789",
"customer_address": "123 Business Ave, New York, NY 10001",
"credit_note_date": "2024-01-15",
"due_date": "2024-02-15",
"currency": "USD",
"status": "draft",
"line_items": []map[string]interface{}{
{
"description": "Web Development Services Refund",
"quantity": 10,
"unit_price": 75.00,
"tax": true,
},
{
"description": "Domain Registration Refund",
"quantity": 1,
"unit_price": 15.00,
"tax": false,
},
},
"subtotal": 765.00,
"total_tax": 168.30,
"total": 933.30,
"total_discount_amount": 0.00,
"supplier_company_name": "Tech Solutions Inc",
"supplier_address": "456 Tech Street, San Francisco, CA 94102",
"supplier_email": "billing@techsolutions.com",
"supplier_tax_number": "987654321",
"supplier_country": "USA",
},
}
body, _ := json.Marshal(credit_notes)
resp, err := http.Post(url, "application/json", bytes.NewBuffer(body))
if err != nil {
panic(err)
}
defer resp.Body.Close()
responseData, _ := ioutil.ReadAll(resp.Body)
fmt.Println(string(responseData))
}
Example response
Credit note upload response
Success response:
{
"status": "done",
"results": [
{
"index": 0,
"status": "success",
"credit_note_id": 5290,
"credit_note_number": "CN-2024-001",
"total": "933.3"
}
]
}
2. Credit note update
- Description: Update an existing credit note by its unique identifier. Supports partial updates – only provided fields will be modified.
- Method: PUT
- URL: https://invoice.vatcompliance.co/api/1/app/l_invoice/credit_notes/{access_token}/{credit_note_id}
- Parameters:
– Path parameters:
access_token (required) – Authentication token
credit_note_id (required) – Unique credit note identifier
– Body parameters: Credit note update object (JSON format)
Example requests
Update credit note by ID
curl -X PUT \
"https://invoice.vatcompliance.co/api/1/app/l_invoice/credit_notes/your-access-token/1234" \
-H "Content-Type: application/json" \
-d '{
"credit_note_date": "2024-01-20",
"due_date": "2024-02-20",
"status": "sent",
"line_items": [
{
"description": "Updated Web Development Services Refund",
"quantity": 15,
"unit_price": 75.00,
"tax": true
},
{
"description": "Additional Consulting Refund",
"quantity": 5,
"unit_price": 100.00,
"tax": true
}
],
"subtotal": 1625.00,
"total_tax": 357.50,
"total": 1982.50,
"total_discount_amount": 0.00
}'
import requests
import json
url = "https://invoice.vatcompliance.co/api/1/app/l_invoice/credit_notes/your-access-token/1234"
headers = {"Content-Type": "application/json"}
update_data = {
"credit_note_date": "2024-01-20",
"due_date": "2024-02-20",
"status": "sent",
"line_items": [
{
"description": "Updated Web Development Services Refund",
"quantity": 15,
"unit_price": 75.00,
"tax": True
},
{
"description": "Additional Consulting Refund",
"quantity": 5,
"unit_price": 100.00,
"tax": True
}
],
"subtotal": 1625.00,
"total_tax": 357.50,
"total": 1982.50,
"total_discount_amount": 0.00
}
response = requests.put(url, headers=headers, data=json.dumps(update_data))
print(response.json())
require 'net/http'
require 'uri'
require 'json'
url = URI("https://invoice.vatcompliance.co/api/1/app/l_invoice/credit_notes/your-access-token/1234")
http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
headers = { "Content-Type" => "application/json" }
update_data = {
"credit_note_date" => "2024-01-20",
"due_date" => "2024-02-20",
"status" => "sent",
"line_items" => [
{
"description" => "Updated Web Development Services Refund",
"quantity" => 15,
"unit_price" => 75.00,
"tax" => true
},
{
"description" => "Additional Consulting Refund",
"quantity" => 5,
"unit_price" => 100.00,
"tax" => true
}
],
"subtotal" => 1625.00,
"total_tax" => 357.50,
"total" => 1982.50,
"total_discount_amount" => 0.00
}
request = Net::HTTP::Put.new(url, headers)
request.body = update_data.to_json
response = http.request(request)
puts response.body
<?php
$url = "https://invoice.vatcompliance.co/api/1/app/l_invoice/credit_notes/your-access-token/1234";
$update_data = [
"credit_note_date" => "2024-01-20",
"due_date" => "2024-02-20",
"status" => "sent",
"line_items" => [
[
"description" => "Updated Web Development Services Refund",
"quantity" => 15,
"unit_price" => 75.00,
"tax" => true
],
[
"description" => "Additional Consulting Refund",
"quantity" => 5,
"unit_price" => 100.00,
"tax" => true
]
],
"subtotal" => 1625.00,
"total_tax" => 357.50,
"total" => 1982.50,
"total_discount_amount" => 0.00
];
$options = [
"http" => [
"header" => "Content-Type: application/json\r\n",
"method" => "PUT",
"content" => json_encode($update_data),
]
];
$context = stream_context_create($options);
$result = file_get_contents($url, false, $context);
if ($result === FALSE) {
die("Error sending request");
}
echo $result;
?>
const fetch = require("node-fetch");
const url = "https://invoice.vatcompliance.co/api/1/app/l_invoice/credit_notes/your-access-token/1234";
const update_data = {
credit_note_date: "2024-01-20",
due_date: "2024-02-20",
status: "sent",
line_items: [
{
description: "Updated Web Development Services Refund",
quantity: 15,
unit_price: 75.00,
tax: true
},
{
description: "Additional Consulting Refund",
quantity: 5,
unit_price: 100.00,
tax: true
}
],
subtotal: 1625.00,
total_tax: 357.50,
total: 1982.50,
total_discount_amount: 0.00
};
fetch(url, {
method: "PUT",
headers: { "Content-Type": "application/json" },
body: JSON.stringify(update_data),
})
.then(res => res.json())
.then(json => console.log(json))
.catch(err => console.error("Error:", err));
using System;
using System.Net.Http;
using System.Text;
using System.Threading.Tasks;
class Program {
static async Task Main() {
var url = "https://invoice.vatcompliance.co/api/1/app/l_invoice/credit_notes/your-access-token/1234";
var client = new HttpClient();
var update_data = new {
credit_note_date = "2024-01-20",
due_date = "2024-02-20",
status = "sent",
line_items = new[] {
new {
description = "Updated Web Development Services Refund",
quantity = 15,
unit_price = 75.00,
tax = true
},
new {
description = "Additional Consulting Refund",
quantity = 5,
unit_price = 100.00,
tax = true
}
},
subtotal = 1625.00,
total_tax = 357.50,
total = 1982.50,
total_discount_amount = 0.00
};
var json = Newtonsoft.Json.JsonConvert.SerializeObject(update_data);
var content = new StringContent(json, Encoding.UTF8, "application/json");
var response = await client.PutAsync(url, content);
string responseBody = await response.Content.ReadAsStringAsync();
Console.WriteLine(responseBody);
}
}
import java.net.http.*;
import java.net.URI;
import java.nio.charset.StandardCharsets;
public class UpdateCreditNote {
public static void main(String[] args) throws Exception {
String url = "https://invoice.vatcompliance.co/api/1/app/l_invoice/credit_notes/your-access-token/1234";
String json = "{\"credit_note_date\":\"2024-01-20\",\"due_date\":\"2024-02-20\",\"status\":\"sent\",\"line_items\":[{\"description\":\"Updated Web Development Services Refund\",\"quantity\":15,\"unit_price\":75.00,\"tax\":true},{\"description\":\"Additional Consulting Refund\",\"quantity\":5,\"unit_price\":100.00,\"tax\":true}],\"subtotal\":1625.00,\"total_tax\":357.50,\"total\":1982.50,\"total_discount_amount\":0.00}";
HttpClient client = HttpClient.newHttpClient();
HttpRequest request = HttpRequest.newBuilder()
.uri(URI.create(url))
.header("Content-Type", "application/json")
.PUT(HttpRequest.BodyPublishers.ofString(json, StandardCharsets.UTF_8))
.build();
HttpResponse response = client.send(request, HttpResponse.BodyHandlers.ofString());
System.out.println(response.body());
}
}
package main
import (
"bytes"
"encoding/json"
"fmt"
"net/http"
"io/ioutil"
)
func main() {
url := "https://invoice.vatcompliance.co/api/1/app/l_invoice/credit_notes/your-access-token/1234"
update_data := map[string]interface{}{
"credit_note_date": "2024-01-20",
"due_date": "2024-02-20",
"status": "sent",
"line_items": []map[string]interface{}{
{
"description": "Updated Web Development Services Refund",
"quantity": 15,
"unit_price": 75.00,
"tax": true,
},
{
"description": "Additional Consulting Refund",
"quantity": 5,
"unit_price": 100.00,
"tax": true,
},
},
"subtotal": 1625.00,
"total_tax": 357.50,
"total": 1982.50,
"total_discount_amount": 0.00,
}
body, _ := json.Marshal(update_data)
req, _ := http.NewRequest("PUT", url, bytes.NewBuffer(body))
req.Header.Set("Content-Type", "application/json")
client := &http.Client{}
resp, err := client.Do(req)
if err != nil {
panic(err)
}
defer resp.Body.Close()
responseData, _ := ioutil.ReadAll(resp.Body)
fmt.Println(string(responseData))
}
Example responses
Update credit note response
Success response
{
"status": "done",
"results": [
{
"index": 0,
"status": "success",
"credit_note_id": 5291,
"credit_note_number": "CN-2025-001",
"total": "245.0"
}
]
}
Limitations and best practices
- Rate Limiting: Maximum 100 requests per minute per access token
- Partial Updates: Only provided fields will be updated, others remain unchanged
- Data Validation: All update data is validated before processing
- Line Items: If updating line items, must provide complete new list
- Date Format: All dates must be in YYYY-MM-DD format
- Decimal Precision: All monetary values support 2 decimal places