Get started

To use the Pack Application (App) API, you can follow the instructions on this page. The Shipium Pack App API assumes you're using one of the authentication mechanisms detailed in our authentication documentation.

🔐
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

Using the Pack App API, you can:

create an order;
submit an order;
split an order;
search an order; or
get an order.

General information about the Pack App within the Shipium platform can be found in the Pack App documentation. Guidance for using the Pack App within the Shipium Console to scan orders and print labels as well as search order details is included in the Pack Application (Pack App) documentation.

Create an order with the Pack App API

The endpoint for creating an order with the Pack App API is included in the table below.

API type	API endpoint
POST	https://api.shipium.com/api/v1/packShip/order

Example cURL call to create an order

This example shows a request to create an order.

curl --request POST \
  --url https://api.shipium.com/api/v1/packShip/order \
  --header 'accept: application/json' \
  --header $AUTHSTRING \
  --header 'content-type: application/json' \
  --data 'INSERT REQUEST BODY FROM BELOW'

Example request body to create an order

The following fields should be included in your JSON request.

{
  "fulfillmentType": "customer",
  "orderSource": "external",
  "partnerOrderId": "partner-order:12345",
  "associatedIdentifiers": [
    "lpn-barcode:12345"
  ],
  "tenantId": null,
  "orderedDateTime": "2025-03-15T10:10:00.111111Z",
  "orderItemQuantities": [
    {
      "orderItemReferenceIdentifier": "partner-order:12334_item:1",
      "hazmat": false,
      "hazmatInfo": null,
      "productTaxCode": null,
      "nmfcCode": null,
      "nmfcFreightClass": null,
      "productId": "partner-product:12345",
      "quantity": 3,
      "productDetails": null
    }
  ],
  "shipFromAddress": null,
  "originId": "<ORIGIN-ID/PARTNER-PROVIDED-ORIGIN-ID FROM PARTNER CONFIG IN SHIPIUM>",
  "destinationAddress": {
    "name": "Wile E. Coyote",
    "phoneNumber": "9995551234",
    "phoneNumberCountryCode": "+1",
    "emailAddress": "[email protected]",
    "company": "ACME",
    "street1": "123 Main St.",
    "street2": "Suite 42",
    "city": "Albuquerque",
    "state": "NM",
    "countryCode": "US",
    "postalCode": "87121",
    "addressType": "residential",
    "addressLineComponents": null
  },
  "shipOption": null,
  "customsInfo": null,
  "totalDeclaredValue": null,
  "orderFulfillmentParameters": {
    "saturdayDelivery": false,
    "thirdPartyBillingSetId": null,
    "forceThirdPartyBilling": false,
    "fulfillmentContext": "<FCTX-ID/PARTNER-PROVIDED-FCTX-ID FROM PARTNER CONFIG IN SHIPIUM>",
    "fulfillmentContextId": null,
    "holdAtLocation": {
      "holdAtLocationId": "MyHALLocation",
      "useHoldAtLocation": true
    },
    "referenceIdentifier": "Order123",
    "partnerReferenceIdentifier": "PartnerRef789",
    "packagingType": null,
    "totalWeight": null,
    "splitOrder": false,
  }
}

Example response body for an order creation

{
  "fulfillmentType": "customer",
  "orderSource": "external",
  "shipiumOrderId": "4dc43fff-c3af-4d7b-8a18-e01f2b4cb312",
  "partnerOrderId": "partner-order:12345",
  "associatedIdentifiers": [
    "lpn-barcode:12345"
  ],
  "tenantId": null,
  "orderedDateTime": "2025-03-15T10:10:00.111111Z",
  "orderItemQuantities": [
    {
      "shipiumOrderId": "4dc43fff-c3af-4d7b-8a18-e01f2b4cb312",
      "partnerOrderId": "partner-order:12345",
      "orderItemReferenceIdentifier": "partner-order:12334_item:1",
      "hazmat": false,
      "hazmatInfo": null,
      "productTaxCode": null,
      "nmfcCode": null,
      "nmfcFreightClass": null,
      "productId": "partner-product:12345",
      "quantity": 3,
      "productDetails": null
    }
  ],
  "shipFromAddress": null,
  "originId": "<ORIGIN-ID/PARTNER-PROVIDED-ORIGIN-ID FROM PARTNER CONFIG IN SHIPIUM>",
  "destinationAddress": {
    "name": "Wile E. Coyote",
    "phoneNumber": "9995551234",
    "phoneNumberCountryCode": "+1",
    "emailAddress": "[email protected]",
    "company": "ACME",
    "street1": "123 Main St.",
    "street2": "Suite 42",
    "city": "Albuquerque",
    "state": "NM",
    "countryCode": "US",
    "postalCode": "87121",
    "addressType": "residential",
    "addressLineComponents": null
  },
  "shipOption": null,
  "customsInfo": null,
  "totalDeclaredValue": null,
  "orderFulfillmentParameters": {
    "saturdayDelivery": false,
    "thirdPartyBillingSetId": null,
    "forceThirdPartyBilling": false,
    "fulfillmentContext": "<FCTX-ID/PARTNER-PROVIDED-FCTX-ID FROM PARTNER CONFIG IN SHIPIUM>",
    "fulfillmentContextId": null,
    "holdAtLocation": {
      "holdAtLocationId": "MyHALLocation",
      "useHoldAtLocation": true
    },
    "referenceIdentifier": "Order123",
    "partnerReferenceIdentifier": "PartnerRef789",
    "packagingType": null,
    "totalWeight": null,
    "splitOrder": false
  }
}

Request and response fields for creating an order

The following table provides required and optional fields for calling the Pack App API to create an order. Optional fields such as those in customsInfo would only be required for international shipments. You can find additional support in the Pack App API Reference.

