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 typeAPI endpoint
POSThttps://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 fieldRequired/OptionalField propertiesDescription
asOfDateTimeOptionalStringA 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 .fulfillmentContextIdRequiredStringA unique identifier for the fulfillment context. This ID must correspond to a Shipium-registered fulfillment context for your organization.
fulfillmentCenters .fulfillmentCost .currencyCodeOptionalStringThe currency code of the fulfillment costs
fulfillmentCenters .fulfillmentCost .perItemOptionalNumber ($float)Additional processing cost added per item in a shipment
fulfillmentCenters .fulfillmentCost .perPackageOptionalNumber ($float)Additional processing cost added per package in a shipment
fulfillmentCenters .packagingTypes .linearDimensions .heightRequiredDecimal
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 .lengthRequiredDecimal
Limited to a value greater than zero
Length of the longest side of the box to be packed
fulfillmentCenters .packagingTypes .linearDimensions .linearUnitRequiredString enumeration
Values are:

- in (inch)
- cm (centimeter)
The unit of measurement the linear dimensions of the box are specified in
fulfillmentCenters .packagingTypes .linearDimensions .widthRequiredDecimal
Limited to a value greater than zero
Length of the second longest side of the box to be packed
fulfillmentCenters .packagingTypes .packagingTypeIdOptional, but required if including packaging type values configured in the Shipium platformStringPacking type identifier
fulfillmentCenters .packagingTypes .packagingMaterialOptional, but required if no packagingTypeId is providedString enumeration
Values are:

- box
- envelope
- flat_pack
- unknown
The shipment packaging material
fulfillmentCenters .packagingTypes .packagingSizeNameOptionalString
Example: 1x1x4 Box
A name your organization wishes to provide for the packaging size
fulfillmentCenters .packagingTypes .weight.weightOptional, but required if no packagingTypeId is providedDecimal
Limited to a number greater than zero
The weight of the empty packaging
fulfillmentCenters .packagingTypes .weight.weightUnitOptional, but required if no packagingTypeId is providedString
Values are:
-g (gram)

- k (kilogram)
- oz (ounce)
- lb (pound)
The unit of measurement in which the empty packaging is specified
orders.currencyCodeOptionalString
Limited to 3 characters and ISO 4217 standards
Currency code of the orders (e.g., USD = U.S. dollars)
orders .destinationAddress .addressTypeRequiredString enumeration
Values are:

- Commercial
- Residential
The type of location for this address
orders .destinationAddress .cityOptionalString
Limited to alphabetical characters
The name of the city for the address
orders .destinationAddress .companyOptionalString
Limited to alphanumeric characters
The company name for the address
orders .destinationAddress .countryCodeRequiredString
Limited to 2 characters and ISO 3166 standards
The country code for the address
orders .destinationAddress .nameOptionalStringThe name associated with the address
orders .destinationAddress .postalCodeRequiredString
Limited to a country-appropriate postal code
The postal code for the address
orders .destinationAddress .regionOptionalStringThe name of the state or region for the address (e.g., NM)
orders .destinationAddress .street1OptionalStringThe first line of the address
orders .destinationAddress .street2OptionalStringThe second line of the address
orders .orderItemQuantities .productIdRequiredStringA unique product identifier (e.g., RN03947-Z43121)
orders .orderItemQuantities .quantityRequiredInteger
Limited to a number greater than zero
The number of units of this product
orders .orderParams .mustShipCompleteOptionalBoolean
True or False
True if all order items must be planned for shipment. The default value is false.
orders .orderParams .orderedDateTimeOptionalString
Limited to the ISO-8601 standard
The timestamp for when the customer ordered the product
orders .orderParams .partnerOrderIdRequiredStringThe identification your organization provided for this order
packagingTypes .linearDimensions .heightOptional, but required if no packagingTypeId is providedDecimal
Limited to a value greater than zero
The numerical value of the shortest side of the package
packagingTypes .linearDimensions .lengthOptional, but required if no packagingTypeId is providedDecimal
Limited to a value greater than zero
The numerical value of the longest side of the package
packagingTypes .linearDimensions .linearUnitOptional, but required if no packagingTypeId is providedString enumeration
Values are:

