Skip to main content

Sales Transactions

This document provides an overview of the operations available for the Sales Transactions business entity. Please note that the queries shown below only present a subset of the fields.

For a full list of fields, please refer to our schema documentation provided within our API. See Explore the API.

Mutations​

Create Sales Transactions​

To create new sales transactions within a Financials or Dimensions database, the Sales Transaction bulk create endpoint can be used. This operation supports both batching and posting of transactions. You can create one or more of the following types of sales transactions using this operation:

  • Sales Invoice
  • Sales Credit Note
  • Sales Receipt
  • Sales Debit Adjustment
  • Sales Credit Adjustment

Request​

Here's an example of how you can use the create mutation:

mutation (
$transactions: [SalesTransactionBulkInput!]!
$validateOnly: Boolean
) {
debtors {
  transactions {
    bulkTransactions {
      bulkCreate(transactions: $transactions, validateOnly: $validateOnly) {
        ... on IntEntityIds {
          ...IntEntityIdDetails
        }
        ... on FailedValidation {
          ...FailedValidationDetails
        }
        ... on UnexpectedError {
          ...UnexpectedErrorDetails
        }
      }
    }
  }
}
}

fragment IntEntityIdDetails on IntEntityIds {
ids
}

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

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

fragment UnexpectedErrorDetails on UnexpectedError {
errorMessage
}

When you execute the create mutation, it performs several steps to create new transactions:

  1. Running business validations: The API performs a number of business validations on the input data to ensure that it meets the required criteria. These validations can include checks for things like valid customer information, correct gross amount, and any other business rules specific to your application. If any validation errors occur, the mutation will return a response with the details of the errors.

  2. Calculating missing information: If any required information is missing from the input object, the mutation will calculate the missing values based on default settings or any other logic defined in the system. This ensures that the transaction has all the necessary data before it is created.

  3. Saving the transaction: If all the necessary information is present and the business validations pass successfully, the mutation will save the transaction in the system and make it available for further processing or retrieval.

Parameters​

Transaction [Required]​

This mutation requires an input object of type SalesTransactionBulkInput, which should contain all the necessary information to create the transaction.

Validate Only​

This operation supports "validate only" mode by setting the validateOnly parameter to true. In this mode, the API will check your transaction against a number of business rules, but will not attempt to save the transaction to the database.

Response​

After executing the create mutation, you will receive a response containing the IDs of the updated transactions if the creation was successful. If any validation errors or unexpected errors occur during the operation, the response will include the details of those errors.

An example of the three response types provided by this request can be found below:

