limbiq logistic API for Shipment

Introduction

This document provides detail information on how you can create, read, update and delete the Shipment through integration service.

This document is divided into 5 sections (excluding introduction section):

JSON Entities - provides detail description of all entities and each field in each entity.
Lookup Types and codes - provides complete list of lookup codes and values along with description.
Responses (HTTP statuses) and Validation Errors - provides the list of HTTP codes that are generated by limbiq platform and also the validations list.
Appendix - provides additional information.
Example - provides a example which you can use and modify to your needs

If you have any questions, please contact support@limbiq.com.

JSON Entities

Below is the list of JSON entities starting with main entity "Shipment". The fields marked as ignored will be ignored by limbiq platform when creating/updating/archiving the entity. These values are generated by limbiq platform and provided to you when you retrieve the object. For the fields that are marked as Optional and a default value is provided, when no value is provided then the default value is set but when the field itself is not added to the object, then the existing value will be retained.

Also note that when you use the field in the object, then the value will be updated (overridden) in the limbiq platform even though the value is empty. If you don’t want to override the existing field value, then don’t use the field. For example, you set the field "priority" to true when creating the "Shipment" and when updating "Shipment", you just used the "priority" field in the object you passed but didn’t set any value (is empty), then system overwrites the existing value with default value.

The same is applicable for the array field. For example, if you create a "Shipment" with array of 3 "TransshipPort"s and when you update the Shipment" with empty array of "TransshipPort"s, then the limbiq platform tries to replace the existing "TransshipPort"s with new set and since at least one is required, an error will be returned.

Instruction object is an exception. Please check Instruction section to get more information.

Any deleted entity cannot be recovered. If you try to request or update the deleted entity, "Entity not Found" error will be returned. Most important: For Cargo and Container, sequence_number field is used as an identifier. If you provide different sequence_number and if the respective entity with that sequence_number already exists, then the existing entity will be overwritten but if no entity exists, then new entity will be created.

Shipment

Field Name	Field Type	Description	Required/Optional/Ignored
id	string	This is unique ID of the "Shipment" and is autogenerated by limbiq platform.	Ignored
limbiq_reference_id	string	The unique readable Reference number auto-generated by limbiq system. This is required field when updating the existing system. If no value is passed, then new Shipment will be created.	Optional
external_id	string	The external Id of the Shipment. Ex: BOL, HBOL, AirwayBill.	Optional
crd	date	Cargo Ready Date for this Shipment	Optional
mot	Lookup field - MOT	Mode of Transport. User should define their primary mode of Transport.	Optional
incoterm	Lookup field - Incoterm	Incoterms (2020).	Optional
transship_ports	Array Of TransshipPort	User can provide TransshipPorts. You can change them on each time. If you don’t have any ports yet, you can leave it empty and fill it afterwards.	Optional
weights	Array of Weight	Usually VGM or Truck Weight, etc.	Optional
shipment_type	Lookup field - ShipmentType	Type of Shipment like FCL or LCL	Optional
carrier	string	Name of the carrier company (Ship company, Trucking company, etc)	Optional
vessel_number	string	This is Ship number or Rail Number or Flight Number or Truck Number.	Optional
carrier_reference_number	string	This is Voyage Number or reference number provided by Carrier. This number is used to query the carrier system for information on the cargo.	Optional
on_carriage	Lookup field - OnCarriage	See List. The type of On Carriage used for this Shipment.	Optional
cargos	Array of Cargo	Shows the orders within a shipment	Optional
containers	Array of Container	When MOT is SEA or SEA-AIR or RAIL, you can set the number of containers required and also additional information on each container. For other MOTs, the container information is ignored.	Optional
additional_references	Array of AdditionalReference	If you have any further references you used in additional services, you can drop here.	Optional
instructions	Array of Instruction	If you want to provide instructions to other Partners, you can add here. Even though it’s an array, you will pass usually one instruction where you can add as much instructions are possible in one field.	Optional
status	Lookup field ShipmentStatus	See List. The status of the Shipment.	Optional
partners	Array of PartnerRole	The email address and role of the partner. Partners are optional when you don’t want to manage your process. If you want to manage your supply chain process then you should add them to this entity.	Optional
owner	string	Generated and used by limbiq internal team.	Optional
deleted	boolean	To delete the Shipment, set true as value. Note: Shipment can be deleted only by the creator.	Optional
created_date	date-time	The date-time on which this Shipment is created in limbiq system. This value is set by limbiq system. If user sets this value, it will be ignored.	Ignored
creator	string	The email address of the user who has created the Shipment. This value is set by limbiq system. If user sets this value, it will be ignored.	Ignored
updated_date	date-time	The date-time on which this Shipment is updated in limbiq system. This value is set by limbiq system. If user sets this value, it will be ignored.	Ignored
updater	string	The email address of the user who has updated the Shipment. This value is set by limbiq system. If user sets this value, it will be ignored.	Ignored

Field Name

Field Type

Description

Required/Optional/Ignored

Default Value

string

This is unique ID of the "Shipment" and is autogenerated by limbiq platform.

Ignored

limbiq_reference_id

string

The unique readable Reference number auto-generated by limbiq system. This is required field when updating the existing system. If no value is passed, then new Shipment will be created.

Optional

external_id

string

The external Id of the Shipment. Ex: BOL, HBOL, AirwayBill.

Optional

crd

date

Cargo Ready Date for this Shipment

Optional

mot

Lookup field - MOT

Mode of Transport. User should define their primary mode of Transport.

Optional

incoterm

Lookup field - Incoterm

