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.

Request and response fields for API calls

The following tables provide required, conditional, and optional fields for calling the Fulfillment Engine API. You can find additional support in the Fulfillment Engine API Reference.

Top-level request fields

Optional fields

Field	Details
`partnerPlanId`	Type: String Example: `myPartnerPlanId123` Description: An optional ID that allows you to set your own ID for looking up the plan after creation
`planDateTime`	Type: String Description: A future date to use as the starting date of the plan. A value of `null` conveys to use 'now' as the plan time.
`name`	Type: String Example: `myFulfillmentEnginePlan` Description: An optional human-readable name your organization has assigned to the plan
`description`	Type: String Description: An optional description you can use to provide additional information for the plan

fulfillmentCenters fields

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.

Required fields

Field	Details
`fulfillmentCenters.fulfillmentContextId`	Type: String Description: A unique identifier for the fulfillment context. This ID must correspond to a Shipium-registered fulfillment context for your organization.
`fulfillmentCenters.packagingTypes .linearDimensions.height`	Type: Decimal (greater than zero) Description: 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`	Type: Decimal (greater than zero) Description: Length of the longest side of the box to be packed
`fulfillmentCenters.packagingTypes .linearDimensions.linearUnit`	Type: String (enumeration) Values: `in` (inch), `cm` (centimeter) Description: The unit of measurement in which the linear dimensions of the box are specified
`fulfillmentCenters.packagingTypes .linearDimensions.width`	Type: Decimal (greater than zero) Description: Length of the second longest side of the box to be packed

Conditional fields

Field	Details
`fulfillmentCenters.packagingTypes .packagingTypeId`	Type: String Condition: Required if including packaging type values configured in the Shipium platform Description: 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`	Type: String (enumeration) Values: `box`, `envelope`, `flat_pack`, `mailing_tube`, `parcel_pallet`, `unknown` Condition: Required if no `packagingTypeId` is provided Description: The shipment packaging material
`fulfillmentCenters.packagingTypes .weight.weight`	Type: Decimal (greater than zero) Condition: Required if no `packagingTypeId` is provided Description: The weight of the empty packaging
`fulfillmentCenters.packagingTypes .weight.weightUnit`	Type: String (enumeration) Values: `g` (gram), `kg` (kilogram), `oz` (ounce), `lb` (pound) Condition: Required if no `packagingTypeId` is provided Description: The unit of measurement in which the empty packaging is specified
`fulfillmentCenters.rules.splitSettings .maxItemsPerPackage`	Type: Integer (int32) Condition: Required when `unit_count` is included as a split type Description: 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 .maxPackagesPerOrder`	Type: Integer (int32) Condition: Required when `max_shipments` is included as a split type Description: 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.

Optional fields

Field	Details
`fulfillmentCenters.fulfillmentCost .currencyCode`	Type: String Description: The currency code of the fulfillment costs
`fulfillmentCenters.fulfillmentCost .perItem`	Type: Number (float) Description: Additional processing cost added per item in a shipment
`fulfillmentCenters.fulfillmentCost .perPackage`	Type: Number (float) Description: Additional processing cost added per package in a shipment
`fulfillmentCenters.packagingTypes .packagingSizeName`	Type: String Example: `1x1x4 box` Description: A name your organization wishes to provide for the packaging size
`fulfillmentCenters.packagingTypes .maxContentWeight.weight`	Type: Decimal (greater than zero) Description: 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`	Type: String (enumeration) Values: `g` (gram), `kg` (kilogram), `oz` (ounce), `lb` (pound) Description: The unit of measurement in which the maximum content weight is specified
`fulfillmentCenters.processingTime`	Type: Array of processing time values Description: 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`	Type: Boolean Values: `true` or `false` Description: When set to `true`, this fulfillment center will support splitting shipments based on types defined in the `splitTypes` field.
`fulfillmentCenters.rules.splitSettings .splitTypes`	Type: String (enumeration) Values: `fc_split`, `hazmat`, `inventory`, `max_shipments`, `package_planner`, `sioc`, `unit_count`, `unknown` Description: 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 fields

Data for packaging at the orders level allows for defining the packaging type to use for a specific order.

Required fields

Field	Details
`orders.destinationAddress.addressType`	Type: String (enumeration) Values: `commercial`, `residential` Description: The type of location for this address
`orders.destinationAddress.countryCode`	Type: String Description: The 2-character ISO 3166 country code for the address
`orders.destinationAddress.postalCode`	Type: String Description: The postal code for the address
`orders.orderItemQuantities.productId`	Type: String Example: `RN03947-Z43121` Description: A unique product identifier
`orders.orderItemQuantities.quantity`	Type: Integer (greater than zero) Description: The number of units of this product
`orders.orderedDateTime`	Type: String (date-time) Description: The ISO 8601 timestamp for when the customer ordered the product
`orders.partnerOrderId`	Type: String Description: The identification your organization provided for this order
`orders.packagingType.linearDimensions .linearUnit`	Type: String (enumeration) Values: `in` (inch), `cm` (centimeter) Description: The unit of measurement in which the linear dimensions of the box are specified
`orders.packagingType.linearDimensions.length`	Type: Decimal (greater than zero) Description: Length of the longest side of the box to be packed
`orders.packagingType.linearDimensions.width`	Type: Decimal (greater than zero) Description: Length of the second longest side of the box to be packed
`orders.packagingType.linearDimensions.height`	Type: Decimal (greater than zero) Description: 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.

Conditional fields

Field	Details
`orders.packagingType.packagingTypeId`	Type: String Condition: Required if including packaging type values configured in the Shipium platform Description: Packing type identifier
`orders.packagingType.packagingMaterial`	Type: String (enumeration) Values: `box`, `envelope`, `flat_pack`, `unknown` Condition: Required if no `packagingTypeId` is provided Description: The shipment packaging material
`orders.packagingType.weight.weightUnit`	Type: String (enumeration) Values: `g` (gram), `kg` (kilogram), `oz` (ounce), `lb` (pound) Condition: Required if no `packagingTypeId` is provided Description: The unit of measurement in which the empty packaging is specified
`orders.packagingType.weight.weight`	Type: Decimal (greater than zero) Condition: Required if no `packagingTypeId` is provided Description: The weight of the empty packaging
`orders.packagingType.maxContentWeight .weightUnit`	Type: String (enumeration) Values: `g` (gram), `kg` (kilogram), `oz` (ounce), `lb` (pound) Condition: Required if Packaging Planner values are included but no `packagingTypeId` is provided Description: The unit of measurement of the maximum weight of the contents that the packaging type can support
`orders.packagingType.maxContentWeight.weight`	Type: Decimal (greater than zero) Condition: Required if Packaging Planner values are included but no `packagingTypeId` is provided Description: The maximum weight of contents that the packaging type can support

Optional fields

Field	Details
`orders.currencyCode`	Type: String Example: `usd` Description: The 3-character ISO 4217 currency code of the orders
`orders.destinationAddress.city`	Type: String Description: The name of the city for the address
`orders.destinationAddress.company`	Type: String Description: The company name for the address
`orders.destinationAddress.name`	Type: String Description: The name associated with the address
`orders.destinationAddress.region`	Type: String Example: `NM` Description: The name of the state or region for the address
`orders.destinationAddress.street1`	Type: String Description: The first line of the address
`orders.destinationAddress.street2`	Type: String Description: The second line of the address
`orders.orderParams.mustShipComplete`	Type: Boolean Values: `true` or `false` Description: This should be `true` if all order items must be planned for shipment. The default value is `false`.
`orders.desiredDeliveryDate`	Type: String Example: `2019-10-31T20:00:00Z` Description: 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.desiredDeliveryDateOptions .exactDateDelivery`	Type: Boolean Values: `true` or `false` Description: 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.desiredDeliveryDateOptions .guaranteedDateDelivery`	Type: Boolean Values: `true` or `false` Description: 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.desiredDeliveryDateOptions .upgradeCostDeltaMax`	Type: String Description: 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.desiredDeliveryDateOptions .currencyCode`	Type: String Description: The ISO 4217 currency code of the `upgradeCostDeltaMax`
`orders.businessDaysOfTransit`	Type: Integer (int32) Example: `3` Description: Indicates the number of business days from the ship time by when the shipment needs to be delivered
`orders.shipOption`	Type: String Example: `standard` Description: A high-level shipping option shown to or selected by a customer
`orders.shippedDateTime`	Type: String (date-time) Description: 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.urn`	Type: String Description: The uniform resource name for identifying the packaging type
`orders.packagingType.packagingSizeName`	Type: String Example: `1x1x4 Box` Description: A name your organization wishes to provide for the packaging size