Request field	Required/Optional	Field properties	Description
`fulfillmentType`	Required	String enumeration Values are: `customer` `at_large` `returns` `hundredweight` `reship`	The fulfillment methodology of the shipment
`orderSource`	Required	String enumeration Values are: `Shipium` `External`	The source of this order whether it is from the Shipium system or externally created
`partnerOrderId`	Optional	String	An optional custom identifier that may be used for this order
`associatedIdentifiers`	Optional	An array of strings	Associated identifiers that are indexed to identify this order; for example, this can be a license plate number (LPN) that is bound to the order. This can be searched but is not interchangeable with `orderId`.
`tenantId`	Optional	String	Either the Shipium Tenant ID or the Tenant ID provided by your organization (Partner Provided ID); when present, this is used to indicate the tenant associated with the shipment.
`orderedDateTime`	Required	String ($date-time)	The timestamp for when the customer placed the order for this product; the timestamp must be a valid ISO 8601 timestamp.
`orderItemQuantities`	Required	An array of order item quantities	A list of `orderItems` comprising the shipment
`orderItemQuantities .orderItemReferenceIdentifier`	Required	String	An external identifier that can reference the order item that exists in an external order management system (OMS); this field will be passed to supported carriers.
`orderItemQuantities.hazmat`	Optional	Boolean `true` or `false`	If `true`, this indicates that the item is hazardous material (hazmat). The default value is `false`. For hazmat requirements, you can refer to Hazardous Materials.
`orderItemQuantities .hazmatInfo.category`	Optional, but required if including `hazmatInfo`	String enumeration Values are: `defined` `contains_lithium_ion` `packaged_lithium_ion` `lithium_ion_battery_only` `contains_lithium_metal` `packaged_lithium_metal` `lithium_metal_battery_only` `dry_ice`	Hazmat category for this order item; use `defined` to specify detailed information.
`orderItemQuantities .hazmatInfo.quantity`	Optional, but required if `category` is defined	Number ($float) Ex.: `2.1`	The amount of quantity type material in quantity units
`orderItemQuantities .hazmatInfo.quantityType`	Optional, but required if `category` is defined	String enumeration Values are: `gross` `net`	Determines whether the quantity includes the raw material (net) or also includes the material housing (gross)
`orderItemQuantities .hazmatInfo.quantityUnits`	Optional, but required if `category` is defined	String enumeration Values are: `g` (gram) `kg` (kilogram) `lb` (pound) `oz` (ounce) `ml` (milliliter) `l` (liter)	The units of measure for the quantity of hazardous materials specified
`orderItemQuantities .hazmatInfo.containerType`	Optional, but required if `category` is defined	String enumeration Values are: `fiberboard_box` `wooden_box` `plastic_jerrican` `metal_box` `steel_drum` `other` `plastic_box` `plastic_drum` `styrofoam_box` `cylinder` `envirotainer` `plywood_box` `aluminum_drum` `aluminum_cylinder` `plastic_pail` `plywood_drum` `fiber_drum` `steel_jerrican` `aluminum_jerrican` `steel_box` `carton` `aluminum_box`	The material in which the hazardous material is packaged
`orderItemQuantities .hazmatInfo.hazmatId`	Optional, but required if `category` is defined	String Ex.: `UN1755`	The International Air Transport Association (IATA) or U.S. Department of Transportation (DOT) regulatory identifier for the commodity as appropriate
`orderItemQuantities .hazmatInfo .properShippingName`	Optional, but required if `category` is defined	String Ex.: `chromic acid solution`	Proper shipping name that is associated with the specified hazmat ID
`orderItemQuantities .hazmatInfo.packingGroup`	Optional	String enumeration Values are: `i` `ii` `iii`	The packing group code for the hazardous material
`orderItemQuantities .hazmatInfo.transportMode`	Optional, but required if `category` is defined	String enumeration Values are: `ground` `passenger_and_cargo_aircraft` `cargo_aircraft_only`	Declares that a package was prepared according to ground, passenger aircraft, or cargo aircraft only
`orderItemQuantities .hazmatInfo .packingInstructionCode`	Optional	String Ex.: `967`	The packing instruction code used for air transport
`orderItemQuantities .hazmatInfo.hazardClass`	Optional, but required if `category` is defined	String enumeration Values are: `class_1_explosive` `class_2_flammable_gas` `class_3_flammable_liquid` `class_4_flammable_solid` `class_5_organic_peroxide` `class_6_poisonous_material` `class_7_radioactive` `class_8_corrosive_material` `class_9_miscellaneous`	The hazard class of the hazmat
`orderItemQuantities .hazmatInfo .subsidiaryClasses`	Optional	String Ex.: `8.1`	The appropriate IATA/DOT subsidiary classes associated with the material and the hazard class
`orderItemQuantities .productTaxCode`	Optional	String	The tax code that applies to the given product
`orderItemQuantities .nmfcCode`	Optional	String	A string representing the narrow type of product being shipped; for example, bricks have an NMFC code of 32100.2 and steel pipes have an NMFC code of 51200.
`orderItemQuantities .nmfcFreightClass`	Optional	String	Useful for less-than-truckload (LTL) shipments string representing the broad class of product being shipped; for example, both bricks and steel pipes have an NMFC class of 50.
`orderItemQuantities .productId`	Required	String Ex.: `RN03947-Z43121`	A product ID for the product being checked, such as ISBN and UPC
`orderItemQuantities .quantity`	Required	Integer ($int32) Ex.: `3`	The number of units of this product
`orderItemQuantities .productDetails`	Optional, but required for international shipments and shipments containing hazardous materials	String Ex.: `perishable` -`limited_quantity` (or `lq`) `ormd` or (`orm-d`) `bound_printed_matter` (or `bpm`)	A list of properties that may affect the shipping of the product
`shipFromAddress .countryCode`	Required	String	The ISO 3166-1 country code for the origin address
`shipFromAddress .postalCode`	Required	String	A country-code-appropriate postal code for the origin address
`shipFromAddress .addressType`	Optional	String enumeration Values are: `commercial` `residential`	The type of location for the origin address
`shipFromAddress .company`	Optional	String	The company name for the origin address
`shipFromAddress.name`	Optional	String	The name of the contact for the origin address
`shipFromAddress .emailAddress`	Optional	String	The email address of the contact for the origin address
`shipFromAddress .phoneNumber`	Optional	String	The phone number of the contact for the origin address
`shipFromAddress .phoneNumber CountryCode`	Optional	String	The phone number country code of the contact for the origin address
`shipFromAddress.city`	Optional	String	The name of the city for the origin address
`shipFromAddress .state`	Optional	String	The two-letter postal abbreviation of the state for the origin address
`shipFromAddress .street1`	Optional	String	The first address line
`shipFromAddress .street2`	Optional	String	The second address line
`shipFromAddress .addressLineComponents`	Optional, but preferred for Mexican addresses	String Ex.: `streetName`: "Fovisste Fuentes Brotantes" `primaryAddressNumber`: "12" `secondaryAddressNumber`: "302" `district`: "Iztacalco" `neighborhood`: "Agrícola Pantitlán"	The address line components for the address, used for some international shipments. This is an optional object. The `street1` and `street2` fields should not be included if using `addressLineComponents`, or an error will be returned. This optional address object is not included in the example JSON requests for this API call. You can find out more about Mexican addresses in Non-U.S. Address Formats.
`originId`	Required, if `shipFromAddress` is not populated	String	The origin to which the order is assigned; it cannot be assigned if `shipFromAddress` is also populated.
`destinationAddress .countryCode`	Required	String	The ISO 3166-1 country code for the destination address
`destinationAddress .postalCode`	Required	String	A country-code-appropriate postal code for the destination address
`destinationAddress .addressType`	Required	String enumeration Values are: `commercial` `residential`	The type of location for the destination address
`destinationAddress .company`	Required	String	The company name for the destination address
`destinationAddress .name`	Required	String	The name of the contact for the destination address
`destinationAddress .emailAddress`	Required	String	The email address of the contact for the destination address
`destinationAddress .phoneNumber`	Required	String	The phone number of the contact for the destination address
`destinationAddress .phoneNumber CountryCode`	Required	String	The phone number country code of the contact for the destination address
`destinationAddress .city`	Required	String	The name of the city for the destination address
`destinationAddress .state`	Required	String	The 2-letter postal abbreviation of the state for the destination address
`destinationAddress .street1`	Required	String	The first destination address line
`destinationAddress .street2`	Required	String	The second destination address line
`destinationAddress .addressLineComponents`	Optional, but preferred for Mexican addresses	String Ex.: `streetName`: "Fovisste Fuentes Brotantes" `primaryAddressNumber`: "12" `secondaryAddressNumber`: "302" `district`: "Iztacalco" `neighborhood`: "Agrícola Pantitlán"	The address line components for the address, used for some international shipments. This is an optional object. The `street1` and `street2` fields should not be included if using `addressLineComponents`, or an error will be returned. This optional address object is not included in the example JSON requests for this API call. You can find out more about Mexican addresses in Non-U.S. Address Formats.
`shipOption`	Optional	String Ex.: `standard`	A high-level shipping option shown to or selected by a customer
`customsInfo .totalCustomsValue`	Optional	Float	The total customs value of the package in total customs value currency units
`customsInfo .totalCustomsValueCurrency`	Optional	String	The ISO 4217 currency code representing the `totalCustomsValue`
`customsInfo .customsDescription`	Optional	String	The detailed description of the items being shipped
`customsInfo .reasonForExport`	Optional	String enumeration Values are: `sale` `gift` `sample` `returns` `personal_effects`	The reason to export an international shipment
`customsInfo.invoiceDate`	Optional	String	Date when the invoice was created; ideally, this is the same as the ship date.
`customsInfo.invoiceNumber`	Optional	String	The Commercial Invoice number, if the Commercial Invoice was generated by your organization
`customsInfo .europeanUnionInfo .vendorIossNumber`	Optional	String	An Import One-Stop-Shop (IOSS) number is a 12-digit identification number that is used to pay the value-added tax (VAT) and declare imports to the European Union (EU). The IOSS number is a type of VAT identification, but it is not the same as a resident VAT registration.
`customsInfo .ultimateConsigneeAddress .name`	Optional	String	The name associated with the address of the person or company who receives the goods for end use
`customsInfo .ultimateConsigneeAddress .phoneNumber`	Optional	String	The phone number of the person or company who receives the goods for end use
`customsInfo .ultimateConsigneeAddress .phoneNumberCountryCode`	Optional	String	The phone number country code of the person or company who receives the goods for end use
`customsInfo .ultimateConsigneeAddress .emailAddress`	Optional	String	The email address of the person or company who receives the goods for end use
`customsInfo .ultimateConsigneeAddress .company`	Optional	String	The company name associated with the person or company who receives the goods for end use
`customsInfo .ultimateConsigneeAddress .street1`	Optional	String	The first address line of the person or company who receives the goods for end use
`customsInfo .ultimateConsigneeAddress .street2`	Optional	String	The second address line of the person or company who receives the goods for end use
`customsInfo .ultimateConsigneeAddress .city`	Optional	String	The name of the city for the address of the person or company who receives the goods for end use
`customsInfo .ultimateConsigneeAddress .state`	Optional	String	The state abbreviation for the address of the person or company who receives the goods for end use
`customsInfo .ultimateConsigneeAddress .countryCode`	Optional	String	The ISO 3166 1 country code for the address of the person or company who receives the goods for end use
`customsInfo .ultimateConsigneeAddress .postalCode`	Optional	String	A country code appropriate postal code for the address of the person or company who receives the goods for end use
`customsInfo .ultimateConsigneeAddress .addressType`	Optional	String enumeration Values are: `commercial` `residential`	The type of location for this address
`customsInfo .ultimateConsigneeAddress .addressLineComponents`	Optional, but preferred for Mexican addresses	String	The address line components for the address, used for some international shipments. This is an optional object. The `street1` and `street2` fields should not be included if using `addressLineComponents`, or an error will be returned. This optional address object is not included in the example JSON requests for this API call. You can find out more about Mexican addresses in Non-U.S. Address Formats .
`customsInfo .ultimateConsigneeType`	Optional	String enumeration Values are: `direct_consumer` `government_entity` `reseller`	The type of the ultimate consignee
`customsInfo .aesInternalTransactionNumber`	Optional	String	The number received if the Electronic Export Information (EEI) was filed and has been accepted in the Automated Export System (AES)
`customsInfo .electronicExportInformation .exportDate`	Optional	String ($local-date) Ex.: `2019-10-29`	The date the goods will be exiting the country
`customsInfo .electronicExportInformation .pointOfOrigin`	Optional	String	The 2-character state abbreviation from which the goods were shipped to the port of export
`customsInfo .b13AFilingOption`	Optional	String enumeration Values are: `not_required` `manually_attached` `filed_electronically` `summary_reporting` `carrier_to_stamp`	Specify the filing option being exercised; required for non-document shipments originating in Canada destined for any country other than Canada, the United States, Puerto Rico, or the U.S. Virgin Islands.
`customsInfo .exportComplianceStatement`	Optional	String	For U.S. export shipments requiring an EEI, enter the ITN number received from AES when you filed your shipment or the FTR (Foreign Trade Regulations) exemption number. The proper format for an ITN number is `AES XYYYYMMDDNNNNNN` where `YYYYMMDD` is date and `NNNNNN` are numbers generated by the AES. Ex: `AESX20220714987654` Note:* The ITN or FTR exemption number you submit in the ship request prints on the international shipping label. For CA export shipments, it can be Proof of report number (15-32 alphanumeric), Summary proof of report number (7-32 alphanumeric) or Exemption number (2 digit) based on the selected `b13AFilingOption`. Ex: `98765432107654321` (POR number), `7654321` (Summary POR number) and `02` (Exemption number). For FTR exemption number, you need provide a predefined value as `NO_EEI_30_37_A`.
`customsInfo .permitNumber`	Optional	String	This is a Permit Number. This field is applicable only to Canada export non-document shipments of any value to any destination. No special characters are allowed.
`customsInfo.customsItems .customsValue`	Optional	Float	The value of each individual item to report to customs in `customsValueCurrency`
`customsInfo.customsItems .customsValueCurrency`	Optional	String	The ISO 4217 currency code representing the `customsValue`
`customsInfo.customsItems .commodityDescription`	Optional	String	A description of this product to be provided to customs
`customsInfo.customsItems .countryOfManufacture`	Optional	String	The ISO 3166 2-digit country code that manufactured the this product
`customsInfo.customsItems .customsWeight.weightUnit`	Optional	String enumeration Values are: `g` (gram) `kg` (kilogram) `oz` (ounce) `lb` (pound)	The unit in which the weight is measured
`customsInfo.customsItems .customsWeight.weight`	Optional	Float	The actual weight in weight units
`customsInfo.customsItems .quantity`	Optional	Integer	The number of units of this customs item
`customsInfo.customsItems .productId`	Optional	String	A product ID for the customs item
`customsInfo.customsItems .quantityUnitOfMeasurement`	Optional	String enumeration Values are: `bag` `barrel` `box` `case_of_goods` `container` `crate` `cylinder` `envelope` `pallet` `piece` `roll` `tube`	The unit of measurement of the item
`customsInfo.customsItems .harmonizedTariffNumber`	Optional	String	The 6- to 15-digit Harmonized System Tariff classification code
`customsInfo.customsItems .commodityPartNumber`	Optional	String	The part number or reference number for the product
`customsInfo.customsItems .marksAndNumbers`	Optional	String	Any special marks, codes, and numbers that may identify the package
`customsInfo.customsItems .electronicExportCommodity Information.exportType`	Optional	String enumeration Values are: `domestic` `foreign`	The type of the export
`customsInfo.customsItems .electronicExportCommodity Information .exportInformationCode`	Optional	String	The 2-digit export information code for the commodity
`customsInfo.customsItems .electronicExportCommodity Information .scheduleBInformation .scheduleBNumber`	Optional	String	The 10-digit Schedule B classification code for the item being exported
`customsInfo.customsItems .electronicExportCommodity Information .scheduleBInformation .scheduleBQuantity`	Optional	Integer	The count of how many Schedule B units are in the shipment
`customsInfo.customsItems .electronicExportCommodity Information .scheduleBInformation .scheduleBUnitOfMeasurement`	Optional	String Values are: `barrels` `carat` `content_kilogram` `square_centimeter` `content_ton` `curie` `clean_yield_kilogram` `dozen` `dozen_pieces` `dozen_pairs` `fiber_meter` `gross_container` `gram` `gross` `hundred` `kilogram` `cubic_kilometer` `kilogram_total_sugars` `liter` `meter` `square_meter` `cubic_meter` `millicurie` `number` `pieces` `proof_liter` `pack` `pairs` `running_bales` `square` `ton` `thousand` `no_quantity_required`	The unit of measure for the Schedule B quantity
`customsInfo.customsItems .electronicExportCommodity Information .eccnNumber`	Optional	String	The 5-digit product ECCN number as issued by the Bureau of Industry and Security; the format is `#A###`.
`customsInfo.customsItems .electronicExportCommodity Information .exportLicenseInformation .licenseType`	Optional	String	The standard license type code as published by the U.S. government
`customsInfo.customsItems .electronicExportCommodity Information .exportLicenseInformation .licenseExemptionCode`	Optional	String	The license exemption code, if the license type does not require a license number
`customsInfo.customsItems .electronicExportCommodity Information .exportLicenseInformation .exportLicense .licenseNumber`	Optional	String	The license number
`customsInfo.customsItems .electronicExportCommodity Information .exportLicenseInformation .exportLicense .licenseLineValue`	Optional	Integer	The export monetary amount allowed per license
`customsInfo.customsItems .electronicExportCommodity Information .exportLicenseInformation .exportLicense .licenseExpiration`	Optional	String ($local-date) Ex.: `2019-10-29`	The license expiration date
`customsInfo.customsItems .b13AFilingOption`	Optional	String enumeration Values are: `not_required` `manually_attached` `filed_electronically` `summary_reporting` `carrier_to_stamp`	Specify the filing option being exercised; required for non-document shipments originating in Canada destined for any country other than Canada, the United States, Puerto Rico, or the U.S. Virgin Islands.
`customsInfo.customsItems .exportComplianceStatement`	Optional	String	For U.S. export shipments requiring an EEI, enter the ITN number received from AES when you filed your shipment or the FTR (Foreign Trade Regulations) exemption number. The proper format for an ITN number is `AES XYYYYMMDDNNNNNN` where `YYYYMMDD` is date and `NNNNNN` are numbers generated by the AES. Ex: `AESX20220714987654` Note:* The ITN or FTR exemption number you submit in the ship request prints on the international shipping label. For CA export shipments, it can be Proof of report number (15-32 alphanumeric), Summary proof of report number (7-32 alphanumeric) or Exemption number (2 digit) based on the selected `b13AFilingOption`. Ex: `98765432107654321` (POR number), `7654321` (Summary POR number) and `02` (Exemption number). For FTR exemption number, you need provide a predefined value as `NO_EEI_30_37_A`.
`customsInfo.incoterm`	Optional	String enumeration Values are: `ddp` (delivery duty paid; the seller delivers the shipment in the foreign country to the named place and assumes all costs, risk, and responsibilities of the shipping process) `ddu` (delivery duty unpaid; the seller delivers the shipment in the foreign country to the named place, and the buyer is responsible for import duties, taxes, and customs clearance) `dap` (delivered at place; the seller arranges and pays for delivery of goods, and the buyer handles import clearance and unloading and in-country transport) `dpu` (delivered at place unloaded; the seller arranges and pays for delivery of goods and is responsible for unloading goods at the destination point) `fca` (free carrier; the seller delivers the goods to a named place and is responsible for export clearance, and the buyer is then responsible for the shipment)	The incoterm , or international commerce term, defines the delivery duty responsibility for buyers and sellers for any mode of transport
`totalDeclaredValue .declaredValue`	Optional	Float	The value to be passed through as the total declared value, which is the total monetary amount of the declared value for the package. This is what will be reimbursed if the package is damaged. If the declared value exceeds the carrier's free threshold, there may a surcharge for passing a declared value.
`totalDeclaredValue .currencyCode`	Optional	String	The currency code for the declared value
`orderFulfillmentParameters`	Optional		These represent hints that correspond to `shipmentParameters` that can be specified ahead of shipment creation on the order. These can be overridden at the time of shipment creation.
`orderFulfillmentParameters .saturdayDelivery`	Optional	Boolean `true` or `false`	Some carrier service methods deliver on Saturday for free, whereas some charge an additional fee for Saturday delivery. If you do not want to incur extra charges for Saturday delivery, this flag should be set to `false`, which is the default setting. Service methods that deliver for free on Saturday will still be considered during carrier selection. However, if you are willing to incur more cost and upgrade the carrier service method to meet a Saturday delivery, you can set this flag to `true`. If this flag is `true`, only carrier service methods that can deliver on Saturday will be considered. All other service methods will be filtered out of carrier selection. Note:* Setting this flag to true does not guarantee a Saturday delivery, which is dependent upon the carrier. If you have included a desired delivery date (DDD) of Saturday or Sunday, setting this flag to false does not impact the DDD for a Saturday delivery.
`orderFulfillmentParameters .thirdPartyBillingSetId`	Optional	String	Either the Shipium third party billing set ID or the third party billing set ID provided by your organization. When present, this is used to indicate the third party billing set that should be used for the billing of the shipment.
`orderFulfillmentParameters .forceThirdPartyBilling`	Optional	Boolean `true` or `false`	If `true`, this indicates that third party billing is a requirement for this shipment. No service method should be selected that does not support third party billing.
`orderFulfillmentParameters .fulfillmentContext`	Required	String	The fulfillment context tag value
`orderFulfillmentParameters .fulfillmentContextId`	Required	String	The fulfillment context ID
`orderFulfillmentParameters .holdAtLocation .useHoldAtLocation`	Optional	Boolean `true` or `false`	If `true`, this indicates that the package should be held at a carrier location for pickup.
`orderFulfillmentParameters .holdAtLocation .holdAtLocationId`	Optional	String	An optional unique identifier for the designated hold location
`orderFulfillmentParameters .referenceIdentifier`	Optional	String	String passed to carriers as a reference; this field can be expanded to include multiple reference identifiers by adding sequential numbers to the field name: `referenceIdentifier2` (up to 5 reference identifiers)
`orderFulfillmentParameters .partnerReferenceIdentifier`	Optional	String	A unique identifier string supplied by your organization, passed to carriers as a reference
`orderFulfillmentParameters .partnerReferenceIdentifier2`	Optional	String	A unique identifier string supplied by your organization, passed to carriers as a reference
`orderFulfillmentParameters .packagingType .packagingMaterial`	Optional	String enumeration Values are: `box` `envelope` `flat_pack` `mailing_tube` `parcel_pallet`	The type of packaging used to create the package for the shipment
`orderFulfillmentParameters .packagingType .packagingSizeName`	Optional	String Ex.: `13x12x10 box`	A custom name for the packaging
`orderFulfillmentParameters .packagingType .packagingTypeId`	Optional, but required if `linearDimensions` is not provided	String Ex.: `ebd94f8b-d390-4c9c-987f-b88343f5bf45`	The `packagingTypeId` that was used for this package; when this value is present, the dimensions pre-configured by your organization are used. When this value is absent, `linearDimensions` is required.
`orderFulfillmentParameters .packagingType .linearDimensions .linearUnit`	Optional, but required if the `packagingTypeId` is not included	String enumeration Values are: `cm` (centimeter) `in` (inch)	The unit in which linear dimensions are provided
`orderFulfillmentParameters .packagingType .linearDimensions.length`	Optional, but required if the `packagingTypeId` is not included	Number ($float) Ex.: `13`	The longest linear dimension (i.e., the longest side of a box or envelope)
`orderFulfillmentParameters .linearDimensions.width`	Optional, but required if the `packagingTypeId` is not included	Number ($float) Ex.: `12`	The second longest linear dimension (i.e., the second longest side of a box or envelope)
`orderFulfillmentParameters .linearDimensions.height`	Optional, but required if the `packagingTypeId` is not included	Number ($float) Ex.: `10`	The least long linear dimension (i.e., the shortest side of a box or envelope). 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.
`orderFulfillmentParameters .packagingType .packagingWeight.weightUnit`	Optional	String enumeration Values are: `g` (gram) `kg` (kilogram) `lb` (pound) `oz` (ounce)	The unit in which weight values are provided
`orderFulfillmentParameters .packagingType .packagingWeight.weight`	Optional	Number ($float) Ex.: `50`	The value of the weight
`orderFulfillmentParameters .totalWeight.weightUnit`	Optional	String enumeration Values are: `g` (gram) `kg` (kilogram) `lb` (pound) `oz` (ounce)	The unit in which weight values are provided
`orderFulfillmentParameters .totalWeight.weight`	Optional	Number ($float) Ex.: `50`	The value of the weight
`orderFulfillmentParameters .splitOrder`	Optional	Boolean `true` or `false`	When `true`, this is a signal that the order will be split into multiple shipments. If this is `true`, the `splitParameters` field must be included in the call to provide information on the makeup of the shipments to fulfill the order. The default value is `false`.
`orderFulfillmentParameters .splitParameters`	Conditional	Array	When `splitOrder` is `true`, this array of fields must be included to provide the definition of the makeup of the shipments the order is split into.

