Skip to main content

Example Integration Commands

In this page we will show a few examples for how to use the Kargo GraphQL API to create shipments in the Kargo system. While these may not cover all the different fields that can be set through the API it's more concerned with showing a standard flow for an integration.

A prerequisite to sending these requests is fetching a Bearer Token to authenticate the request. This is explained in Authentication.

Create a Shipment​

In Kargo, the Shipment is the principal method of organizing the data the system ingests. From the API, it is possible to create shipments that will occur in the future. The shipment that is created will then be linked to the real world events that occur at a given dock door1. So, it is important to consider when creating a shipment that it must include all the orders that will be loaded/unloaded from the time the door opens to the time the door closes.

Let's create a scheduled shipment which will have associated orders, but where we don't know yet what dock door it's going to be assigned to. We must create the shipment first

Show GraphQL Mutation
mutation UpdateShipment(input: $input) {
  updateShipment(input: $input) {
    success
    id
  }
}
Show GraphQL Variables
{
  "input": {
    "businessSlug": "<bslug>"
    "facilitySlug": "<fslug>"
    "shipmentNumber": "<shipmentNumber> -- unique to facility, if already exists this will overwrite an existing shipment",
    "direction": "RECEIVING",
    "status": "SCHEDULED",
  }
}

Look at UpdateShipmentInput for a better understanding of all the possible fields when creating a shipment.

Also note at this point it's important to store the id value that has been returned by the UpdateShipment mutation.

Create an Order​

In Kargo, an Order is how we store information about what should be expected to make it's way on and off trucks. Creating an order is simple and straightforward. We use orderNumber to determine if the order already exists. If the order already exists, it will be updated with the new information. If it does not exist, it will be created.

Show GraphQL Mutation
mutation createOrUpdateOrder(input: $input) {
  createOrder(input: $input) {
    success
    id
  }
}
Show GraphQL Variables
{
  "input": {
    "shipmentId": "12345678"
    "expectedQuantity": "14 -- [optional] should always be in pallets"
    "businessSlug": "<bslug>"
    "facilitySlug": "<fslug>"
    "orderNumber": "<orderNumber> -- unique to facility, if already exists this will overwrite an existing shipment",
    "direction": "INBOUND",
    "purchaseOrder": "PO-1234",
    "items": [
      {
        "lpn": "0033456",
        "sku": "SKU-1234",
        "quantity": 120,
        "quantityUnit": "CASE"
      },
      {
        "lpn": "0033457",
        "sku": "SKU-1234",
        "quantity": 140,
        "quantityUnit": "CASE"
      }
    ]
  }
}

Append Items to an Order​

In specific cases (for example when fluid loading pallets) you may not know all the items an order should be assigned before the shipment begins. In this case you can send items as they are picked to the API. It's as simple as setting the appendItems flag to true in the OrderInput. This will ensure that any items you include in the payload are only appended, but it will also update the other input values passed in for the order. You can also just add items without updating the order itself using the addItemsToOrder mutation.

Show GraphQL Mutation
mutation AddItemsToOrder(input: $input) {
  addItemsToOrder(input: $input) {
    success
  }
}
Show GraphQL Variables
{
  "input": {
    "id": "<orderNumber>"
    "items": [
      {
        "lpn": "0033456",
        "sku": "SKU-1234",
        "quantity": 120,
        "quantityUnit": "CASE"
      }
    ]
  }
}

Delete Items from an Order​

In conjunction with the above use case you may also need to remove a picked pallet from the order for many reasons. In order to this you can use the deleteItemsFromOrder mutation.

Show GraphQL Mutation
mutation DeleteItemsFromOrder(input: $input) {
  deleteItemsFromOrder(input: $input) {
    success
  }
}
Show GraphQL Variables
{
  "input": {
    "id": "<orderNumber>"
    "items": [
      "0033457"
    ]
  }
}

Assigning a Shipment to a Dock Door​

Once you know what dock door a shipment should be assigned to then it's possible to assign that shipment through the Kargo API by simply calling the updateShipment mutation again (with the addition of status, expectedArrivalAt and dockSlug fields). You should also include all the fields you included in the first call.

Show GraphQL Mutation
mutation UpdateShipment(input: $input) {
  updateShipment(input: $input) {
    success
    id
  }
}
Show GraphQL Variables
{
  "input": {
    "businessSlug": "<bslug>"
    "facilitySlug": "<fslug>"
    "shipmentNumber": "<shipmentNumber> -- unique to facility, if already exists this will overwrite an existing shipment",
    "direction": "RECEIVING",
    "status": "DOOR_ASSIGNED",
    "expectedArrivalAt": "2024-12-09T18:09:12Z",
    "dockSlug": "8"
  }
}

Footnotes​

  1. In the situation where we have Gateways as opposed to dock doors we likely need to have a more in depth conversation about how we link shipments. ↩