Incoterms (2020).

Optional

transship_ports

Array Of TransshipPort

User can provide TransshipPorts. You can change them on each time. If you don’t have any ports yet, you can leave it empty and fill it afterwards.

Optional

weights

Array of Weight

Usually VGM or Truck Weight, etc.

Optional

shipment_type

Lookup field - ShipmentType

Type of Shipment like FCL or LCL

Optional

carrier

string

Name of the carrier company (Ship company, Trucking company, etc)

Optional

vessel_number

string

This is Ship number or Rail Number or Flight Number or Truck Number.

Optional

carrier_reference_number

string

This is Voyage Number or reference number provided by Carrier. This number is used to query the carrier system for information on the cargo.

Optional

on_carriage

Lookup field - OnCarriage

See List. The type of On Carriage used for this Shipment.

Optional

cargos

Array of Cargo

Shows the orders within a shipment

Optional

containers

Array of Container

When MOT is SEA or SEA-AIR or RAIL, you can set the number of containers required and also additional information on each container. For other MOTs, the container information is ignored.

Optional

additional_references

Array of AdditionalReference

If you have any further references you used in additional services, you can drop here.

Optional

instructions

Array of Instruction

If you want to provide instructions to other Partners, you can add here. Even though it’s an array, you will pass usually one instruction where you can add as much instructions are possible in one field.

Optional

status

Lookup field ShipmentStatus

See List. The status of the Shipment.

Optional

partners

Array of PartnerRole

The email address and role of the partner. Partners are optional when you don’t want to manage your process. If you want to manage your supply chain process then you should add them to this entity.

Optional

owner

string

Generated and used by limbiq internal team.

Optional

deleted

boolean

To delete the Shipment, set true as value. Note: Shipment can be deleted only by the creator.

Optional

created_date

date-time

The date-time on which this Shipment is created in limbiq system. This value is set by limbiq system. If user sets this value, it will be ignored.

Ignored

creator

string

The email address of the user who has created the Shipment. This value is set by limbiq system. If user sets this value, it will be ignored.

Ignored

updated_date

date-time

The date-time on which this Shipment is updated in limbiq system. This value is set by limbiq system. If user sets this value, it will be ignored.

Ignored

updater

string

The email address of the user who has updated the Shipment. This value is set by limbiq system. If user sets this value, it will be ignored.

Ignored

TransshipPort

Field Name	Field Type	Description	Required/Optional/Ignored
id	string	This is unique ID of the transshipport and is autogenerated by limbiq platform.	Ignored
type	Lookup field - TransshipPortType	Type of the TransshipPort	Required
address	string	Physical address of the location. It could be port address, pickup warehouse address, destination warehouse address, etc	Optional
city	City	The city of the transship port along with UNLocode.	Optional
planned_date	date	The planned date at which the cargo can be picked up or dropped off or shipped or arrived, etc	Optional
planned_time	time	The planned time at which the cargo can be picked up or dropped off or shipped or arrived, etc	Optional
estimated_date	date	The estimated date at which the cargo can be picked up or dropped off or shipped or arrived, etc	Optional
estimated_time	time	The estimated time at which the cargo can be picked up or dropped off or shipped or arrived, etc	Optional
actual_date	date	The actual date at which the cargo was picked up or dropped off or shipped or arrived, etc	Optional
actual_time	time	The actual time at which the cargo was picked up or dropped off or shipped or arrived, etc	Optional
ordinal	integer	The order of "TransshipPort"s through which the cargo is transported. (route). This value must be unique. If no value is provided, limbiq platform will autoassign the incremental value. If ordinal is provided for some of "TransshipPort"s and not for some, then limbiq will auto-assign for the missing ones based on the maximum value (incrementing from that value). And if duplicate value is provided, the last transshipport with duplicate value will override other transshipports of same value.	Optional

Field Name

Field Type

Description

Required/Optional/Ignored

Default Value

string

This is unique ID of the transshipport and is autogenerated by limbiq platform.

Ignored

type

Lookup field - TransshipPortType

Type of the TransshipPort

Required

address

string

Physical address of the location. It could be port address, pickup warehouse address, destination warehouse address, etc

Optional

city

City

The city of the transship port along with UNLocode.

Optional

planned_date

date

The planned date at which the cargo can be picked up or dropped off or shipped or arrived, etc

Optional

planned_time

time

The planned time at which the cargo can be picked up or dropped off or shipped or arrived, etc

Optional

estimated_date

date

The estimated date at which the cargo can be picked up or dropped off or shipped or arrived, etc

Optional

estimated_time

time

The estimated time at which the cargo can be picked up or dropped off or shipped or arrived, etc

Optional

actual_date

date

The actual date at which the cargo was picked up or dropped off or shipped or arrived, etc

Optional

actual_time

time

The actual time at which the cargo was picked up or dropped off or shipped or arrived, etc

Optional

ordinal

integer

The order of "TransshipPort"s through which the cargo is transported. (route). This value must be unique. If no value is provided, limbiq platform will autoassign the incremental value. If ordinal is provided for some of "TransshipPort"s and not for some, then limbiq will auto-assign for the missing ones based on the maximum value (incrementing from that value). And if duplicate value is provided, the last transshipport with duplicate value will override other transshipports of same value.

Optional

City

Field Name	Field Type	Description	Required/Optional/Ignored	Default Value
name	string	Name of the city	Required
un_locode	string	UNLocode of the city. Please provide if available as it will the same city matches with multiple UNLocodes.	Optional

Field Name

Field Type

Description

