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.

You'll need to provide information for the following four top-level entities for this API:

Fulfillment centers. Data at the fulfillment center, or origin, level includes addresses and other standard details; processing times at each fulfillment center; carriers, service methods, and related costs for each fulfillment center; and Fulfillment Engine-specific configuration information, such as whether split shipments should be allowed and what types of splits will be considered (e.g., hazmat, no inventory available for all order items).
Orders. This entity is a list of orders to plan. Data for orders includes the date and time of the order, the destination address, and item quantities for the order.
Packaging types. Data at the packaging type level is used as a default across fulfillment centers when no packaging information is available when calling Fulfillment Engine for a plan. If provided, this data will override all preconfigured packaging types for the planning activity.
Product details. Inventory data includes product availability and cost, dimensions and weight, and special attributes or designations (e.g., hazardous material).

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
`partnerPlanId`	Optional	String Ex.: `myPartnerPlanId123`	An optional ID that allows you to set your own ID for looking up the plan after creation
`fulfillmentCenters .fulfillment ContextId`	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`			Data for packaging types at the fulfillment center level allows for overriding packaging types for a specific fulfillment center. This is more specific than packagingTypes at the primary entity level and will override those values when processing for a specific fulfillment center.
`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`	Conditional (optional, but required if including packaging type values configured in the Shipium platform)	String	Packing type identifier; you also can include your own unique `partnerProvidedId` for this value. If you include both linear dimensions and the `packagingTypeId`, the `packagingTypeId` takes precedence.
`fulfillmentCenters .packagingTypes .packagingMaterial`	Conditional (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`	Conditional (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`	Conditional (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
`fulfillmentCenters .packagingTypes .maxContentWeight .weight`	Optional	Decimal Limited to a number greater than zero	This is the default product weight that will be used when no specific weight information is provided for a product in a Fulfillment Engine plan.
`fulfillmentCenters .packagingTypes .maxContentWeight .weightUnit`	Optional	String enumeration Values are: -`g` (gram) `k` (kilogram) `oz` (ounce) `lb` (pound)	The unit of measurement in which the maximum content weight is specified
`fulfillmentCenters .processingTime`	Optional	An array of processing time values	The amount of time it takes for the fulfillment center to process a shipment; the expected format is based on the ISO-8601 duration format: `PnDTnHnMn.nS`.
`fulfillmentCenters .rules .splitSettings .allowSplits`	Optional	Boolean `true` or `false`	When set to `true`, this fulfillment center will support splitting shipments based on types defined in the `splitTypes` field.
`fulfillmentCenters .rules .splitSettings .maxItemsPer Package`	Conditional (optional, but required when `unit_count` is included as a split type)	Integer	The maximum number of items allowed per package when planning runs generate shipments from order items; this value is used when `unit_count` is an entry in the `splitTypes` field list.
`fulfillmentCenters .rules .splitSettings .maxPackagesPer Order`	Conditional (optional, but required when `max_shipments` is included as a split type)	Integer	The maximum number of packages allowed per order for planning runs; this value is used when the `max_shipments` is an entry in the `splitTypes` field list.
`fulfillmentCenters .rules .splitSettings .splitTypes`	Optional	String enumeration Values are: `fc_split` `hazmat` `inventory` `max_shipments` `package_planner` `sioc` `unit_count` `unknown`	A list of split types supported by the fulfillment center. When the value is `unit_count`, the `maxItemsPerPackage` field also must be populated; when the value is `max_shipments`, the `maxPackagesPerOrder` field must also be populated.
`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 .orderedDateTime`	Optional	String Limited to the ISO-8601 standard	The timestamp for when the customer ordered the product
`orders .partnerOrderId`	Required	String	The identification your organization provided for this order
`orders .desiredDeliveryDate`	Optional	String Ex.: `2019-10-31T20:00:00Z`	The string representation of either an ISO-8601 date or a local date for desired delivery: yyyy-mm-dd. The date or date-time the package is intended to arrive to the customer. This is used to determine the most appropriate service method when generating a label.
`orders .desiredDelivery DateOptions .exactDateDelivery`	Optional	Boolean `true` or `false`	If `true`, this instructs the carrier to deliver the package on the date provided in the `desiredDeliveryDate` field. Desired, Exact, & Guaranteed Delivery Dates provides details on exact date delivery.
`orders .desiredDelivery DateOptions .guaranteedDate Delivery`	Optional	Boolean `true` or `false`	If `true`, this indicates that your organization is willing to accept any applicable carrier date certain surcharge to the estimated label cost. Not all carriers support guaranteed date delivery. This restricts carrier selection to service methods that can support guaranteed date delivery.
`orders .desiredDelivery DateOptions .upgradeCostDeltaMax`	Optional	String	If set, this is the maximum amount of additional spend that your organization is willing to pay to upgrade a shipment to the desired delivery date (DDD) if the lowest cost carrier service method is unable to safely meet the DDD.
`orders .desiredDelivery DateOptions .currencyCode`	Optional	String	The ISO-4217 currency code of the `upgradeCostDeltaMax`
`orders .businessDays OfTransit`	Optional	Integer ($int32) Ex.: 3	Indicates the number of business days from the ship time by when the shipment needs to be delivered
`orders.shipOption`	Optional	String Ex.: `standard`	A high-level shipping option shown to or selected by a customer
`orders .shippedDateTime`	Optional	String ($date-time)	The timestamp for when you (or your fulfillment partner) shipped the product from your (or their) warehouse; the timestamp must be a valid ISO 8601 timestamp. If not provided, this value defaults to `orderedDateTime`.
`orders .packagingType`			Data for packaging at the orders level allows for defining the packaging type to use for a specific order.
`orders .packagingType .packagingTypeId`	Conditional (optional, but required if including packaging type values configured in the Shipium platform)	String	Packing type identifier
`orders .packagingType .packagingMaterial`	Conditional (optional, but required if no `packagingTypeId` is provided)	String enumeration Values are: box envelope flat_pack unknown	The shipment packaging material
`orders .packagingType .linearDimensions .linearUnit`	Required	String enumeration Values are: in (inch) cm (centimeter)	The unit of measurement the linear dimensions of the box are specified in
`orders .packagingType .linearDimensions .length`	Required	Decimal Limited to a value greater than zero	Length of the longest side of the box to be packed
`orders .packagingType .linearDimensions .width`	Required	Decimal Limited to a value greater than zero	Length of the second longest side of the box to be packed
`orders .packagingType .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.
`orders .packagingType .weight.weightUnit`	Conditional (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 .packagingType .weight.weight`	Conditional (optional, but required if no `packagingTypeId` is provided)	Decimal Limited to a value greater than zero	The weight of the empty packaging
`orders .packagingType .maxContentWeight .weightUnit`	Conditional (optional, but required if Packaging Planner values are included but no `packagingTypeId` is provided)	String Values are: -g (gram) k (kilogram) oz (ounce) lb (pound)	The unit of measurement of the maximum weight of the contents that the packaging type can support
`orders .packagingType .maxContentWeight .weight`	Conditional (optional, but required if Packaging Planner values are included but no `packagingTypeId` is provided)	Decimal Limited to a value greater than zero	The maximum weight of contents that the packaging type can support
`orders .packagingType.urn`	Optional	String	The uniform resource name for identifying the packaging type
`orders .packagingType .packagingSizeName`	Optional	String Example: 1x1x4 Box	A name your organization wishes to provide for the packaging size
`packagingTypes`			Data for packaging types at this primary level allows for specifying the packaging types to use for the request across fulfillment centers.
`packagingTypes .linearDimensions .height`	Conditional (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`	Conditional (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`	Conditional (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`	Conditional (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`	Conditional (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`	Conditional (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`	Required	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`	Conditional (optional, but required if the `hazmat` field is TRUE)	String enumeration Values are: `aerosols_flammable` `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`	Conditional (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`	Conditional (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`	Conditional (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 .properShipping Name`	Conditional (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`	Conditional (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 .fulfillment CenterId`	Optional	String	The unique identifier for the fulfillment center that corresponds to a fulfillment center configured in the Shipium platform
`productDetails .inventoryStatuses .fulfillment ContextId`	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; this value should be zero (0) for a fulfillment center that has no inventory to fill the request.
`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 .productDetails`	Required	String Ex.: -`limited_quantity` (or `lq`) `ormd` (or `orm-d`) `perishable` `bound_printed_matter` (or `bpm`)	A list of product details that may affect shipping of the product
`productDetails .productId`	Required	String	The product stock-keeping unit (SKU)
`productDetails .weight.weight`	Conditional (optional, but required if including `productDetails.weight`)	Decimal Limited to a number greater than zero	The weight of the product
`productDetails .weight.weightUnit`	Conditional (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
`name`	Optional	String Ex.: `myFulfillmentEnginePlan`	An optional human-readable name your organization has assigned to the plan
`description`	Optional	String	An optional description you can use to provide additional information for the plan

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
`partnerId`	The unique identification (ID) for your organization
`tenantId`	The unique ID assigned to the tenant by Shipium, if applicable
`planId`	The unique ID for the Fulfillment Engine plan generated by Shipium
`partnerPlanId`	An optional ID that is returned if you set your own ID for looking up plans in the call request
`proposedShipments.cost.carrier`	The proposed carrier 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.cost.cost`	The estimated cost to ship the package out of the fulfillment center
`proposedShipments.cost.performance .effectiveShipDateTime`	Calculation for the effective ship date time that a shipment will ship out
`proposedShipments.cost.performance .estimatedDeliveryDate`	The date and time by when the package is estimated to be delivered to the customer
`proposedShipments.cost.performance .estimatedDeliveryDateLocal`	The local date-time of the destination of the shipment
`proposedShipments.cost.performance .destinationTimezoneId`	The zone ID used for the destination of the shipment
`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 .length`	The numerical value of the longest side of the packaging
`proposedShipments .packagingType.linearDimensions .height`	The numerical value of the shortest side of the packaging
`proposedShipments .packagingType.linearDimensions .linearUnit`	The unit of measurement in which the linear dimensions of the packaging are specified (`in` or `cm`)
`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 .proposedShipmentId`	A unique ID of the shipment
`proposedShipments .shipmentItems.linearDimensions .length`	The numerical value of the longest side of the items to be shipped
`proposedShipments .shipmentItems.linearDimensions .height`	The numerical value of the shortest 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.linearDim .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

{
  "partnerPlanId": "myPartnerPlanId123",
  "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",
          "packagingSizeName": "large box",
          "weight": {
             "weight": 50,
             "weightUnit": "lb"
            },
          "maxContentWeight": {
             "weightUnit": "lb",
             "weight": 50
            }
          }
       ],
      "processingTime": "PnDTnHnMn.nS",
      "rules": {
        "splitSettings": {
          "allowSplits": true,
          "maxItemsPerPackage": 0,
          "maxPackagesPerOrder": 0,
          "splitTypes": [
            "hazmat"
          ]
        }
      }
    }
  ],
  "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",
      "packagingType": {
          "linearDimensions": {
            "height": 10,
            "length": 13,
            "linearUnit": "in",
            "width": 12
          },
          "packagingTypeId": "a7c89cab-e9b8-42d9-8b27-3021133912d7",
          "packagingMaterial": "box",
          "packagingSizeName": "large box",
          "weight": {
            "weight": 50,
            "weightUnit": "lb"
          },
		      "maxContentWeight": {
		        "weight": 100,
		       	"weightUnit": "lb"
          }
      }
    }
  ],
  "packagingTypes": [
    {
      "linearDimensions": {
        "height": 10,
        "length": 13,
        "linearUnit": "in",
        "width": 12
      },
      "packagingTypeId": "a7c89cab-e9b8-42d9-8b27-3021133912d7",
      "packagingMaterial": "box",
      "packagingSizeName": "large box",
      "weight": {
        "weight": 50,
        "weightUnit": "lb"
      },
	    "maxContentWeight": {
	      "weight": 100,
		    "weightUnit": "lb"
      }
    }
  ],
  "planDateTime": "2024-01-16T18:22:12.454Z",
  "productDetails": [
    {
      "fulfillmentAttributes": [
        "Extra_Padding_Required"
      ],
      "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": [
        "special_handling"
      ],
      "productId": "RN03947--Z43121",
      "weight": {
        "weight": 50,
        "weightUnit": "lb"
      }
    }
  ]
}

Example response

{
  "active": true,
  "archived": true,
  "auditInfo": {
    "createdBy": "user_name",
    "creationTimeStamp": "2023-09-07T15:36:55.503Z",
    "lastUpdatedBy": "user_name",
    "lastUpdatedTimeStamp": "2023-09-07T15:36:55.503Z",
    "version": 1
  },
  "description": "fulfillment",
  "name": "my_fe_plan",
  "partnerId": "096b869c-769b-40dd-b337-eb5120e08f99",
  "tenantId": "04a23f17-8773-459c-a26a-1d5a539bcf04",
  "planId": "3fadf9cd-0c57-47b6-95dd-94629c6f7312",
  "partnerPlanId": "myPartnerPlanId123",
  "proposedShipments": [
    {
      "cost": {
        "carrier": "ups",
        "cost": 0,
        "serviceMethod": "ups-ground-service-method"
      },
      "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": "76172e5c-e2c1-4652-b5f0-bd43e2d41ee0",
      "packagingType": {
        "linearDimensions": {
          "height": 10,
          "length": 13,
          "linearUnit": "in",
          "width": 12
        },
        "packagingTypeId": "a7c89cab-e9b8-42d9-8b27-3021133912d7",
        "packagingMaterial": "box",
        "packagingSizeName": "large box",
        "weight": {
          "weight": 50,
          "weightUnit": "lb"
        },
        "maxContentWeight": {
          "weight": 100,
          "weightUnit": "lb"
        }
      },
      "proposedShipmentId": "db862e2f-d38f-4dc8-9e07-3500e1b11337",
      "shipmentItems": [
        {
          "linearDimensions": {
            "height": 10,
            "length": 13,
            "linearUnit": "in",
            "width": 12
          },
          "partnerOrderId": "myCustomPartnerOrderId123",
          "productId": "RN03947--Z43121",
          "weight": {
            "weight": 50,
            "weightUnit": "lb"
          }
        }
      ],
      "totalWeight": {
        "weight": 50,
        "weightUnit": "lb"
      }
    }
  ],
  "resultingInventory": {
    "additionalProp1": [
      {
        "fulfillmentContextId": "76172e5c-e2c1-4652-b5f0-bd43e2d41ee0",
        "fulfillmentCostCurrencyCode": "usd",
        "fulfillmentCostPerItem": 0,
        "quantityAvailable": 0
      }
    ],
    "additionalProp2": [
      {
        "fulfillmentContextId": "76172e5c-e2c1-4652-b5f0-bd43e2d41ee0",
        "fulfillmentCostCurrencyCode": "usd",
        "fulfillmentCostPerItem": 0,
        "quantityAvailable": 0
      }
    ],
    "additionalProp3": [
      {
        "fulfillmentContextId": "76172e5c-e2c1-4652-b5f0-bd43e2d41ee0",
        "fulfillmentCostCurrencyCode": "usd",
        "fulfillmentCostPerItem": 0,
        "quantityAvailable": 0
      }
    ]
  },
  "unfulfillableItems": [
    {
      "countUnfulfilled": 0,
      "orderItem": {
        "productId": "RN03947--Z43121",
        "quantity": 0
      },
      "partnerOrderId": "myCustomPartnerOrderId123",
      "reason": "Product requires special handling not available at any fulfillment center"
    }
  ],
  "urn": "urn:fe:global-config:FE91F3A8-6838-469A-B9F8-2D82127573DC:1"
}

Example request body with inclusion of desired delivery date

{
  "orders": [
    {
      "currencyCode": "usd",
      "desiredDeliveryDate": "2025-02-25",
      "desiredDeliveryDateOptions": {
        "exactDeliveryDate": true
      },
      "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": "PRD-12345",
          "quantity": 1
        }
      ],
      "orderedDateTime": "2024-10-28T14:34:55.123456Z",
      "partnerOrderId": "ORD-12345"
    }
  ],
  "productDetails": [
    {
      "inventoryStatuses": [
        {
          "fulfillmentContextId": "45f9a048-771c-4d85-8421-80d94abc1194",
          "fulfillmentCostCurrencyCode": "usd",
          "fulfillmentCostPerItem": 0,
          "quantityAvailable": 2
        }
      ],
      "linearDimensions": {
        "height": 10,
        "length": 13,
        "linearUnit": "in",
        "width": 12
      },
      "productId": "PRD-12345",
      "weight": {
        "weight": 1,
        "weightUnit": "lb"
      }
    }
  ]
}

