Sales Order Transactions

This document provides an overview of the operations available for the Sales Order (Selling) 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 Order Transactions

To create new Sales Order transactions within a Financials or Dimensions database, the Transaction create endpoints can be used. These endpoints allow the creation of Sales Order, Sales Credit Note and Sales Estimate transactions.

Request

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

Sales Order

mutation ($transaction: SalesOrderInput!) {
  selling {
    transactions {
      salesOrder {
        create(salesOrder: $transaction) {
          ... on SalesOrderWriteResult {
            ...SalesOrderWriteResultDetails
          }
          ... on FailedValidation {
            ...FailedValidationDetails
          }
          ... on UnexpectedError {
            ...UnexpectedErrorDetails
          }
        }
      }
    }
  }
}

fragment SalesOrderWriteResultDetails on SalesOrderWriteResult {
  orderNumber
  documentPrimary
}

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

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

fragment UnexpectedErrorDetails on UnexpectedError {
  errorMessage
}

Sales Credit Note

mutation ($transaction: SalesOrderInput!) {
  selling {
    transactions {
      salesCreditNote {
        create(salesCreditNote: $transaction) {
          ... on SalesOrderWriteResult {
            ...SalesOrderWriteResultDetails
          }
          ... on FailedValidation {
            ...FailedValidationDetails
          }
          ... on UnexpectedError {
            ...UnexpectedErrorDetails
          }
        }
      }
    }
  }
}

fragment SalesOrderWriteResultDetails on SalesOrderWriteResult {
  orderNumber
  documentPrimary
}

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

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

fragment UnexpectedErrorDetails on UnexpectedError {
  errorMessage
}

Sales Estimate

mutation ($transaction: SalesOrderInput!) {
  selling {
    transactions {
      salesEstimate {
        create(salesEstimate: $transaction) {
          ... on SalesOrderWriteResult {
            ...SalesOrderWriteResultDetails
          }
          ... on FailedValidation {
            ...FailedValidationDetails
          }
          ... on UnexpectedError {
            ...UnexpectedErrorDetails
          }
        }
      }
    }
  }
}

fragment SalesOrderWriteResultDetails on SalesOrderWriteResult {
  orderNumber
  documentPrimary
}

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.

Response

After executing the create mutation, you will receive a response containing the ID of the transaction 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:

Success

{
  "data": {
    "selling": {
      "transactions": {
        "salesOrder": {
          "create": {
            "orderNumber": "3035",
            "documentPrimary": 120
          }
        }
      }
    }
  }
}

Validation

{
  "data": {
    "selling": {
      "transactions": {
        "salesOrder": {
          "create": {
            "errors": [
              {
                "message": "No text has been supplied for a text line!",
                "details": []
              }
            ],
            "warnings": []
          }
        }
      }
    }
  }
}

Unexpected Error

{
  "data": {
    "selling": {
      "transactions": {
        "salesOrder": {
          "create": {
            "Unexpected error message"
          }
        }
      }
    }
  }
}

Queries

Get Outstanding Sales Orders

To retrieve information about a specific outstanding Sales Order transaction, you can use the selling\transactions\outstandingSalesOrders queries. These queries will return all header and detail values for outstanding order transactions

Here's an example of how you can use the selling\transactions\outstandingSalesOrders\header query to get the details of a Outstanding Sales Order transactions:

Request

query {
  selling {
    transactions {
      outstandingSalesOrders {
        header {
          items {
            orderNumber
            orderType
            orderStatus
            workStatus
            accountCode
            accountName
            customerRef
            orderDate
            orderGross
            netOutstanding
            periodNumber
            yearLink
            yearLabel
            requiredDate
            enteredDate
            completionDate
            auditNo
            enteredBy
            exchangeRate
            batchRef
            batched
            creditCardNo
            currencyGross
            currencyNetOutstanding
            currencySymbol
            dateEdited
            deliveryAccountCode
            deliveryAccountName
            deliveryRoute
            orderDescription
            userSort1
            userSort2
            userSort3
            invoiceAccountCode
            invoiceCustomerName
            onDispute
            subLedger
            urgent
          }
        }
      }
    }
  }
}