{
  "data": {
    "debtors": {
      "transactions": {
        "bulkTransactions": {
          "bulkCreate": {
              [100, 101, 102]
          }
        }
      }
    }
  }

Update Sales Transactions​

To update a sales transaction, you can use the bulk update mutation. Like the transaction creation request, this mutation requires an input object of type SalesTransactionBulkInput, which should contain the information you wish to update on the existing transaction.

note

It is only possible to update batched transactions via this operation.

Request​

Here's an example of how you can use the update mutation to update a sales transaction:

mutation (
  $transactions: [SalesTransactionBulkInput!]!
  $validateOnly: Boolean
) {
  debtors {
    transactions {
      bulkTransactions {
        bulkUpdate(transactions: $transactions, validateOnly: $validateOnly) {
          ... on IntEntityIds {
            ...IntEntityIdDetails
          }
          ... on FailedValidation {
            ...FailedValidationDetails
          }
          ... on UnexpectedError {
            ...UnexpectedErrorDetails
          }
        }
      }
    }
  }
}

fragment IntEntityIdDetails on IntEntityIds {
  ids
}

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

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

fragment UnexpectedErrorDetails on UnexpectedError {
  errorMessage
}

When you execute the update mutation, it performs the following steps to update the sales transaction:

  1. Finding the transaction: The mutation first finds the sales transaction in the system.
  2. Updating the information: The mutation then updates the transaction with the new information provided in the SalesTransactionInput object. You can modify any relevant fields such as customer information, transaction lines, or any other details specific to your application.
  3. Recalculating missing information: If any required information is missing from the input object, the mutation will calculate the missing values based on default settings or any other logic defined in the system. This ensures that the transaction has all the necessary data before it is created.
  4. Running business validations: Similar to the create mutation, the update mutation also performs business validations on the updated data to ensure it meets the required criteria. If any validation errors occur, the mutation will return a response with the details of the errors.
  5. Saving the updated transaction: If all the necessary information is present and the business validations pass successfully, the mutation will save the updated transaction in the system. This means that the changes will be persisted and available for further processing or retrieval.

Parameters​

Transaction [Required]​

This mutation requires an input object of type SalesTransactionBulkInput, which should contain all the necessary information to create the transaction.

Validate Only​

This operation supports "validate only" mode by setting the validateOnly parameter to true, in this mode, the API will check your transaction against a number of business rules, but will not attempt to save the transaction to the database.

Response​

After executing the update mutation, you will receive a response containing the updated sales transaction's ID if the update was successful. If any validation errors or unexpected errors occur during the operation, the response will include the details of those errors.

An example of the three response types provided by this request can be found below:

{
  "data": {
    "debtors": {
      "transactions": {
        "bulkTransactions": {
          "bulkUpdate": {
            [100,101,102]
          }
        }
      }
    }
  }
}

Delete Sales Transactions​

To delete sales transactions, you can use the delete mutation. This operation contains a mandatory primaryKeys parameter which should be populated with the primary key of each transaction you want to delete.

note

Note this endpoint only supports the deletion of Sales Transactions. For the removal of other transaction types, please refer to our API schema documentation: Explore the API

Here's an example of how you can use the delete mutation to delete sales transactions:

mutation ($primaryKeys: [Int!]!) {
  debtors {
    transactions {
      batchedTransactions {
        delete(primaryKeys: $primaryKeys) {
          ... 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
}

In the above example, you need to provide the primaryKeys array containing the primary keys of the transactions you want to delete. The mutation will then attempt to delete the specified transactions.

If the deletion is successful, the response will include a succeeded field with a value of true. If any validation errors occur during the deletion process, the response will include the details of those errors in the errors field. Additionally, if there are any warnings related to the deletion, they will be included in the warnings field. If an unexpected error occurs, the response will include an errorMessage field with the details of the error.

An example of the three response types provided by this request can be found below:

{
  "data": {
    "debtors": {
      "transactions": {
        "batchedTransactions": {
          "delete": {
            "succeeded"
          }
        }
      }
    }
  }
}

Queries​

Get Batched Sales Transaction​

To retrieve information about a specific batched sales transaction, you can use the transactionEntry\header query. This query requires an input parameter id which represents the primary key of the transaction you want to retrieve.

Here's an example of how you can use the transactionEntry\header query to get the details of a batched sales transaction:

query ($id: Int!) {
  debtors {
    transactions {
      transactionEntry {
        header(id: $id) {
          transactionType
          hasNextPage
          header {
            ...HeaderDetails
          }
          detailLines {
            ...DetailLinesData
          }
        }
      }
    }
  }
}

fragment HeaderDetails on SalesTransactionHeader {
  primaryKey
  headerReference
  description
  creditController
  customer {
    code
    name
    anyCurrency
    onStop
    terms
    taxRegistrationNumber
  }
  dates {
    date
    dueDate
    receiptDate
  }
  values {
    ...TransactionValueData
  }
  period {
    year
    yearLabel
    number
  }
  subLedger {
    code
    description
  }
}

fragment DetailLinesData on SalesTransactionDetail {
  primaryKey
  detail
  tax {
    code
    rate
    type
  }
  values {
    ...TransactionValueData
  }
  costing {
    project {
      code
      name
    }
    costCentre {
      code
      name
    }
  }
}

fragment TransactionValueData on TransactionValues {
  net
  tax
  gross
  currencyNet
  currencyTax
  currencyGross
}

In this query, you need to provide the id parameter with the primary key of the batched sales transaction you want to retrieve. The response will include detailed information about the transaction, including the transaction type, header details, customer information, dates, values, period, subledger details, and detail lines.

The query only returns first page of detail lines, to get additional pages please use transactionEntry/details.

query (
  $filter: SalesTransactionDetailFilterInput!
  $sort: [SalesTransactionDetailSortSortByInput!]
  $first: Int
) {
  debtors {
    transactions {
      transactionEntry {
        details(filter: $filter, sort: $sort, first: $first) {
          items {
            primaryKey
            detail
            analysis {
              code
              name
              nominalUpdate {
                debit {
                  code
                  name
                }
                credit {
                  code
                  name
                }
                tax {
                  code
                  name
                }
              }
            }
            tax {
              code
              rate
              type
            }
            values {
              net
              tax
              gross
              currencyNet
              currencyTax
              currencyGross
            }
            costing {
              project {
                code
                name
              }
              costCentre {
                code
                name
              }
            }
            accrual {
              accrueOverPeriods
              defer
              account {
                code
                name
              }
            }
          }
        }
      }
    }
  }
}

Query Transaction Headers​

To retrieve information about transaction headers, you can use the allTransactions\header query. This query requires input parameters such as $first, $sort, $filter to specify the number of results, sorting criteria, and filtering conditions.

Filter options vary from field to field based on the type of the field, see SalesTransactionEnquiryFilterInput GraphQL type in API Reference.

Grouping by various columns is also possible. When a group column is specified, the result will be a unique list of values for the grouped column. It is possible to aggregate other columns as well by specifying $aggregate.

$fieldSelection is a parameter that can be used to specify which fields should be returned, it override the specification in the query. Fields selection can also be done through the query.

Here's an example of how you can use the header query to get transaction header details:

query (
  $first: Int
  $filter: SalesTransactionEnquiryFilterInput!
  $sort: [SalesTransactionEnquirySortSortByInput!]
  $group: SalesTransactionEnquirySort
  $aggregate: SalesTransactionEnquirySortGroupByInput
  $fieldSelection: [SalesTransactionEnquirySort]
) {
  debtors {
    transactions {
      allTransactions {
        header(
          first: $first
          sort: $sort
          filter: $filter
          group: $group
          aggregate: $aggregate
          fieldSelection: $fieldSelection
        ) {
          items {
            accountCode
            accountName
            transactionDate
            periodNumber
            orderNumber
            transactionType
            headerRef
            batched
            net
            tax
            enteredBy
            transactionDescription
            gross
            outstanding
            reconciled
            auditNo
            yearLabel
            dueDate
            dateEntered
            batchRef
            customerRef
            headerKey
            reverseTax
            exchangeRate
            sortKey
            anticipatedPaymentDate
            currencyGross
            currencyNet
            currencyOutstanding
            currencySymbol
            currencyTax
            onDispute
            subLedger
            country
            queryReason
            lastUpdatedBy
            lastUpdatedDateTime
            postedBy
            postedDateTime
            createdBy
            createdDateTime
            deliveryAddress
            deliveryTown
            deliveryCounty
            deliveryPostcode
            deliveryCountry
            deliveryContact
            transactionAddress
            transactionTown
            transactionCounty
            transactionCountry
            transactionPostcode
            transactionContact
            hasAllocationHistory
            hasMultipleDueDates
          }
        }
      }
    }
  }
}

In the above query, you can customize the parameters $first, $sort, and $filter to retrieve the desired number of results, apply sorting based on specific fields, and filter the transactions based on certain conditions.

The response will include an array of transaction headers, each containing various fields such as account code, account name, transaction date, etc.

Query Details​

To retrieve detailed information about sales transactions, you can use the details field within the allTransactions query. This field requires the following input parameters:

  • $first: Specifies the maximum number of results to retrieve.
  • $sort: Specifies the sorting order for the results based on specific fields.
  • $filter: Specifies the conditions to filter the transactions.

Here's an example of how you can use the details field to retrieve detailed information about sales transactions:

query($first: Int, $sort: [SalesTransactionEnquiryDetailSortSortByInput!], $filter: SalesTransactionEnquiryDetailFilterInput!) {
  debtors{
    transactions{
      allTransactions {
       details (first: $first, sort: $sort, filter: $filter) {
        items {
          primaryKey
          headerPrimary
          analysisCode
          analysisName
          itemCode
          projectCode
          projectName
          costCentreCode
          costCentreName
          orderNumber
          net
          taxCode
          tax
          gross
          transactionAuditNumber
          detail
          costPrice
          sellPrice
          accountCode
          accountName
          currentSortKey
          currencyGross
          currencyNet
          currencySymbol
          currencyTax
          dueDate
          quantity
          analysisType
        }  
      }
      }
    }
  }
}

In the above query, you can customize the parameters $first, $sort, and $filter to retrieve the desired number of results, apply sorting based on specific fields, and filter the transactions based on certain conditions.

The response will include an array of transaction details, each containing various fields such as primary key, analysis code, item code, net amount, tax amount, etc.