packagingTypes fields

Data for packaging types at this primary level allows for specifying the packaging types to use for the request across fulfillment centers.

Required fields

Field	Details
`packagingTypes.packagingTypeId`	Type: String Description: Packaging type identifier
`packagingTypes.packagingMaterial`	Type: String (enumeration) Values: `box`, `envelope`, `flat_pack`, `mailing_tube`, `parcel_pallet`, `unknown` Description: The shipment packaging material
`packagingTypes.weight.weight`	Type: Decimal (greater than zero) Description: The weight of the packaging
`packagingTypes.weight.weightUnit`	Type: String (enumeration) Values: `g` (gram), `kg` (kilogram), `oz` (ounce), `lb` (pound) Description: The unit of measurement in which the packaging is specified

Conditional fields

Field	Details
`packagingTypes.linearDimensions.height`	Type: Decimal (greater than zero) Condition: Required if no `packagingTypeId` is provided Description: The numerical value of the shortest side of the package
`packagingTypes.linearDimensions.length`	Type: Decimal (greater than zero) Condition: Required if no `packagingTypeId` is provided Description: The numerical value of the longest side of the package
`packagingTypes.linearDimensions.linearUnit`	Type: String (enumeration) Values: `in` (inch), `cm` (centimeter) Condition: Required if no `packagingTypeId` is provided Description: The unit of measurement in which the linear dimensions of the package are specified
`packagingTypes.linearDimensions.width`	Type: Decimal (greater than zero) Condition: Required if no `packagingTypeId` is provided Description: The numerical value of the second longest side of the package
`packagingTypes.maxContentWeight.weightUnit`	Type: String (enumeration) Values: `g` (gram), `kg` (kilogram), `oz` (ounce), `lb` (pound) Condition: Required if Packaging Planner values are included but no `packagingTypeId` is provided Description: The unit of measurement of the maximum weight of the contents that the packaging type can support
`packagingTypes.maxContentWeight.weight`	Type: Decimal (greater than zero) Condition: Required if Packaging Planner values are included but no `packagingTypeId` is provided Description: The maximum weight of contents that the packaging type can support

Optional fields

Field	Details
`packagingTypes.packagingSizeName`	Type: String Example: `1x1x4 box` Description: A name your organization wishes to provide for the packaging size

productDetails fields

Required fields

Field	Details
`productDetails.fulfillmentAttributes`	Type: String Description: A list of attributes that may affect the shipping of the product
`productDetails.hazmatInfo.quantity`	Type: Number Description: The amount of quantity type material in quantity units
`productDetails.hazmatInfo.quantityType`	Type: String (enumeration) Values: `gross`, `net` Description: Determines whether the quantity includes the raw material (net) or also includes the material housing (gross)
`productDetails.hazmatInfo.quantityUnits`	Type: String (enumeration) Values: `g` (gram), `kg` (kilogram), `l` (liter), `ml` (milliliter), `lb` (pound), `oz` (ounce) Description: The units of measure for the quantity of hazardous materials specified
`productDetails.inventoryStatuses .fulfillmentContextId`	Type: String Description: A unique identifier for the fulfillment context. This ID must correspond to a Shipium-registered fulfillment context for your organization.
`productDetails.inventoryStatuses .quantityAvailable`	Type: Integer (int32) Description: 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`	Type: Decimal (greater than zero) Description: The numerical value of the shortest side of the product
`productDetails.linearDimensions.length`	Type: Decimal (greater than zero) Description: The numerical value of the longest side of the product
`productDetails.linearDimensions.linearUnit`	Type: String (enumeration) Values: `in` (inch), `cm` (centimeter) Description: The unit of measurement in which the linear dimensions of the product are specified
`productDetails.linearDimensions.width`	Type: Decimal (greater than zero) Description: The numerical value of the second longest side of the product
`productDetails.productDetails`	Type: Array of strings Values: `limited_quantity` (preferred for LQ/ORM-D; alias: `lq`), `bound_printed_matter` (alias: `bpm`), `perishable`, `ormd` (legacy; alias: `orm-d`) Description: A list of product properties that affect carrier selection and handling; see productDetails Reference for details.
`productDetails.productId`	Type: String Description: The product stock-keeping unit (SKU)

Conditional fields

Field	Details
`productDetails.hazmatInfo.category`	Type: String (enumeration) Values: `aerosols_flammable`, `contains_lithium_ion`, `contains_lithium_metal`, `defined`, `lithium_ion_battery_only`, `lithium_metal_battery_only`, `packaged_lithium_ion`, `packaged_lithium_metal` Condition: Required if the `hazmat` field is `true` Description: Hazmat category for this order item. Use `defined` to specify detailed information.
`productDetails.hazmatInfo.containerType`	Type: String (enumeration) Values: `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` Condition: Required if the `hazmat` field is `true` Description: The material in which the hazardous material is packed
`productDetails.hazmatInfo.hazardClass`	Type: String (enumeration) Values: `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` Condition: Required if the `category` field is `defined` Description: Hazard class of the hazardous material
`productDetails.hazmatInfo.hazmatId`	Type: String Condition: Required if the `category` field is `defined` Description: The International Air Transport Association (IATA) or U.S. Department of Transportation (DOT) regulatory identifier for the commodity as appropriate
`productDetails.hazmatInfo.properShippingName`	Type: String Condition: Required if the `category` field is `defined` Description: The proper shipping name that is associated with the specified `hazmatId`
`productDetails.hazmatInfo.transportMode`	Type: String (enumeration) Values: `cargo_aircraft_only`, `ground`, `passenger_and_cargo_aircraft` Condition: Required if the `category` field is `defined` Description: The transport mode for the hazardous material
`productDetails.weight.weight`	Type: Decimal (greater than zero) Condition: Required if including `productDetails.weight` Description: The weight of the product
`productDetails.weight.weightUnit`	Type: String (enumeration) Values: `g` (gram), `kg` (kilogram), `oz` (ounce), `lb` (pound) Condition: Required if including `productDetails.weight` Description: The unit of measurement in which the weight is specified

Optional fields

Field	Details
`productDetails.hazmat`	Type: Boolean Values: `true` or `false` Description: If `true`, indicates that the item is hazmat. The default value is `false`.
`productDetails.hazmatInfo.packingGroup`	Type: String (enumeration) Values: `i`, `ii`, `iii` Description: The degree of danger the material presents
`productDetails.hazmatInfo .packingInstructionCode`	Type: String Description: The packing instruction code used for air transport
`productDetails.hazmatInfo.subsidiaryClasses`	Type: String Description: The appropriate IATA or DOT subsidiary classes associated with the material and the hazard class
`productDetails.inventoryStatuses .fulfillmentCenterId`	Type: String Description: The unique identifier for the fulfillment center that corresponds to a fulfillment center configured in the Shipium platform
`productDetails.inventoryStatuses .fulfillmentCostCurrencyCode`	Type: String Example: `usd` Description: The 3-character ISO 4217 currency code of the fulfillment cost
`productDetails.inventoryStatuses .fulfillmentCostPerItem`	Type: Number Description: The price of fulfilling one item from the fulfillment center

Response attributes

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 required fields in the following table must be included in your API call.

Field	Details
`fulfillmentCenters.rules.splitSettings .allowSplits`	Type: Boolean Values: `true` or `false` Description: When set to `true`, this fulfillment center will support splitting shipments based on types defined in the `splitTypes` field.
`fulfillmentCenters.rules.splitSettings .splitTypes`	Type: String (enumeration) Values: `fc_split`, `hazmat`, `inventory`, `max_shipments`, `package_planner`, `sioc`, `unit_count`, `unknown` Description: 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: