Skip to main content

​
Overview

Parties represent organizations or individuals involved in a business transaction. In UBL invoices, you’ll typically work with:
  • Accounting Supplier Party: The seller/provider issuing the invoice
  • Accounting Customer Party: The buyer/recipient of the invoice
  • Tax Representative Party: Optional tax representative
  • Delivery Party: Party handling delivery
  • Carrier Party: Transportation provider

​
Party Structure

A party in UBL contains:
  • Party Identifications: Tax IDs, registration numbers
  • Party Names: Legal and trade names
  • Postal Address: Physical location
  • Party Tax Schemes: Tax registration information
  • Party Legal Entities: Legal entity details
  • Contact: Contact information

​
Creating a Supplier Party

1

Import Required Components

import {
  AccountingSupplierParty,
  Party,
  PartyTaxScheme,
  PartyLegalEntity,
  TaxScheme,
  PostalAddress,
  Country,
  Contact
} from 'ubl-builder';
2

Create Party Identification

Add tax identification and other IDs:
const party = new Party({
  partyTaxSchemes: [],
  partyLegalEntities: [],
  postalAddress: null as any // Will set below
});

// Add party identification (NIT, tax ID, etc.)
party.addPartyIdentification({
  id: '900123456',
  schemeAgencyID: '195',
  schemeAgencyName: 'CO, DIAN',
  schemeID: '7', // Verification digit
  schemeName: '31' // NIT
});
For Colombian invoices, use schemeName: '31' for NIT (Tax ID) and include the verification digit in schemeID.
3

Add Party Name

Set the legal or trade name:
// Add from string (simple)
party.addPartyName('ACME Corporation S.A.S.');

// Or add with PartyName object
import { PartyName } from 'ubl-builder';

party.addPartyName(new PartyName({
  name: 'ACME Corporation S.A.S.'
}));
4

Set Postal Address

Add the physical address:
const address = new PostalAddress({
  id: '11001',
  cityName: 'Bogotá',
  countrySubentity: 'Bogotá D.C.',
  countrySubentityCode: '11',
  addressLines: [
    { line: 'Calle 100 # 8A-55' },
    { line: 'Torre B, Piso 12' }
  ],
  country: new Country({
    identificationCode: 'CO',
    name: 'Colombia'
  })
});

party.attributes.postalAddress = address;
5

Add Tax Scheme Information

Register tax scheme details:
party.addPartyTaxScheme({
  registrationName: 'ACME Corporation S.A.S.',
  companyID: '900123456',
  taxLevelCode: 'O-13', // Grandes Contribuyentes
  taxScheme: new TaxScheme({
    id: '01',
    name: 'IVA'
  })
});

// Add additional tax schemes if needed
party.addPartyTaxScheme({
  registrationName: 'ACME Corporation S.A.S.',
  companyID: '900123456',
  taxScheme: new TaxScheme({
    id: 'ZZ', // Other
    name: 'No aplica'
  })
});
Common Colombian tax level codes:
  • O-13: Grandes Contribuyentes (Large Taxpayers)
  • O-15: Autoretenedor (Self-withholding)
  • O-23: Régimen Simple
  • R-99-PN: Persona Natural (Individual)
6

Add Legal Entity Information

party.addPartyLegalEntity(new PartyLegalEntity({
  registrationName: 'ACME Corporation S.A.S.',
  companyID: '900123456',
  corporateRegistrationScheme: {
    id: '12345',
    name: 'SETP'
  },
  registrationAddress: address // Reuse the postal address
}));
7

Add Contact Information

Optional contact details:
party.setContact(new Contact({
  name: 'John Smith',
  telephone: '+57 1 234 5678',
  electronicMail: '[email protected]'
}));
8

Create Accounting Supplier Party

Wrap the party in AccountingSupplierParty:
const supplier = new AccountingSupplierParty({
  party: party
});

// Add to invoice
invoice.setAccountingSupplierParty(supplier);

​
Creating a Customer Party

The customer party follows a similar structure: 
import { AccountingCustomerParty } from 'ubl-builder';

const customerParty = new Party({
  partyTaxSchemes: [],
  partyLegalEntities: [],
  postalAddress: null as any
});

// Add identification
customerParty.addPartyIdentification({
  id: '800123456',
  schemeAgencyID: '195',
  schemeAgencyName: 'CO, DIAN',
  schemeID: '3', // Verification digit
  schemeName: '31' // NIT
});

// Add name
customerParty.addPartyName('Client Company S.A.');

// Add address
customerParty.attributes.postalAddress = new PostalAddress({
  id: '05001',
  cityName: 'Medellín',
  countrySubentity: 'Antioquia',
  countrySubentityCode: '05',
  addressLines: [{ line: 'Carrera 43A # 1-50' }],
  country: new Country({
    identificationCode: 'CO',
    name: 'Colombia'
  })
});

// Add tax scheme
customerParty.addPartyTaxScheme({
  registrationName: 'Client Company S.A.',
  companyID: '800123456',
  taxLevelCode: 'O-15',
  taxScheme: new TaxScheme({ id: '01', name: 'IVA' })
});

// Add legal entity
customerParty.addPartyLegalEntity(new PartyLegalEntity({
  registrationName: 'Client Company S.A.',
  companyID: '800123456'
}));

// Create customer party
const customer = new AccountingCustomerParty({
  party: customerParty
});

invoice.setAccountingCustomerParty(customer);

​
Complete Supplier Example

import {
  AccountingSupplierParty,
  Party,
  PartyTaxScheme,
  PartyLegalEntity,
  TaxScheme,
  PostalAddress,
  Country,
  Contact,
  AddressLine
} from 'ubl-builder';