Example response with desired delivery date

{
    "active": true,
    "archived": false,
    "auditInfo": {
        "createdBy": "fulfillment-engine-integration-tests-internal",
        "creationTimeStamp": "2025-02-20T18:42:35.347Z",
        "lastUpdatedBy": "fulfillment-engine-integration-tests-internal",
        "lastUpdatedTimeStamp": "2025-02-20T18:42:35.347Z",
        "version": 1
    },
    "description": null,
    "name": null,
    "partnerId": "8e75cc7f-05bb-4520-9233-9768201f033b",
    "partnerPlanId": null,
    "planId": "1b185e91-1fb9-44eb-b483-93c1832a07b5",
    "proposedShipments": [
        {
            "cost": {
                "carrier": "ups",
                "cost": 51.7,
                "performance": {
                    "destinationTimezoneId": "America/Denver",
                    "effectiveShipDateTime": "2025-02-20T18:42:35.425Z",
                    "estimatedDeliveryDate": "2025-02-26T03:00:00Z",
                    "estimatedDeliveryDateLocal": "2025-02-25T20:00:00"
                },
                "serviceMethod": "ups-ground-service-method"
            },
            "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": "45f9a048-771c-4d85-8421-80d94abc1194",
            "packagingType": {
                "linearDimensions": {
                    "height": 23,
                    "length": 23,
                    "linearUnit": "in",
                    "width": 23
                },
                "maxContentWeight": {
                    "weight": 50,
                    "weightUnit": "lb"
                },
                "packagingMaterial": "box",
                "packagingSizeName": "FC default box",
                "packagingTypeId": null,
                "weight": {
                    "weight": 1,
                    "weightUnit": "lb"
                }
            },
            "proposedShipmentId": "a5da5b41-2b88-4d8f-a58c-7c3780728540",
            "shipmentItems": [
                {
                    "linearDimensions": null,
                    "partnerOrderId": "ORD-12345",
                    "productId": "PRD-12345",
                    "weight": null
                }
            ],
            "totalWeight": {
                "weight": 2,
                "weightUnit": "lb"
            }
        }
    ],
    "resultingInventory": {
        "PRD-12345": [
            {
                "fulfillmentContextId": "45f9a048-771c-4d85-8421-80d94abc1194",
                "fulfillmentCostCurrencyCode": "usd",
                "fulfillmentCostPerItem": 0,
                "quantityAvailable": 1
            }
        ]
    },
    "tenantId": null,
    "unfulfillableItems": [],
    "urn": "urn:fe:plan:1b185e91-1fb9-44eb-b483-93c1832a07b5:1"
}

