Skip to main content

Ship orders

Use order shipment operations when a merchant integration needs to trigger shipment for all currently shippable quantities of an order, and to read back the tracking codes it has to forward to the end customer.

Available operations​

  • Read orders represented in Pickware ERP with orders, or load one by global ID with order.
  • Read order line items with orderLineItems, or load one by global ID with orderLineItem.
  • Ship an order completely with shipOrderCompletely.
  • Read the tracking codes of a shipped order from Order.trackingCodes.

Example: ship an order​

mutation ShipOrder($input: ShipOrderCompletelyInput!) {
  shipOrderCompletely(input: $input) {
    id
    orderNumber
    deliveryState
    trackingCodes
  }
}
{
  "input": {
    "orderId": "T3JkZXI6MDE4...",
    "warehouseId": "V2FyZWhvdXNlOjAx..."
  }
}

Pass warehouseId when shipment should use a specific warehouse. If it is omitted, Pickware ERP uses the configured default warehouse.

What shipping does​

shipOrderCompletely ships every quantity of the order that is not shipped yet, in one step:

  1. It takes the stock from the warehouse, from its bin locations and its unknown bin location, and books it onto the order, as stock movements with the process type shipping.
  2. It creates the fulfillments in Shopify for the shipped quantities of the order's fulfillment orders. The fulfillments carry the tracking codes that trackingCodes already lists for the order; the mutation itself takes no tracking codes.
  3. It sends the webhook topic order/completely-shipped, or order/partially-shipped when quantities of the order remain open afterwards. See Webhooks.

deliveryState mirrors the fulfillment status of the order in Shopify and follows it when the order is synchronized from Shopify, so the value in the mutation's response can still be the one from before the shipment.

When shipping fails​

The mutation ships all open quantities or books no stock at all. It fails, and books no stock, when:

  • the warehouse has status: Decommissioning,
  • the warehouse does not belong to the location of the order's open fulfillment orders, or those fulfillment orders belong to several locations,
  • the warehouse does not hold enough stock for every open quantity,
  • a fulfillment order of the order is on hold, in Pickware ERP or in Shopify,
  • a picking process for the order is in progress in Pickware WMS,
  • Shopify rejects a fulfillment, for example because another process is changing the fulfillment order at the same moment, or
  • Shopify cannot be reached. This error has the code UPSTREAM_UNAVAILABLE; retry later. See Errors.

On the Shopify side, a failed call is not all or nothing: when Shopify rejects one of several fulfillments of the same call, the fulfillments it had already accepted stay in Shopify, although Pickware booked no stock. Check the order's fulfillments in Shopify before you retry.

Example: read the tracking codes of an order​

trackingCodes is a JSON array of strings and is readable on its own, so an integration that ships elsewhere can poll it to notify the end customer:

query OrderTrackingCodes($id: ID!) {
  order(id: $id) {
    orderNumber
    deliveryState
    trackingCodes
  }
}

The field lists the tracking codes of the shipping labels created with Pickware for the order, across all of its parcels. It does not include the tracking codes of return labels, or tracking numbers that were added to a fulfillment directly in Shopify. It is an empty array while no label exists.