The response attributes for creating an order are defined in the following table. Response attributes with associated request field descriptions in the table above are not included here.

Response attribute	Description
`fulfillmentType`	Fulfillment methodology of the shipment
`orderSource`	The source of this order whether it is from the Shipium system or externally created
`tenantId`	Either the Shipium tenant ID or the tenant ID your organization configured in the Shipium system; when present, this is used to indicate the tenant associated with the shipment.
`shipiumOrderId`	Identification use to represent the group of delivery estimates purchased
`partnerOrderId`	The unique identifier representing this order
`orderedDateTime`	The timestamp for when the customer ordered the product; the timestamp is an ISO 8601 timestamp.
`orderItemQuantities`	A list of order items comprising the shipment
`orderItemQuantities.deliveryEstimateId`	The delivery estimate ID associated with the product
`associatedIdentifiers`	Associated identifiers that are indexed to identify this order; for example, this can be an LPN that is bound to the order.
`shipOption`	A high-level shipping option shown to or selected by a customer
`originId`	The origin to which the order is assigned
`shipFromAddress`	The address of the location where the package is being shipped
`destinationAddress`	The address of the location where the package is being delivered
`customsInfo`	Customs information about the package for international shipping
`totalDeclaredValue`	The total monetary amount of the declared value for the package
`orderFulfillmentParameters`	These represent hints that correspond to Shipment Parameters that can be specified ahead of shipment creation on the order. These can be overridden at the time of shipment creation.
`orderStatus`	State of the order