Example request for package and product handling cost overrides

{
  "orders": [
    {
      "currencyCode": "usd",
      "desiredDeliveryDate": "2023-08-20T15:51:30.982Z",
      "destinationAddress": {
        "addressType": "residential",
        "city": "Albuquerque",
        "company": "ACME",
        "countryCode": "US",
        "name": "Wile E. Coyote",
        "postalCode": "87121",
        "region": "NM",
        "street1": "123 Main St.",
        "street2": "Suite 42"
      },
      "orderItemQuantities": [
        {
          "productId": "SKU1",
          "quantity": 1
        }
      ],
      "orderedDateTime": "2019-10-28T14:34:55.123456Z",
      "partnerOrderId": "MyOrder1"
    }
  ],
  "productDetails": [
    {
      "inventoryStatuses": [
        {
          "fulfillmentContextId": "4b2ac183-a657-4477-bfe6-d2b6c74bc7b5",
          "fulfillmentCenterName": "NY",
          "fulfillmentCostCurrencyCode": "usd",
          "fulfillmentCostPerItem": null,
          "quantityAvailable": 10
        }
      ],
      "linearDimensions": {
        "height": 10,
        "length": 13,
        "linearUnit": "in",
        "width": 12
      },
      "productId": "SKU1",
      "weight": {
        "weight": 1,
        "weightUnit": "lb"
      }
    }
  ],
  "fulfillmentCenters": [
    {
      "fulfillmentContextId": "4b2ac183-a657-4477-bfe6-d2b6c74bc7b5",
      "fulfillmentCost": {
        "currencyCode": "usd",
        "perItem": 1.0,
        "perPackage": 4.0     // <<-- This is where the fulfillment center package handling cost is set
      }
    }
  ]
}

