Skip to main content

Purchase Order Transactions

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

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

Request​

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

mutation ($transaction: PurchaseOrderInput!) {
  purchasing {
    transactions {
      purchaseOrder {
        create(purchaseOrder: $transaction) {
          ... on PurchaseOrderWriteResult {
            ...purchaseOrderWriteResultDetails
          }
          ... on FailedValidation {
            ...FailedValidationDetails
          }
          ... on UnexpectedError {
            ...UnexpectedErrorDetails
          }
        }
      }
    }
  }
}

fragment purchaseOrderWriteResultDetails on PurchaseOrderWriteResult {
  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 Supplier 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:

{
  "data": {
    "purchasing": {
      "transactions": {
        "purchaseOrder": {
          "create": {
            "orderNumber": "3035",
            "documentPrimary": 120
          }
        }
      }
    }
  }
}

Queries​

Get Outstanding Purchase Orders​

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

Here's an example of how you can use the purchasing\transactions\outstandingPurchaseOrders\header query to get the details of a Outstanding Purchase Order transactions:

query {
  purchasing {
    transactions {
      outstandingPurchaseOrders {
        header {
          items {
            orderNumber
            orderType
            orderStatus
            accountCode
            accountName
            orderDate
            orderGross
            netOutstanding
            periodNumber
            yearLink
            yearLabel
            requiredDate
            completionDate
            auditNo
            enteredBy
            exchangeRate
            batchRef
            currencyGross
            currencyNetOutstanding
            currencySymbol
            deliveryAccountCode
            orderDescription
            userSort1
            userSort2
            userSort3
            subLedger
          }
        }
      }
    }
  }
}

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 Purchase Order Lines, you can use the details field within the purchasing\transactions\outstandingPurchaseOrders query. This field requires the following input parameters:

query {
  purchasing {
    transactions {
      outstandingPurchaseOrders {
        details {
          items {
            analysisCode
            analysisName
            subAnalysis
            description
            quantityOrdered
            quantityDelivered
            quantityInvoiced
            gross
            netOutstanding
            costPrice
            lineDiscount
            projectCode
            projectName
            costCentreCode
            detail
            auditNo
            requiredDate
            accountCode
            costCentreName
            accountName
            accountSortKey
            accountUserSort1
            accountUserSort2
            accountUserSort3
            currencySymbol
            currencyGross
            currencyNetOutstanding
            currencyCostPrice
            currencyLineDiscount
            headerUserSort1
            headerUserSort2
            headerUserSort3
            itemName
            itemCode
            orderNumber
            transactionUserKey1
            transactionUserKey2
            transactionUserKey3
            transactionUserKey4
            transactionUserKey5
            taxCode
            taxRate
          }
        }
      }
    }
  }
}

Get Outstanding Purchase Order Credit Notes​

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

Here's an example of how you can use the purchasing\transactions\outstandingpurchaseCreditNote\header query to get the details of a Outstanding Purchase Credit Note transactions:

query {
  purchasing {
    transactions {
      outstandingCreditNotes {
        header {
          items {
            orderNumber
            orderType
            orderStatus
            accountCode
            accountName
            orderDate
            orderGross
            netOutstanding
            periodNumber
            yearLink
            yearLabel
            requiredDate
            completionDate
            auditNo
            enteredBy
            exchangeRate
            batchRef
            currencyGross
            currencyNetOutstanding
            currencySymbol
            deliveryAccountCode
            orderDescription
            userSort1
            userSort2
            userSort3
            subLedger
          }
        }
      }
    }
  }
}

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 Purchase Order Lines, you can use the details field within the purchasing\transactions\outstandingPurchaseOrders query. This field requires the following input parameters:

query {
  purchasing {
    transactions {
      outstandingCreditNotes {
        details {
          items {
            analysisCode
            analysisName
            subAnalysis
            quantityOrdered
            quantityDelivered
            quantityInvoiced
            gross
            costPrice
            lineDiscount
            projectCode
            projectName
            costCentreCode
            detail
            auditNo
            requiredDate
            costCentreName
            currencyGross
            currencyNetOutstanding
            currencyCostPrice
            currencyLineDiscount
            itemName
            itemCode
            orderNumber
            transactionUserKey1
            transactionUserKey2
            transactionUserKey3
            transactionUserKey4
            transactionUserKey5
            taxCode
            taxRate
          }
        }
      }
    }
  }
}