Required/Optional/Ignored

Default Value

name

string

Name of the city

Required

un_locode

string

UNLocode of the city. Please provide if available as it will the same city matches with multiple UNLocodes.

Optional

Cargo

Field Name	Field Type	Description	Required/Optional/Ignored
id	string	This is unique ID of the cargo and is autogenerated by limbiq platform.	Ignored
sequence_number	integer	Incremental unique sequence number (1, 2, 3) of the "Cargo". The value must be unique for each "POLine". This is used as identifier to update the existing cargo for existing "POLine". If same sequence_number is used for more than one cargo, then the last one with same sequence number will override the previous one (with same sequence number).	Required
container_sequence_number	integer	The container to which the cargo is loaded. Either container_sequence_number or container_number are required if you want to attach the cargo to container, otherwise it is optional.	Optional
container_number	string	The container to which the cargo is loaded. Either container_sequence_number or container_number are required if you want to attach the cargo to container, otherwise it is optional.	Optional
purchase_order_number	string	The Purcharse order Number of the products. This is used only when the cargo is subcollection of Shipment. If the purchase_order_number does not exist in limbiq, a new Purchase order will be created.	Optional
product_name	string	Name of the product in this cargo. This is used only when the cargo is subcollection of Shipment. If product_name for the above purchase order does not exist in limbiq, a new POLine will be created in the respective Purchase order.	Optional
product_code	string	Code of the product in this cargo. This is used only when the cargo is subcollection of Shipment. If product_code for the above purchase order does not exist in limbiq, a new POLine will be created in the respective Purchase order.	Optional
quantity	Quantity	Total number of items in this cargo.	Optional
weights	Array of Weight	Different weights of the cargo	Optional
volume	Volume	Volume of the cargo.	Optional
packaging_type	string	Type of the package	Optional
packaging_quantity	integer	Number of packages in this cargo.	Optional
packaging_dimension	PackagingDimension	Packaging dimensions of the packages.	Optional
additional_references	Array of AdditionalReference	If you have any further references you used in additional services, you can drop here.	Optional
hazmat	Hazmat	Hazardous material classification	Optional

Field Name

Field Type

Description

Required/Optional/Ignored

Default Value

string

This is unique ID of the cargo and is autogenerated by limbiq platform.

Ignored

sequence_number

integer

Incremental unique sequence number (1, 2, 3) of the "Cargo". The value must be unique for each "POLine". This is used as identifier to update the existing cargo for existing "POLine". If same sequence_number is used for more than one cargo, then the last one with same sequence number will override the previous one (with same sequence number).

Required

container_sequence_number

integer

The container to which the cargo is loaded. Either container_sequence_number or container_number are required if you want to attach the cargo to container, otherwise it is optional.

Optional

container_number

string

The container to which the cargo is loaded. Either container_sequence_number or container_number are required if you want to attach the cargo to container, otherwise it is optional.

Optional

purchase_order_number

string

The Purcharse order Number of the products. This is used only when the cargo is subcollection of Shipment. If the purchase_order_number does not exist in limbiq, a new Purchase order will be created.

Optional

product_name

string

Name of the product in this cargo. This is used only when the cargo is subcollection of Shipment. If product_name for the above purchase order does not exist in limbiq, a new POLine will be created in the respective Purchase order.

Optional

product_code

string

Code of the product in this cargo. This is used only when the cargo is subcollection of Shipment. If product_code for the above purchase order does not exist in limbiq, a new POLine will be created in the respective Purchase order.

Optional

quantity

Quantity

Total number of items in this cargo.

Optional

weights

Array of Weight

Different weights of the cargo

Optional

volume

Volume

Volume of the cargo.

Optional

packaging_type

string

Type of the package

Optional

packaging_quantity

integer

Number of packages in this cargo.

Optional

packaging_dimension

PackagingDimension

Packaging dimensions of the packages.

Optional

additional_references

Array of AdditionalReference

If you have any further references you used in additional services, you can drop here.

Optional

hazmat

Hazmat

Hazardous material classification

Optional

Quantity

Field Name	Field Type	Description	Required/Optional/Ignored	Default Value
value	integer	The total number of products.	Required
uom	string	See list. The unit of measure of the product. For new POLine, if no value is entered, Pieces is set as default value.	Optional

Field Name

Field Type

Description

Required/Optional/Ignored

Default Value

value

integer

The total number of products.

Required

uom

string

See list. The unit of measure of the product. For new POLine, if no value is entered, Pieces is set as default value.

Optional

Weight

Field Name	Field Type	Description	Required/Optional/Ignored
type	Lookup field - WeightType	See List. The Weight Type. If no value is entered, then GROSS - Gross Weight is assumed as value.	Optional
value	double	The actual weight	Required
uom	Lookup field - WeightUOM	See List. The UOM of weight and if no value is entered, then KG is assumed as value.	Optional

Field Name

Field Type

Description

Required/Optional/Ignored

Default Value

type

Lookup field - WeightType

See List. The Weight Type. If no value is entered, then GROSS - Gross Weight is assumed as value.

Optional

value

double

The actual weight

Required

uom

Lookup field - WeightUOM

See List. The UOM of weight and if no value is entered, then KG is assumed as value.

Optional

Volume

Field Name	Field Type	Description	Required/Optional/Ignored	Default Value
value	double	The actual volume	Required
uom	Lookup field - VolumeUOM	The Unit of Measure of "Volume" and if no value is provided, then CBM - CubicMeter is assumed as value	Optional

Field Name

Field Type

Description

Required/Optional/Ignored