Example response with package and product handling cost overrides


{
    "partnerId": "76abb3d4-8990-4f80-aa13-4c2007cb852a",
    "tenantId": "this-needs-to-come-from-the-tenant-header...",
    "urn": "urn:fe:plan:a477a6fb-e078-4e1a-8054-7025a5e80a57:1",
    "name": "set-name-with-something...",
    "description": "set-description-with-something...",
    "active": true,
    "archived": false,
    "auditInfo": {
        "createdBy": "fulfillment-engine-integration-tests-internal",
        "creationTimeStamp": "2024-01-17T18:47:51.794Z",
        "lastUpdatedBy": "fulfillment-engine-integration-tests-internal",
        "lastUpdatedTimeStamp": "2024-01-17T18:47:51.794Z",
        "version": 1
    },
    "planId": "a477a6fb-e078-4e1a-8054-7025a5e80a57",
    "proposedShipments": [
        {
            "proposedShipmentId": "192b51f1-2a1d-4bd5-80c2-49f857cfdf98",
            "fulfillmentContextId": "4b2ac183-a657-4477-bfe6-d2b6c74bc7b5",
            "cost": {
                "carrier": "ups",
                "serviceMethod": "ups-ground-service-method",
                "cost": 9.0
            },
            "destinationAddress": {
                "name": "Wile E. Coyote",
                "company": "ACME",
                "street1": "123 Main St.",
                "street2": "Suite 42",
                "city": "Albuquerque",
                "region": "NM",
                "countryCode": "US",
                "postalCode": "87121",
                "addressType": "residential"
            },
            "packagingType": {
                "packagingTypeId": null,
                "packagingMaterial": "box",
                "linearDimensions": {
                    "linearUnit": "in",
                    "length": 12.0,
                    "width": 11.0,
                    "height": 10.0
                },
                "weight": {
                    "weightUnit": "lb",
                    "weight": 1.0
                }
            },
            "shipmentItems": [
                {
                    "productId": "SKU1",
                    "partnerOrderId": "MyOrder1",
                    "linearDimensions": null,
                    "weight": null
                }
            ],
            "totalWeight": {
                "weightUnit": "lb",
                "weight": 1.0
            }
        }
    ],
    "resultingInventory": {
        "SKU1": [
            {
                "fulfillmentContextId": "4b2ac183-a657-4477-bfe6-d2b6c74bc7b5",
                "quantityAvailable": 9,
                "fulfillmentCostCurrencyCode": "usd",
                "fulfillmentCostPerItem": null
            }
        ]
    },
    "unfulfillableItems": []
}