function createSupplier() {
  const party = new Party({
    partyTaxSchemes: [],
    partyLegalEntities: [],
    postalAddress: null as any
  });

  // Identification
  party.addPartyIdentification({
    id: '900123456',
    schemeAgencyID: '195',
    schemeAgencyName: 'CO, DIAN (Dirección de Impuestos y Aduanas Nacionales)',
    schemeID: '7',
    schemeName: '31'
  });

  // Name
  party.addPartyName('ACME Corporation S.A.S.');

  // Address
  const address = new PostalAddress({
    id: '11001',
    cityName: 'Bogotá',
    countrySubentity: 'Bogotá D.C.',
    countrySubentityCode: '11',
    addressLines: [
      new AddressLine({ line: 'Calle 100 # 8A-55' }),
      new AddressLine({ line: 'Zona Industrial, Edificio Norte' })
    ],
    country: new Country({
      identificationCode: 'CO',
      name: 'Colombia'
    })
  });
  party.attributes.postalAddress = address;

  // Tax Schemes
  party.addPartyTaxScheme(new PartyTaxScheme({
    registrationName: 'ACME Corporation S.A.S.',
    companyID: '900123456',
    taxLevelCode: 'O-13',
    taxScheme: new TaxScheme({
      id: '01',
      name: 'IVA'
    })
  }));

  // Legal Entity
  party.addPartyLegalEntity(new PartyLegalEntity({
    registrationName: 'ACME Corporation S.A.S.',
    companyID: '900123456',
    registrationAddress: address
  }));

  // Contact
  party.setContact(new Contact({
    name: 'Accounting Department',
    telephone: '+57 1 234 5678',
    telefax: '+57 1 234 5679',
    electronicMail: '[email protected]'
  }));

  return new AccountingSupplierParty({ party });
}

const supplier = createSupplier();
invoice.setAccountingSupplierParty(supplier);

​
Additional Party Types

​
Tax Representative Party

For invoices requiring a tax representative: 
import { TaxRepresentativeParty } from 'ubl-builder';

const taxRep = new TaxRepresentativeParty({
  partyTaxSchemes: [],
  partyLegalEntities: [],
  postalAddress: null as any
});

taxRep.addPartyName('Tax Representative Firm');
taxRep.addPartyTaxScheme({
  registrationName: 'Tax Representative Firm',
  companyID: '700123456',
  taxScheme: new TaxScheme({ id: '01', name: 'IVA' })
});

invoice.setTaxRepresentativeParty(taxRep);

​
Delivery Party

For delivery information: 
import { Delivery, DeliveryParty } from 'ubl-builder';

const deliveryParty = new DeliveryParty({
  partyTaxSchemes: [],
  partyLegalEntities: [],
  postalAddress: null as any
});

deliveryParty.addPartyName('Logistics Company S.A.');

const delivery = new Delivery({
  deliveryParty: deliveryParty,
  deliveryAddress: new PostalAddress({
    cityName: 'Cali',
    countrySubentity: 'Valle del Cauca',
    addressLines: [{ line: 'Avenida 6N # 23-45' }],
    country: new Country({ identificationCode: 'CO' })
  }),
  requestedDeliveryPeriod: {
    startDate: '2024-03-10',
    endDate: '2024-03-15'
  }
});

invoice.addDelivery(delivery);

​
Party Testing

Test your party configuration: 
const party = new Party({} as any);
party.addPartyName('Test Company');
party.addPartyIdentification({ id: '900123456' });

const json = party.parseToJson();
console.log(JSON.stringify(json, null, 2));

// Expected output:
// {
//   "cac:PartyName": [{ "cbc:Name": { "#text": "Test Company" } }],
//   "cac:PartyIdentification": [{ "cbc:ID": { "#text": "900123456" } }]
// }

​
Best Practices

Validation Tips

  • Always include at least one party identification
  • Provide complete tax scheme information for Colombian invoices
  • Use proper tax level codes (O-13, O-15, etc.)
  • Include verification digit in schemeID
  • Validate NIT/tax ID format before creating parties

Address Formatting

  • Use official city and department codes
  • Include complete street addresses
  • Set proper country identification code (CO for Colombia)
  • Consider using multiple address lines for clarity

Contact Information

  • Include at least email or telephone
  • Use proper international phone format (+57 for Colombia)
  • Provide department or contact person name
  • Keep contact info current for delivery and inquiries

​
Common Patterns

​
Reusing Party Information

// Create a reusable party configuration
function createPartyConfig(data: {
  nit: string;
  name: string;
  city: string;
  address: string;
}) {
  const party = new Party({
    partyTaxSchemes: [],
    partyLegalEntities: [],
    postalAddress: null as any
  });

  party.addPartyIdentification({ id: data.nit });
  party.addPartyName(data.name);
  party.addPartyTaxScheme({
    registrationName: data.name,
    companyID: data.nit,
    taxScheme: new TaxScheme({ id: '01', name: 'IVA' })
  });

  party.attributes.postalAddress = new PostalAddress({
    cityName: data.city,
    addressLines: [{ line: data.address }],
    country: new Country({ identificationCode: 'CO' })
  });

  return party;
}

// Use for different party types
const supplierParty = createPartyConfig({
  nit: '900123456',
  name: 'Supplier Corp',
  city: 'Bogotá',
  address: 'Calle 100 # 8A-55'
});

const customerParty = createPartyConfig({
  nit: '800123456',
  name: 'Customer Inc',
  city: 'Medellín',
  address: 'Carrera 43A # 1-50'
});

​
Next Steps

Creating Invoices

Learn how to create complete UBL invoices

Tax Calculations

Add tax totals and calculations to invoices

Build docs developers (and LLMs) love

Get started for freeTalk to us