- in (inch)
- cm (centimeter)
The unit of measurement in which the linear dimensions of the package are specified
packagingTypes .linearDimensions .widthOptional, but required if no packagingTypeId is providedDecimal
Limited to a value greater than zero
The numerical value of the second longest side of the package
packagingTypes .packagingTypeIdRequiredStringPacking type identifier
packagingTypes .packagingMaterialRequiredString enumeration
Values are:

- box
- envelope
- flat_pack
- unknown
The shipment packaging material
packagingTypes .weight.weightRequiredDecimal
Limited to a number greater than zero
The weight of the packaging
packagingTypes .weight.weightUnitRequiredString enumeration
Values are:

- g (gram)
- kg (kilogram)
- oz (ounce)
- lb (pound)
The unit of measurement in which the packaging is specified
packagingTypes .maxContentWeight .weightUnitOptional, but required if Packaging Planner values are included but no packagingTypeId is providedString
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 .weightOptional, but required if Packaging Planner values are included but no packagingTypeId is providedDecimal
Limited to a number greater than zero
The maximum weight of contents that the packaging type can support
packagingTypes .packagingSizeNameOptionalString
Example: 1x1x4 Box
A name your organization wishes to provide for the packaging size
planDateTimeOptionalStringA 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 AttributesOptionalStringA list of attributes that may affect the shipping of the product
productDetails .hazmatOptionalBoolean
True or False
If true, indicates that the item is hazmat. The default value is false.
productDetails .hazmatInfo.categoryOptional, but required if the hazmat field is TRUEString 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 .containerTypeOptional, but required if the hazmat field is TRUEString 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 .hazardClassOptional, but required if the category field is definedString 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 .hazmatIdOptional, but required if the category field is defined-StringThe International Air Transport Association (IATA) or U.S. Department of Transportation (DOT) regulatory identifier for the commodity as appropriate
productDetails .hazmatInfo .packingGroupOptionalString enumeration
Values are:

- i
- ii
- iii
The degree of danger the material presents
productDetails .hazmatInfo .packingInstruction CodeOptionalStringThe packing instruction code used for air transport
productDetails .hazmatInfo .properShippingNameOptional, but required if the category field is definedStringThe proper shipping name that is associated with the specified hazmatId
productDetails .hazmatInfo .quantityRequiredNumberThe amount of quantity type material in quantity units
productDetails .hazmatInfo .quantityTypeRequiredString enumeration
Values are:

- Gross
- Net
Determines whether the quantity includes the raw material (net) or also includes the material housing (gross)
productDetails .hazmatInfo .quantityUnitsRequiredString 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 .subsidiaryClassesOptionalStringThe appropriate IATA or DOT subsidiary classes associated with the material and the hazard class
productDetails .hazmatInfo .transportModeOptional, but required if the category field is definedString enumeration
Valuesare:

- cargo_aircraft_only
- ground
- passenger_and_cargo_aircraft
The packing instruction code used for air transport
productDetails .inventoryStatuses .fulfillmentContextIdRequiredStringA unique identifier for the fulfillment context. This ID must correspond to a Shipium-registered fulfillment context for your organization.
productDetails .inventoryStatuses .fulfillmentCost CurrencyCodeOptionalString
Limited to 3 characters and ISO 4217 standards
Currency code of the fulfillment cost (e.g., USD = U.S. dollars)
productDetails .inventoryStatuses .fulfillmentCost PerItemOptionalNumberThe price of fulfilling one item from the fulfillment center
productDetails .inventoryStatuses .quantityAvailableRequiredIntegerThe quantity of the item available at the fulfillment center
productDetails .linearDimensions .heightRequiredDecimal
Limited to a value greater than zero
The numerical value of the shortest side of the product
productDetails .linearDimensions .lengthRequiredDecimal
Limited to a value greater than zero
The numerical value of the longest side of the product
productDetails .linearDimensions .linearUnitRequiredString
Limited to inch (in) or centimeter (cm)
The unit of measurement in which the linear dimensions of the product are specified
productDetails .linearDimensions .widthRequiredDecimal
Limited to a value greater than zero
The numerical value of the second longest side of the product
productDetails .productIdRequiredStringThe product stock-keeping unit (SKU)
productDetails .weight.weightOptional, but required if including productDetails.weightDecimal
Limited to a number greater than zero
The weight of the product
productDetails .weight.weightUnitOptional, but required if including productDetails.weightString 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:

  1. 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.
  2. unfulfillableItems contains order items that could not be fulfilled, usually due to insufficient inventory available across all FCs.
  3. 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 attributeDescription
