Closing Purchase Orders

Inside this guide:
Introduction
Prerequisites
Performing the mutation
Dealing with errors
Next steps

Introduction

In some situations a Purchase Order has not been delivered to you in full but you do not want this Order to remain active and be counted in the Zencargo UI or reporting. In this case, rather than deleting the Purchase Order - which would remove all the data from the platform - you should close this Purchase Order.

The most likely use case to trigger this action is that the Purchase Order is partially booked but you receive confirmation that some lots will never be shipped, either because you have cancelled them or they were omitted from a previous shipment and you do not want to re-ship them.

Once a Purchase Order is closed, it is treated the same as a fully delivered purchase order (it is omitted from any reporting or UI that looks at active orders.

Prerequisites

To follow this guide, please ensure you are able to call the Zencargo API either using our API Console or in the HTTP client of your choice. See the Making your first call series of guides for how to do this.

Also ensure there is a PurchaseOrder in the system that is not closed or delivered.

Performing the mutation

The easiest way to follow along with this guide is by using the API Console, where you'll be able to copy and paste the example code without having to worry about authentication or formatting. If you're using a different HTTP client, make sure you format the GraphQL correctly.

Defining the variables

Copy and paste the block below into the query variables section of the API console, substituting the purchaseOrderId field for your own value.

{
  "purchaseOrderId": PURCHASE_ORDER_ID
}

Now that we have our variable, let's look at how to construct the mutation. Paste the code below into the query section (the one at the top in the console) but don't try to execute the mutation.

mutation ($purchaseOrderId: String!) {
  purchaseOrdersCloseOrder(input: {purchaseOrderId: $purchaseOrderId})
}

This code defines an operation type (a mutation) and defines the type of the variable we'll supply, $input and defines it contains a $purchaseOrderId of the order to close. We then define the mutation name and how the input should be passed into this mutation - in our case we just pass our $input variable as input:.

POST /graphql query:

mutation ($purchaseOrderId: String!) {
  purchaseOrdersCloseOrder(input: {purchaseOrderId: $purchaseOrderId}) {
    clientMutationId
  }
}

Variable:

{
  "purchaseOrderId": "650a3f0f-1ca0-4724-a761-5c28b8e6f8f5"
}

Assuming you got the valid purchaseOrderId, you should get back this response.

{
  "data": {
    "purchaseOrdersCloseOrder": {
      "clientMutationId": null
    }
  }
}

Congratulations! You've closed your first Purchase Order. This call succeeded, but that won't always be the case.

Dealing with errors in your mutations

By now, you're familiar with the idea that you can request what you'd like from the return value of the mutation. As you can see from our purchaseOrdersCloseOrder mutation documentation, we are able to retrieve an errors field. This is a GraphQL standard that will be available on every mutation on the Zencargo API.

Run the previous mutation again, with the same variables, you'll get back this response.

JSON response:

{
  "data": {
    "purchaseOrdersCloseOrder": null
  },
  "errors": [
    {
      "message": "Permission denied to execute PurchaseOrders::GraphQL::Mutations::ClosePurchaseOrder",
      "locations": [
        {
          "line": 2,
          "column": 3
        }
      ],
      "path": [
        "purchaseOrdersCloseOrder"
      ]
    }
  ]
}

As you can see, we tried to close the Purchase Order for the second time. This time the Purchase Order is already closed and the response contains an error message.

Next Steps