Response

  {
  "data": {
    "selling": {
      "transactions": {
        "outstandingSalesOrders": {
          "header": {
            "items": [
              {
                "orderNumber": 3000,
                "orderType": "Order",
                "orderStatus": "Complete",
                "workStatus": "Full Process",
                "accountCode": "GB-12686",
                "accountName": "In At Pede Industries",
                "customerRef": "",
                "orderDate": "2023-05-10T00:00:00",
                "orderGross": 408,
                "netOutstanding": 0,
                "periodNumber": 1,
                "yearLink": 13,
                "yearLabel": "2024",
                "requiredDate": "2023-05-15T00:00:00",
                "enteredDate": "2023-05-10T11:07:13.343",
                "completionDate": "2024-07-15T13:37:47.117",
                "auditNo": 1,
                "enteredBy": "SA",
                "exchangeRate": 0,
                "batchRef": "",
                "batched": false,
                "creditCardNo": "",
                "currencyGross": 0,
                "currencyNetOutstanding": 0,
                "currencySymbol": "GBP",
                "dateEdited": null,
                "deliveryAccountCode": "GB-12686",
                "deliveryAccountName": "In At Pede Industries",
                "deliveryRoute": null,
                "orderDescription": "",
                "userSort1": "",
                "userSort2": "",
                "userSort3": "",
                "invoiceAccountCode": "GB-12686",
                "invoiceCustomerName": "In At Pede Industries",
                "onDispute": false,
                "subLedger": "",
                "urgent": false
              }
            ]
          }
        }
      }
    }
  }
}

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.

• $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.

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

To retrieve detailed information about Sales Order Lines, you can use the details field within the selling\transactions\outstandingSalesOrders query. This field requires the following input parameters:

query {
  selling {
    transactions {
      outstandingSalesOrders {
        details {
          items {
            itemType
            analysisName
            analysisCode
            itemCode
            subAnalysis
            description
            orderedQuantity
            deliveredQuantity
            invoicedQuantity
            gross
            netOutstanding
            tax
            profit
            margin
            projectCode
            projectName
            costCentreCode
            costCentreName
            detail
            auditNo
            taxCode
            accountCode
            accountName
            accountUserSort1
            accountUserSort2
            accountUserSort3
            commodityCode
            countryOfOrigin
            currencyGross
            currencyNetOutstanding
            currencySymbol
            currencyTax
            deliveryCustomerCode
            deliveryCustomerName
            headerUserSort1
            headerUserSort2
            headerUserSort3
            itemCostPrice
            currencyItemCostPrice
            itemName
            transactionDetailKey
            nominalCreditAccount
            nominalDebitAccount
            nominalTaxAccount
            orderNumber
            periodNumber
            serialNumber
            stockAnalysis
            stockNominalCreditAccount
            stockNominalDebitAccount
            stockSortKey
            stockUserSort1
            stockUserSort2
            stockUserSort3
            transactionUserKey1
            transactionUserKey2
            transactionUserKey3
            transactionUserKey4
            transactionUserKey5
            yearLink
            yearLabel
            unitSellPrice
            currencyUnitSellPrice
            userChar1
            userChar2
            userChar3
            userChar4
            userDate1
            userDate2
            userFlag1
            userFlag2
            userNumber1
            userNumber2
            taxControlAccount
            taxRate
            taxType
          }
        }
      }
    }
  }
}

Get Outstanding Sales Credit Notes

To retrieve information about the outstanding Sales Order Credit Note transactions present in a Financials database, you can use the selling\transactions\outstandingSalesCreditNote queries. These queries will return all header and detail values for outstanding transactions

Here's an example of how you can use the selling\transactions\outstandingSalesCreditNote\header query to get the details of a Outstanding Sales Credit Note transactions:

Request