Examples for order splits

Fulfillment Engine splits order items into shipment groups based on information passed in the API. Splits can be based on the following:

setting at a fulfillment center level (fc_split)
item is hazmat (hazmat). The value for productDetails.hazmat in the API call must be true.
no inventory available to fulfill in single origin (inventory)
maximum packages per order (max_shipments). An integer value should be included for fulfillmentCenters.rules.maxPackagesPerOrder in the API call.
use of the Packaging Planner (package_planner)
item ships in its own container (sioc). The value for productDetails.productDetails in the API call must be sioc.
maximum number of items per package (unit_count)

For any type of split, the two fields in the following table must be included in your API call.

Request field	Required/Optional	Field properties	Description
`fulfillmentCenters.rules .splitSettings .allowSplits`	Required	Boolean `true` or `false`	When set to `true`, this fulfillment center will support splitting shipments based on types defined in the `splitTypes` field.
`fulfillmentCenters.rules .splitSettings .splitTypes`	Required	String enumeration Values are: `fc_split` `hazmat` `inventory` `max_shipments` `package_planner` `sioc` `unit_count` `unknown`	The types of splits supported by this fulfillment center; the types are described in more detail in the bulleted list above this table.

Request field

Required/Optional

Field properties

Description

fulfillmentCenters.rules
  .splitSettings
  .allowSplits

Required

Boolean
true or false

When set to true, this fulfillment center will support splitting shipments based on types defined in the splitTypes field.

fulfillmentCenters.rules
  .splitSettings
  .splitTypes

Required

String enumeration
Values are:

fc_split
hazmat
inventory
max_shipments
package_planner
sioc
unit_count
unknown

The types of splits supported by this fulfillment center; the types are described in more detail in the bulleted list above this table.

Example request body for fulfillment center split

In order to be a candidate for splitting across fulfillment centers, the fulfillment center must be marked as supporting fulfillment center splits. The value passed in the API call for fulfillmentCenters.rules.splitSettings.splitTypes must be fc_split.

{
  "description": "partner provided plan description",
  "fulfillmentCenters": [
    {
      "fulfillmentContextId": "4b2ac183-a657-4477-bfe6-d2b6c74bc7b5",
      "rules": {
        "splitSettings": {
          "allowSplits": true,
          "splitTypes": [
            "fc_split"
          ]
        }
      }
    },
    {
      "fulfillmentContextId": "d20cdd21-ec3b-4902-b64f-4877c6113c83",
      "rules": {
        "splitSettings": {
          "allowSplits": true,
          "splitTypes": [
            "fc_split"
          ]
        }
      }
    }
  ],
  "name": "partner provided plan name",
  "orders": [
    {
      "currencyCode": "USD",
      "desiredDeliveryDate": "2023-08-20T15:51:30.982Z",
      "destinationAddress": {
        "addressType": "residential",
        "city": "Albuquerque",
        "company": "ACME",
        "countryCode": "US",
        "name": "Wile E. Coyote",
        "postalCode": "87121",
        "region": "NM",
        "street1": "123 Main St.",
        "street2": "Suite 42"
      },
      "orderItemQuantities": [
        {
          "productId": "product1",
          "quantity": 1
        },
        {
          "productId": "product2",
          "quantity": 2
        }
      ],
      "orderedDateTime": "2019-10-28T14:34:55.123456Z",
      "packagingType": {
        "linearDimensions": {
          "height": 20,
          "length": 20,
          "linearUnit": "in",
          "width": 20
        },
        "maxContentWeight": {
          "weight": 50,
          "weightUnit": "lb"
        },
        "packagingMaterial": "box",
        "packagingSizeName": "Partner selected 9x8x7 box",
        "weight": {
          "weight": 1,
          "weightUnit": "lb"
        }
      },
      "partnerOrderId": "MyOrder1"
    }
  ],
  "partnerPlanId": "partner provided plan id",
  "productDetails": [
    {
      "inventoryStatuses": [
        {
          "fulfillmentContextId": "4b2ac183-a657-4477-bfe6-d2b6c74bc7b5",
          "quantityAvailable": 1
        },
        {
          "fulfillmentContextId": "d20cdd21-ec3b-4902-b64f-4877c6113c83",
          "quantityAvailable": 1
        }
      ],
      "linearDimensions": {
        "height": 6,
        "length": 7,
        "linearUnit": "in",
        "width": 8
      },
      "productId": "product1",
      "weight": {
        "weight": 1.2,
        "weightUnit": "lb"
      }
    },
    {
      "inventoryStatuses": [
        {
          "fulfillmentContextId": "4b2ac183-a657-4477-bfe6-d2b6c74bc7b5",
          "quantityAvailable": 1
        },
        {
          "fulfillmentContextId": "d20cdd21-ec3b-4902-b64f-4877c6113c83",
          "quantityAvailable": 1
        }
      ],
      "linearDimensions": {
        "height": 5,
        "length": 7,
        "linearUnit": "in",
        "width": 6
      },
      "productId": "product2",
      "weight": {
        "weight": 1.3,
        "weightUnit": "lb"
      }
    }
  ]
}

