Reference Data#

Several fields throughout the API require IDs that refer to records maintained by the platform: country IDs, language IDs, currency IDs, and so on. These are not created by you; they are provided by Moloni ON and shared across all companies. A smaller set (taxes, measurement units, payment methods) is configured per company during setup.

This guide shows how to query each of these and explains which are global versus company-scoped.

Global reference data#

These resources are the same for all companies. You can query them without a companyId and cache the results locally; they change very rarely.

Countries#

Every customer, supplier, and company has a countryId. Use the countries query to look up IDs:

query {
  countries(options: { defaultLanguageId: 2 }) {
    data {
      countryId
      iso3166_1
      name
    }
  }
}

Pass defaultLanguageId to get country names in your preferred language. See Translated Fields for how this works.

Languages#

The languageId controls the language used for translated fields (document type names, etc.) and can be set on customers and suppliers to indicate their preferred language for documents.

query {
  languages {
    data {
      languageId
      name
      iso3166
    }
  }
}

Currencies#

Moloni ON supports multi-currency documents. The default currency for Portuguese companies is EUR. Use currencies to find the ID if you need to issue documents in a foreign currency:

query {
  currencies(options: { defaultLanguageId: 2 }) {
    data {
      currencyId
      name
      abbreviation
      symbol
    }
  }
}

When creating a document in a foreign currency, use currencyExchangeId to attach an exchange rate.

Document types#

Document types define what kind of document you are creating: invoice, receipt, credit note, etc. They are system-wide and fixed. Use the documentTypes query to see all types with their IDs and API codes:

query {
  documentTypes(options: { defaultLanguageId: 2 }) {
    data {
      documentTypeId
      apiCode
      apiCodePlural
      saftDocCode
      title
      titlePlural
    }
  }
}

See the Document Types guide for the complete table with all types and their SAF-T codes.

Company-scoped reference data#

These resources are set up per company during onboarding. Moloni ON creates sensible defaults automatically. Query them using your companyId.

Taxes#

Taxes are pre-configured for each company based on the company's country. For Portuguese companies, the standard VAT rates (23%, 13%, 6%) and any applicable exemptions are created automatically.

query {
  taxes(companyId: 1) {
    data {
      taxId
      name
      type
      value
      isDefault
    }
  }
}

When creating products, attach taxes using their taxId. The tax is then applied automatically to any document line that uses that product.

Measurement units#

Every product requires a measurementUnitId. Moloni ON creates standard units (Unit, Hour, Kg, etc.) automatically for each company.

query {
  measurementUnits(companyId: 1) {
    data {
      measurementUnitId
      name
      abbreviation
    }
  }
}

If the unit you need does not exist, create it with measurementUnitCreate:

mutation {
  measurementUnitCreate(
    companyId: 1
    data: { name: "Unit", abbreviation: "un" }
  ) {
    errors { field msg }
    data {
      measurementUnitId
      name
      abbreviation
    }
  }
}

Payment methods#

Payment methods are used on receipts to record how a customer paid. Moloni ON creates defaults (Cash, Bank Transfer) during company setup. Query them to find the IDs you need:

query {
  paymentMethods(companyId: 1) {
    data {
      paymentMethodId
      name
      isDefault
    }
  }
}

Add new payment methods with paymentMethodCreate:

mutation {
  paymentMethodCreate(
    companyId: 1
    data: { name: "Multibanco", isDefault: false }
  ) {
    errors { field msg }
    data {
      paymentMethodId
      name
    }
  }
}

Caching strategy#

Global reference data (countries, languages, currencies, document types) changes very rarely. You can safely cache it at startup:

On startup:
  → fetch countries, languages, currencies, documentTypes
  → store in memory / local DB

On each request:
  → fetch company-scoped data if needed (taxes, measurementUnits, paymentMethods)
    or cache with a short TTL (e.g. 1 hour)

Next steps#

• Translated Fields: Use defaultLanguageId to get names in any language
• Creating an Invoice: Uses documentSetId, customerId, and product taxId
• First Time Invoicing: Full walkthrough that uses taxes, measurement units, and payment methods
• Document Types: Full document type table with SAF-T codes