Creating an Order and Shipment

This example will cover creating an order, creating a shipment tied to that order, and marking the shipment and order as shipped and completed, respectively.

This example relies heavily on the order and shipment collections. For more information on the fields available, visit the articles we have on Orders and Shipments. Replace "newcentury" with your own accountPathComponent.

We need to make sure we have an account with products and facilities. We will be using the fields productUrl, productId, and facilityUrl fairly extensively in our example. A full list of the products and facilities available for your specific account can be found by running the GET requests below against our API endpoints for facility and product:

Fetch Facilities

curl https://app.finaleinventory.com/newcentury/api/facility --header 'authorization: Basic XXX'

Fetch Products

curl https://app.finaleinventory.com/newcentury/api/product --header 'authorization: Basic XXX'

From these lists, we can pick the facilities and products we would like to use in our order and shipment(s). Let's assume our productUrl is "/newcentury/api/product/100000", our productId is "100000", and our facilityUrl is "/newcentury/api/facility/100000" for our magazine and "/newcentury/api/facility/100001" for our location.

With this, we can create a sales order with an origin facility (magazine) as our origin facility and four of our products, priced at $16.56 each.

Create Sales Order

curl --request POST \
     --url https://app.finaleinventory.com/newcentury/api/order \
     --header 'authorization: Basic XXX' \
     --d '{"orderId":"uniqueId-105","orderTypeId":"SALES_ORDER","originFacilityUrl":"/newcentury/api/facility/100000","orderItemList":[{"productId":"100000","productUrl":"/newcentury/api/product/100000","unitPrice":16.56,"quantity":4}]}'

Finale responds with the following:

{
  "orderId":"uniqueId-105",
  "orderUrl":"/newcentury/api/order/uniqueId-105",
  "orderTypeId":"SALES_ORDER",
  "orderHistoryListUrl":"/newcentury/api/order/uniqueId-105/history/",
  "lastUpdatedDate":"2018-04-30T23:18:03",
  "createdDate":"2018-04-30T23:18:03",
  "actionUrlLock":"/newcentury/api/order/uniqueId-105/lock",
  "actionUrlComplete":"/newcentury/api/order/uniqueId-105/complete",
  "actionUrlCancel":"/newcentury/api/order/uniqueId-105/cancel",
  "reserveAllUrl":"/newcentury/api/order/uniqueId-105/reserveall",
  "orderDate":"2018-04-30T23:18:03",
  "orderItemListTotal":66.24,
  "statusId":"ORDER_CREATED",
  "originFacilityUrl":"/newcentury/api/facility/100000",
  "orderItemList":[
    {
      "orderItemUrl":"/newcentury/api/order/uniqueId-105/orderItem/00000001",
      "reserveUrl":"/newcentury/api/order/uniqueId-105/orderItem/00000001/reserve",
      "productId":"100000",
      "productUrl":"/newcentury/api/product/100000",
      "unitPrice":16.56,
      "quantity":4
    }
  ],
  "orderAdjustmentList":[],
  "orderRoleList":[],
  "contentList":[],
  "userFieldDataList":[],
  "invalidations":["/newcentury/api/order/","/newcentury/api/ordersummary/","/newcentury/api/order/uniqueId-105/history/"]
}

There are a couple of things to note in this transaction. In our POST request, we specified the field orderId to equal "uniqueId-105". This id must be unique for the order collection. If this request would create a duplicate record, our API would respond with:

{"msg":"database integrity violation due to reference to object that does not exist or duplicate object"}

Now that we have an order, we will use the orderUrl returned from our create order request to create a shipment attached to our order. This time, let's let the system generate a shipmentId automatically but specify our own shipmentIdUser.

Create Shipment

curl --request POST \
     --url https://app.finaleinventory.com/newcentury/api/shipment/ \
     --header 'authorization: Basic XXX' \
     --data '{"shipmentIdUser":"uniqueId-105-1","shipmentTypeId":"SALES_SHIPMENT","primaryOrderUrl":"/newcentury/api/order/uniqueId-105","statusId":"SHIPMENT_INPUT","shipmentItemList":[{"facilityUrl":"/newcentury/api/facility/100001","productId":"100000","productUrl":"/newcentury/api/product/100000","quantity":4}]}'

Finale responds with the following:

{
  "shipmentId":"100000",
  "shipmentIdUser":"uniqueId-105-1",
  "shipmentUrl":"/newcentury/api/shipment/100000",
  "shipmentTypeId":"SALES_SHIPMENT",
  "actionUrlCancel":"/newcentury/api/shipment/100000/cancel",
  "actionUrlPack":"/newcentury/api/shipment/100000/pack",
  "actionUrlUnpack":"/newcentury/api/shipment/100000/unpack",
  "actionUrlShip":"/newcentury/api/shipment/100000/ship",
  "actionUrlTransfer":"/newcentury/api/shipment/100000/transfer",
  "primaryOrderUrl":"/newcentury/api/order/uniqueId-105",
  "statusId":"SHIPMENT_INPUT",
  "lastUpdatedDate":"2018-04-30T23:19:26",
  "createdDate":"2018-04-30T23:19:26",
  "userFieldDataList":[],
  "shipmentItemList":[
    {
      "facilityUrl":"/newcentury/api/facility/100001",
      "productId":"100000",
      "productUrl":"/newcentury/api/product/100000",
      "quantity":4
    }
  ],
  "contentList":[],
  "transferList":[],
  "statusIdHistoryList":[{"statusId":null,"txStamp":1525130366,"userLoginUrl":"/newcentury/api/userlogin/test"}],
  "invalidations":["/newcentury/api/shipment/","/newcentury/api/order/","/newcentury/api/order/uniqueId-105"]
}

We can use POST requests to the root API endpoints (order, shipment, etc.) to create entities of that type. We can also use POST requests to specific entity URLs to modify that entity. We will use this to mark our shipment as shipped.

Mark Shipment as Shipped

curl --request POST \
     --url https://app.finaleinventory.com/newcentury/api/shipment/100000 \
     --header 'authorization: Basic XXX' \
     --data '{"statusId":"SHIPMENT_SHIPPED"}'

Finale responds with the following:

{
  "shipmentId":"100000",
  "shipmentIdUser":"uniqueId-105-1",
  "shipmentUrl":"/newcentury/api/shipment/100000",
  "statusId":"SHIPMENT_SHIPPED"
}

Now that our shipment is shipped, we can choose to mark the order we created as complete by using actionUrlComplete to complete our order:

Complete Order

curl --request POST \
     --url https://app.finaleinventory.com/newcentury/api/order/uniqueId-105/complete \
     --header '' \
     --data '{}'

Finale responds with the following:

{
  "orderId":"uniqueId-105",
  "orderUrl":"/newcentury/api/order/uniqueId-105",
  "orderTypeId":"SALES_ORDER",
  "statusId":"ORDER_COMPLETED"
}

Note that the statusId holds significant meaning regarding the fields that can be modified on the order. For example, marking the order as "ORDER_COMPLETED" means that the order cannot be modified in any way until it is marked as editable again.