Sales order example

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 (For larger accounts, this may take some time):

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

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

From these lists, we can pick the facilites and products we would like to use in our order and shipment(s). Lets 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 (see facilities for more details on the difference between magazine and 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.

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 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 atteched to our order. This time, lets let the system generate a shipmentId automatically, but specify our own shipmentIdUser; this is the name of the shipment shown to the user in the Finale web application.

We also have to specify which location each item in this shipment is coming from. We will be using "/newcentury/api/facility/100001" (see facilities for more details).

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.

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",  
  // ...  
}

This is how we can modify many attributes of any entity using the Finale API. There are some restrictions to this; some fields are read-only, others can only be set on creation. Documentation can be found on each entity type in the resources section of this site.

Now that our shipment is shipped, we can choose to mark the order we created as complete. We have an endpoint that will allow us to do this without having to verify the data we send to the Finale API: actionUrls. These have been returned in every request so far to the order and shipment APIs. We will use actionUrlComplete to complete our order, using the url "/newcentury/api/order/uniqueId-105/complete":

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 on whether certain fields 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 the order is marked as editable again, through the Finale web application or the Finale API.

Many of these fields in the order and shipment entities can be modified. See our resources section on each collection to see what fields are available for you to utilize.