Basic Invoice Example

Create a simple UBL 2.1 invoice with minimal required fields

This example demonstrates the simplest possible invoice you can create with the UBL Builder library. It includes only the essential fields required for a valid UBL 2.1 invoice.

Installation

First, install the library:

npm install ubl-builder

Basic Invoice Code

TypeScript

import { Invoice } from 'ubl-builder';

const invoice = new Invoice('123456789', {});
invoice.addProperty('xmlns', 'urn:oasis:names:specification:ubl:schema:xsd:Invoice-2');

const xml = invoice.getXml();
console.log(xml);

Generated XML Output

The code above generates the following UBL 2.1 XML:

<?xml version="1.0" encoding="UTF-8" standalone="no"?>
<Invoice
    xmlns="urn:oasis:names:specification:ubl:schema:xsd:Invoice-2">
    <cbc:UBLVersionID>UBL 2.1</cbc:UBLVersionID>
    <cbc:ID>123456789</cbc:ID>
    <cbc:IssueDate>2020-09-13</cbc:IssueDate>
    <cbc:IssueTime>02:10:44-05:00</cbc:IssueTime>
</Invoice>

Adding Basic Fields

Let’s enhance the invoice with additional required fields:

TypeScript

import { Invoice } from 'ubl-builder';

const invoiceOptions = {
  enviroment: '2', // '1' for production, '2' for testing
  issuer: {
    prefix: 'INV',
    resolutionNumber: '321654987',
    startDate: '2024-01-01',
    endDate: '2025-12-31',
    startRange: '1000',
    endRange: '5000',
    technicalKey: 'tech-key-123',
  },
  software: {
    id: 'soft-123',
    pin: '123456789',
    providerNit: '900123456-1',
  },
};

const invoice = new Invoice('INV-001', invoiceOptions);

// Set default UBL namespaces
invoice.setDefaultProperties();

// Set basic invoice fields
invoice.setID('INV-001');
invoice.setUBLVersionID('UBL 2.1');
invoice.setIssueDate('2026-03-06');
invoice.setIssueTime('10:30:00-05:00');
invoice.setInvoiceTypeCode('01'); // Standard invoice
invoice.setDocumentCurrencyCode('USD');
invoice.addNote('Payment due within 30 days');

const xml = invoice.getXml(true); // true for pretty formatting
console.log(xml);

Key Fields Explained

Field	Description
ID	Unique invoice number
UBLVersionID	UBL standard version (typically “UBL 2.1”)
IssueDate	Date the invoice was issued (YYYY-MM-DD format)
IssueTime	Time the invoice was issued (HH:MM:SS±HH:MM format)
InvoiceTypeCode	Type of invoice (01 = standard, 02 = credit note, etc.)
DocumentCurrencyCode	Currency code (USD, EUR, COP, etc.)
Note	Additional notes or payment terms

The invoice constructor requires two parameters:

1. Invoice ID (string): The unique invoice identifier
2. Options (object): Configuration object with issuer, software, and environment details

For a minimal test invoice, you can pass an empty object {} as the options parameter. However, for production use, always include complete issuer and software configuration.

Next Steps

• Learn how to add tax calculations in Invoice with Tax
• See a full-featured invoice in Complete Invoice
• Explore the API Reference for all available methods