Default Value

value

double

The actual volume

Required

uom

Lookup field - VolumeUOM

The Unit of Measure of "Volume" and if no value is provided, then CBM - CubicMeter is assumed as value

Optional

PackagingDimension

Field Name	Field Type	Description	Required/Optional/Ignored
length	double	The length of the package.	Optional
width	double	The width of the package.	Optional
height	double	The height of the package.	Optional
uom	Lookup field - DimensionUOM	See List. The UOM of Dimensions and if no value is entered, then CM - Centimeter is assumed as value.	Optional

Field Name

Field Type

Description

Required/Optional/Ignored

Default Value

length

double

The length of the package.

Optional

width

double

The width of the package.

Optional

height

double

The height of the package.

Optional

uom

Lookup field - DimensionUOM

See List. The UOM of Dimensions and if no value is entered, then CM - Centimeter is assumed as value.

Optional

Hazmat

Field Name	Field Type	Description	Required/Optional/Ignored
class	Lookup field HazmatClass	Dangerous goods are divided into nine classes (in addition to several subcategories) on the basis of the specific chemical characteristics producing the risk.	Required
packing_group	Lookup field HazmatPackagingGroup	Packing groups are used for the purpose of determining the degree of protective packaging required for dangerous goods during transportation	Optional
un_na_number	string	Four-digit numbers ranging from 0004-3534 are called United Nations (UN) numbers. They help identify hazardous international cargo traveling in the United States. Goods that aren’t classified or regulated by the United Nations receive North American (NA) numbers. These four-digit numbers range from 8000-9279 and are assigned by the DOT	Optional

Field Name

Field Type

Description

Required/Optional/Ignored

Default Value

class

Lookup field HazmatClass

Dangerous goods are divided into nine classes (in addition to several subcategories) on the basis of the specific chemical characteristics producing the risk.

Required

packing_group

Lookup field HazmatPackagingGroup

Packing groups are used for the purpose of determining the degree of protective packaging required for dangerous goods during transportation

Optional

un_na_number

string

Four-digit numbers ranging from 0004-3534 are called United Nations (UN) numbers. They help identify hazardous international cargo traveling in the United States. Goods that aren’t classified or regulated by the United Nations receive North American (NA) numbers. These four-digit numbers range from 8000-9279 and are assigned by the DOT

Optional

Container

Field Name	Field Type	Description	Required/Optional/Ignored
id	string	This is unique ID of the container and is autogenerated by limbiq platform.	Ignored
sequence_number	integer	Incremenetal unique sequence number (1, 2, 3). When planning a shipment, user may not know the type of the container or container number, instead may know only the number of containers required. Then add that many container objects with incremental sequential number.	Required
container_number	string	The container identification number provided by the Shipper or Forwarder (used also for tracking).	Optional
container_code	string	We follow ISO 6346 Standard. Please check here for further information - https://en.wikipedia.org/wiki/ISO_6346	Optional
container_size	string	The size of the container - 20, 40, 45, etc.	Optional
container_type	string	The type of the container - GP, HC, High Cube, Dry, Refrigerated, etc. This is free form field and you can provide appropriate value that matches to your system	Optional
teu	integer	TEU - Twenty foot Equivalent Unit. For 20 ft container, the value will be 1. For 40 or 45 ft container, the value will be 2.	Optional
weights	Array of Weight	List of different weights of the container.	Optional
additional_references	Array of AdditionalReference	If you have any further references you used in additional services, you can drop here.	Optional
instructions	Array of Instruction	List of instructions that can be provided to other partners. The instructions will be available to the associated entities - PO, PO Line, Shipment.	Optional
created_date	date-time	The date-time at which this container is added to limbiq system. This value is set by limbiq system. If user passes this value, it will be ignored.	Ignored
creator	string	The email address of the user who has created the container. This value is set by limbiq system. If user passes this value, it will be ignored.	Ignored
updated_date	date-time	The date-time at which the information of this container is updated or deleted. This value is set by limbiq system. If user passes this value, it will be ignored.	Ignored
updater	string	The email address of the user who has updated or deleted the container. This value is set by limbiq system. If user passes this value, it will be ignored.	Ignored

Field Name

Field Type

Description

Required/Optional/Ignored

Default Value

string

This is unique ID of the container and is autogenerated by limbiq platform.

Ignored

sequence_number

integer

Incremenetal unique sequence number (1, 2, 3). When planning a shipment, user may not know the type of the container or container number, instead may know only the number of containers required. Then add that many container objects with incremental sequential number.

Required

container_number

string

The container identification number provided by the Shipper or Forwarder (used also for tracking).

Optional

container_code

string

We follow ISO 6346 Standard. Please check here for further information - https://en.wikipedia.org/wiki/ISO_6346

Optional

container_size

string

The size of the container - 20, 40, 45, etc.

Optional

container_type

string

The type of the container - GP, HC, High Cube, Dry, Refrigerated, etc. This is free form field and you can provide appropriate value that matches to your system

Optional

teu

integer

TEU - Twenty foot Equivalent Unit. For 20 ft container, the value will be 1. For 40 or 45 ft container, the value will be 2.

Optional

weights

Array of Weight

List of different weights of the container.

Optional

additional_references

Array of AdditionalReference

If you have any further references you used in additional services, you can drop here.

Optional

instructions

Array of Instruction

List of instructions that can be provided to other partners. The instructions will be available to the associated entities - PO, PO Line, Shipment.

Optional

created_date

date-time

The date-time at which this container is added to limbiq system. This value is set by limbiq system. If user passes this value, it will be ignored.

