The shipments property is defined as an array to support split-shipments. A single order can include multiple order items produced, and ship them to different addresses. The shipment's items array is used to indicate which items go to each shipment by referencing orderItemGroupId values and associated quantities to be included for that shipment.

Here are a few of the key options for a shipment:

• shippingAddress - Required. Specify the address information for mailing the shipment. For US shipments, the state field must be a two-letter abbreviation.
• confirmationEmailAddress - Optional. If provided, then an email will be sent to this address when the shipment is fulfilled. This is separate from the confirmationEmailAddress field on the shipment object, which triggers a system email that the order is placed. For split-shipment scenarios, these may need to be different.
• customId - Optional. This can provide a custom id to be associated with the shipment in the Fulfill Engine system. A shipment id will still be generated in Fulfill Engine, but the custom id will also show in the portal. When the order only has one shipment, then this may generally be the same value as the customId provided for the order itself.
• customPackingSlipUrl - Optional. Provide a custom URL for a packing slip to be printed. This should be in a 4x6 format.
• items - Optional. Indicates which order items from the order will be included in this shipment. If more than one shipment is defined for the order, then this property is required.
  • orderItemGroupId - A reference to entries in the orderItemGroups array provided on the order request. This should match the id of one of the entries in that array.
  • quantity - The quantity of this particular order item group that should be included in this shipment. An orderItemGroup will have an overall quantity at the order request level, and all or a subset can be allocated to individual shipments.
• shippingTier - Optional. Specify the shipping tier to be used for the shipment. If not specified, then the default setting for your account will be used. The allowed options for this field may vary based on your account but could include: economy, standard, threeday, twoday, or nextday.
• shippingCarrier, shippingService - Optional. A specific carrier and service can sometimes be provided, as an alternative to specifying a shipping tier. You will need to speak with your account representative for whether this approach can work for you and what values may be supported.
• returnToAddress - Optional. Override the from/return information provided on the shipping label for the shipment. This can be configured within your Fulfill Engine store/account, but can be overridden on a shipment by shipment basis here.