For AI agents: visit https://docs.shipium.com/llms.txt for an index of all pages formatted in Markdown and endpoints in OpenAPI.
# Get started [Skip link to Get started](https://docs.shipium.com/docs/fulfillment-engine-api\#get-started)
To use the Fulfillment Engine API, you must first configure your account. Guidance can be found in the [Fulfillment Engine](https://docs.shipium.com/docs/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:
1. **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).
2. **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.
3. **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.
4. **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 [Skip link to Create a fulfillment plan with the Fulfillment Engine API](https://docs.shipium.com/docs/fulfillment-engine-api\#create-a-fulfillment-plan-with-the-fulfillment-engine-api)
The Fulfillment Engine API is designed to be flexible to fit your organization’s business strategy and technical capabilities. All API calls assume you're using one of the authentication mechanisms detailed in our [authentication documentation](https://docs.shipium.com/docs/authentication). 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 [Skip link to Authentication for API Calls](https://docs.shipium.com/docs/fulfillment-engine-api\#authentication-for-api-calls)
>
> In the cURL example on this page, the environment variable `AUTHSTRING` is used to handle authorization. The recipe below shows how to set it correctly for both API Key and OAuth users.
🔐
Authenticating for Curl
Open Recipe
## Request and response fields for API calls [Skip link to Request and response fields for API calls](https://docs.shipium.com/docs/fulfillment-engine-api\#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 [Skip link to Top-level request fields](https://docs.shipium.com/docs/fulfillment-engine-api\#top-level-request-fields)
#### Optional fields [Skip link to Optional fields](https://docs.shipium.com/docs/fulfillment-engine-api\#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](https://docs.shipium.com/docs/fulfillment-contexts) referenced in the request; see the [validation errors](https://docs.shipium.com/docs/fulfillment-engine-api#validation-errors) table for behavior when multiple contexts resolve to different tenants. |
### fulfillmentCenters fields [Skip link to fulfillmentCenters fields](https://docs.shipium.com/docs/fulfillment-engine-api\#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 [Skip link to Required fields](https://docs.shipium.com/docs/fulfillment-engine-api\#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 [Skip link to Conditional fields](https://docs.shipium.com/docs/fulfillment-engine-api\#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](https://docs.shipium.com/docs/fulfillment-contexts) 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](https://docs.shipium.com/docs/fulfillment-contexts). 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](https://docs.shipium.com/docs/configure-packaging-configuration) 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](https://docs.shipium.com/docs/configure-packaging-configuration) material |
| `fulfillmentCenters.packagingTypes .weight.weight` | **Type:** Decimal (greater than zero)
**Condition:** Required if no `packagingTypeId` is provided
**Description:** The weight of the empty [packaging](https://docs.shipium.com/docs/configure-packaging-configuration) |
| `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](https://docs.shipium.com/docs/configure-packaging-configuration) 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 [Skip link to Optional fields](https://docs.shipium.com/docs/fulfillment-engine-api\#optional-fields-1)
| 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](https://www.iso.org/iso-8601-date-and-time-format.html) 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 [Skip link to orders fields](https://docs.shipium.com/docs/fulfillment-engine-api\#orders-fields)
Data for packaging at the orders level allows for defining the packaging type to use for a specific order.
#### Required fields [Skip link to Required fields](https://docs.shipium.com/docs/fulfillment-engine-api\#required-fields-1)
| 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](https://docs.shipium.com/docs/non-us-address-formats#per-country-details) 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](https://www.iso.org/iso-8601-date-and-time-format.html) 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 [Skip link to Conditional fields](https://docs.shipium.com/docs/fulfillment-engine-api\#conditional-fields-1)
| Field | Details |
| --- | --- |
| `orders.packagingType.packagingTypeId` | **Type:** String
**Condition:** Required if including [packaging type](https://docs.shipium.com/docs/configure-packaging-configuration) 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](https://docs.shipium.com/docs/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](https://docs.shipium.com/docs/packaging-planner) values are included but no `packagingTypeId` is provided
**Description:** The maximum weight of contents that the packaging type can support |
#### Optional fields [Skip link to Optional fields](https://docs.shipium.com/docs/fulfillment-engine-api\#optional-fields-2)
| Field | Details |
| --- | --- |
| `orders.currencyCode` | **Type:** String
**Example:**`usd`
**Description:** The 3-character [ISO 4217](https://www.iso.org/iso-4217-currency-codes.html) 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](https://docs.shipium.com/docs/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](https://www.iso.org/iso-8601-date-and-time-format.html) date or a local date for [desired delivery](https://docs.shipium.com/docs/desired-and-exact-delivery-dates): `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](https://docs.shipium.com/docs/desired-and-exact-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](https://docs.shipium.com/docs/desired-and-exact-delivery-dates). |
| `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](https://docs.shipium.com/docs/desired-and-exact-delivery-dates) (DDD) if the lowest cost carrier service method is unable to safely meet the DDD. |
| `orders.desiredDeliveryDateOptions .currencyCode` | **Type:** String
**Description:** The [ISO 4217](https://www.iso.org/iso-4217-currency-codes.html) currency code of the `upgradeCostDeltaMax` |
| `orders.businessDaysOfTransit` | **Type:** Integer (int32)
**Example:**`3`
**Description:** Indicates the number of [business days](https://docs.shipium.com/docs/business-days-of-transit) from the ship time by when the shipment needs to be delivered |
| `orders.shipOption` | **Type:** String
**Example:**`standard`
**Description:** A high-level [shipping option](https://docs.shipium.com/docs/shipment-ship-option-overview) 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](https://www.iso.org/iso-8601-date-and-time-format.html) 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 [Skip link to packagingTypes fields](https://docs.shipium.com/docs/fulfillment-engine-api\#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 [Skip link to Required fields](https://docs.shipium.com/docs/fulfillment-engine-api\#required-fields-2)
| Field | Details |
| --- | --- |
| `packagingTypes.packagingTypeId` | **Type:** String
**Description:** [Packaging](https://docs.shipium.com/docs/configure-packaging-configuration) type identifier |
| `packagingTypes.packagingMaterial` | **Type:** String (enumeration)
**Values:**`box`, `envelope`, `flat_pack`, `mailing_tube`, `parcel_pallet`, `unknown`
**Description:** The shipment [packaging](https://docs.shipium.com/docs/configure-packaging-configuration) material |
| `packagingTypes.weight.weight` | **Type:** Decimal (greater than zero)
**Description:** The weight of the [packaging](https://docs.shipium.com/docs/configure-packaging-configuration) |
| `packagingTypes.weight.weightUnit` | **Type:** String (enumeration)
**Values:**`g` (gram), `kg` (kilogram), `oz` (ounce), `lb` (pound)
**Description:** The unit of measurement in which the [packaging](https://docs.shipium.com/docs/configure-packaging-configuration) is specified |
#### Conditional fields [Skip link to Conditional fields](https://docs.shipium.com/docs/fulfillment-engine-api\#conditional-fields-2)
| 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](https://docs.shipium.com/docs/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](https://docs.shipium.com/docs/packaging-planner) values are included but no `packagingTypeId` is provided
**Description:** The maximum weight of contents that the packaging type can support |
#### Optional fields [Skip link to Optional fields](https://docs.shipium.com/docs/fulfillment-engine-api\#optional-fields-3)
| Field | Details |
| --- | --- |
| `packagingTypes.packagingSizeName` | **Type:** String
**Example:**`1x1x4 box`
**Description:** A name your organization wishes to provide for the [packaging](https://docs.shipium.com/docs/configure-packaging-configuration) size |
### productDetails fields [Skip link to productDetails fields](https://docs.shipium.com/docs/fulfillment-engine-api\#productdetails-fields)
#### Required fields [Skip link to Required fields](https://docs.shipium.com/docs/fulfillment-engine-api\#required-fields-3)
| 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](https://docs.shipium.com/docs/hazardous-materials-support) 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](https://docs.shipium.com/docs/hazardous-materials-support#productdetails-reference) for details. |
| `productDetails.productId` | **Type:** String
**Description:** The product stock-keeping unit (SKU) |
#### Conditional fields [Skip link to Conditional fields](https://docs.shipium.com/docs/fulfillment-engine-api\#conditional-fields-3)
| 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](https://docs.shipium.com/docs/fulfillment-contexts) 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](https://docs.shipium.com/docs/fulfillment-contexts). 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](https://docs.shipium.com/docs/hazardous-materials-support) 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](https://docs.shipium.com/docs/hazardous-materials-support) 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](https://docs.shipium.com/docs/hazardous-materials-support) |
| `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](https://docs.shipium.com/docs/hazardous-materials-support) |
| `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 [Skip link to Optional fields](https://docs.shipium.com/docs/fulfillment-engine-api\#optional-fields-4)
| Field | Details |
| --- | --- |
| `productDetails.hazmat` | **Type:** Boolean
**Values:**`true` or `false`
**Description:** If `true`, indicates that the item is [hazmat](https://docs.shipium.com/docs/hazardous-materials-support). 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](https://docs.shipium.com/docs/configure-fulfillment-configuration) in the Shipium platform |
| `productDetails.inventoryStatuses .fulfillmentCostCurrencyCode` | **Type:** String
**Example:**`usd` **Description:** The 3-character [ISO 4217](https://www.iso.org/iso-4217-currency-codes.html) currency code of the fulfillment cost |
| `productDetails.inventoryStatuses .fulfillmentCostPerItem` | **Type:** Number
**Description:** The price of fulfilling one item from the fulfillment center |
### Response attributes [Skip link to Response attributes](https://docs.shipium.com/docs/fulfillment-engine-api\#response-attributes)
The Fulfillment Engine response attributes are defined in the following table.
There are three major sections of the response:
1. **proposedShipments** contains the list of shipments recommended, including FC, packaging and cost details, items and links for each element in the `shipmentItems` array back to the originating order.
2. **unfulfillableItems** contains order items that could not be fulfilled, usually due to insufficient inventory available across all FCs.
3. **resultingInventory** contains the ending inventory state. If a given SKU in a given warehouse started out with a quantity of 10 and 4 were used as part of producing shipments then this array will contain a `quantityAvailable` of 6 for that FC and SKU, reflecting the end state of the inventory after assignments are complete.
| Response 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](https://www.iso.org/iso-4217-currency-codes.html) 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 [Skip link to Shipium assumptions for the Fulfillment Engine API](https://docs.shipium.com/docs/fulfillment-engine-api\#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 [Skip link to Example cURL call](https://docs.shipium.com/docs/fulfillment-engine-api\#example-curl-call)
cURL
```curl
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 [Skip link to Example request body](https://docs.shipium.com/docs/fulfillment-engine-api\#example-request-body)
Sample Request
```json
{
"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 [Skip link to Example response](https://docs.shipium.com/docs/fulfillment-engine-api\#example-response)
Sample Response
```json
{
"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 [Skip link to Example request and response bodies with tenant assertion](https://docs.shipium.com/docs/fulfillment-engine-api\#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](https://docs.shipium.com/docs/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 [Skip link to Assert tenant with Shipium UUID](https://docs.shipium.com/docs/fulfillment-engine-api\#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.
Sample Request with Shipium UUID
```json
{
"partnerPlanId": "myPartnerPlanId123",
"tenantId": "bda6a517-969a-42b8-80df-c7f4f65fd8ec",
"fulfillmentCenters": [ ... ],
"orders": [ ... ],
"productDetails": [ ... ]
}
```
Sample Response with Shipium UUID
```json
{
"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 [Skip link to Assert tenant with partner alias](https://docs.shipium.com/docs/fulfillment-engine-api\#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](https://partner.shipium.com/login).
Sample Request with Partner Alias
```json
{
"partnerPlanId": "myPartnerPlanId123",
"tenantId": "ACME_Tenant_Coyote",
"fulfillmentCenters": [ ... ],
"orders": [ ... ],
"productDetails": [ ... ]
}
```
Sample Response with Partner Alias
```json
{
"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) [Skip link to Omit ,[object Object], (implicit inheritance from fulfillment contexts)](https://docs.shipium.com/docs/fulfillment-engine-api\#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](https://docs.shipium.com/docs/fulfillment-engine-api#validation-errors) table for details.
Sample Request with Implicit Tenant
```json
{
"partnerPlanId": "myPartnerPlanId123",
"fulfillmentCenters": [ ... ],
"orders": [ ... ],
"productDetails": [ ... ]
}
```
Sample Response with Implicit Tenant
```json
{
"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 [Skip link to Example request body with inclusion of desired delivery date](https://docs.shipium.com/docs/fulfillment-engine-api\#example-request-body-with-inclusion-of-desired-delivery-date)
Sample Request with DDD
```text
{
"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 [Skip link to Example response with desired delivery date](https://docs.shipium.com/docs/fulfillment-engine-api\#example-response-with-desired-delivery-date)
Sample Response with DDD
```text
{
"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 [Skip link to Example request for package and product handling cost overrides](https://docs.shipium.com/docs/fulfillment-engine-api\#example-request-for-package-and-product-handling-cost-overrides)
Sample Request with Cost Overrides
```text
{
"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 [Skip link to Example response with package and product handling cost overrides](https://docs.shipium.com/docs/fulfillment-engine-api\#example-response-with-package-and-product-handling-cost-overrides)
Sample Response with Cost Overrides
```text
{
"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 [Skip link to Examples for order splits](https://docs.shipium.com/docs/fulfillment-engine-api\#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](https://docs.shipium.com/edit/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 [Skip link to Example request body for fulfillment center split](https://docs.shipium.com/docs/fulfillment-engine-api\#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`.
Sample Request for Fulfillment Center Split
```text
{
"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 [Skip link to Example response for fulfillment center split](https://docs.shipium.com/docs/fulfillment-engine-api\#example-response-for-fulfillment-center-split)
Sample Response for Fulfillment Center Split
```text
{
"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 [Skip link to Example request body for Packaging Planner split](https://docs.shipium.com/docs/fulfillment-engine-api\#example-request-body-for-packaging-planner-split)
This use case is if you are also using Shipium’s [Packaging Planner](https://docs.shipium.com/edit/packaging-planner) service. The value passed in the API call for `fulfillmentCenters.rules.splitSettings.splitTypes` must be `package_planner`.
Sample Request for Packaging Planner Split
```text
{
"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 [Skip link to Example response for Packaging Planner split](https://docs.shipium.com/docs/fulfillment-engine-api\#example-response-for-packaging-planner-split)
Sample Response for Packaging Planner Split
```text
{
"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 [Skip link to Example request body for maximum items per package split](https://docs.shipium.com/docs/fulfillment-engine-api\#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`.
Sample Request for Max Items Per Package Split
```text
{
"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 [Skip link to Example response for maximum items per package split](https://docs.shipium.com/docs/fulfillment-engine-api\#example-response-for-maximum-items-per-package-split)
Sample Response for Max Items Per Package Split
```text
{
"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 [Skip link to Validation errors](https://docs.shipium.com/docs/fulfillment-engine-api\#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](https://docs.shipium.com/docs/fulfillment-contexts) is active in the [Shipium Console](https://partner.shipium.com/login). |
| `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](https://partner.shipium.com/login). |
# Resources [Skip link to Resources](https://docs.shipium.com/docs/fulfillment-engine-api\#resources)
Your Shipium team member is available to help along the way. However, you might find these resources helpful:
- [Terms and Definitions](https://docs.shipium.com/docs/common-terms)
- [Troubleshooting Guide](https://docs.shipium.com/docs/troubleshooting-guide)
- [Contact Shipium Support](https://docs.shipium.com/docs/contacting-shipium-support)
Updated 2 months ago
* * *
### What’s Next
- [Fulfillment Engine](https://docs.shipium.com/docs/fulfillment-engine)
Did this page help you?
Yes
No
Copy Page
🦉
# Recipe Title
Recipe Description
x
```
```
1{"success":true}
## Are you sure?