First Time Invoicing

This guide walks you through the complete setup needed to issue your first invoice and record its payment via the Moloni ON API. By the end you will have:

A document set (the numbering series for invoices and receipts)
A payment method to record how the customer pays
A product category and a product
A customer
A finalized invoice and its matching receipt

Each step builds on the previous one, so work through them in order.

Prerequisites

Before starting, make sure you have:

A valid OAuth access token or API key (see API Clients or API Keys)
Your company's companyId, returned by the companies query

A document set is a numbered series for your documents. Each document type you want to use (invoice, receipt, credit note, etc.) must be associated with at least one document set. The document set holds the sequential counter, so invoice #1, #2, #3 all belong to the same set.

A single document set can cover multiple document types. The example below creates one set for both invoices (documentTypeId: 1) and receipts (documentTypeId: 2), both starting at number 1:

mutation {
  documentSetCreate(
    companyId: 1
    data: {
      name: "Main Series"
      isDefault: true
      documentTypes: [
        { documentTypeId: 1, initialNumber: 1 }
        { documentTypeId: 2, initialNumber: 1 }
      ]
    }
  ) {
    errors { field msg }
    data {
      documentSetId
      name
      isDefault
    }
  }
}

Save the documentSetId from the response. You will use it when creating invoices and receipts.

Portuguese companies: AT registration

If your company is registered in Portugal, each document type in the set must include an at block for tax authority (AT) series registration. Setting isAutomatic: true tells the API to communicate the series to AT automatically as soon as the document set is created. The state starts as initialise and moves to active once AT accepts the registration.

mutation {
  documentSetCreate(
    companyId: 1
    data: {
      name: "Main Series"
      isDefault: true
      documentTypes: [
        {
          documentTypeId: 1
          initialNumber: 1
          at: {
            date: "2025-01-01"
            state: initialise
            isAutomatic: true
          }
        }
        {
          documentTypeId: 2
          initialNumber: 1
          at: {
            date: "2025-01-01"
            state: initialise
            isAutomatic: true
          }
        }
      ]
    }
  ) {
    errors { field msg }
    data {
      documentSetId
      name
      documentTypes {
        documentTypeId
        at { state code }
      }
    }
  }
}

For manual AT registration instead, set isAutomatic: false and provide the code you received from AT with state: active. The validation code AT assigns to each series is an 8-character string of uppercase consonants only (no vowels, no digits) — for example KLMPDSTV.

If you need to configure or review the AT communication settings for a document set (such as switching between automatic and manual, or checking the registration state), you can do so directly in the Moloni ON AC. Navigate to the document set's settings page at:

https://ac.molonion.pt/{companySlug}/documentSets/{documentSetId}

Step 2: Check your payment methods

Moloni ON creates default payment methods for your company during setup (typically Cash and Bank Transfer). Query them to find the IDs you will need when creating receipts:

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

Note the paymentMethodId for the method you want to use. If none of the defaults fit your needs, you can add a new one:

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

Step 3: Create a product category

Products must belong to a category. Create one with a descriptive name:

mutation {
  productCategoryCreate(
    companyId: 1
    data: { name: "Electronics" }
  ) {
    errors { field msg }
    data {
      productCategoryId
      name
    }
  }
}

Save the productCategoryId from the response.

Step 4: Get a measurement unit

Every product requires a measurement unit. Moloni ON creates standard units for your company automatically (such as "Unit" or "Hour"). List them to find the one you need:

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

If the unit you need is not listed, create it:

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

Save the measurementUnitId.

Step 5: Check available taxes

Taxes are pre-configured for your company based on your country. Query them to find the rate to apply to your product:

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

Note the taxId of the rate you want (for example the standard VAT rate for your country).

Step 6: Create a product

Create a product using the category, measurement unit, and tax from the previous steps:

mutation {
  productCreate(
    companyId: 1
    data: {
      productCategoryId: 5
      type: 1
      reference: "CHRG-001"
      name: "Laptop Charger"
      price: 20.00
      measurementUnitId: 1
      taxes: [
        { taxId: 1, ordering: 1 }
      ]
    }
  ) {
    errors { field msg }
    data {
      productId
      name
      price
    }
  }
}

The type field controls the product category:

Value	Meaning
`1`	Product (physical goods)
`2`	Service
`3`	Other

Portuguese companies: SAF-T product type

If your company is registered in Portugal, you must also provide the productAT block on every product. This sets the SAF-T product type required by the Portuguese Tax Authority:

productAT: { productType: M }

Value	SAF-T meaning
`M`	Mercadorias (goods for resale)
`P`	Matérias-primas, subsidiárias e de consumo (raw materials)
`A`	Activos próprios (own fixed assets)
`S`	Serviços (services)
`T`	Outros (other)
`B`	Bens imóveis (real estate)

The value must match the nature of the product as defined in the SAF-T (PT) schema.

See Overview & Creating a Product for the full list of available fields including stock management, variants, and identifications.

Save the productId from the response.

Step 7: Create a customer

Create the customer you will invoice:

mutation {
  customerCreate(
    companyId: 1
    data: {
      number: "C001"
      name: "Acme Corporation"
      email: "billing@acme.example"
      countryId: 1
      languageId: 1
    }
  ) {
    errors { field msg }
    data {
      customerId
      name
    }
  }
}

countryId and languageId are required. Use the countries and languages queries to look up the correct IDs for your situation.

Save the customerId from the response.

Step 8: Create an invoice

Issue a finalized invoice using the IDs collected in the steps above:

mutation {
  invoiceCreate(
    companyId: 1
    data: {
      documentSetId: 10
      customerId: 55
      date: "2025-06-01T09:00:00.000Z"
      expirationDate: "2025-07-01"
      status: 1
      products: [
        {
          productId: 99
          qty: 1
          ordering: 1
        }
      ]
    }
  ) {
    errors { field msg }
    data {
      documentId
      number
      totalValue
      status
    }
  }
}

The response includes:

documentId: the ID you need to reference this invoice in the receipt
number: the sequential invoice number within the document set
totalValue: the total amount due, including taxes

Setting status: 1 finalizes the invoice immediately and assigns it a number. Use status: 0 to save it as a draft first.

Taxes are applied automatically

You do not need to pass taxes on each line item. The API applies the taxes configured on the product automatically. Only include the taxes array on a line item if you want to override the product defaults for that specific line.

For a full description of all available invoice fields, see Creating an Invoice.

Step 9: Record the payment

Once the customer pays, issue a receipt to settle the invoice. Use the documentId from the previous step, the paymentMethodId from Step 2, and the total amount from the invoice response:

mutation {
  receiptCreate(
    companyId: 1
    data: {
      documentSetId: 10
      customerId: 55
      date: "2025-06-01T10:00:00.000Z"
      status: 1
      relatedWith: [
        { relatedDocumentId: 1234, value: 24.60 }
      ]
      payments: [
        { paymentMethodId: 1, value: 24.60 }
      ]
    }
  ) {
    errors { field msg }
    data {
      documentId
      number
      totalValue
    }
  }
}

The relatedWith array links the receipt to the invoice and specifies how much of each invoice is being settled. The payments array records the method and amount received.

For more on partial payments and settling multiple invoices at once, see Paying an Invoice.

Next steps

Creating an Invoice: Full invoice fields, draft workflow, and tax overrides
Paying an Invoice: Partial payments, multiple payment methods, and settlement details
Overview & Creating a Product: Variants, property groups, stock management, and identifications
API Reference: Browse every query, mutation, and type