Ignored

creator

string

The email address of the user who has created the container. This value is set by limbiq system. If user passes this value, it will be ignored.

Ignored

updated_date

date-time

The date-time at which the information of this container is updated or deleted. This value is set by limbiq system. If user passes this value, it will be ignored.

Ignored

updater

string

The email address of the user who has updated or deleted the container. This value is set by limbiq system. If user passes this value, it will be ignored.

Ignored

AdditionalReference

If you have any additional references that are not listed in shipment (Ex: Invoice Number, Stuffing Number, Shipper reference number, etc), then you can pass them as AdditionalReference object. Note that the reference_field_name is the name of the Additional Reference and is free form text - Ex: Invoice Number. If the respective field does not exist, it will be automatically created. Also please make sure there are no typos else the fields are duplicated with typos.

Field Name	Field Type	Description	Required/Optional/Ignored
id	string	Auto generated unique ID by limbiq.	Ignored
reference_field_name	string	The free-form text of reference field name.	Required
reference_field_value	string	The field value.	Required
deleted	boolean	To delete the additional reference, set true as value.	Optional

Field Name

Field Type

Description

Required/Optional/Ignored

Default Value

string

Auto generated unique ID by limbiq.

Ignored

reference_field_name

string

The free-form text of reference field name.

Required

reference_field_value

string

The field value.

Required

deleted

boolean

To delete the additional reference, set true as value.

Optional

PartnerRole

Field Name	Field Type	Description	Required/Optional/Ignored	Default Value
email	string	the email address of the partner.	Required
role	string	Role of the Partner in this "Shipment" or "Shipment" - Ex. Consignee, Shipper, Forwarder, Notify Party.	Required

Field Name

Field Type

Description

Required/Optional/Ignored

Default Value

string

the email address of the partner.

Required

role

string

Role of the Partner in this "Shipment" or "Shipment" - Ex. Consignee, Shipper, Forwarder, Notify Party.

Required

Instruction

Every "Instruction" object is considered as new instruction and hence a new "Instruction" is added in limbiq platform each time it is added to the parent object (either it is create action or update action). For ex. You created a "Shipment" by setting the "Instruction" and then updated the "Shipment" by passing the same "Instruction", then limbiq platform creates 2 "Instruction"s with same value. If you want to avoid duplicates, set and send only new "Instruction"s.

Also only the creator of the "Instruction"s, can delete them. If other partner, tries to delete the "Instruction" not created by her/him, then the "Instruction" is ignored (no error is returned). For ex: A forwarder added an "Instruction" and the consignee get the list and tries to delete the one created by forwarder, then the action will be ignored by limbiq platform.

Field Name	Field Type	Description	Required/Optional/Ignored
id	string	Auto generated unique ID by limbiq.	Ignored
value	string	The actual instructions.	Required
deleted	boolean	To delete the instruction, set true as value.	Optional
created_date	date-time	The date-time at which this instruction is added to limbiq system. This value is set by limbiq system. If user passes this value, it will be ignored.	Ignored
creator	string	The email address of the user who has created the attachment. This value is set by limbiq system. If user passes this value, it will be ignored.	Ignored
updated_date	date-time	The date-time at which this instruction is deleted. This value is set by limbiq system. If user passes this value, it will be ignored.	Ignored
updater	string	The email address of the user who has deleted the instruction. This value is set by limbiq system. If user passes this value, it will be ignored.	Ignored

Field Name

Field Type

Description

Required/Optional/Ignored

Default Value

string

Auto generated unique ID by limbiq.

Ignored

value

string

The actual instructions.

Required

deleted

boolean

To delete the instruction, set true as value.

Optional

created_date

date-time

The date-time at which this instruction is added to limbiq system. This value is set by limbiq system. If user passes this value, it will be ignored.

Ignored

creator

string

The email address of the user who has created the attachment. This value is set by limbiq system. If user passes this value, it will be ignored.

Ignored

updated_date

date-time

The date-time at which this instruction is deleted. This value is set by limbiq system. If user passes this value, it will be ignored.

Ignored

updater

string

The email address of the user who has deleted the instruction. This value is set by limbiq system. If user passes this value, it will be ignored.

Ignored

Lookup Types and Codes

Below is the list of lookup codes with description for each Lookup type. Limbiq platform supports only these codes wherever they are referred and if any other code than these are provided, either they are ignored or an error is returned. Please see each field description to know which behavior is applied.

ShipmentStatus

ShipmentStatus	Description
CARGO_PLANNED	Plan cargo for a shipment
CARGO_READY	Cargo is ready to book a shipment
SHIPMENT_PLACED	Shipment is placed at a carrier
SHIPMENT_CONFIRMED	Shipment is confirmed, so that it will transported by the carrier
CARGO_DISPATCHED	Cargo is dispatched from shipper
SHIPPED	Shipment is on the way
ARRIVED_AT_POD	Shipment has arrived port of discharge or port of arrival
ARRIVED_AT_DESTINATION	Shipment has arrived final destination

Description

CARGO_PLANNED

Plan cargo for a shipment

CARGO_READY

Cargo is ready to book a shipment

SHIPMENT_PLACED

Shipment is placed at a carrier

SHIPMENT_CONFIRMED

Shipment is confirmed, so that it will transported by the carrier

CARGO_DISPATCHED

Cargo is dispatched from shipper

SHIPPED

Shipment is on the way

ARRIVED_AT_POD

Shipment has arrived port of discharge or port of arrival

ARRIVED_AT_DESTINATION

