Customers

Customers are the counterparties you bill, and every sales document (invoice, receipt, credit note, etc.) is issued to a customer. Each company maintains its own customer list.

The default customer

Every company has a default customer (isDefault: true). It is used as a fallback when creating documents without a specific customer and represents generic/anonymous billing (e.g. cash sales). There is exactly one default customer per company, and it cannot be deleted.

Required fields

When creating a customer, three things are required:

Field	Type	Notes
`number`	`String!`	Unique reference code within the company
`countryId`	`Int!`	The customer's country
`name` or `vat`	`String`	At least one must be provided

Auto-generate the number

Use customerNextNumber to get the next available sequential number before creating:

query {
  customerNextNumber(companyId: 1) {
    data
    errors { field msg }
  }
}

Creating a customer

mutation {
  customerCreate(
    companyId: 1
    data: {
      number: "C001"
      name: "Acme Corporation"
      vat: "123456789"
      countryId: 1
      email: "billing@acme.com"
      phone: "+351 210 000 000"
      address: "Rua Exemplo, 1"
      city: "Lisboa"
      zipCode: "1000-001"
    }
  ) {
    data {
      customerId
      number
      name
      vat
    }
    errors { field msg }
  }
}

VAT number (NIF) validation

The API validates the vat field against the rules for the customer's country. For Portuguese customers (countryId: 1), the NIF must be a 9-digit number that passes the official Modulo 11 checksum. Make sure you are sending real, valid NIFs. Test or placeholder numbers will fail with:

{ "field": "vat", "msg": "Invalid VAT inserted" }

For EU customers, you can optionally verify the VAT number against the EU VIES database before creating the customer using the viesCheck query.

Billing defaults

You can attach billing preferences to a customer at creation or update time. When a document is created for this customer, these defaults are pre-filled:

Field	Description
`paymentMethodId`	Default payment method (cash, transfer, etc.)
`maturityDateId`	Default payment terms / due date rule
`deliveryMethodId`	Default delivery method
`documentSetId`	Default document set (numbering series)
`priceClassId`	Default price class for product pricing
`discount`	Global discount percentage applied to all line items
`creditLimit`	Maximum outstanding balance allowed
`paymentDay`	Day of the month when payment is expected
`taxes`	Array of default taxes to apply to this customer's documents
`exemptionReason`	VAT exemption reason code (required when tax-exempt)
`notesOnDocs`	Whether to include `documentNotes` on every document
`documentNotes`	Text printed on every document for this customer

API vs. the web app

These defaults exist to prefill the document creation form in the Moloni ON web app (ac.molonion.pt). When creating a document through the API, the API does not automatically pull these customer defaults. You must explicitly send every field and value you want on the document in the mutation itself.

Getting a customer

query {
  customer(companyId: 1, customerId: 42) {
    data {
      customerId
      number
      name
      vat
      email
      phone
      address
      city
      zipCode
      balance
      creditLimit
      discount
      country { name }
      paymentMethod { name }
      maturityDate { name }
      taxes {
        tax { name value }
        cumulative
        ordering
      }
    }
    errors { field msg }
  }
}

Listing and searching customers

query {
  customers(
    companyId: 1
    options: {
      search: { field: ALL, value: "Acme" }
      pagination: { page: 1, qty: 20 }
      order: { field: name, sort: ASC }
    }
  ) {
    data {
      customerId
      number
      name
      vat
      email
      balance
    }
    options {
      pagination { page qty count }
    }
    errors { field msg }
  }
}

Search fields

You can search by a specific field or use ALL to search across all of them:

`field` value	Searches in
`ALL`	Name, number, VAT, email, phone, contact, address, alternate addresses
`name`	Customer name
`number`	Customer reference number
`vat`	VAT / tax number
`email`	Email address
`address`	Street address
`city`	City
`zipCode`	Postal code
`phone`	Phone number
`contactName`	Primary contact name

Filtering

Use filter to narrow results by exact field values:

query {
  customers(
    companyId: 1
    options: {
      filter: [
        { field: countryId, comparison: EQ, value: "1" }
        { field: visible, comparison: EQ, value: "1" }
      ]
      pagination: { page: 1, qty: 20 }
    }
  ) {
    data {
      customerId
      name
    }
    options {
      pagination { page qty count }
    }
  }
}

See Filtering & Search for full details on filter syntax.

Updating a customer

Only the fields you send are updated, everything else stays unchanged. customerId is required to identify the record:

mutation {
  customerUpdate(
    companyId: 1
    data: {
      customerId: 42
      email: "new@acme.com"
      creditLimit: 5000.00
      discount: 10
    }
  ) {
    data {
      customerId
      email
      creditLimit
      discount
    }
    errors { field msg }
  }
}

Deleting customers

The customerDelete mutation accepts an array of IDs, so you can delete multiple customers in one call. It returns a summary with how many were deleted and any errors:

mutation {
  customerDelete(companyId: 1, customerId: [42, 43]) {
    status
    deletedCount
    elementsCount
    errors { field msg }
  }
}

Not all customers can be deleted

A customer with existing documents is not deletable. Check the deletable field on the customer before attempting deletion, as a false value means the customer is referenced by at least one document and the delete will be silently skipped for that ID.

Retrieve all documents issued to a customer with getCustomerRelatedDocuments:

query {
  getCustomerRelatedDocuments(
    companyId: 1
    customerId: 42
    options: {
      pagination: { page: 1, qty: 20 }
    }
  ) {
    data {
      documentId
      documentTypeId
      number
      date
      totalValue
      status
    }
    options {
      pagination { page qty count }
    }
  }
}

Alternate addresses

Customers can have multiple shipping/delivery addresses stored as alternateAddresses. These are returned as an array on the customer object and can be passed on individual documents to override the default billing address.

Next steps

Suppliers: Manage your supplier contacts
Salespersons: Assign sales staff to documents and track commissions
Creating an Invoice: Create a document for a customer
Filtering, Search & Ordering: Filter and search customer lists