Example response for fulfillment center split

{
  "active": true,
  "archived": false,
  "description": "partner provided plan description",
  "name": "partner provided plan name",
  "partnerId": "76abb3d4-8990-4f80-aa13-4c2007cb852a",
  "partnerPlanId": "partner provided plan id",
  "planId": "a8e1e825-4ad3-4b95-971d-520e6c6b9fbb",
  "proposedShipments": [
    {
      "cost": {
        "carrier": "ups",
        "cost": 5.05,
        "serviceMethod": "ups-ground-service-method"
      },
      "destinationAddress": {
        "addressType": "residential",
        "city": "Albuquerque",
        "company": "ACME",
        "countryCode": "US",
        "name": "Wile E. Coyote",
        "postalCode": "87121",
        "region": "NM",
        "street1": "123 Main St.",
        "street2": "Suite 42"
      },
      "fulfillmentContextId": "4b2ac183-a657-4477-bfe6-d2b6c74bc7b5",
      "packagingType": {
        "linearDimensions": {
          "height": 20,
          "length": 20,
          "linearUnit": "in",
          "width": 20
        },
        "maxContentWeight": {
          "weight": 50,
          "weightUnit": "lb"
        },
        "packagingMaterial": "box",
        "packagingSizeName": "Partner selected 9x8x7 box",
        "packagingTypeId": null,
        "weight": {
          "weight": 1,
          "weightUnit": "lb"
        }
      },
      "proposedShipmentId": "41bda27c-a5b8-42cc-a739-795624703f83",
      "shipmentItems": [
        {
          "linearDimensions": null,
          "partnerOrderId": "MyOrder1",
          "productId": "product2",
          "weight": null
        },
        {
          "linearDimensions": null,
          "partnerOrderId": "MyOrder1",
          "productId": "product1",
          "weight": null
        }
      ],
      "totalWeight": {
        "weight": 3.5,
        "weightUnit": "lb"
      }
    },
    {
      "cost": {
        "carrier": "ups",
        "cost": 5.05,
        "serviceMethod": "ups-ground-service-method"
      },
      "destinationAddress": {
        "addressType": "residential",
        "city": "Albuquerque",
        "company": "ACME",
        "countryCode": "US",
        "name": "Wile E. Coyote",
        "postalCode": "87121",
        "region": "NM",
        "street1": "123 Main St.",
        "street2": "Suite 42"
      },
      "fulfillmentContextId": "d20cdd21-ec3b-4902-b64f-4877c6113c83",
      "packagingType": {
        "linearDimensions": {
          "height": 20,
          "length": 20,
          "linearUnit": "in",
          "width": 20
        },
        "maxContentWeight": {
          "weight": 50,
          "weightUnit": "lb"
        },
        "packagingMaterial": "box",
        "packagingSizeName": "Partner selected 9x8x7 box",
        "packagingTypeId": null,
        "weight": {
          "weight": 1,
          "weightUnit": "lb"
        }
      },
      "proposedShipmentId": "9947ac72-5f3a-477a-95ce-2e59466d8025",
      "shipmentItems": [
        {
          "linearDimensions": null,
          "partnerOrderId": "MyOrder1",
          "productId": "product2",
          "weight": null
        }
      ],
      "totalWeight": {
        "weight": 2.3,
        "weightUnit": "lb"
      }
    }
  ],
  "resultingInventory": {
    "product1": [
      {
        "fulfillmentContextId": "4b2ac183-a657-4477-bfe6-d2b6c74bc7b5",
        "fulfillmentCostCurrencyCode": null,
        "fulfillmentCostPerItem": null,
        "quantityAvailable": 0
      },
      {
        "fulfillmentContextId": "d20cdd21-ec3b-4902-b64f-4877c6113c83",
        "fulfillmentCostCurrencyCode": null,
        "fulfillmentCostPerItem": null,
        "quantityAvailable": 1
      }
    ],
    "product2": [
      {
        "fulfillmentContextId": "4b2ac183-a657-4477-bfe6-d2b6c74bc7b5",
        "fulfillmentCostCurrencyCode": null,
        "fulfillmentCostPerItem": null,
        "quantityAvailable": 0
      },
      {
        "fulfillmentContextId": "d20cdd21-ec3b-4902-b64f-4877c6113c83",
        "fulfillmentCostCurrencyCode": null,
        "fulfillmentCostPerItem": null,
        "quantityAvailable": 0
      }
    ]
  },
  "tenantId": null,
  "unfulfillableItems": [],
  "urn": "urn:fe:plan:a8e1e825-4ad3-4b95-971d-520e6c6b9fbb:1"
}