Shipment has arrived final destination

ShipmentType

ShipmentType	Description
FCL	Full Container Load
LCL	Less than Container Load
FTL	Full Truck Load
LTL	Less than Truck Load
PARTIAL_TL	Partial Load
GROUPAGE	Groupage
AIR_FREIGHT	Air Freight
RAIL_FREIGHT	Rail Freight

Description

FCL

Full Container Load

LCL

Less than Container Load

FTL

Full Truck Load

LTL

Less than Truck Load

PARTIAL_TL

Partial Load

GROUPAGE

Groupage

AIR_FREIGHT

Air Freight

RAIL_FREIGHT

Rail Freight

MOT

MOT (Mode of Transport)	Description
SEA	Sea
AIR	Air
SEA-AIR	Sea and Air
TRUCK	Truck
RAIL	Rail

MOT (Mode of Transport)

Description

SEA

Sea

AIR

Air

SEA-AIR

Sea and Air

TRUCK

Truck

RAIL

Rail

Incoterm

Incoterm (2020)	Description
EXW	Ex Works (named place of delivery)
FCA	Free Carrier (named place of delivery)
FAS	Free Alongside Ship (named port of shipment)
FOB	Free on Board (named port of shipment)
CFR	Cost and Freight (named port of destination)
CIF	Cost, Insurance & Freight (named port of destination)
CPT	Carriage Paid To (named place of destination)
CIP	Carriage and Insurance Paid to (named place of destination)
DAP	Delivered At Place (named place of destination)
DPU	Delivered At Place Unloaded (named place of destination)
DDP	Delivered Duty Paid (named place of destination)

Incoterm (2020)

Description

EXW

Ex Works (named place of delivery)

FCA

Free Carrier (named place of delivery)

FAS

Free Alongside Ship (named port of shipment)

FOB

Free on Board (named port of shipment)

CFR

Cost and Freight (named port of destination)

CIF

Cost, Insurance & Freight (named port of destination)

CPT

Carriage Paid To (named place of destination)

CIP

Carriage and Insurance Paid to (named place of destination)

DAP

Delivered At Place (named place of destination)

DPU

Delivered At Place Unloaded (named place of destination)

DDP

Delivered Duty Paid (named place of destination)

TransshipPortType

TransshipPortType	Description
PICKUP_LOCATION	Pickup location of cargo. Usually origin warehouse (of Shipper)
POL	Port of Loading
VIA	Via
PORT	Shipping Port or Airport (usually used as Via but to be specific)
TERMINAL	Shipping Terminal or Airport Terminal
CUSTOM_CHECK	Customs location
BORDER	Cross country border
DOCK	Dock (at Shipping Yard, etc) where cargo is delivered intermittently
CROSS_DOCKING	Cross Docking
BREAK_OF_GUAGE	Break of Guage
POD	Port of Discharge or Port of Arrival
DESTINATION	Final Destination
CONTAINER_YARD	Container Yard where the container is picked up empty and returned empty after transport
LOCATION	Any type of location if you can’t specify it

Description

PICKUP_LOCATION

Pickup location of cargo. Usually origin warehouse (of Shipper)

POL

Port of Loading

VIA

Via

PORT

Shipping Port or Airport (usually used as Via but to be specific)

TERMINAL

Shipping Terminal or Airport Terminal

CUSTOM_CHECK

Customs location

BORDER

Cross country border

DOCK

Dock (at Shipping Yard, etc) where cargo is delivered intermittently

CROSS_DOCKING

Cross Docking

BREAK_OF_GUAGE

Break of Guage

POD

Port of Discharge or Port of Arrival

DESTINATION

Final Destination

CONTAINER_YARD

Container Yard where the container is picked up empty and returned empty after transport

LOCATION

Any type of location if you can’t specify it

WeightType

WeightType	Description
NET	Net Weight is the total weight of just the raw cargo, or for container - is the total weight (gross as above) of the cargo after it has been packed into a container – but excluding the tare weight of the container
GROSS	Gross Weight is the total weight of the raw cargo (example – Peppadews) + the weight of bottles or cans that it is packed in.. If the bottles and cans are further packed into cartons which are placed on a pallet, then the weight of the peppadews + bottles + cartons + pallets = gross weight, or for container - is the total weight of the cargo + the tare weight of the container
TARE	Tare Weight is the weight of the empty container
DWT	Dead Weight: refers to the weight that a ship can safely carry – this includes the weight of the cargo on board the ship, the crew, stores, fuel, water, allast etc.. If the total weight exceeds the DWT certified by the ship builder, then the ship could be in danger of sinking or damage..
PAYLOAD	Payload is the maximum cargo weight that a container can carry and excludes the tare weight of the container.. Containers have CSC plates that reflect the payload that the container is allowed to carry..
GT	Gross Tonnage: refers to a ships overall internal volume including crew accommodation, machinery, navigation equipment etc
NT	Net Tonnage: refers to a ships GT minus the the space used up by the crew accommodation, machinery, navigation equipment etc – basically the space that is available for the carriage of passengers and cargo..
VGM	Verified Gross Mass: for container

Description

NET

Net Weight is the total weight of just the raw cargo, or for container - is the total weight (gross as above) of the cargo after it has been packed into a container – but excluding the tare weight of the container

GROSS

Gross Weight is the total weight of the raw cargo (example – Peppadews) + the weight of bottles or cans that it is packed in.. If the bottles and cans are further packed into cartons which are placed on a pallet, then the weight of the peppadews + bottles + cartons + pallets = gross weight, or for container - is the total weight of the cargo + the tare weight of the container