activeIndicates whether this asset is active (a value of TRUE) or inactive (FALSE)
archivedIndicates whether this asset is archived (a value of TRUE) or inactive (FALSE)
auditInfo.createdByThe username of the last person (or system) who created the entity
auditInfo.creationTimeStampISO-8601 formatted date in UTC when the entity was initially created
auditInfo.lastUpdatedByThe username of the last person (or system) to update the entity
auditInfo.lastUpdatedTimeStampISO-8601 formatted date in UTC when the entity was last updated
auditInfo.versionA number corresponding to each version change
descriptionExplanatory information about this asset
nameA human-readable name for this asset
partnerIdThe unique identification (ID) for your organization
partnerProvidedIdThe unique ID provided by your organization for this asset
planIdThe unique ID for the Fulfillment Engine plan generated by Shipium
proposedShipments.cost.carrierThe proposed carrier to ship the package out of the fulfillment center
proposedShipments.cost.costThe estimated cost to ship the package out of the fulfillment center
proposedShipments.cost .serviceMethodThe proposed carrier service method to ship the package out of the fulfillment center
proposedShipments .destinationAddress.addressTypeThe type of location for this address (i.e., commercial or residential)
proposedShipments .destinationAddress.cityThe name of the city for the address
proposedShipments .destinationAddress.companyThe company name for the address
proposedShipments .destinationAddress.countryCodeThe ISO-3166 country code for the address
proposedShipments .destinationAddress.nameThe name associated with the address
proposedShipments .destinationAddress.postalCodeThe postal code for the address
proposedShipments .destinationAddress.regionThe name of the state or region for the address
proposedShipments .destinationAddress.street1The first line of the address
proposedShipments .destinationAddress.street2The second line of the address
proposedShipments .fulfillmentContextIdThe unique ID of the fulfillment context
proposedShipments .packagingType.linearDimensions.heightThe numerical value of the shortest side of the packaging
proposedShipments .packagingType.linearDimensions.lengthThe numerical value of the longest side of the packaging
proposedShipments .packagingType.linearDimensions.linearUnitThe unit of measurement in which the linear dimensions of the packaging are specified
proposedShipments .packagingType.linearDimensions.widthThe
numerical value of the second
longest side of the
packaging
proposedShipments .packagingType.packagingTypeIdPackaging type identifier
proposedShipments .packagingType.packagingMaterialThe shipment packaging material (box, envelope, flat pack, or unknown)
proposedShipments .packagingType.packagingSizeNameThe name your organization provided for the packaging size
proposedShipments .packagingType.weight.weightThe weight of the packaging
proposedShipments .packagingType.weight.weightUnitThe unit of measurement the packaging is specified in
proposedShipments .shipiumProposedShipmentIdA proposed unique ID to use for the shipment
proposedShipments .shipmentItems.linearDimensions.heightThe numerical value of the shortest side of the
items to be shipped
proposedShipments .shipmentItems.linearDimensions.lengthThe numerical value of the longest side of the items to be shipped
proposedShipments .shipmentItems.linearDimensions.linearUnitThe unit of measurement
the linear dimensions of the items to be shipped are specified in
proposedShipments .shipmentItems.linearDimensions.widthThe
numerical value of the second
longest side of the items to be shipped
proposedShipments .shipmentItems.partnerOrderIdThe ID your organization provided for this order
proposedShipments .shipmentItems.productIdA unique product identifier (e.g., RN03947-Z43121)
proposedShipments .shipmentItems.weight.weightThe weight of the items to be shipped
proposedShipments .shipmentItems.weight.weightUnitThe unit of measurement the items to be shipped are specified in
proposedShipments .totalWeight.weightThe total weight of the proposed shipment
proposedShipments .totalWeight.weightUnitThe unit of measurement the total proposed shipment is specified in
unfulfillableItems.countUnfulfilledThe number of unfulfillable items for the order
unfulfillableItems.orderItem.productIdA unique product identifier (e.g., RN03947-Z43121) for the unfulfillable item
unfulfillableItems.orderItem.quantityThe number of units of the product
unfulfillableItems.partnerOrderIdA unique order identifier for the unfulfillable items provided by your organization
unfulfillableItems.reasonThe reason the item could not be fulfilled
urnThe 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:


What’s Next