Customer

A customer is a master record in the Financials application that stores information about organisations who purchase goods or services from a company. It contains details such as the customer's name, main contact, and physical address.

Customer List

To obtain a list of Customer records, the following GraphQL query may be utilised:

Example Customer Record List GraphQL Query

query (
  $filter: CustomerFilterInput
  $sort: [CustomerSortSortByInput!]
  $after: String
) {
  debtors {
    masterRecords {
      customers {
        records(filter: $filter, sort: $sort, after: $after) {
          items {
            customerDetails {
              ...customerDetails
            }
            summaryData {
              ...SummaryDetails
            }
          }
          pageInfo {
            hasNextPage
            endCursor
          }
        }
      }
    }
  }
}
fragment customerDetails on CustomerDetails {
  primaryKey
  uniqueId
  code
  name
  onStop
  notes
  contactDetails {
    ...ContactDetails
  }
  addressDetails {
    ...AddressDetails
  }
  userSort {
    ...UserSortDetails
  }
  customerCustomFields {
    ...CustomFieldDetails
  }
}

fragment SummaryDetails on SummaryData {
  balance
  currencyBalance
  turnoverYTD
  currencyTurnoverYTD
  turnoverPtd
}

fragment ContactDetails on ContactDetails {
  title
  firstName
  surname
  salute
  jobTitle
  initials
  contact
}

fragment AddressDetails on AddressDetails {
  primaryKey
  address
  town
  county
  country
  postCode
  email
  telephone
  mobile
  website
  fax
  invoiceAddressCode
  deliveryAddressCode
  statementEmail
}

fragment UserSortDetails on UserSort {
  sortKey
  userSort1
  userSort2
  userSort3
}

fragment CustomFieldDetails on CustomerCustomFields {
  userCharacters {
    char1
    char2
    char3
    char4
    char5
    char6
    char7
    char8
  }
  userNumbers {
    number1
    number2
    number3
  }
  userDates {
    date1
    date2
    date3
  }
  userFlags {
    flag1
    flag2
    flag3
  }
}

Using this query, you can tailor your results using the following features:

• Filtering: The list of customer records can be filtered using the provided filter parameter. An example of this Filter can be found below:

  {
    "filter": {
      "name": {
        "beginsWith": "The"
      },
      "onStop": {
        "eq": false
      },
      "overCreditLimit": {
        "eq": true
      }
    }
  }

• Grouping: To group customer records, use the group parameter provided. For more details see Aggregation.

• Sorting: To order results use the sort parameter provided. For more details on ordering the results returned by the API, see Sorting.

• Pagination: This API endpoint returns 100 records per page. For more information on paging, see Pagination.

Create Customer

To create a new customer, you can use the following GraphQL mutation:

mutation ($customer: CustomerInput!) {
  debtors {
    masterRecords {
      customer {
        create(customer: $customer) {
          __typename
          ... on IntEntityId {
            ...IntEntityIdDetails
          }
          ... on FailedValidation {
            ...FailedValidationDetails
          }
          ... on UnexpectedError {
            ... UnexpectedErrorDetails
          }
        }
      }
    }
  }
}

fragment IntEntityIdDetails on IntEntityId {
  id
}

fragment FailedValidationDetails on FailedValidation {
  errors {
    ...ValidationItemDetails
  }
  warnings {
    ...ValidationItemDetails
  }
}

fragment ValidationItemDetails on ValidationItem {
  message
  details {
    primaryKey
    field
    value
  }
}

fragment UnexpectedErrorDetails on UnexpectedError {
  errorMessage
}

Populate $customer with the actual information about the customer you want to create. Please refer to CustomerInput GraphQL type in Api Reference.

Update Customer

To update an existing customer, you can use the following GraphQL mutation:

mutation ($customer: CustomerInput!) {
  debtors {
    masterRecords {
      customer {
        update(customer: $customer) {
          __typename
          ... on IntEntityId {
            ...IntEntityIdDetails
          }
          ... on FailedValidation {
            ...FailedValidationDetails
          }
          ... on UnexpectedError {
            ... UnexpectedErrorDetails
          }
        }
      }
    }
  }
}

fragment IntEntityIdDetails on IntEntityId {
  id
}

fragment FailedValidationDetails on FailedValidation {
  errors {
    ...ValidationItemDetails
  }
  warnings {
    ...ValidationItemDetails
  }
}

fragment ValidationItemDetails on ValidationItem {
  message
  details {
    primaryKey
    field
    value
  }
}

fragment UnexpectedErrorDetails on UnexpectedError {
  errorMessage
}

Delete Customer

To delete customers by their ID, you can use the following GraphQL mutation:

mutation ($primaryKeys: [Int!]) {
  debtors {
    masterRecords {
      customer {
        delete(primaryKeys: $primaryKeys) {
          __typename
          ... on Succeeded {
            ... SucceededDetails
          }
          ... on FailedValidation {
            ... FailedValidationDetails
          }
          ... on UnexpectedError {
            ... UnexpectedErrorDetails
          }
        }
      }
    }
  }
}

fragment SucceededDetails on Succeeded {
  succeeded
}

fragment FailedValidationDetails on FailedValidation {
  errors {
    ...ValidationItemDetails
  }
  warnings {
    ...ValidationItemDetails
  }
}

fragment ValidationItemDetails on ValidationItem {
  message
  details {
    primaryKey
    field
    value
  }
}

fragment UnexpectedErrorDetails on UnexpectedError {
  errorMessage
}