Usage Notes
To create a shipment within PortalApp, please provide as much data as possible about the Shipment and the Purchase Orders. At a minimum, we need to identify the Purchase Order and the Items.
Purchase Order Level
Purchase Orders for your shipment must already exist in our system. In order for us to identify the Purchase Order(s) in your shipment, you must provide back to Spring Systems either our <po_id> (given to you in the initial PO data), or retailer_id, retailer:tp_name, and po_num. Note that po_rel_num, mark_for_location:tp_location_id, and/or mark_for_location:tp_location_code are also mandatory if they are used for a particular PO.
Item Level
Items for your shipment should already exist in our system and in your Purchase Order. In order for us to identify the Items(s), you must provide back to Spring Systems either our:
po_item_id or…..
our product_id or…..
product:product_additional:identifiers:gtin or…..
product:product_additional:vendor_item_num (Must be unique. Only use if you do not have a GTIN.
These items would have been given to you in our initial Purchase Order data.
Trigger outgoing transaction
The option to “send_outgoing_transaction_after “ is generally defaulted to yes.
This controls whether PortalApp will trigger a send event after you pass PortalApp data to create
a transaction. For example, you create a shipment or invoice, PortalApp will generally run a
send event to pass this transaction along to other parties such as a retailer. Note that this can
be controlled 3 different ways
- Default setting within PortalApp - set on each connection or API user permission.
Please confirm with your PM or tech if this is set to on or off. - Override passed within each API call URL. send_outgoing_transaction_after
(1 is yes, 0 is no) - Override passed within the data payload. Here is an example for shipment (ASN)
Passing an empty tag will work similar to passing a 0, e.g. indicate to not trigger subsequent
transactions.
Options 2, 3 take precedence, so if 2 or 3 is passed that is the priority and will ignore what 1
says. If both 2 and 3 are both sent, and do not match, then PortalApp will default to send the
transaction (e.g. if they don't match then one of them must say send so therefore send).
Updating a preexisting shipment
If the Spring Systems <ship_info_id> tag is provided and matches an existing shipment then the shipment with that specific id will be updated. If <ship_info_id> is not provided, then a new shipment will be created.
Update carton level
If a carton number is provided, this will update that carton, such as changing the contents or quantity. To remove a carton from a shipment, pass the tag delete_carton_flag with a value of 1 within the ship carton section. This will remove that carton from the shipment. Example:
<ship_carton>
<delete_carton_flag>1</delete_carton_flag>
</ship_carton>
Externally Assigned Carton Numbers
Maintaining the uniqueness ship_carton_number is a critical concept, and especially important for GS1-128 labels and EDI ASN’s (856). External systems that are sending shipment data to PortalApp can provide these numbers or can request PortalApp to generate these numbers for them. If external system will be assigning carton numbers, these fields are mandatory:
ship_carton:ship_carton_number (must NOT include check digit)
ship_carton:warehouse_carton_number
ship_carton:warehouse_carton_number_has_checkdigit
Do not include the check digit when passing ship_carton_number to PortalApp. Failure to properly do this will risk duplication of carton numbers and incorrect labels if a user attempts to re-print labels from PortalApp.
If external system will be assigning carton numbers, PortalApp needs to know exactly what label number was printed on the GS1-128 label and whether this number already includes a check digit.
Third party applications can provide carton numbers to PortalApp (ship_carton_number ) or this could be left blank and PortalApp will generate a carton number. If PortalApp generates the carton number, however, the third party application must store this number as it will be mandatory for processing a carton update or delete procedure.
For more detail refer to Appendix.
Request Shipping Documents
This endpoint can also be used to request shipping documents from Spring Systems. See “Appendix I – Auto Delivery of Shipping Documents” for more information.
Mandatory Fields
Once the Purchase Order and Items have been identified, you must of course also provide all mandatory shipment information (retailer dependent) such as
ship_info:ship_info_ship_date
ship_info:ship_info_delivery_date
ship_info:ship_info_carrier_name
ship_info:ship_info_carrier_scac
ship_info:ship_info_carrier_code
ship_info:ship_info_tracking
ship_info:bill_of_lading
ship_info:master_bill_of_lading
ship_info:load_number
ship_info:trailer_number
ship_info:seal_number
ship_info:ship_pay_method
ship_info:weight.value (and/or carton weight)
ship_info:weight.units_of_measure (and/or carton weight)
ship_info:ship_to_location_id
ship_info:ship_to_location (all necessary detail)
ship_info:ship_from_location (all necessary detail)
ship_carton:ship_carton_number
ship_carton:warehouse_carton_number
ship_carton:warehouse_carton_number_has_checkdigit
ship_carton:po_item_pack:po_item_pack_qty
mark_for_location:tp_location_id -and/or- mark_for_location:tp_location_code
And anything else that may be required on the ASN for that particular Trading Partner.