TARE

Tare Weight is the weight of the empty container

DWT

Dead Weight: refers to the weight that a ship can safely carry – this includes the weight of the cargo on board the ship, the crew, stores, fuel, water, allast etc.. If the total weight exceeds the DWT certified by the ship builder, then the ship could be in danger of sinking or damage..

PAYLOAD

Payload is the maximum cargo weight that a container can carry and excludes the tare weight of the container.. Containers have CSC plates that reflect the payload that the container is allowed to carry..

Gross Tonnage: refers to a ships overall internal volume including crew accommodation, machinery, navigation equipment etc

Net Tonnage: refers to a ships GT minus the the space used up by the crew accommodation, machinery, navigation equipment etc – basically the space that is available for the carriage of passengers and cargo..

VGM

Verified Gross Mass: for container

WeightUOM

WeightUOM (Unit of Measure)	Description
KG	Kilograms
POUND	Pounds

WeightUOM (Unit of Measure)

Description

Kilograms

POUND

Pounds

VolumeUOM

VolumeUOM (Unit of Measure)	Description
CBM	Cubic Meter
CFT	Cubic Feet

VolumeUOM (Unit of Measure)

Description

CBM

Cubic Meter

CFT

Cubic Feet

DimensionUOM

DimensionUOM (Unit of Measure)	Description
CM	Centimeters
IN	Inches
FT	Feet

DimensionUOM (Unit of Measure)

Description

Centimeters

Inches

Feet

HazmatClass

Hazmat Class	Description
1.1	Explosives with a mass explosion hazard
1.2	Explosives with a blast/projection hazard.
1.3	Explosives with a minor blast hazard. (rocket propellant, display fireworks)
1.4	Explosives with a major fire hazard. (consumer fireworks, ammunition)
1.5	Blasting agents
1.6	Extremely insensitive explosives
2.1	Flammable Gas
2.2	Nonflammable Gas, Oxygen (Alternative Placard)
2.3	Poisonous Gas, Inhalation Hazard (Alternative Placard)
3	Flammable Liquids, Combustible (Alternate Placard), Fuel Oil (Alternate Placard), Gasoline (Alternate Placard)
4.1	Flammable Solids
4.2	Spontaneously Combustible Solids
4.3	Dangerous when Wet
5.1	Oxidizing Agent
5.2	Organic Peroxide Oxidizing Agent
6.1	Poison
6.2	Biohazard
7	Radioactive
8	Corrosive
9	Miscellaneous

HazmatPackagingGroup

Hazmat Packaging Group	Description
1	Packing Group I, if they have an initial boiling point of 35°C or less at an absolute pressure of 101.3 kPa and any flash point, such as diethyl ether or carbon disulfide
2	Packing Group II, if they have an initial boiling point greater than 35°C at an absolute pressure of 101.3 kPa and a flash point less than 23°C, such as gasoline (petrol) and acetone
3	Packing Group III, if the criteria for inclusion in Packing Group I or II are not met, such as kerosene and diesel

OnCarriage

ConfirmationProcessStep	Description
NA	Not applicable
TRUCK	Truck
BARGE_TRUCK	First Barge than Truck
BARGE_RAIL_TRUCK	First Barge, Second RAIL, Third Truck
RAIL	Rail
RAIL_TRUCK	First Rail than Truck

ConfirmationProcessStep

Description

Not applicable

TRUCK

Truck

BARGE_TRUCK

First Barge than Truck

BARGE_RAIL_TRUCK

First Barge, Second RAIL, Third Truck

RAIL

Rail

RAIL_TRUCK

First Rail than Truck

Responses and Validation Errors

Below are the HTTP Codes that are used by limbiq platform.

Http Code	Return Value	Description
200	Entity is created or updated or deleted	The is the successful code and will be returned when the respective action is successfully completed.
400	Validation failed on requested entity	This means that the request is not well-formed, or syntactically incorrect, or violates schema.
404	Entity not found.	This error occurs when you try to delete the Shipment and it is available in the limbiq platform.

Http Code

Return Value

Description

200

Entity is created or updated or deleted

The is the successful code and will be returned when the respective action is successfully completed.

400

Validation failed on requested entity

This means that the request is not well-formed, or syntactically incorrect, or violates schema.

404

Entity not found.

This error occurs when you try to delete the Shipment and it is available in the limbiq platform.

Below are the list of validation errors that occur because of missing or wrong information sent to limbiq platform.

Entity	Validation Error
All	In all entities, wherever it is mentioned as required and the value is not provided,"FieldName: value is required" error will be returned.
All	Wherever applicable: If wrong status is used than what is mentioned in the Lookup codes, then and error "entity name: Wrong status" will be returned.
TransshipPort	The dates follow below order and if they are in different order, then an error "Date2: Should be greater than Date1" Estimated date of POL < Estimated date of POD < Estimated date of Destination Actual date of POL < Actual date of POD < Actual date of Destination

Entity

Validation Error

All

In all entities, wherever it is mentioned as required and the value is not provided,"FieldName: value is required" error will be returned.

All

Wherever applicable: If wrong status is used than what is mentioned in the Lookup codes, then and error "entity name: Wrong status" will be returned.

TransshipPort

The dates follow below order and if they are in different order, then an error "Date2: Should be greater than Date1" Estimated date of POL < Estimated date of POD < Estimated date of Destination Actual date of POL < Actual date of POD < Actual date of Destination

Appendix

Recommended TransshipPort Types for MOT/Incoterm

Table 1. As a Consignee
MOT	Incoterm	Recommended TransshipPort Types
All(Except TRUCK)	EXW	PICKUP_LOCATION, POL, POD, DESTINATION
All(Except TRUCK)	CIP	PICKUP_LOCATION, POL, POD, DESTINATION
All(Except TRUCK)	DAP	POD, DESTINATION
All(Except TRUCK)	FCA	PICKUP_LOCATION, POL, POD, DESTINATION
All(Except TRUCK)	DPU	DESTINATION
All(Except TRUCK)	CPT	POL, POD, DESTINATION
All(Except TRUCK)	DDP	DESTINATION
SEA, SEA-AIR	FAS	POL, POD, DESTINATION
SEA, SEA-AIR	CFR	POL, POD, DESTINATION
SEA, SEA-AIR	FOB	POL, POD, DESTINATION
SEA, SEA-AIR	CIF	POL, POD, DESTINATION
TRUCK	EXW	PICKUP_LOCATION, DESTINATION
TRUCK	CIP	PICKUP_LOCATION, DESTINATION
TRUCK	DAP	DESTINATION
TRUCK	FCA	PICKUP_LOCATION, DESTINATION
TRUCK	DPU	DESTINATION
TRUCK	CPT	PICKUP_LOCATION, DESTINATION
TRUCK	DDP	DESTINATION

Example

{
    "id": "ed9e68c0-7e6d-45d7-9f16-cf738c3def64",
    "limbiq_reference_id": "LIM1001518",
    "external_id": "BL123456789",
    "crd": "2020-09-05",
    "mot": "SEA",
    "incoterm": "FOB",
    "incoterm_location": {
       "name": "Duisburg",
        "un_locode": "DEDUI"
    },
    "transship_ports": [
        {
            "id": "86038b4d-a5b2-465a-913c-d186897f4e76",
            "type": "POL",
            "city": {
                "name": "Hong Kong",
                "un_locode": "HKHKG"
            },
            "estimated_date": "2020-09-14",
            "estimated_time": "09:30",
            "actual_date": "2020-09-14",
            "actual_time": "11:13",
            "ordinal": 0
        },
        {
            "id": "58d05c5f-8848-40c0-a1ff-c6cf88f0d128",
            "type": "POD",
            "city": {
                "name": "Rotterdam",
                "un_locode": "NLRTM"
            },
            "estimated_date": "2020-10-13",
            "estimated_time": "11:30",
            "ordinal": 1
        },
        {
            "id": "42908310-fc8f-4e68-8a14-ca1d4e8cb1a2",
            "type": "DESTINATION",
            "city": {
                "name": "Duisburg",
                "un_locode": "DEDUI"
            },
            "estimated_date": "2020-10-17",
            "estimated_time": "13:00",
            "ordinal": 2
        }
    ],
    "weights": [
        {
            "type": "GROSS",
            "value": 20234.65,
            "uom": "KG"
        }
    ],
    "shipment_type": "FCL",
    "carrier": "Next Carrier",
    "vessel_number": "Santa Maria",
    "carrier_reference_number": "001W",
    "on_carriage": "BARGE",
    "cargos": [
        {
            "id": "5566a6a6-2346-4b3b-9359-b4dce3fa4ee1",
            "sequence_number": 1,
            "container_sequence_number": 1,
            "container_number": "CONT1234567",
            "purchase_order_number": "20201045",
            "product_name": "Kinder Shoes Blue",
            "product_code": "4545-5765-6452",
            "quantity": {
                "value": 1628.0,
                "uom": "CTN"
            },
            "weights": [
                {
                    "type": "GROSS",
                    "value": 16234.65,
                    "uom": "KG"
                }
            ],
            "volume": {
                "value": "54.76",
                "uom": "CBM"
            },
            "packaging_type": "CTN",
            "packaging_quantity": 1628,
            "packaging_dimension": {
                "length": 50,
                "width": 60,
                "height": 11,
                "uom": "CM"
            },
            "hazmat": {
                "class": "1.1",
                "packing_group": "1"
            }
        }
    ],
    "containers": [
        {
            "id": "1d494ebd-5f8f-4ef6-9450-b7758568c5eb",
            "sequence_number": 1,
            "container_number": "CONT1234567",
            "container_code": "45G1",
            "weights": [
                {
                    "type": "GROSS",
                    "value": 20234.65,
                    "uom": "KG"
                }
            ],
            "additional_references": [
                {
                    "reference_field_name": "Seal Number",
                    "reference_field_value": "12312312312"
                },
                {
                    "reference_field_name": "ATB Number",
                    "reference_field_value": "66756564753"
                }
            ]
        }
    ],
    "status": "SHIPPED",
    "instructions": [
        {
            "value": "SUPPLIER: Supplier Ltd., Contact: API Supplier, Address: Philosophenweg 31-33, 47051 Duisburg, Telefon: +49 203 9287 9872, Email: support@limbiq.com"
        }
    ],
    "deleted": false,
    "created_date": "2020-08-02T12:42:22.628Z",
    "creator": "supplier@limbiq.com",
    "updated_date": "2020-08-02T12:42:22.628Z",
    "updater": "supplier@limbiq.com",
    "partners": [
        {
            "email": "forwarder@limbiq.com",
            "role": "Forwarder"
        },
        {
            "email": "consignee@limbiq.com",
            "role": "Consignee"
        },
        {
            "email": "supplier@limbiq.com",
            "role": "Shipper"
        },
        {
            "email": "notification_party@user.com",
            "role": "Notify Party"
        }
    ]
}