query {
  selling {
    transactions {
      outstandingCreditNotes {
        header {
          items {
            orderNumber
            accountCode
            accountName
            requiredDate
            workStatus
            customerRef
            orderGross
            netOutstanding
            orderDate
            urgent
            batchRef
            currencySymbol
            deliveryRoute
            enteredBy
            orderDescription
            currencyGross
            currencyNetOutstanding
            sortKey
            userSort1
            userSort2
            userSort3
            periodNumber
            enteredDate
            yearLabel
            subLedger
            batched
            creditCardNo
            dateEdited
            completionDate
            exchangeRate
            base2Rate
            auditNo
            orderType
            base2Gross
            base2NetOutstanding
            deliveryAccountName
            invoiceAccountCode
            invoiceCustomerName
            onDispute
            userChar1
            userChar2
            userChar3
            userChar4
            userDate1
            userDate2
            userFlag1
            userFlag2
            userNumber1
            userNumber2
            orderStatus
          }
        }
      }
    }
  }
}

Response

  {
  "data": {
    "selling": {
      "transactions": {
        "outstandingCreditNotes": {
          "header": {
            "items": [
              {
                "orderNumber": 3037,
                "accountCode": "101",
                "accountName": "Nulla Industries",
                "requiredDate": "2024-09-30T00:00:00",
                "workStatus": "Full Process",
                "customerRef": "",
                "orderGross": -910.52,
                "netOutstanding": -758.77,
                "orderDate": "2024-09-25T00:00:00",
                "urgent": false,
                "batchRef": "",
                "currencySymbol": "GBP",
                "deliveryRoute": null,
                "enteredBy": "SA",
                "orderDescription": "",
                "currencyGross": 0,
                "currencyNetOutstanding": 0,
                "sortKey": "",
                "userSort1": "",
                "userSort2": "CUSTOMVALUE2",
                "userSort3": "",
                "periodNumber": 6,
                "enteredDate": "2024-04-25T12:14:01.513",
                "yearLabel": "2025",
                "subLedger": "MLAC-1",
                "batched": true,
                "creditCardNo": "",
                "dateEdited": null,
                "completionDate": null,
                "exchangeRate": 0,
                "base2Rate": 0,
                "auditNo": 38,
                "orderType": "CreditNote",
                "base2Gross": 0,
                "base2NetOutstanding": 0,
                "deliveryAccountName": "Nulla Industries",
                "invoiceAccountCode": "101",
                "invoiceCustomerName": "Nulla Industries",
                "onDispute": false,
                "userChar1": null,
                "userChar2": null,
                "userChar3": null,
                "userChar4": null,
                "userDate1": null,
                "userDate2": null,
                "userFlag1": null,
                "userFlag2": null,
                "userNumber1": null,
                "userNumber2": null,
                "orderStatus": "Outstanding"
              }
            ]
          }
        }
      }
    }
  }
}

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.

• $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.

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

To retrieve detailed information about Sales Order Lines, you can use the details field within the selling\transactions\outstandingSalesOrders query. This field requires the following input parameters:

query {
  selling {
    transactions {
      outstandingCreditNotes {
        details {
          items {
            itemType
            itemCode
            detail
            gross
            orderedQuantity
            deliveredQuantity
            invoicedQuantity
            requiredDate
            net
            analysisCode
            analysisName
            projectCode
            projectName
            costCentreCode
            costCentreName
            currencyGross
            currencyNetOutstanding
            transactionUserKey1
            transactionUserKey2
            transactionUserKey3
            transactionUserKey4
            transactionUserKey5
            netOutstanding
            profit
            margin
            itemName
            auditNo
            taxCode
            base2Gross
            tax
            base2Tax
            accountCode
            accountName
            accountUserSort1
            accountUserSort2
            accountUserSort3
            commodityCode
            countryOfOrigin
            currencySymbol
            currencyTax
            deliveryCustomerCode
            deliveryCustomerName
            itemCostPrice
            nominalCreditAccount
            nominalDebitAccount
            nominalTaxAccount
            orderNumber
            periodNumber
            serialNumber
            stockAnalysis
            stockNominalCreditAccount
            stockNominalDebitAccount
            stockSortKey
            stockUserSort1
            stockUserSort2
            stockUserSort3
            subAnalysis
            yearLabel
            unitSellPrice
            userChar1
            userChar2
            userChar3
            userChar4
            userDate1
            userDate2
            userFlag1
            userFlag2
            userNumber1
            userNumber2
            taxControlAccount
            taxRate
            taxType
          }
        }
      }
    }
  }
}