Example request body for Packaging Planner split

This use case is if you are also using Shipium’s Packaging Planner service. The value passed in the API call for fulfillmentCenters.rules.splitSettings.splitTypes must be package_planner.

{
  "description": "partner provided plan description",
  "fulfillmentCenters": [
    {
      "fulfillmentContextId": "4b2ac183-a657-4477-bfe6-d2b6c74bc7b5",
      "rules": {
        "splitSettings": {
          "allowSplits": true,
          "splitTypes": [
            "package_planner"
          ]
        }
      }
    }
  ],
  "name": "partner provided plan name",
  "orders": [
    {
      "currencyCode": "USD",
      "desiredDeliveryDate": "2023-08-20T15:51:30.982Z",
      "destinationAddress": {
        "addressType": "residential",
        "city": "Albuquerque",
        "company": "ACME",
        "countryCode": "US",
        "name": "Wile E. Coyote",
        "postalCode": "87121",
        "region": "NM",
        "street1": "123 Main St.",
        "street2": "Suite 42"
      },
      "orderItemQuantities": [
        {
          "productId": "product1",
          "quantity": 1
        },
        {
          "productId": "product2",
          "quantity": 1
        }
      ],
      "orderedDateTime": "2019-10-28T14:34:55.123456Z",
      "partnerOrderId": "MyOrder1"
    }
  ],
  "packagingTypes": [
    {
      "linearDimensions": {
        "height": 10,
        "length": 13,
        "linearUnit": "in",
        "width": 12
      },
      "maxContentWeight": {
        "weight": 50,
        "weightUnit": "lb"
      },
      "packagingMaterial": "box",
      "packagingSizeName": "13x12x10 box",
      "weight": {
        "weight": 1,
        "weightUnit": "lb"
      }
    }
  ],
  "partnerPlanId": "partner provided plan id",
  "productDetails": [
    {
      "inventoryStatuses": [
        {
          "fulfillmentContextId": "4b2ac183-a657-4477-bfe6-d2b6c74bc7b5",
          "quantityAvailable": 10
        }
      ],
      "linearDimensions": {
        "height": 10,
        "length": 12,
        "linearUnit": "in",
        "width": 11
      },
      "productId": "product1",
      "weight": {
        "weight": 1.2,
        "weightUnit": "lb"
      }
    },
    {
      "inventoryStatuses": [
        {
          "fulfillmentContextId": "4b2ac183-a657-4477-bfe6-d2b6c74bc7b5",
          "quantityAvailable": 10
        }
      ],
      "linearDimensions": {
        "height": 50,
        "length": 50,
        "linearUnit": "in",
        "width": 50
      },
      "productId": "product2",
      "weight": {
        "weight": 1.3,
        "weightUnit": "lb"
      }
    }
  ]
}

Example response for Packaging Planner split

{
  "active": true,
  "archived": false,
  "description": "partner provided plan description",
  "name": "partner provided plan name",
  "partnerId": "76abb3d4-8990-4f80-aa13-4c2007cb852a",
  "partnerPlanId": "partner provided plan id",
  "proposedShipments": [
    {
      "cost": {
        "carrier": "ups",
        "cost": 4,
        "serviceMethod": "ups-ground-service-method"
      },
      "destinationAddress": {
        "addressType": "residential",
        "city": "Albuquerque",
        "company": "ACME",
        "countryCode": "US",
        "name": "Wile E. Coyote",
        "postalCode": "87121",
        "region": "NM",
        "street1": "123 Main St.",
        "street2": "Suite 42"
      },
      "fulfillmentContextId": "4b2ac183-a657-4477-bfe6-d2b6c74bc7b5",
      "packagingType": {
        "linearDimensions": {
          "height": 10,
          "length": 13,
          "linearUnit": "in",
          "width": 12
        },
        "maxContentWeight": {
          "weight": 50,
          "weightUnit": "lb"
        },
        "packagingMaterial": "box",
        "packagingSizeName": "13x12x10 box",
        "packagingTypeId": null,
        "weight": {
          "weight": 1,
          "weightUnit": "lb"
        }
      },
      "shipmentItems": [
        {
          "linearDimensions": null,
          "partnerOrderId": "MyOrder1",
          "productId": "product1",
          "weight": null
        }
      ],
      "totalWeight": {
        "weight": 2.2,
        "weightUnit": "lb"
      }
    }
  ],
  "resultingInventory": {
    "product1": [
      {
        "fulfillmentContextId": "4b2ac183-a657-4477-bfe6-d2b6c74bc7b5",
        "fulfillmentCostCurrencyCode": null,
        "fulfillmentCostPerItem": null,
        "quantityAvailable": 9
      }
    ],
    "product2": [
      {
        "fulfillmentContextId": "4b2ac183-a657-4477-bfe6-d2b6c74bc7b5",
        "fulfillmentCostCurrencyCode": null,
        "fulfillmentCostPerItem": null,
        "quantityAvailable": 10
      }
    ]
  },
  "tenantId": null,
  "unfulfillableItems": [
    {
      "countUnfulfilled": 1,
      "orderItem": {
        "productId": "product2",
        "quantity": 1
      },
      "partnerOrderId": "MyOrder1",
      "reason": "UNPACKABLE ITEM"
    }
  ]
}