Submit an order

The endpoint for submitting an order for fulfillment with the Pack App API is included in the table below.

API type	API endpoint
POST	`/api/v1/packShip/order/{orderId}/submit`

Required path element. orderId (Replace with either Shipium's order identifier or your own, if provided when the order was created.)

Example cURL call to submit an order

This example shows a request to submit an order for standard fulfillment.

curl --request POST \
--url https://api.shipium.com/api/v1/packShip/order/4dc43fff-c3af-4d7b-8a18-e01f2b4cb312/submit \
--header 'accept: application/json' \
--header $AUTHSTRING \
--header 'content-type: application/json' \
--data 'INSERT REQUEST BODY FROM BELOW'

Example request body to submit an order for a standard complete shipment

{
  "generateLabel": true,
  "packagingType": {
    "packagingMaterial": "box",
    "linearDimensions": {
      "linearUnit": "in",
      "length": 12.0,
      "width": 10.0,
      "height": 8.0
    },
    "packagingWeight": {
      "weightUnit": "lb",
      "weight": 0.5
    }
  },
  "totalWeight": {
    "weightUnit": "lb",
    "weight": 3.2
  },
  "labelParameters": {
    "labelFormats": ["pdf", "png"],
    "includeLabelImagesInResponse": true,
    "testMode": false,
    "eligibleForManifest": true
  },
  "shipmentParameters": {
    "currencyCode": "USD",
    "shippedDateTime": "2025-01-15T10:00:00Z",
    "desiredDeliveryDate": "2025-01-17T17:00:00Z"
  },
  "carrierSelectionOptions": {
    "carrierServiceMethodAllowList": ["ups-ground-service-method", "fedex-ground-service-method"]
  }
}

Example response body for standard complete shipment order submit

{
  "fulfillmentType": "customer",
  "orderSource": "external",
  "tenantId": "tenant-123",
  "shipiumOrderId": "4dc43fff-c3af-4d7b-8a18-e01f2b4cb312",
  "partnerOrderId": "partner-order:12345",
  "orderedDateTime": "2025-01-15T08:00:00.000Z",
  "orderItemQuantities": [
    {
      "productId": "SKU-12345",
      "quantity": 3
    }
  ],
  "associatedIdentifiers": [],
  "destinationAddress": {
    "name": "Wile E. Coyote",
    "street1": "123 Main St.",
    "city": "Albuquerque",
    "state": "NM",
    "countryCode": "US",
    "postalCode": "87121",
    "addressType": "residential"
  },
  "orderStatus": "complete",
  "orderFulfillmentInfo": {
    "shipments": [
      {
        "shipiumShipmentId": "ship-001-abc123",
        "partnerShipmentId": null,
        "shipiumOrderId": "4dc43fff-c3af-4d7b-8a18-e01f2b4cb312",
        "partnerOrderId": "partner-order:12345",
        "type": "complete",
        "carrierTrackingId": "1Z999AA1234567890",
        "carrier": "ups",
        "carrierServiceMethodId": "ups-ground-service-method",
        "orderItemQuantities": [
          {
            "productId": "SKU-12345",
            "quantity": 3
          }
        ]
      }
    ],
    "unfulfilledItems": []
  }
}

Example request body to submit a split order (runtime split)

{
  "generateLabel": true,
  "splitOrder": true,
  "splitParameters": {
    "reasonCode": "item_size",
    "orderItemQuantities": [
      {
        "productId": "SKU-12345",
        "quantity": 2
      }
    ]
  },
  "packagingType": {
    "packagingMaterial": "box",
    "linearDimensions": {
      "linearUnit": "in",
      "length": 10.0,
      "width": 8.0,
      "height": 6.0
    }
  },
  "totalWeight": {
    "weightUnit": "lb",
    "weight": 2.0
  },
  "labelParameters": {
    "labelFormats": ["pdf"],
    "includeLabelImagesInResponse": true,
    "testMode": false
  },
  "shipmentParameters": {
    "currencyCode": "USD"
  }
}

Example response body for runtime split order submit (first split)

{
  "fulfillmentType": "customer",
  "orderSource": "external",
  "shipiumOrderId": "4dc43fff-c3af-4d7b-8a18-e01f2b4cb312",
  "partnerOrderId": "partner-order:12345",
  "orderedDateTime": "2025-01-15T08:00:00.000Z",
  "orderItemQuantities": [
    {
      "orderItemReferenceIdentifier": "partner-order:12334_item:1",
      "productId": "SKU-12345",
      "quantity": 5
    }
  ],
  "destinationAddress": {
    "name": "Wile E. Coyote",
    "street1": "123 Main St.",
    "city": "Albuquerque",
    "state": "NM",
    "countryCode": "US",
    "postalCode": "87121",
    "addressType": "residential"
  },
  "orderStatus": "partial_ship",
  "orderFulfillmentInfo": {
    "shipments": [
      {
        "shipiumShipmentId": "ship-002-def456",
        "partnerShipmentId": null,
        "shipiumOrderId": "4dc43fff-c3af-4d7b-8a18-e01f2b4cb312",
        "partnerOrderId": "partner-order:12345",
        "parametersReferenceId": "runtime-split-001",
        "type": "split",
        "carrierTrackingId": "1Z999AA1234567891",
        "carrier": "UPS",
        "carrierServiceMethodId": "ups-ground-service-method",
        "orderItemQuantities": [
          {
            "orderItemReferenceIdentifier": "partner-order:12334_item:1",
            "productId": "SKU-12345",
            "quantity": 2
          }
        ]
      }
    ],
    "unfulfilledItems": [
      {
        "orderItemReferenceIdentifier": "partner-order:12334_item:1",
        "productId": "SKU-12345",
        "quantity": 3
      }
    ]
  }
}

Example request body to submit a split order (pre-defined split reference)

{
  "generateLabel": true,
  "splitOrder": true,
  "splitReferenceId": "split-001",
  "packagingType": {
    "packagingMaterial": "envelope",
    "linearDimensions": {
      "linearUnit": "in",
      "length": 9.0,
      "width": 6.0,
      "height": 1.0
    }
  },
  "totalWeight": {
    "weightUnit": "lb",
    "weight": 0.5
  },
  "labelParameters": {
    "labelFormats": ["pdf", "zpl"],
    "includeLabelImagesInResponse": false,
    "testMode": false
  },
  "shipmentParameters": {
    "currencyCode": "USD",
    "saturdayDelivery": false
  }
}

Example response body for pre-defined split order submit (using reference ID)

{
  "fulfillmentType": "customer",
  "orderSource": "external",
  "shipiumOrderId": "4dc43fff-c3af-4d7b-8a18-e01f2b4cb312",
  "partnerOrderId": "partner-order:12345",
  "orderedDateTime": "2025-01-15T08:00:00.000Z",
  "orderItemQuantities": [
    {
      "orderItemReferenceIdentifier": "partner-order:12334_item:1",
      "productId": "SKU-12345",
      "quantity": 5
    }
  ],
  "destinationAddress": {
    "name": "Wile E. Coyote",
    "street1": "123 Main St.",
    "city": "Albuquerque",
    "state": "NM",
    "countryCode": "US",
    "postalCode": "87121",
    "addressType": "residential"
  },
  "orderFulfillmentParameters": {
    "splitOrder": true,
    "splitParameters": [
      {
        "splitReferenceId": "split-001",
        "reasonCode": "customer_request",
        "fulfilled": true,
        "orderItemQuantities": [
          {
            "orderItemReferenceIdentifier": "partner-order:12334_item:1",
            "productId": "SKU-12345",
            "quantity": 2
          }
        ]
      }
    ]
  },
  "orderStatus": "partial_ship",
  "orderFulfillmentInfo": {
    "shipments": [
      {
        "shipiumShipmentId": "ship-003-ghi789",
        "partnerShipmentId": null,
        "shipiumOrderId": "4dc43fff-c3af-4d7b-8a18-e01f2b4cb312",
        "partnerOrderId": "partner-order:12345",
        "parametersReferenceId": "split-001",
        "type": "split",
        "carrierTrackingId": "1Z999AA1234567892",
        "carrier": "FedEx",
        "carrierServiceMethodId": "fedex-ground-service-method",
        "orderItemQuantities": [
          {
            "orderItemReferenceIdentifier": "partner-order:12334_item:1",
            "productId": "SKU-12345",
            "quantity": 2
          }
        ]
      }
    ],
    "unfulfilledItems": [
      {
        "orderItemReferenceIdentifier": "partner-order:12334_item:1",
        "productId": "SKU-12345",
        "quantity": 3
      }
    ]
  }
}

Request and response fields for submitting an order

The following table provides required and optional fields for calling the Pack App API to submit an order. You can find additional support in the Pack App API Reference.

Field	Required	Type	Description
`generateLabel`	Optional	Boolean `true` or `false`	When `true`, a request to the selected carrier will be sent to generate a label for the shipment based on the information provided in the `labelParameters` field of this object. When `false`, this step is skipped and the system will record what carrier service method would have generated a label for. The default value is `true`.
`packagingType.packagingMaterial`	Optional	String enumeration Values are: `box` `envelope` `flat_pack` `mailing_tube` `parcel_pallet`	The type of packaging used
`packagingType.packagingSizeName`	Optional	String Ex.: `13x12x10 box`	A custom name for the packaging
`packagingType.packagingTypeId`	Optional, but required if `linearDimensions` is not provided	String Ex.: `ebd94f8b-d390-4c9c-987f-b88343f5bf45`	The `packagingTypeId` that was used for this package; when this value is present, the dimensions pre-configured by your organization are used. When this value is absent, `linearDimensions` is required.
`packagingType.linearDimensions .linearUnit`	Required (if `linearDimensions` provided)	String enumeration Values are: `in` (inch) `cm` (centimeter)	The unit in which linear dimensions are provided
`packagingType.linearDimensions .length`	Required (if `linearDimensions` provided)	Number	The longest linear dimension (i.e., the longest side of a box or envelope)
`packagingType.linearDimensions .width`	Required (if `linearDimensions` provided)	Number	The second longest linear dimension (i.e., the second longest side of a box or envelope)
`packagingType.linearDimensions .height`	Required (if `linearDimensions` provided)	Number	The least long linear dimension (i.e., the shortest side of a box or envelope). 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.
`packagingType.packagingWeight .weightUnit`	Required (if `packagingWeight` provided)	String enumeration Values are: `g` (gram) `kg` (kilogram) `oz` (ounce) `lb` (pound)	The unit in which weight values are provided
`packagingType.packagingWeight .weight`	Required (if `packagingWeight` provided)	Number	The value of the packaging weight
`totalWeight.weightUnit`	Required (if `totalWeight` provided)	String enumeration Values are: `g` (gram) `kg` (kilogram) `oz` (ounce) `lb` (pound)	The unit in which weight values are provided
`totalWeight.weight`	Required (if `totalWeight` provided)	Number (float)	The value of the weight.
`labelParameters.labelFormats`	Optional	Array of strings Values are: `pdf` `png` `zpl`	List of formats in which to generate the package label
`labelParameters .includeLabelImagesInResponse`	Optional	Boolean `true` or `false`	When `true`, the response includes raw image data of generated labels.
`labelParameters.testMode`	Optional	Boolean `true` or `false`	When `true`, calls will be made to carrier sandbox servers. No actual labels are created, only a representation of the label. No money is charged to the underlying account.
`labelParameters .eligibleForManifest`	Optional	Boolean `true` or `false`	When `true` or `null`, the label will be included in end-of-day and scheduled manifests. A `false` value indicates the label should not be manifested.
`shipmentParameters .currencyCode`	Required (if `shipmentParameters` is provided)	String Ex.: `USD`	Currency in which all rates for shipping carrier selection costs will be calculated
`shipmentParameters .shippedDateTime`	Optional	String	Timestamp for when you shipped the product from your warehouse in ISO 8601 format
`shipmentParameters .desiredDeliveryDate`	Optional	String	The date and time the package is intended to arrive to the customer in ISO 8601 date-time format
`shipmentParameters .saturdayDelivery`	Optional	Boolean `true` or `false`	Some carrier service methods deliver on Saturday for free, whereas some charge an additional fee for Saturday delivery. If you do not want to incur extra charges for Saturday delivery, this flag should be set to `false`, which is the default setting. Service methods that deliver for free on Saturday will still be considered during carrier selection. However, if you are willing to incur more cost and upgrade the carrier service method to meet a Saturday delivery, you can set this flag to `true`. If this flag is `true`, only carrier service methods that can deliver on Saturday will be considered. All other service methods will be filtered out of carrier selection. Note:* Setting this flag to true does not guarantee a Saturday delivery, which is dependent upon the carrier. If you have included a desired delivery date (DDD) of Saturday or Sunday, setting this flag to false does not impact the DDD for a Saturday delivery.
`shipmentParameters .referenceIdentifier`	Optional	String	String passed to carriers as a reference; this field can be expanded to include multiple reference identifiers by adding sequential numbers to the field name: `referenceIdentifier2` (up to 5 reference identifiers)
`shipmentParameters .partnerReferenceIdentifier`	Optional	String	A unique identifier string supplied by your organization, passed to carriers as a reference
`shipmentParameters .partnerReferenceIdentifier2`	Optional	String	A unique identifier string supplied by your organization, passed to carriers as a reference
`carrierSelectionOptions .carrierServiceMethodAllowList`	Optional	Array of strings	List of `carrierServiceMethodId` and/or `carriers` that should be considered for selection
`splitOrder`	Optional	Boolean `true` or `false`	When `true`, this is a signal that the order submit will execute a split shipment. The default value is `false`.
`splitReferenceId`	Conditional	String	When `splitOrder` is `true`, this field references a pre-defined split in the order. If both this field and `splitParameters` are provided, this field will be used to execute the split.
`splitParameters`	Conditional	Object	When `splitOrder` is `true`, this field is used to define a ad hoc runtime split of items from the referenced order. If both this field and `splitReferenceId` are provided, `splitReferenceId` will be used to execute the split.
`splitParameters.reasonCode`	Optional	String enumeration Values are: `customer_request` `item_size` `stock_not_available`	Defines the reason for breaking the order into multiple shipments
`splitParameters .orderItemQuantities .orderItemReferenceIdentifier`	Optional	String	An external identifier that can reference the order item
`splitParameters .orderItemQuantities.productId`	Conditional (required if `splitParameters` are provided)	String	A product ID for the product (e.g., SKU, UPC)
`splitParameters .orderItemQuantities.quantity`	Conditional (required if `splitParameters` are provided)	Integer	The number of units of this product

The response attributes for submitting an order are defined in the following table. Response attributes with associated request field descriptions in the table above are not included here.

Field	Description
`fulfillmentType`	Fulfillment methodology of the shipment (`customer`, `at_large`, `returns`, `hundredweight`, `reship`, `unknown`)
`orderSource`	Source of the order (`shipium`, `external`)
`tenantId`	Either the Shipium tenant ID or the partner-provided tenant ID
`shipiumOrderId`	The Shipium-generated unique identifier for the order
`partnerOrderId`	Your organization's own unique identifier for the order
`orderedDateTime`	Timestamp when the customer ordered the product (ISO-8601 format)
`orderItemQuantities`	Array of all order items with quantities
`associatedIdentifiers`	Associated identifiers indexed to identify this order (e.g., LPN); can be searched but not interchangeable with `orderId`
`destinationAddress`	Shipping destination address information.
`orderStatus`	Current state of the order (`open`, `open_split`, `complete`, `complete_multiship`, `cancelled`, `partial_ship`, `error`)
`orderFulfillmentParameters .splitParameters.fulfilled`	When `true`, there has been a shipment generated for this set of order split parameters and the items referenced in the split parameters of the order are accounted for as shipping / shipped.
`orderFulfillmentInfo`	Information about shipments fulfilling the order and remaining items
`orderFulfillmentInfo.shipments`	Array of shipments generated to fulfill order items
`orderFulfillmentInfo.unfulfilledItems`	Array of items remaining to be shipped

Split an order

Split shipments functionality is integrated into the Pack App order submission process. To split shipments, you use the standard submit endpoint with additional split parameters. You can only create one split shipment per submit call. If you need to split an order into multiple shipments (e.g., 2 boxes), you'll need to make multiple calls to the submit endpoint with the different split configurations.

The endpoint for submitting a split shipment is the same as the standard order submission:

API type	API endpoint
POST	https://api.shipium.com/api/v1/packShip/order/{orderId}/submit

There are two ways to split an order: runtime splits and pre-defined splits.

Runtime splits

This workflow is used when you want to define the split at the time of submission.

1. Create an order

First, you'll create an order using a standard call to POST /api/v1/packShip/order.

2. Submit the first split (runtime)

Next, you'll submit the first split by calling POST /api/v1/packShip/order/{orderId}/submit and defining the split in the splitParameters object.

Example request body for runtime split

{
  "generateLabel": true,
  "splitOrder": true,
  "splitParameters": {
    "reasonCode": "item_size",
    "orderItemQuantities": [
      {
        "orderItemReferenceIdentifier": "partner-order:12334_item:1",
        "productId": "SKU-12345",
        "quantity": 2
      }
    ]
  },
  "packagingType": {
    "packagingMaterial": "box",
    "linearDimensions": {
      "linearUnit": "in",
      "length": 10.0,
      "width": 8.0,
      "height": 6.0
    }
  },
  "totalWeight": {
    "weightUnit": "lb",
    "weight": 2.0
  },
  "labelParameters": {
    "labelFormats": [
      "pdf"
    ],
    "includeLabelImagesInResponse": true,
    "testMode": false
  },
  "shipmentParameters": {
    "currencyCode": "USD"
  }
}

Example response body for runtime split

{
  "fulfillmentType": "customer",
  "orderSource": "external",
  "shipiumOrderId": "4dc43fff-c3af-4d7b-8a18-e01f2b4cb312",
  "partnerOrderId": "partner-order:12345",
  "orderedDateTime": "2025-01-15T08:00:00.000Z",
  "orderItemQuantities": [
    {
      "orderItemReferenceIdentifier": "partner-order:12334_item:1",
      "productId": "SKU-12345",
      "quantity": 5
    }
  ],
  "destinationAddress": {
    "name": "Wile E. Coyote",
    "street1": "123 Main St.",
    "city": "Albuquerque",
    "state": "NM",
    "countryCode": "US",
    "postalCode": "87121",
    "addressType": "residential"
  },
  "orderStatus": "partial_ship",
  "orderFulfillmentInfo": {
    "shipments": [
      {
        "shipiumShipmentId": "ship-002-def456",
        "partnerShipmentId": null,
        "shipiumOrderId": "4dc43fff-c3af-4d7b-8a18-e01f2b4cb312",
        "partnerOrderId": "partner-order:12345",
        "parametersReferenceId": "runtime-split-001",
        "type": "split",
        "carrierTrackingId": "1Z999AA1234567891",
        "carrier": "UPS",
        "carrierServiceMethodId": "ups-ground-service-method",
        "orderItemQuantities": [
          {
            "orderItemReferenceIdentifier": "partner-order:12334_item:1",
            "productId": "SKU-12345",
            "quantity": 2
          }
        ]
      }
    ],
    "unfulfilledItems": [
      {
        "orderItemReferenceIdentifier": "partner-order:12334_item:1",
        "productId": "SKU-12345",
        "quantity": 3
      }
    ]
  }
}

Pre-defined splits

This workflow is used when you want to define the splits on the order object ahead of time and then reference them during submission.

1. Create an order with pre-defined splits

First, you'll create an order by calling POST /api/v1/packShip/order, with the splitOrder flag set to true and define the splits in the splitParameters array.

Example request body for creating an order with pre-defined splits

{
  "fulfillmentType": "customer",
  "orderSource": "external",
  "partnerOrderId": "partner-order:12345",
  "orderedDateTime": "2025-03-15T10:10:00.111111Z",
  "orderItemQuantities": [
    {
      "orderItemReferenceIdentifier": "partner-order:12334_item:1",
      "productId": "SKU-12345",
      "quantity": 5
    }
  ],
  "destinationAddress": {
    "name": "Wile E. Coyote",
    "street1": "123 Main St.",
    "city": "Albuquerque",
    "state": "NM",
    "countryCode": "US",
    "postalCode": "87121"
  },
  "orderFulfillmentParameters": {
    "splitOrder": true,
    "splitParameters": [
      {
        "splitReferenceId": "split-A",
        "reasonCode": "item_size",
        "orderItemQuantities": [
          {
            "orderItemReferenceIdentifier": "partner-order:12334_item:1",
            "productId": "SKU-12345",
            "quantity": 2
          }
        ]
      },
      {
        "splitReferenceId": "split-B",
        "reasonCode": "item_size",
        "orderItemQuantities": [
          {
            "orderItemReferenceIdentifier": "partner-order:12334_item:1",
            "productId": "SKU-12345",
            "quantity": 3
          }
        ]
      }
    ]
  }
}

2. Submit a pre-defined split

Next, you'll submit one of the pre-defined splits by calling POST /api/v1/packShip/order/{orderId}/submit and referencing the splitReferenceId.

Example request body for submitting a pre-defined split

{
  "generateLabel": true,
  "splitOrder": true,
  "splitReferenceId": "split-A",
  "packagingType": {
    "packagingMaterial": "box",
    "linearDimensions": {
      "linearUnit": "in",
      "length": 10.0,
      "width": 8.0,
      "height": 6.0
    }
  },
  "totalWeight": {
    "weightUnit": "lb",
    "weight": 2.0
  },
  "labelParameters": {
    "labelFormats": [
      "pdf"
    ],
    "includeLabelImagesInResponse": true,
    "testMode": false
  }
}

Example response body for submitting a pre-defined split

{
  "fulfillmentType": "customer",
  "orderSource": "external",
  "shipiumOrderId": "4dc43fff-c3af-4d7b-8a18-e01f2b4cb312",
  "partnerOrderId": "partner-order:12345",
  "orderedDateTime": "2025-01-15T08:00:00.000Z",
  "orderItemQuantities": [
    {
      "orderItemReferenceIdentifier": "partner-order:12334_item:1",
      "productId": "SKU-12345",
      "quantity": 5
    }
  ],
  "destinationAddress": {
    "name": "Wile E. Coyote",
    "street1": "123 Main St.",
    "city": "Albuquerque",
    "state": "NM",
    "countryCode": "US",
    "postalCode": "87121",
    "addressType": "residential"
  },
  "orderFulfillmentParameters": {
    "splitOrder": true,
    "splitParameters": [
      {
        "splitReferenceId": "split-A",
        "reasonCode": "item_size",
        "fulfilled": true,
        "orderItemQuantities": [
          {
            "orderItemReferenceIdentifier": "partner-order:12334_item:1",
            "productId": "SKU-12345",
            "quantity": 2
          }
        ]
      },
      {
        "splitReferenceId": "split-B",
        "reasonCode": "item_size",
        "fulfilled": false,
        "orderItemQuantities": [
          {
            "orderItemReferenceIdentifier": "partner-order:12334_item:1",
            "productId": "SKU-12345",
            "quantity": 3
          }
        ]
      }
    ]
  },
  "orderStatus": "partial_ship",
  "orderFulfillmentInfo": {
    "shipments": [
      {
        "shipiumShipmentId": "ship-003-ghi789",
        "partnerShipmentId": null,
        "shipiumOrderId": "4dc43fff-c3af-4d7b-8a18-e01f2b4cb312",
        "partnerOrderId": "partner-order:12345",
        "parametersReferenceId": "split-A",
        "type": "split",
        "carrierTrackingId": "1Z999AA1234567892",
        "carrier": "FedEx",
        "carrierServiceMethodId": "fedex-ground-service-method",
        "orderItemQuantities": [
          {
            "orderItemReferenceIdentifier": "partner-order:12334_item:1",
            "productId": "SKU-12345",
            "quantity": 2
          }
        ]
      }
    ],
    "unfulfilledItems": [
      {
        "orderItemReferenceIdentifier": "partner-order:12334_item:1",
        "productId": "SKU-12345",
        "quantity": 3
      }
    ]
  }
}

How to submit remaining items for split shipments

After you have created one or more split shipments, you can submit the remaining items of the order in a final shipment. To do this, you make a standard call to the POST /api/v1/packShip/order/{orderId}/submit endpoint without including the splitOrder, splitReferenceId, or splitParameters fields. This will create a final shipment containing all remaining unfulfilled items from the order.

Example request body to submit remaining items

{
  "generateLabel": true,
  "packagingType": {
    "packagingMaterial": "box",
    "linearDimensions": {
      "linearUnit": "in",
      "length": 12.0,
      "width": 10.0,
      "height": 8.0
    }
  },
  "totalWeight": {
    "weightUnit": "lb",
    "weight": 1.2
  },
  "labelParameters": {
    "labelFormats": [
      "pdf"
    ],
    "includeLabelImagesInResponse": true,
    "testMode": false
  },
  "shipmentParameters": {
    "currencyCode": "USD"
  }
}

Example response body for submitting remaining items

{
  "fulfillmentType": "customer",
  "orderSource": "external",
  "shipiumOrderId": "4dc43fff-c3af-4d7b-8a18-e01f2b4cb312",
  "partnerOrderId": "partner-order:12345",
  "orderedDateTime": "2025-01-15T08:00:00.000Z",
  "orderItemQuantities": [
    {
      "orderItemReferenceIdentifier": "partner-order:12334_item:1",
      "productId": "SKU-12345",
      "quantity": 5
    }
  ],
  "destinationAddress": {
    "name": "Wile E. Coyote",
    "street1": "123 Main St.",
    "city": "Albuquerque",
    "state": "NM",
    "countryCode": "US",
    "postalCode": "87121",
    "addressType": "residential"
  },
  "orderStatus": "complete_multiship",
  "orderFulfillmentInfo": {
    "shipments": [
      {
        "shipiumShipmentId": "ship-002-def456",
        "partnerShipmentId": null,
        "shipiumOrderId": "4dc43fff-c3af-4d7b-8a18-e01f2b4cb312",
        "partnerOrderId": "partner-order:12345",
        "

Request and response fields for split shipments

The following table provides required and optional fields for split shipment functionality added to the standard submit request.

Field	Required	Type	Description
`splitOrder`	Required for splits	Boolean `true` or `false`	Set to `true` to enable split shipment mode.
`splitReferenceId`	Conditional	String	Reference to a pre-defined split parameter set on the order; use this OR `splitParameters`, but not both.
`splitParameters`	Conditional	Object	Runtime definition of split parameters; use this OR `splitReferenceId`, but not both.
`splitParameters.reasonCode`	Required if using `splitParameters`	String enumeration Values are: `stock_not_available` `item_size_exceeds_box_limits` `customer_request`	The reason for splitting the shipment
`splitParameters.orderItemQuantities`	Required if using `splitParameters`	Array of item quantity objects	Items to include in this split shipment
`splitParameters.orderItemQuantities .orderItemReferenceIdentifier`	Required if using `splitParameters`	String	The order item reference identifier from the original order
`splitParameters.orderItemQuantities .productId`	Required if using `splitParameters`	String	A product ID for the product being checked, such as ISBN or UPC; a `productId` is required for each item within the `orderItemQuantities` array when you are defining a split at runtime.
`splitParameters.orderItemQuantities .quantity`	Required if using `splitParameters`	Number	The quantity of this item to include in the split shipment; must be > 0 and ≤ remaining quantity on the referenced order item

The response includes standard shipment fields plus these split-specific attributes.

Attribute	Description
`type`	Will be `split` for split shipments
`referenceId`	The split reference ID if one was used
`shipiumOrderId`	The original order ID that was split
`orderItemQuantities`	Items included in this specific split shipment

Tracking split orders

When you retrieve an order (Get an Order) that has been split using GET /api/v1/packShip/order/{orderId}, the response will include:

fulfillmentInfo.shipments. An array of shipment objects that have been created for the order
fulfillmentInfo.unfulfilledItems. An array of items that are not yet fulfilled for a split order

This allows you to track the progress of each split and identify any remaining unfulfilled items.

Search an order

The search endpoint returns results in pages. Order search results will contain the following response headers with data on how to access the previous and next pages in the total body of results based on the count (page size) request parameter you pass in your API call.

Response header element. X-Page-Next represents the start of the next page of order search results. To access the next page, you'll call the Order Search API again with the value of this field in the anchor request parameter. If this response header is null or missing, it means that this is the last page of the order search results.

Response header element. X-Page-Previous represents the start of the previous page of order search results. To access the previous page, you'll call the Order Search API again with the value of this field in the anchor request parameters. If this response header is null or missing, it means that this is the first page of the order search results.

Response header element. X-Total-Count represents the total number of orders matching the request parameters sent in the order search request.

The endpoint for searching an order with the Pack App API is included in the table below.

API type	API endpoint
POST	https://api.shipium.com/api/v1/packShip/order/search

Example cURL call to search an order

This example shows a request to search an order.

curl --request GET \
--location "https://api.shipium.com/api/v1/packShip/order/search?associatedIdentifiers=lpn-barcode%3A12345&anchor=0&count=50" \
--header 'Accept: application/json' \
--header $AUTHSTRING

Example response body for an order search

[
  {
    "fulfillmentType": "customer",
    "orderSource": "external",
    "shipiumOrderId": "4dc43fff-c3af-4d7b-8a18-e01f2b4cb312",
    "partnerOrderId": "partner-order:12345",
    "associatedIdentifiers": [
      "lpn-barcode:12345"
    ],
    "tenantId": null,
    "orderedDateTime": "2025-03-15T10:10:00.111111Z",
    "orderItemQuantities": [
      {
        "shipiumOrderId": "4dc43fff-c3af-4d7b-8a18-e01f2b4cb312",
        "partnerOrderId": "partner-order:12345",
        "orderItemReferenceIdentifier": "partner-order:12334_item:1",
        "hazmat": false,
        "hazmatInfo": null,
        "productTaxCode": null,
        "nmfcCode": null,
        "nmfcFreightClass": null,
        "productId": "partner-product:12345",
        "quantity": 3,
        "productDetails": null
      }
    ],
    "shipFromAddress": null,
    "originId": "<ORIGIN-ID/PARTNER-PROVIDED-ORIGIN-ID FROM PARTNER CONFIG IN SHIPIUM>",
    "destinationAddress": {
      "name": "Wile E. Coyote",
      "phoneNumber": "9995551234",
      "phoneNumberCountryCode": "+1",
      "emailAddress": "[email protected]",
      "company": "ACME",
      "street1": "123 Main St.",
      "street2": "Suite 42",
      "city": "Albuquerque",
      "state": "NM",
      "countryCode": "US",
      "postalCode": "87121",
      "addressType": "residential",
      "addressLineComponents": null
    },
    "shipOption": null,
    "customsInfo": null,
    "totalDeclaredValue": null,
    "orderFulfillmentParameters": {
      "saturdayDelivery": false,
      "thirdPartyBillingSetId": null,
      "forceThirdPartyBilling": false,
      "fulfillmentContext": "<FCTX-ID/PARTNER-PROVIDED-FCTX-ID FROM PARTNER CONFIG IN SHIPIUM>",
      "fulfillmentContextId": null,
      "packagingType": null,
      "totalWeight": null
    }
  }
]

Request and response fields for searching an order

The following table provides required and optional fields for calling the Pack App API to search an order. You can find additional support in the Pack App API Reference.

Request field	Required/Optional	Field properties	Description
`shipiumTenantId`	Optional	String	If provided, this will be used to constrain the search to a specified Shipium tenant ID.
`associatedIdentifiers`	Optional	String	Search by associated identifiers. Identifiers are not constrained to be unique across orders.
`fromDate`	Optional	String ($date-time) Ex.: `2019-10-29T01:12:33.123456Z`	Bounds of the oldest order date on which to search for orders
`toDate`	Optional	String ($date-time) Ex.: `2019-10-29T01:12:33.123456Z`	Bounds of the newest order date on which to search for orders
`orderStatuses`	Optional	String enumeration	Order statuses by which to constrain results
`anchor`	Optional	String	Identifier for the current page of data
`count`	Optional	Long	The number of results to include on each page of the response

The response attributes for searching an order are defined in the following table. Some response attributes are associated with the request fields described in the request fields table for calling the Pack App API to create an order. Those attributes are not listed here.

Response attribute	Description
`fulfillmentType`	Fulfillment methodology of the shipment
`orderSource`	The source of this order whether it is from the Shipium system or externally created
`tenantId`	Either the Shipium tenant ID or the tenant ID your organization configured in the Shipium system; when present, this is used to indicate the tenant associated with the shipment.
`shipiumOrderId`	Identification use to represent the group of delivery estimates purchased
`partnerOrderId`	The unique identifier representing this order
`orderedDateTime`	The timestamp for when the customer ordered the product; the timestamp is an ISO 8601 timestamp.
`orderItemQuantities`	A list of order items comprising the shipment
`orderItemQuantities.deliveryEstimateId`	The delivery estimate ID associated with the product
`associatedIdentifiers`	Associated identifiers that are indexed to identify this order; for example, this can be an LPN that is bound to the order.
`shipOption`	A high-level shipping option shown to or selected by a customer
`originId`	The origin to which the order is assigned
`shipFromAddress`	The address of the location where the package is being shipped
`destinationAddress`	The address of the location where the package is being delivered
`customsInfo`	Customs information about the package for international shipping
`totalDeclaredValue`	The total monetary amount of the declared value for the package
`orderFulfillmentParameters`	These represent hints that correspond to Shipment Parameters that can be specified ahead of shipment creation on the order. These can be overridden at the time of shipment creation.
`orderStatus`	State of the order

Get an order

The endpoint for getting an order with the Pack App API is included in the table below.

API type	API endpoint
POST	https://api.shipium.com/api/v1/packShip/order/{orderId}

Required path element. orderId or partnerOrderId (Replace with either Shipium’s order identifier or your own, if provided when the order was created.)

Example cURL call to get an order

This example shows a request to get an order. You'll call the api/v1/packShip/order endpoint and append your own order number to the call, like the one shown in the example.

curl --request GET \
--location "https://api.shipium.com/api/v1/packShip/order/4dc43fff-c3af-4d7b-8a18-e01f2b4cb312" \
--header 'Accept: application/json' \
--header $AUTHSTRING

Example response body for getting an order

{
  "fulfillmentType": "customer",
  "orderSource": "external",
  "shipiumOrderId": "4dc43fff-c3af-4d7b-8a18-e01f2b4cb312",
  "partnerOrderId": "partner-order:12345",
  "associatedIdentifiers": [
    "lpn-barcode:12345"
  ],
  "tenantId": null,
  "orderedDateTime": "2025-03-15T10:10:00.111111Z",
  "orderItemQuantities": [
    {
      "shipiumOrderId": "4dc43fff-c3af-4d7b-8a18-e01f2b4cb312",
      "partnerOrderId": "partner-order:12345",
      "orderItemReferenceIdentifier": "partner-order:12334_item:1",
      "hazmat": false,
      "hazmatInfo": null,
      "productTaxCode": null,
      "nmfcCode": null,
      "nmfcFreightClass": null,
      "productId": "partner-product:12345",
      "quantity": 3,
      "productDetails": null
    }
  ],
  "shipFromAddress": null,
  "originId": "<ORIGIN-ID/PARTNER-PROVIDED-ORIGIN-ID FROM PARTNER CONFIG IN SHIPIUM>",
  "destinationAddress": {
    "name": "Wile E. Coyote",
    "phoneNumber": "9995551234",
    "phoneNumberCountryCode": "+1",
    "emailAddress": "[email protected]",
    "company": "ACME",
    "street1": "123 Main St.",
    "street2": "Suite 42",
    "city": "Albuquerque",
    "state": "NM",
    "countryCode": "US",
    "postalCode": "87121",
    "addressType": "residential",
    "addressLineComponents": null
  },
  "shipOption": null,
  "customsInfo": null,
  "totalDeclaredValue": null,
  "orderFulfillmentParameters": {
    "saturdayDelivery": false,
    "thirdPartyBillingSetId": null,
    "forceThirdPartyBilling": false,
    "fulfillmentContext": "<FCTX-ID/PARTNER-PROVIDED-FCTX-ID FROM PARTNER CONFIG IN SHIPIUM>",
    "fulfillmentContextId": null,
    "packagingType": null,
    "totalWeight": null
  },
  "fulfillmentInfo": {
    "shipments": [],
    "unfulfilledItems": []
}

Response attributes for getting an order

The response attributes for getting an order are defined in the following table. Some response attributes are associated with the request fields described in the request fields table for calling the Pack App API to create an order. Those attributes are not listed here.

Response attribute	Description
`fulfillmentType`	Fulfillment methodology of the shipment
`orderSource`	The source of this order whether it is from the Shipium system or externally created
`tenantId`	Either the Shipium tenant ID or the tenant ID your organization configured in the Shipium system; when present, this is used to indicate the tenant associated with the shipment.
`shipiumOrderId`	Identification use to represent the group of delivery estimates purchased
`partnerOrderId`	The unique identifier representing this order
`orderedDateTime`	The timestamp for when the customer ordered the product; the timestamp is an ISO 8601 timestamp.
`orderItemQuantities`	A list of order items comprising the shipment
`orderItemQuantities.deliveryEstimateId`	The delivery estimate ID associated with the product
`associatedIdentifiers`	Associated identifiers that are indexed to identify this order; for example, this can be an LPN that is bound to the order.
`shipOption`	A high-level shipping option shown to or selected by a customer
`originId`	The origin to which the order is assigned
`shipFromAddress`	The address of the location where the package is being shipped
`destinationAddress`	The address of the location where the package is being delivered
`customsInfo`	Customs information about the package for international shipping
`totalDeclaredValue`	The total monetary amount of the declared value for the package
`orderFulfillmentParameters`	These represent hints that correspond to Shipment Parameters that can be specified ahead of shipment creation on the order. These can be overridden at the time of shipment creation.
`orderStatus`	State of the order
`fulfillmentInfo.shipments`	An array of shipment objects that have been created for the order
`fulfillmentInfo.unfulfilledItems`	An array of items that are not yet fulfilled for a split order

Resources

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