Assign Shipment

Much like the Assign Order API, the Assign Shipment API will assign a shipment to a fulfiller. It can do this either automatically or manually based on a provided Location ID.

This API can also be used to reassign, backorder, and cancel items from a shipment. For cancellation, the request body should only contain the items that will be rejected from the assignment. These actions can split shipments by assigning each item separately. See the examples for how to do this, but note that orders cannot be split once fulfilled. They can only be split while the shipment is in pullInventory or printPackingSlip. See the Transition State guide for an explanation of these states.

Version	2.0
Call	https://integration.shopatron.com/api/v2/shipment/action/assign
Supported Formats	JSON
HTTP Method	POST
Schema	https://integration.shopatron.com/api/v2/schema/shipment/action/assign.json

The .json address above can be used to access the schema within Postman. An example use of the Assign Shipment API follows below, or view the schema or the sample Postman Collection.

Example

The example will demonstrate how to manage orders with the assignment, cancellation, and backorder structures for Assign Shipment calls. There are not different endpoints for each of these, only differences in the body content that determine what should be done with the shipment items.

Required Parameters

Each of the three actions that can be done to a shipment with this API require:

Parameter	Type	Description
shipmentID	integer	A unique identifier for the shipment. The minimum value is “1”.
sendEmails	boolean	Should emails be sent?
rectifyOrder	boolean	Should the order be rectified?
packageAssignment	array	The details for how to assign the shipment. See the description of how to build this object below.

Package Assignment Options

The Package Assignment property can be defined by any of three possible options. One is the standard assign option, while the others are the cancel and backorder actions that can be performed by this API.

Note that even in cases where shipmentStatus is not a required parameter, the suggested best practice is to provide the status regardless. This will help ensure that OMS assigns the shipment as intended. While the rectifyOrder parameter does flag the order to be automatically placed into READY status, using shipmentStatus = “READY” is more reliable as it explicitly ensures that the shipment is assigned appropriately. RectifyOrder is best used as a back-up in a case where the user is not aware that the shipment should be manually assigned to READY.

Option One: Assign

The following properties are available to assign a shipment. AutoAssign, locationID, shippingAmount, shippingTaxAmount, and itemAssign are required.

Parameter	Type	Description
shipmentID	integer	A unique identifier for the shipment. The minimum value is “1”.
autoAssign	boolean	Whether the order should be auto assigned to a fulfiller.
locationID	integer	A unique identifier for the fulfillment location. The minimum value is “1”.
shippingAmount	number	The shipping amount of the shipment. The minimum value is “0”.
shippingTaxAmount	number	The shipping tax amount of the shipment. The minimum value is “0”.
shippingTaxRate	number	The shipping tax rate of the shipment. The minimum value is “0”.
shipmentStatus	enum	The current status of the shipment (READY or ASSIGNED).
itemAssign	object	A list of the specific items being assigned. See below for the parameters to build this object.

Option Two: Cancel

Only one property is required to cancel a shipment assignment.

Parameter	Type	Description
shipmentStatus	enum	The current status of the shipment (CANCELLED).
itemAssign	object	A list of the specific items being assigned. See below for the parameters to build this object.

Option Three: Backorder

To assign a shipment to backorder, use the following structure. Both parameters are required.

Parameter	Type	Description
shipmentStatus	enum	The current status of the shipment (BACKORDER).
backOrderReleaseDate	string	The date the shipment will be released from backorder. Supports date-time format.
itemAssign	object	A list of the specific items being assigned. See below for the parameters to build this object.

Item Assign

Each of these options can be combined with an Item Assign (/packageAssignment/itemAssign/) object to specify the package items being assigned. The Item Assign parameters are listed below, but only an orderItemID is required.

Parameter	Type	Description
orderItemID	integer	A unique identifier for the order item. The minimum value is “0”.
itemTaxAmount	number	The amount of tax on the order item. The minimum value is “0”.
itemTaxRate	number	The rate of tax on the order item. The minimum value is “0”.
quantity	integer	The quantity of order items included.
dispositionReason	enum	The reason for the cancellation (customer_changed_mind, created_by_mistake, etc.).
dispositionOtherReason	string	If dispositionReason is ’other’, provide an explanation here. The minimum length is 1 and the maximum length is 255.

The Assign Request

This is the entire request that will assign a shipment. There are two items defined in this sample, one being automatically assigned and the other manually assigned to Location 11111.

{  
   "shipmentID":0123456,
   "sendEmails":false,
   "rectifyOrder":true,
   "packageAssignment":[
   	  {  
         "autoAssign":false,
         "locationID":112344,
         "shippingAmount":4.99,
         "shippingTaxAmount":0,
         "itemAssign":[  
            {  
               "orderItemID":098765,
               "itemTaxAmount":0,
               "quantity":1
            }
         ]
      },
      {  
         "autoAssign":false,
         "locationID":01010,
         "shippingAmount":2.00,
         "shippingTaxAmount":0,
         "itemAssign":[  
            {  
               "orderItemID":0110110,
               "itemTaxAmount":0,
               "quantity":1
            }
         ]
      }
   ]
}

The returned response follows the same structure as the Get Shipment API, providing information about the shipment that was assigned.

The Cancel Request

The Item Assign block should only contain the items that will be rejected from the assignment.

{  
   "shipmentID":0123456,
   "sendEmails":false,
   "rectifyOrder":true,
   "packageAssignment":[  
      {  
         "shipmentStatus":"CANCELLED",
         "itemAssign":[  
            {  
               "orderItemID":434343
            }
         ]
      }
   ]
}

The returned response follows the same structure as the Get Shipment API, providing information about the shipment that was assigned.

The Backorder Request

This is the entire request that will place an order in backorder.

{  
   "shipmentID":0123456,
   "sendEmails":false,
   "rectifyOrder":true,
   "packageAssignment":[  
      {  
         "shipmentStatus":"BACKORDER",
         "itemAssign":[  
            {  
               "orderItemID":89898989,
               "quantity":1,
               "backOrderDuration":7
            }
         ]
      }
   ]
}

The returned response follows the same structure as the Get Shipment API, providing information about the shipment that was assigned.