Example request body for maximum items per package split

The value passed in the API call for fulfillmentCenters.rules.splitSettings.splitTypes must be unit_count. An integer value should be included for fulfillmentCenters.rules.maxItemsPerPackage.

{
  "fulfillmentCenters": [
    {
      "fulfillmentContextId": "4b2ac183-a657-4477-bfe6-d2b6c74bc7b5",
      "rules": {
        "splitSettings": {
          "allowSplits": true,
          "maxItemsPerPackage": 4,
          "splitTypes": [
            "unit_count"
          ]
        }
      }
    }
  ],
  "orders": [
    {
      "currencyCode": "USD",
      "desiredDeliveryDate": "2023-08-20T15:51:30.982Z",
      "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": "product1",
          "quantity": 5
        }
      ],
      "orderedDateTime": "2019-10-28T14:34:55.123456Z",
      "partnerOrderId": "partnerOrderId"
    }
  ],
  "productDetails": [
    {
      "inventoryStatuses": [
        {
          "fulfillmentContextId": "4b2ac183-a657-4477-bfe6-d2b6c74bc7b5",
          "fulfillmentCostCurrencyCode": "usd",
          "fulfillmentCostPerItem": 0,
          "quantityAvailable": 5
        }
      ],
      "linearDimensions": {
        "height": 10,
        "length": 13,
        "linearUnit": "in",
        "width": 12
      },
      "productId": "product1",
      "weight": {
        "weight": 1,
        "weightUnit": "lb"
      }
    }
  ]
}

Example response for maximum items per package split

{
  "active": true,
  "archived": false,
  "auditInfo": {
    "createdBy": "fulfillment-engine-integration-tests-internal",
    "creationTimeStamp": "2024-01-22T23:46:50.619Z",
    "lastUpdatedBy": "fulfillment-engine-integration-tests-internal",
    "lastUpdatedTimeStamp": "2024-01-22T23:46:50.619Z",
    "version": 1
  },
  "description": "set-description-with-something...",
  "name": "set-name-with-something...",
  "partnerId": "76abb3d4-8990-4f80-aa13-4c2007cb852a",
  "planId": "dd17b1fb-a472-4df7-8ac2-1513b950ac40",
  "proposedShipments": [
    {
      "cost": {
        "carrier": "ups",
        "cost": 4,
        "serviceMethod": "ups-ground-service-method"
      },
      "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": "4b2ac183-a657-4477-bfe6-d2b6c74bc7b5",
      "packagingType": {
        "linearDimensions": {
          "height": 10,
          "length": 12,
          "linearUnit": "in",
          "width": 11
        },
        "packagingTypeId": null,
        "packagingMaterial": "box",
        "weight": {
          "weight": 1,
          "weightUnit": "lb"
        }
      },
      "proposedShipmentId": "03f36117-13b5-4de8-81ba-0ed78c99eb91",
      "shipmentItems": [
        {
          "linearDimensions": null,
          "partnerOrderId": "partnerOrderId",
          "productId": "product1",
          "weight": null
        },
        {
          "linearDimensions": null,
          "partnerOrderId": "partnerOrderId",
          "productId": "product1",
          "weight": null
        },
        {
          "linearDimensions": null,
          "partnerOrderId": "partnerOrderId",
          "productId": "product1",
          "weight": null
        },
        {
          "linearDimensions": null,
          "partnerOrderId": "partnerOrderId",
          "productId": "product1",
          "weight": null
        }
      ],
      "totalWeight": {
        "weight": 1,
        "weightUnit": "lb"
      }
    },
    {
      "cost": {
        "carrier": "ups",
        "cost": 4,
        "serviceMethod": "ups-ground-service-method"
      },
      "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": "4b2ac183-a657-4477-bfe6-d2b6c74bc7b5",
      "packagingType": {
        "linearDimensions": {
          "height": 10,
          "length": 12,
          "linearUnit": "in",
          "width": 11
        },
        "packagingTypeId": null,
        "packagingMaterial": "box",
        "weight": {
          "weight": 1,
          "weightUnit": "lb"
        }
      },
      "proposedShipmentId": "03edeacb-92c9-4efb-abb8-c61ed15d46a4",
      "shipmentItems": [
        {
          "linearDimensions": null,
          "partnerOrderId": "partnerOrderId",
          "productId": "product1",
          "weight": null
        }
      ],
      "totalWeight": {
        "weight": 1,
        "weightUnit": "lb"
      }
    }
  ],
  "resultingInventory": {
    "product1": [
      {
        "fulfillmentContextId": "4b2ac183-a657-4477-bfe6-d2b6c74bc7b5",
        "fulfillmentCostCurrencyCode": "usd",
        "fulfillmentCostPerItem": 0,
        "quantityAvailable": 0
      }
    ]
  },
  "tenantId": "this-needs-to-come-from-the-tenant-header...",
  "unfulfillableItems": [],
  "urn": "urn:fe:plan:dd17b1fb-a472-4df7-8ac2-1513b950ac40:1"
}

Resources

Your Shipium team member is available to help along the way. However, you might find these resources helpful: