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).

If your organization uses tenants, you can optionally assert a tenantId on plan requests to apply tenant-scoped configuration during planning.

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
`tenantId`	Type: String Example: `ACME_Tenant_Coyote` Description: Either the Shipium-generated tenant UUID or your organization's partner-provided tenant alias. When provided, this asserts the tenant associated with the plan and applies tenant-scoped configuration (such as carrier accounts, contracts, and rate sets) during planning. When omitted, the tenant is inherited from the fulfillment contexts referenced in the request; see the validation errors table for behavior when multiple contexts resolve to different tenants.

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.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.fulfillmentContextId`	Type: String Condition: Required if no `fulfillmentCenters.fulfillmentContext` tag is provided Description: A unique identifier for the fulfillment context. This ID must correspond to a Shipium-registered fulfillment context for your organization. If both `fulfillmentContextId` and `fulfillmentContext` are provided, they must refer to the same context.
`fulfillmentCenters.fulfillmentContext`	Type: String Example: `ACME_Main_FC` Condition: Required if no `fulfillmentCenters.fulfillmentContextId` is provided Description: The user-defined tag or alias for a Shipium-registered fulfillment context. The tag must match exactly one active fulfillment context for your organization; an unknown or ambiguous tag will result in a `400 Bad Request` response.
`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.partnerReferenceIdentifier`	Type: String Description: An optional identifier your organization provides, used for reporting and cross-product correlation across Shipium APIs. Pass the same value you used in your Delivery Promise calls to correlate this order across the full API chain. Continue passing this value in downstream Carrier Selection calls. This value is not passed to carriers. See Link API Calls Across Shipium Products for the full cross-product linking guide.
`orders.partnerReferenceIdentifier2`	Type: String Description: An optional secondary identifier your organization provides for additional reporting or correlation context
`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: Array of strings 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 .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.inventoryStatuses .fulfillmentContextId`	Type: String Condition: Required if no `productDetails.inventoryStatuses.fulfillmentContext` tag is provided Description: A unique identifier for the fulfillment context. This ID must correspond to a Shipium-registered fulfillment context for your organization. If both `fulfillmentContextId` and `fulfillmentContext` are provided, they must refer to the same context.
`productDetails.inventoryStatuses .fulfillmentContext`	Type: String Example: `ACME_Main_FC` Condition: Required if no `productDetails.inventoryStatuses.fulfillmentContextId` is provided Description: The user-defined tag or alias for a Shipium-registered fulfillment context. The tag must match exactly one active fulfillment context for your organization; an unknown or ambiguous tag will result in a `400 Bad Request` response.
`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: Array of strings 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
`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
`requestTenantId`	The tenant identifier as it was submitted on the request, returned in the same form (Shipium UUID or partner alias) that was sent. This field is omitted from the response when no `tenantId` was provided on the request.
`shipiumTenantId`	The canonical Shipium-generated tenant UUID resolved for this plan; returned whenever a tenant is associated with the plan, whether asserted explicitly via the request `tenantId` field or inherited implicitly from the fulfillment contexts in the request
`partnerTenantId`	The canonical partner-provided tenant alias resolved for this plan; returned whenever a tenant is associated with the plan, whether asserted explicitly via the request `tenantId` field or inherited implicitly from the fulfillment contexts in the 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.fulfillmentContext`	The user-defined tag or alias of the fulfillment context (e.g., `ACME_Main_FC`)
`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 .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
`resultingInventory.fulfillmentCenterId`	The unique identifier for the fulfillment center where this inventory is held
`resultingInventory.fulfillmentContextId`	The unique ID of the fulfillment context associated with this inventory
`resultingInventory.fulfillmentContext`	The user-defined tag or alias of the fulfillment context (e.g., `ACME_Main_FC`)
`resultingInventory.quantityAvailable`	The ending quantity of this product available at this fulfillment context after proposed shipments are assigned
`resultingInventory .fulfillmentCostCurrencyCode`	The 3-character ISO 4217 currency code for the fulfillment cost
`resultingInventory.fulfillmentCostPerItem`	The price of fulfilling one item from this fulfillment context
`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",
  "tenantId": "ACME_Tenant_Coyote",
  "fulfillmentCenters": [
    {
      "fulfillmentContext": "ACME_Main_FC",
      "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
      },
      "partnerReferenceIdentifier": "ORD-2026-12345",
      "partnerReferenceIdentifier2": "PLAN:abc-def-ghi",
      "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": [
        {
          "fulfillmentContext": "ACME_Main_FC",
          "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",
  "requestTenantId": "ACME_Tenant_Coyote",
  "shipiumTenantId": "bda6a517-969a-42b8-80df-c7f4f65fd8ec",
  "partnerTenantId": "ACME_Tenant_Coyote",
  "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",
      "fulfillmentContext": "ACME_Main_FC",
      "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": {
    "RN03947--Z43121": [
      {
        "fulfillmentContextId": "76172e5c-e2c1-4652-b5f0-bd43e2d41ee0",
        "fulfillmentContext": "ACME_Main_FC",
        "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 and response bodies with tenant assertion

The tenantId field at the top level of a plan request is optional. When provided, it asserts the tenant the plan is for and applies tenant-scoped configuration (such as carrier accounts, contracts, and rate sets) during planning. When omitted, the tenant is inherited from the fulfillment contexts referenced in the request, provided those contexts all resolve to the same tenant.

The Fulfillment Engine response always includes shipiumTenantId and partnerTenantId whenever a tenant is associated with the plan, regardless of whether the tenant was asserted explicitly or inherited implicitly. The requestTenantId field is included only when the request asserted a tenantId, and is returned in the same form (Shipium UUID or partner alias) that was sent.

The following three examples illustrate the request and response patterns for each variation. Only the tenant-relevant fields are shown; all other request and response fields behave as documented in the primary example.

Assert tenant with Shipium UUID

This pattern is useful when your integration stores the canonical Shipium-generated tenant UUID and references it directly on plan requests.

{
  "partnerPlanId": "myPartnerPlanId123",
  "tenantId": "bda6a517-969a-42b8-80df-c7f4f65fd8ec",
  "fulfillmentCenters": [ ... ],
  "orders": [ ... ],
  "productDetails": [ ... ]
}

{
  "planId": "3fadf9cd-0c57-47b6-95dd-94629c6f7312",
  "partnerPlanId": "myPartnerPlanId123",
  "requestTenantId": "bda6a517-969a-42b8-80df-c7f4f65fd8ec",
  "shipiumTenantId": "bda6a517-969a-42b8-80df-c7f4f65fd8ec",
  "partnerTenantId": "ACME_Tenant_Coyote",
  "proposedShipments": [ ... ],
  "resultingInventory": { ... },
  "unfulfillableItems": []
}

Assert tenant with partner alias

This pattern is useful when your integration uses your organization's own tenant naming convention. The alias must be unique within your organization's tenants and is configured in the Shipium Console.

{
  "partnerPlanId": "myPartnerPlanId123",
  "tenantId": "ACME_Tenant_Coyote",
  "fulfillmentCenters": [ ... ],
  "orders": [ ... ],
  "productDetails": [ ... ]
}

{
  "planId": "3fadf9cd-0c57-47b6-95dd-94629c6f7312",
  "partnerPlanId": "myPartnerPlanId123",
  "requestTenantId": "ACME_Tenant_Coyote",
  "shipiumTenantId": "bda6a517-969a-42b8-80df-c7f4f65fd8ec",
  "partnerTenantId": "ACME_Tenant_Coyote",
  "proposedShipments": [ ... ],
  "resultingInventory": { ... },
  "unfulfillableItems": []
}

Omit `tenantId` (implicit inheritance from fulfillment contexts)

When tenantId is omitted, Shipium resolves the tenant from the fulfillment contexts referenced in the request. This pattern works when all referenced contexts resolve to the same tenant, or when all referenced contexts are global (untenanted). If the contexts resolve to multiple tenants, the request fails validation; see the validation errors table for details.

{
  "partnerPlanId": "myPartnerPlanId123",
  "fulfillmentCenters": [ ... ],
  "orders": [ ... ],
  "productDetails": [ ... ]
}

{
  "planId": "3fadf9cd-0c57-47b6-95dd-94629c6f7312",
  "partnerPlanId": "myPartnerPlanId123",
  "shipiumTenantId": "bda6a517-969a-42b8-80df-c7f4f65fd8ec",
  "partnerTenantId": "ACME_Tenant_Coyote",
  "proposedShipments": [ ... ],
  "resultingInventory": { ... },
  "unfulfillableItems": []
}

Note that requestTenantId is omitted from this response because no tenantId was asserted on the request.

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",
      "partnerReferenceIdentifier": "ORD-2026-12345",
      "partnerReferenceIdentifier2": "PLAN:abc-def-ghi"
    }
  ],
  "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
            }
        ]
    },
    "shipiumTenantId": "bda6a517-969a-42b8-80df-c7f4f65fd8ec",
    "partnerTenantId": "ACME_Tenant_Coyote",
    "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",
      "partnerReferenceIdentifier": "ORD-2026-12345",
      "partnerReferenceIdentifier2": "PLAN:abc-def-ghi"
    }
  ],
  "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",
    "shipiumTenantId": "bda6a517-969a-42b8-80df-c7f4f65fd8ec",
    "partnerTenantId": "ACME_Tenant_Coyote",
    "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",
      "partnerReferenceIdentifier": "ORD-2026-12345",
      "partnerReferenceIdentifier2": "PLAN:abc-def-ghi"
    }
  ],
  "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
      }
    ]
  },
  "shipiumTenantId": "bda6a517-969a-42b8-80df-c7f4f65fd8ec",
  "partnerTenantId": "ACME_Tenant_Coyote",
  "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",
      "partnerReferenceIdentifier": "ORD-2026-12345",
      "partnerReferenceIdentifier2": "PLAN:abc-def-ghi"
    }
  ],
  "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
      }
    ]
  },
  "shipiumTenantId": "bda6a517-969a-42b8-80df-c7f4f65fd8ec",
  "partnerTenantId": "ACME_Tenant_Coyote",
  "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",
      "partnerReferenceIdentifier": "ORD-2026-12345",
      "partnerReferenceIdentifier2": "PLAN:abc-def-ghi"
    }
  ],
  "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
      }
    ]
  },
  "shipiumTenantId": "bda6a517-969a-42b8-80df-c7f4f65fd8ec",
  "partnerTenantId": "ACME_Tenant_Coyote",
  "unfulfillableItems": [],
  "urn": "urn:fe:plan:dd17b1fb-a472-4df7-8ac2-1513b950ac40:1"
}

Validation errors

When a request to the Fulfillment Engine API fails validation, the API returns a 400 Bad Request response with an error message describing the problem. The following errors can occur when Shipium resolves fulfillment contexts by tag or ID.

Error message	Cause	Resolution
`No fulfillment context found for tag: {tag}`	The provided tag does not exist or is not currently active for your organization.	Confirm the tag is spelled correctly and that the associated fulfillment context is active in the Shipium Console.
`Multiple fulfillment contexts ({count}) found for tag: {tag}`	The tag matches more than one active fulfillment context for your organization.	Ensure tags are unique across your fulfillment contexts, or pass `fulfillmentContextId` instead of `fulfillmentContext` to identify a specific context.
`Provided fulfillmentContextId [{providedId}] does not match fulfillmentContextId [{resolvedId}] for tag: {tag}`	Both a `fulfillmentContextId` and a `fulfillmentContext` tag were provided in a single `inventoryStatuses[]` or `fulfillmentCenters[]` entry, but the provided ID does not match the ID that the tag resolves to.	Provide only one of the two fields, or confirm that the ID and tag refer to the same context.
`the request tenantId [{requestTenantId}] differs from the fulfillment context tenantId [{contextTenantId}]`	The asserted `tenantId` on the request is scoped to a different tenant than a `fulfillmentContextId` provided in `fulfillmentCenters[]` or `productDetails.inventoryStatuses[]`.	Confirm the asserted `tenantId` matches the tenant scoping of every fulfillment context in the request. Either remove the conflicting fulfillment context, change the asserted tenant, or use a global (untenanted) fulfillment context.
`fulfillment contexts span multiple tenants`	The request omits `tenantId` and the fulfillment contexts referenced in the request resolve to more than one tenant. Without an asserted tenant, Shipium cannot determine which tenant's configuration to apply.	Provide an explicit `tenantId` at the request level to assert which tenant the plan is for, or limit the fulfillment contexts in the request to those scoped to a single tenant (or to global contexts).
`unable to find tenantId [{tenantId}]`	The provided `tenantId` value does not match any active tenant for your organization, either as a Shipium UUID or as a partner alias.	Confirm the value is spelled correctly and that the tenant is active in the Shipium Console.

Resources

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

Get started

Create a fulfillment plan with the Fulfillment Engine API

Authentication for API Calls

Request and response fields for API calls

Top-level request fields

Optional fields

fulfillmentCenters fields

Required fields

Conditional fields

Optional fields

orders fields

Required fields

Conditional fields

Optional fields

packagingTypes fields

Required fields

Conditional fields

Optional fields

productDetails fields

Required fields

Conditional fields

Optional fields

Response attributes

Shipium assumptions for the Fulfillment Engine API

Example cURL call

Example request body

Example response

Example request and response bodies with tenant assertion

Assert tenant with Shipium UUID

Assert tenant with partner alias

Omit tenantId (implicit inheritance from fulfillment contexts)

Example request body with inclusion of desired delivery date

Example response with desired delivery date

Example request for package and product handling cost overrides

Example response with package and product handling cost overrides

Examples for order splits

Example request body for fulfillment center split

Example response for fulfillment center split

Example request body for Packaging Planner split

Example response for Packaging Planner split

Example request body for maximum items per package split

Example response for maximum items per package split

Validation errors

Resources

Omit `tenantId` (implicit inheritance from fulfillment contexts)