Fulfillment Engine API
Optimally fulfill orders with Shipium's Fulfillment Engine API.
Get started
To use the Fulfillment Engine API, you must first configure your account. Guidance can be found in the Fulfillment Engine documentation. This document provides instructions for using the API.
Create a fulfillment plan with the Fulfillment Engine API
The Fulfillment Engine API is designed to be flexible to fit your organization’s business strategy and technical capabilities. All API calls assume you're using one of the authentication mechanisms detailed in our authentication documentation. The endpoint for all Fulfillment Engine API calls is included in the table below.
API type | API endpoint |
---|---|
POST | https://api.shipium.com/api/v1/fe/plans |
Authentication for API Calls
In the cURL example on this page, the environment variable
AUTHSTRING
is used to handle authorization. The recipe below shows how to set it correctly for both API Key and OAuth users.
The following table provides all required and optional fields for calling the Fulfillment Engine API. You can find additional support in the Fulfillment Engine API Reference.
Request field | Required/Optional | Field properties | Description |
---|---|---|---|
asOfDateTime | Optional | String | A date used to recreate a plan as of a certain point in time. This parameter will prevent the use of caching for this request. The most common use case is to provide null , which represents 'now'. |
fulfillmentCenters .fulfillmentContextId | Required | String | A unique identifier for the fulfillment context. This ID must correspond to a Shipium-registered fulfillment context for your organization. |
fulfillmentCenters .fulfillmentCost .currencyCode | Optional | String | The currency code of the fulfillment costs |
fulfillmentCenters .fulfillmentCost .perItem | Optional | Number ($float) | Additional processing cost added per item in a shipment |
fulfillmentCenters .fulfillmentCost .perPackage | Optional | Number ($float) | Additional processing cost added per package in a shipment |
fulfillmentCenters .packagingTypes .linearDimensions .height | Required | Decimal Limited to a value greater than zero | Length of the shortest side of the box to be packed Note on envelopes: This height should represent the highest product you would reasonably put in this envelope before losing more than 10% of the length of the envelope in other dimensions. |
fulfillmentCenters .packagingTypes .linearDimensions .length | Required | Decimal Limited to a value greater than zero | Length of the longest side of the box to be packed |
fulfillmentCenters .packagingTypes .linearDimensions .linearUnit | Required | String enumeration Values are: - in (inch)- cm (centimeter) | The unit of measurement the linear dimensions of the box are specified in |
fulfillmentCenters .packagingTypes .linearDimensions .width | Required | Decimal Limited to a value greater than zero | Length of the second longest side of the box to be packed |
fulfillmentCenters .packagingTypes .packagingTypeId | Optional, but required if including packaging type values configured in the Shipium platform | String | Packing type identifier |
fulfillmentCenters .packagingTypes .packagingMaterial | Optional, but required if no packagingTypeId is provided | String enumeration Values are: - box - envelope - flat_pack - unknown | The shipment packaging material |
fulfillmentCenters .packagingTypes .packagingSizeName | Optional | String Example: 1x1x4 Box | A name your organization wishes to provide for the packaging size |
fulfillmentCenters .packagingTypes .weight.weight | Optional, but required if no packagingTypeId is provided | Decimal Limited to a number greater than zero | The weight of the empty packaging |
fulfillmentCenters .packagingTypes .weight.weightUnit | Optional, but required if no packagingTypeId is provided | String Values are: - g (gram)- k (kilogram)- oz (ounce)- lb (pound) | The unit of measurement in which the empty packaging is specified |
orders.currencyCode | Optional | String Limited to 3 characters and ISO 4217 standards | Currency code of the orders (e.g., USD = U.S. dollars) |
orders .destinationAddress .addressType | Required | String enumeration Values are: - Commercial - Residential | The type of location for this address |
orders .destinationAddress .city | Optional | String Limited to alphabetical characters | The name of the city for the address |
orders .destinationAddress .company | Optional | String Limited to alphanumeric characters | The company name for the address |
orders .destinationAddress .countryCode | Required | String Limited to 2 characters and ISO 3166 standards | The country code for the address |
orders .destinationAddress .name | Optional | String | The name associated with the address |
orders .destinationAddress .postalCode | Required | String Limited to a country-appropriate postal code | The postal code for the address |
orders .destinationAddress .region | Optional | String | The name of the state or region for the address (e.g., NM) |
orders .destinationAddress .street1 | Optional | String | The first line of the address |
orders .destinationAddress .street2 | Optional | String | The second line of the address |
orders .orderItemQuantities .productId | Required | String | A unique product identifier (e.g., RN03947-Z43121) |
orders .orderItemQuantities .quantity | Required | Integer Limited to a number greater than zero | The number of units of this product |
orders .orderParams .mustShipComplete | Optional | BooleanTrue or False | True if all order items must be planned for shipment. The default value is false . |
orders .orderParams .orderedDateTime | Optional | String Limited to the ISO-8601 standard | The timestamp for when the customer ordered the product |
orders .orderParams .partnerOrderId | Required | String | The identification your organization provided for this order |
packagingTypes .linearDimensions .height | Optional, but required if no packagingTypeId is provided | Decimal Limited to a value greater than zero | The numerical value of the shortest side of the package |
packagingTypes .linearDimensions .length | Optional, but required if no packagingTypeId is provided | Decimal Limited to a value greater than zero | The numerical value of the longest side of the package |
packagingTypes .linearDimensions .linearUnit | Optional, but required if no packagingTypeId is provided | String enumeration Values are: - in (inch)- cm (centimeter) | The unit of measurement in which the linear dimensions of the package are specified |
packagingTypes .linearDimensions .width | Optional, but required if no packagingTypeId is provided | Decimal Limited to a value greater than zero | The numerical value of the second longest side of the package |
packagingTypes .packagingTypeId | Required | String | Packing type identifier |
packagingTypes .packagingMaterial | Required | String enumeration Values are: - box - envelope - flat_pack - unknown | The shipment packaging material |
packagingTypes .weight.weight | Required | Decimal Limited to a number greater than zero | The weight of the packaging |
packagingTypes .weight.weightUnit | Required | String enumeration Values are: - g (gram)- kg (kilogram)- oz (ounce)- lb (pound) | The unit of measurement in which the packaging is specified |
packagingTypes .maxContentWeight .weightUnit | Optional, but required if Packaging Planner values are included but no packagingTypeId is provided | String Values are: - g (gram)- kg (kilogram)- oz (ounce)- lb (pound) | The unit of measurement of the maximum weight of the contents that the packaging type can support |
packagingTypes .maxContentweight .weight | Optional, but required if Packaging Planner values are included but no packagingTypeId is provided | Decimal Limited to a number greater than zero | The maximum weight of contents that the packaging type can support |
packagingTypes .packagingSizeName | Optional | String Example: 1x1x4 Box | A name your organization wishes to provide for the packaging size |
planDateTime | Optional | String | A future date to use as the starting date of the plan. A value of null conveys to use 'now' as the plan time. |
productDetails .fulfillment Attributes | Optional | String | A list of attributes that may affect the shipping of the product |
productDetails .hazmat | Optional | BooleanTrue or False | If true , indicates that the item is hazmat. The default value is false . |
productDetails .hazmatInfo .category | Optional, but required if the hazmat field is TRUE | String enumeration Values are: - contains_lithium_ion - contains_lithium_metal - defined - lithium_ion_battery_only - lithium_metal_battery_only - packaged_lithium_ion - packaged_lithium_metal | Hazmat category for this order item. Use 'defined' to specify detailed information. |
productDetails .hazmatInfo .containerType | Optional, but required if the hazmat field is TRUE | String enumeration Values are: - aluminum_box - aluminum_cylinder - aluminum_drum - aluminum_jerrican - carton - cylinder - envirotainer - fiber_drum - fiberboard_box - metal_box - other - plastic_box - plastic_drum - plastic_jerrican - plastic_pail - plywood_box - plywood_drum - steel_box - steel_drum - steel_jerrican - styrofoam_box - wooden_box | The material in which the hazardous material is packed |
productDetails .hazmatInfo .hazardClass | Optional, but required if the category field is defined | String enumeration Values are: - class_1_explosive - class_2_flammable_gas - class_3_flammable_liquid - class_4_flammable_solid - class_5_organic_peroxide - class_6_poisonous_material - class_7_radioactive - class_8_corrosive_material - class_9_miscellaneous - forbidden - other | Hazard class of the hazardous material |
productDetails .hazmatInfo .hazmatId | Optional, but required if the category field is defined | -String | The International Air Transport Association (IATA) or U.S. Department of Transportation (DOT) regulatory identifier for the commodity as appropriate |
productDetails .hazmatInfo .packingGroup | Optional | String enumeration Values are: - i - ii - iii | The degree of danger the material presents |
productDetails .hazmatInfo .packingInstruction Code | Optional | String | The packing instruction code used for air transport |
productDetails .hazmatInfo .properShippingName | Optional, but required if the category field is defined | String | The proper shipping name that is associated with the specified hazmatId |
productDetails .hazmatInfo .quantity | Required | Number | The amount of quantity type material in quantity units |
productDetails .hazmatInfo .quantityType | Required | String enumeration Values are: - Gross - Net | Determines whether the quantity includes the raw material (net) or also includes the material housing (gross) |
productDetails .hazmatInfo .quantityUnits | Required | String enumeration Values are: - g (gram)- kg (kilogram)- l (liter)- ml (milliliter)- lb (pound)- oz (ounce) | The units of measure for the quantity of hazardous materials specified |
productDetails .hazmatInfo .subsidiaryClasses | Optional | String | The appropriate IATA or DOT subsidiary classes associated with the material and the hazard class |
productDetails .hazmatInfo .transportMode | Optional, but required if the category field is defined | String enumeration Valuesare: - cargo_aircraft_only - ground - passenger_and_cargo_aircraft | The packing instruction code used for air transport |
productDetails .inventoryStatuses .fulfillmentContext Id | Required | String | A unique identifier for the fulfillment context. This ID must correspond to a Shipium-registered fulfillment context for your organization. |
productDetails .inventoryStatuses .fulfillmentCost CurrencyCode | Optional | String Limited to 3 characters and ISO 4217 standards | Currency code of the fulfillment cost (e.g., USD = U.S. dollars) |
productDetails .inventoryStatuses .fulfillmentCost PerItem | Optional | Number | The price of fulfilling one item from the fulfillment center |
productDetails .inventoryStatuses .quantityAvailable | Required | Integer | The quantity of the item available at the fulfillment center |
productDetails .linearDimensions .height | Required | Decimal Limited to a value greater than zero | The numerical value of the shortest side of the product |
productDetails .linearDimensions .length | Required | Decimal Limited to a value greater than zero | The numerical value of the longest side of the product |
productDetails .linearDimensions .linearUnit | Required | String Limited to inch (in) or centimeter (cm) | The unit of measurement in which the linear dimensions of the product are specified |
productDetails .linearDimensions .width | Required | Decimal Limited to a value greater than zero | The numerical value of the second longest side of the product |
productDetails .productId | Required | String | The product stock-keeping unit (SKU) |
productDetails .weight.weight | Optional, but required if including productDetails.weight | Decimal Limited to a number greater than zero | The weight of the product |
productDetails .weight.weightUnit | Optional, but required if including productDetails.weight | String enumeration Values are: - g (gram)- kg (kilogram)- oz (ounce)- lb (pound) | The unit of measurement in which the weight is specified |
The Fulfillment Engine response attributes are defined in the following table.
There are three major sections of the response:
- proposedShipments contains the list of shipments recommended, including FC, packaging and cost details, items and links for each element in the
shipmentItems
array back to the originating order. - unfulfillableItems contains order items that could not be fulfilled, usually due to insufficient inventory available across all FCs.
- resultingInventory contains the ending inventory state. If a given SKU in a given warehouse started out with a quantity of 10 and 4 were used as part of producing shipments then this array will contain a
quantityAvailable
of 6 for that FC and SKU, reflecting the end state of the inventory after assignments are complete.
Response attribute | Description |
---|---|
active | Indicates whether this asset is active (a value of TRUE) or inactive (FALSE) |
archived | Indicates whether this asset is archived (a value of TRUE) or inactive (FALSE) |
auditInfo.createdBy | The username of the last person (or system) who created the entity |
auditInfo.creationTimeStamp | ISO-8601 formatted date in UTC when the entity was initially created |
auditInfo.lastUpdatedBy | The username of the last person (or system) to update the entity |
auditInfo.lastUpdatedTimeStamp | ISO-8601 formatted date in UTC when the entity was last updated |
auditInfo.version | A number corresponding to each version change |
description | Explanatory information about this asset |
name | A human-readable name for this asset |
partnerId | The unique identification (ID) for your organization |
partnerProvidedId | The unique ID provided by your organization for this asset |
planId | The unique ID for the Fulfillment Engine plan generated by Shipium |
proposedShipments.cost.carrier | The proposed carrier to ship the package out of the fulfillment center |
proposedShipments.cost.cost | The estimated cost to ship the package out of the fulfillment center |
proposedShipments.cost .serviceMethod | The proposed carrier service method to ship the package out of the fulfillment center |
proposedShipments .destinationAddress.addressType | The type of location for this address (i.e., commercial or residential) |
proposedShipments .destinationAddress.city | The name of the city for the address |
proposedShipments .destinationAddress.company | The company name for the address |
proposedShipments .destinationAddress.countryCode | The ISO-3166 country code for the address |
proposedShipments .destinationAddress.name | The name associated with the address |
proposedShipments .destinationAddress.postalCode | The postal code for the address |
proposedShipments .destinationAddress.region | The name of the state or region for the address |
proposedShipments .destinationAddress.street1 | The first line of the address |
proposedShipments .destinationAddress.street2 | The second line of the address |
proposedShipments .fulfillmentContextId | The unique ID of the fulfillment context |
proposedShipments .packagingType.linearDimensions.height | The numerical value of the shortest side of the packaging |
proposedShipments .packagingType.linearDimensions.length | The numerical value of the longest side of the packaging |
proposedShipments .packagingType.linearDimensions.linearUnit | The unit of measurement in which the linear dimensions of the packaging are specified |
proposedShipments .packagingType.linearDimensions.width | The numerical value of the second longest side of the packaging |
proposedShipments .packagingType.packagingTypeId | Packaging type identifier |
proposedShipments .packagingType.packagingMaterial | The shipment packaging material (box, envelope, flat pack, or unknown) |
proposedShipments .packagingType.packagingSizeName | The name your organization provided for the packaging size |
proposedShipments .packagingType.weight.weight | The weight of the packaging |
proposedShipments .packagingType.weight.weightUnit | The unit of measurement the packaging is specified in |
proposedShipments .shipiumProposedShipmentId | A proposed unique ID to use for the shipment |
proposedShipments .shipmentItems.linearDimensions.height | The numerical value of the shortest side of the items to be shipped |
proposedShipments .shipmentItems.linearDimensions.length | The numerical value of the longest side of the items to be shipped |
proposedShipments .shipmentItems.linearDimensions.linearUnit | The unit of measurement the linear dimensions of the items to be shipped are specified in |
proposedShipments .shipmentItems.linearDimensions.width | The numerical value of the second longest side of the items to be shipped |
proposedShipments .shipmentItems.partnerOrderId | The ID your organization provided for this order |
proposedShipments .shipmentItems.productId | A unique product identifier (e.g., RN03947-Z43121) |
proposedShipments .shipmentItems.weight.weight | The weight of the items to be shipped |
proposedShipments .shipmentItems.weight.weightUnit | The unit of measurement the items to be shipped are specified in |
proposedShipments .totalWeight.weight | The total weight of the proposed shipment |
proposedShipments .totalWeight.weightUnit | The unit of measurement the total proposed shipment is specified in |
unfulfillableItems.countUnfulfilled | The number of unfulfillable items for the order |
unfulfillableItems.orderItem.productId | A unique product identifier (e.g., RN03947-Z43121) for the unfulfillable item |
unfulfillableItems.orderItem.quantity | The number of units of the product |
unfulfillableItems.partnerOrderId | A unique order identifier for the unfulfillable items provided by your organization |
unfulfillableItems.reason | The reason the item could not be fulfilled |
urn | The uniform resource name for identifying this asset |
Shipium assumptions for the Fulfillment Engine API
- Orders
Order items that can be fulfilled from the same order will be grouped for maximum consolidation opportunity.
Order items will be split into shipment groups based on the information passed in the API call (e.g., hazmat).
Orders will be processed into proposed shipments based on the order in which they are listed in the API call. - Inventory
Order items will be consolidated into proposed shipments based on the inventory levels provided by your organization.
Example cURL call
curl --request POST
--url https://api.shipium.com/api/v1/fe/plans
--header 'accept: application/json'
--header $AUTHSTRING
--header 'content-type: application/json'
--data 'INSERT REQUEST BODY FROM BELOW'
Example request body
{
"asOfDateTime": "2024-01-16T18:22:12.454Z",
"fulfillmentCenters": [
{
"fulfillmentContextId": "76172e5c-e2c1-4652-b5f0-bd43e2d41ee0",
"fulfillmentCost": {
"currencyCode": "usd",
"perItem": 0,
"perPackage": 0
},
"packagingTypes": [
{
"linearDimensions": {
"height": 10,
"length": 13,
"linearUnit": "in",
"width": 12
},
"packagingTypeId": "a7c89cab-e9b8-42d9-8b27-3021133912d7",
"packagingMaterial": "box",
"weight": {
"weight": 50,
"weightUnit": "lb"
},
maxContentWeight: {
"weightUnit": "lb",
"weight": 50
},
}
],
"orders": [
{
"currencyCode": "USD",
"desiredDeliveryDate": "2024-01-16T18:22:12.454Z",
"destinationAddress": {
"addressType": "commercial",
"city": "Albuquerque",
"company": "ACME",
"countryCode": "US",
"name": "Wile E. Coyote",
"postalCode": "87121",
"region": "NM",
"street1": "123 Main St.",
"street2": "Suite 42"
},
"orderItemQuantities": [
{
"productId": "RN03947--Z43121",
"quantity": 0
}
],
"orderParams": {
"mustShipComplete": true
},
"orderedDateTime": "2019-10-28T14:34:55.123456Z",
"partnerOrderId": "myCustomPartnerOrderId123"
}
],
"packagingTypes": [
{
"linearDimensions": {
"height": 10,
"length": 13,
"linearUnit": "in",
"width": 12
},
"packagingId": "a7c89cab-e9b8-42d9-8b27-3021133912d7",
"packagingMaterial": "box",
"weight": {
"weight": 50,
"weightUnit": "lb"
}
}
],
"planDateTime": "2024-01-16T18:22:12.454Z",
"productDetails": [
{
"fulfillmentAttributes": [
"string"
],
"hazmat": true,
"hazmatInfo": {
"category": "defined",
"containerType": "aluminum_jerrican",
"hazardClass": "class_8_corrosive_material",
"hazmatId": "UN1755",
"packingGroup": "ii",
"packingInstructionCode": "967",
"properShippingName": "Chromic Acid Solution",
"quantity": 2.1,
"quantityType": "gross",
"quantityUnits": "l",
"subsidiaryClasses": [
8.1
],
"transportMode": "passenger_and_cargo_aircraft"
},
"inventoryStatuses": [
{
"fulfillmentContextId": "76172e5c-e2c1-4652-b5f0-bd43e2d41ee0",
"fulfillmentCostCurrencyCode": "usd",
"fulfillmentCostPerItem": 0,
"quantityAvailable": 0
}
],
"linearDimensions": {
"height": 10,
"length": 13,
"linearUnit": "in",
"width": 12
},
"productDetails": [
"string"
],
"productId": "string",
"weight": {
"weight": 50,
"weightUnit": "lb"
}
}
]
}
Example response
{
"active": true,
"archived": true,
"auditInfo": {
"createdBy": "string",
"creationTimeStamp": "2023-09-07T15:36:55.503Z",
"lastUpdatedBy": "string",
"lastUpdatedTimeStamp": "2023-09-07T15:36:55.503Z",
"version": 1
},
"description": "string",
"name": "string",
"partnerId": "string",
"partnerProvidedId": "string",
"planId": "string",
"proposedShipments": [
{
"cost": {
"carrier": "string",
"cost": 0,
"serviceMethod": "string"
},
"destinationAddress": {
"addressType": "commercial",
"city": "Albuquerque",
"company": "ACME",
"countryCode": "US",
"name": "Wile E. Coyote",
"postalCode": "87121",
"region": "NM",
"street1": "123 Main St.",
"street2": "Suite 42"
},
"fulfillmentContextId": "string",
"packagingType": {
"linearDimensions": {
"height": 10,
"length": 13,
"linearUnit": "in",
"width": 12
},
"packagingTypeId": "string",
"packagingMaterial": "box",
"weight": {
"weight": 50,
"weightUnit": "lb"
}
},
"shipiumProposedShipmentId": "string",
"shipmentId": "string",
"shipmentItems": [
{
"linearDimensions": {
"height": 10,
"length": 13,
"linearUnit": "in",
"width": 12
},
"partnerOrderId": "string",
"productId": "RN03947--Z43121",
"weight": {
"weight": 50,
"weightUnit": "lb"
}
}
],
"totalWeight": {
"weight": 50,
"weightUnit": "lb"
}
}
],
"resultingInventory": {
"additionalProp1": [
{
"fulfillmentCenterId": "string",
"fulfillmentCostCurrencyCode": "usd",
"fulfillmentCostPerItem": 0,
"quantityAvailable": 0
}
],
"additionalProp2": [
{
"fulfillmentCenterId": "string",
"fulfillmentCostCurrencyCode": "usd",
"fulfillmentCostPerItem": 0,
"quantityAvailable": 0
}
],
"additionalProp3": [
{
"fulfillmentCenterId": "string",
"fulfillmentCostCurrencyCode": "usd",
"fulfillmentCostPerItem": 0,
"quantityAvailable": 0
}
]
},
"tenantId": "string",
"unfulfillableItems": [
{
"countUnfulfilled": 0,
"orderItem": {
"productId": "RN03947--Z43121",
"quantity": 0
},
"partnerOrderId": "string",
"reason": "string"
}
],
"urn": "urn:fe:global-config:FE91F3A8-6838-469A-B9F8-2D82127573DC:1"
}
Resources
Your Shipium team member is available to help along the way. However, you might find these resources helpful:
Updated about 1 month ago