Purchase orders

Note: You can download a Postman example of the below queries in this article's attachments.

This article covers purchase order creation in Xledger and how to retrieve payment information against those purchase orders.

Below is an activity diagram of the use case, here we are only concerned with the API calls in blue :

Prerequisites

For most purchase orders setup you will want to have Suppliers and Projects passed to the invoice. If you need to integrate those resources, please refer to the following articles:

• Create or update supplier
• Create or update project

Functional specifications and integration workshops will cover other aspects of the data fields if needed.

Purchase Order Creation

The first step you need to take is to create the Purchase Order, please see the mandatory field and an  example of the creation:

• Subledger.code

mutation {
  addPurchaseOrders(inputs: [{node: {
    orderNumber: 123456
    orderAt: "2023-01-01"
    subledger: {code: "Supplier code"}
    poOrderType: {name: "PURCHASE_ORDER"}
    purchaseAt: "2023-01-01"
    headerInfo: "Header description"
    glObject1: {code: ""}
    glObject2: {code: ""}
    glObject3: {code: ""}
    glObject4: {code: ""}
    glObject5: {code: ""}
    xgl: {code: ""}
    currency: {code: "GBP"}
    account: {code: "Account code"}
    amount: 50.00
    invoiceAmount: 50.00
    }}]) {
    edges {
      node {
        dbId
      }
    }
  }
}

The next step is to create the purchase order detail, please see the mandatory field and an example of the creation:

• Product.code

mutation {
  addPurchaseOrderDetails(inputs: [{node: {
    purchaseOrderHeader: {dbId: "Use the dbId generated from above"}
    lineNumber: 1
    product: {code: "Product code"}
    unit: {description: "EA"}
    glObject1: {code: ""}
    glObject2: {code: ""}
    glObject3: {code: ""}
    glObject4: {code: ""}
    glObject5: {code: ""}
    xgl: {code: ""}
    quantity: 1
    unitPrice: 50.00
    amount: 50.00
    invoiceAmount: 50.00
    text: "free text field"
    taxRule: {code: "Tax rule code"}
    account: {code: "Account code"}
  }}]) {
    edges {
      node {
        dbId
      }
    }
  }
}

The next step you need to do is to send the dbId number generated from addPurchaseOrders back to the system that you are integrating with. This will need to be stored in a free and accessible field so that it can be used to match the two records, from both systems at a later date.

Payment Status Retrieval

Once the Purchase Order has been created in Xledger, they will eventually get posted and paid (this is done by the Xledger users and is not an integration process). Doing this will update the Purchase Order to a status of Finished and the Posted field will display the total amount invoiced. By polling for modified Purchase Orders regularly, you can get information on when a Purchase Order has been paid.

Below is an example of the query that should be used. We advise that you poll for changes regularly (15 minutes) to get smaller results. So that you know – the last parameter will specify how many records are returned; you can adjust it to your needs. You can use the dbId number of the Purchase Order, which you should have stored in the system we are integrating with so you can match the two records.

{
  purchaseOrders(last: 10, filter: {modifiedAt_lt: "2023-01-01T00:15:00"}) {
    edges {
      node {
        dbId
        description
        createdAt
        modifiedAt
        orderNumber
        amount
        invoiceAmount
        posted
        receivedAmount
        headerInfo
        account {
          code
          description
        }
        subledger {
          code
          description
        }
      }
    }
  }
}