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.

🔐

Authenticating for Curl

Open Recipe

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` - `mailing_tube` - `parcel_pallet` - `unknown`	The shipment packaging material
`fulfillmentCenters .packagingTypes .packagingSizeName`	Optional	String Ex.: `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 enumeration 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	Boolean `true` 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` - `mailing_tube` - `parcel_pallet` - `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 enumeration 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 Ex.: `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	Boolean `true` 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 Values are: - `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 enumeration Values are: - `in` (inch) - `cm` (centimeter)	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, mailing tube, parcel pallet, 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:

Get started

Create a fulfillment plan with the Fulfillment Engine API

📘Authentication for API Calls

Shipium assumptions for the Fulfillment Engine API

Example cURL call

Example request body

Example response

Resources

📘
Authentication for API Calls