Guides
Start typing to search…

Pack App API

Ship packages from your warehouse management system's pack stations or stores with Shipium's Pack App API.

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:

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 typeAPI endpoint
POSThttps://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",
  "currencyCode": "USD",
  "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": {
    "thirdPartyBillingSetId": null,
    "forceThirdPartyBilling": false,
    "fulfillmentContext": "<FCTX-ID/PARTNER-PROVIDED-FCTX-ID FROM PARTNER CONFIG IN SHIPIUM>",
    "fulfillmentContextId": null,
    "carrierServiceMethodAllowList": [
      "ups-ground-service-method",
      "fedex-home-delivery-service-method"
  ],
    "holdAtLocation": {
      "holdAtLocationId": "MyHALLocation",
      "useHoldAtLocation": true
    },
    "referenceIdentifier": "Order123",
    "partnerReferenceIdentifier": "PartnerRef789",
    "packagingType": null,
    "totalWeight": null,
    "splitOrder": false,
    "deliveryParameters": {
      "applyToSplits": false,
      "businessDaysOfTransit": null,
      "deliveryNote": null,
      "deliverySignatureOption": "none",
      "deliveryWindow": null,
      "desiredDeliveryDate": "2025-04-15T20:00:00Z",
      "desiredDeliveryDateOptions": null,
      "lastMileDeliveryOptions": null,
      "preferredCarrierDeliveryDateTime": null,
      "saturdayDelivery": false
    }
  }
}

Example response body for an order creation

{
  "fulfillmentType": "customer",
  "orderSource": "external",
  "currencyCode": "USD",
  "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": {
    "thirdPartyBillingSetId": null,
    "forceThirdPartyBilling": false,
    "fulfillmentContext": "<FCTX-ID/PARTNER-PROVIDED-FCTX-ID FROM PARTNER CONFIG IN SHIPIUM>",
    "fulfillmentContextId": null,
    "carrierServiceMethodAllowList": [
      "ups-ground-service-method",
      "fedex-home-delivery-service-method"
  ],
    "holdAtLocation": {
      "holdAtLocationId": "MyHALLocation",
      "useHoldAtLocation": true
    },
    "referenceIdentifier": "Order123",
    "partnerReferenceIdentifier": "PartnerRef789",
    "packagingType": null,
    "totalWeight": null,
    "splitOrder": false,
    "deliveryParameters": {
      "applyToSplits": false,
      "businessDaysOfTransit": null,
      "deliveryNote": null,
      "deliverySignatureOption": "none",
      "deliveryWindow": null,
      "desiredDeliveryDate": "2025-04-15T20:00:00Z",
      "desiredDeliveryDateOptions": null,
      "lastMileDeliveryOptions": null,
      "preferredCarrierDeliveryDateTime": null,
      "saturdayDelivery": false
    }
  }
}

Set delivery parameters at order creation

You can specify delivery preferences when creating an order using the deliveryParameters object within orderFulfillmentParameters. These settings are stored on the order and automatically applied when generating a label at pack/ship time. This allows packers and shippers to focus on packing and shipping without needing to specify delivery options at runtime.

Any equivalent parameters passed at pack/ship time will override the values stored in deliveryParameters.

Request and response fields for creating an order

The following tables provide required, conditional, 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.

Required fields

Field

Details

fulfillmentType

Type: String (enumeration)
Values: customer, at_large, returns, hundredweight, reship
Description: The fulfillment methodology of the shipment

orderSource

Type: String (enumeration)
Values: Shipium, External
Description: The source of this order, whether it is from the Shipium system or externally created

currencyCode

Type: String (enumeration)
Example: usd
Description: The ISO 4217 code for the currency used in the transaction resulting in the order

orderedDateTime

Type: String (date-time)
Description: The timestamp for when the customer placed the order for this product; the timestamp must be a valid ISO 8601 timestamp.

orderItemQuantities

Type: Array of order item quantities
Description: A list of orderItems comprising the shipment

orderItemQuantities .orderItemReferenceIdentifier

Type: String
Description: 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.productId

Type: String
Example: RN03947-Z43121
Description: A product ID for the product being checked, such as ISBN and UPC

orderItemQuantities.quantity

Type: Integer (int32)
Example: 3
Description: The number of units of this product

destinationAddress.countryCode

Type: String
Description: The ISO 3166-1 country code for the destination address

destinationAddress.postalCode

Type: String
Description: A country-code-appropriate postal code for the destination address

destinationAddress.addressType

Type: String (enumeration)
Values: commercial, residential
Description: The type of location for the destination address

destinationAddress.company

Type: String
Description: The company name for the destination address

destinationAddress.name

Type: String
Description: The name of the contact for the destination address

destinationAddress.emailAddress

Type: String
Description: The email address of the contact for the destination address

destinationAddress.phoneNumber

Type: String
Description: The phone number of the contact for the destination address

destinationAddress .phoneNumberCountryCode

Type: String
Description: The phone number country code of the contact for the destination address

destinationAddress.city

Type: String
Description: The name of the city for the destination address

destinationAddress.state

Type: String
Description: The 2-letter postal abbreviation of the state for the destination address

destinationAddress.street1

Type: String
Description: The first destination address line

destinationAddress.street2

Type: String
Description: The second destination address line

orderFulfillmentParameters .fulfillmentContext

Type: String
Description: The fulfillment context tag value

orderFulfillmentParameters .fulfillmentContextId

Type: String
Description: The fulfillment context ID

Conditional fields

Field

Details

originId

Type: String
Condition: Required if shipFromAddress is not populated
Description: The origin to which the order is assigned; it cannot be assigned if shipFromAddress is also populated.

shipFromAddress.countryCode

Type: String
Condition: Required if originId is not populated
Description: The ISO 3166-1 country code for the origin address

shipFromAddress.postalCode

Type: String
Condition: Required if originId is not populated
Description: A country-code-appropriate postal code for the origin address

orderItemQuantities.productDetails

Type: String
Example: perishable, limited_quantity (or lq), ormd (or orm-d), bound_printed_matter (or bpm)
Condition: Required for international shipments and shipments containing hazardous materials
Description: A list of properties that may affect the shipping of the product

orderItemQuantities.hazmatInfo.category

Type: String (enumeration)
Values: defined, contains_lithium_ion, packaged_lithium_ion, lithium_ion_battery_only, contains_lithium_metal, packaged_lithium_metal, lithium_metal_battery_only, dry_ice
Condition: Required if including hazmatInfo
Description: Hazmat category for this order item; use defined to specify detailed information.

orderItemQuantities.hazmatInfo.quantity

Type: Number (float)
Example: 2.1
Condition: Required if category is defined
Description: The amount of quantity type material in quantity units

orderItemQuantities.hazmatInfo.quantityType

Type: String (enumeration)
Values: gross, net
Condition: Required if category is defined
Description: Determines whether the quantity includes the raw material (net) or also includes the material housing (gross)

orderItemQuantities.hazmatInfo.quantityUnits

Type: String (enumeration)
Values: g (gram), kg (kilogram), lb (pound), oz (ounce), ml (milliliter), l (liter)
Condition: Required if category is defined
Description: The units of measure for the quantity of hazardous materials specified

orderItemQuantities.hazmatInfo.containerType

Type: String (enumeration)
Values: 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
Condition: Required if category is defined
Description: The material in which the hazardous material is packaged

orderItemQuantities.hazmatInfo.hazmatId

Type: String
Example: UN1755
Condition: Required if category is defined
Description: The International Air Transport Association (IATA) or U.S. Department of Transportation (DOT) regulatory identifier for the commodity as appropriate

orderItemQuantities.hazmatInfo.properShippingName

Type: String
Example: chromic acid solution
Condition: Required if category is defined
Description: Proper shipping name that is associated with the specified hazmat ID

orderItemQuantities.hazmatInfo.transportMode

Type: String (enumeration)
Values: ground, passenger_and_cargo_aircraft, cargo_aircraft_only
Condition: Required if category is defined
Description: Declares that a package was prepared according to ground, passenger aircraft, or cargo aircraft only

orderItemQuantities.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
Condition: Required if category is defined
Description: The hazard class of the hazmat

orderFulfillmentParameters.packagingType .packagingTypeId

Type: String
Example: ebd94f8b-d390-4c9c-987f-b88343f5bf45
Condition: Required if linearDimensions is not provided
Description: 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

Type: String (enumeration)
Values: cm (centimeter), in (inch)
Condition: Required if the packagingTypeId is not included
Description: The unit in which linear dimensions are provided

orderFulfillmentParameters.packagingType .linearDimensions.length

Type: Number (float)
Example: 13
Condition: Required if the packagingTypeId is not included
Description: The longest linear dimension (i.e., the longest side of a box or envelope)

orderFulfillmentParameters.packagingType .linearDimensions.width

Type: Number (float)
Example: 12
Condition: Required if the packagingTypeId is not included
Description: The second longest linear dimension (i.e., the second longest side of a box or envelope)

orderFulfillmentParameters.packagingType .linearDimensions.height

Type: Number (float)
Example: 10
Condition: Required if the packagingTypeId is not included
Description: 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.splitParameters

Type: Array
Condition: Required when splitOrder is true
Description: 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.

Optional fields

🚧

Use with caution

Using carrierServiceMethodAllowList significantly limits shipping options during carrier selection. This may result in higher shipping costs or a "no eligible carriers" error if none of the specified methods meet the shipment requirements. Use this feature only when you need to enforce specific shipping methods. You can find more information in the Specify Carrier Service and Method documentation.

Field

Details

partnerOrderId

Type: String
Description: An optional custom identifier that may be used for this order

associatedIdentifiers

Type: Array of strings
Description: 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

Type: String
Description: 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.

orderItemQuantities.hazmat

Type: Boolean
Values: true or false
Description: 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.packingGroup

Type: String (enumeration)
Values: i, ii, iii
Description: The packing group code for the hazardous material

orderItemQuantities.hazmatInfo .packingInstructionCode

Type: String
Example: 967
Description: The packing instruction code used for air transport

orderItemQuantities.hazmatInfo .subsidiaryClasses

Type: String
Example: 8.1
Description: The appropriate IATA/DOT subsidiary classes associated with the material and the hazard class

orderItemQuantities.productTaxCode

Type: String
Description: The tax code that applies to the given product

orderItemQuantities.nmfcCode

Type: String
Description: 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

Type: String
Description: 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.

shipFromAddress.addressType

Type: String (enumeration)
Values: commercial, residential
Description: The type of location for the origin address

shipFromAddress.company

Type: String
Description: The company name for the origin address

shipFromAddress.name

Type: String
Description: The name of the contact for the origin address

shipFromAddress.emailAddress

Type: String
Description: The email address of the contact for the origin address

shipFromAddress.phoneNumber

Type: String
Description: The phone number of the contact for the origin address

shipFromAddress.phoneNumberCountryCode

Type: String
Description: The phone number country code of the contact for the origin address

shipFromAddress.city

Type: String
Description: The name of the city for the origin address

shipFromAddress.state

Type: String
Description: The 2-letter postal abbreviation of the state for the origin address

shipFromAddress.street1

Type: String
Description: The first address line

shipFromAddress.street2

Type: String
Description: The second address line

shipFromAddress.addressLineComponents

Type: String
Example: streetName: "Fovisste Fuentes Brotantes", primaryAddressNumber: "12", secondaryAddressNumber: "302", district: "Iztacalco", neighborhood: "Agrícola Pantitlán"
Description: The address line components for the address, used for some international shipments. The street1 and street2 fields should not be included if using addressLineComponents, or an error will be returned. Preferred for Mexican addresses. You can find out more about Mexican addresses in Non-U.S. Address Formats.

destinationAddress.addressLineComponents

Type: String
Example: streetName: "Fovisste Fuentes Brotantes", primaryAddressNumber: "12", secondaryAddressNumber: "302", district: "Iztacalco", neighborhood: "Agrícola Pantitlán"
Description: The address line components for the address, used for some international shipments. The street1 and street2 fields should not be included if using addressLineComponents, or an error will be returned. Preferred for Mexican addresses. You can find out more about Mexican addresses in Non-U.S. Address Formats.

shipOption

Type: String
Example: standard
Description: A high-level shipping option shown to or selected by a customer

customsInfo.totalCustomsValue

Type: Float
Description: The total customs value of the package in total customs value currency units

customsInfo.totalCustomsValueCurrency

Type: String
Description: The ISO 4217 currency code representing the totalCustomsValue

customsInfo.customsDescription

Type: String
Description: The detailed description of the items being shipped

customsInfo.reasonForExport

Type: String (enumeration)
Values: sale, gift, sample, returns, personal_effects
Description: The reason to export an international shipment

customsInfo.invoiceDate

Type: String
Description: Date when the invoice was created; ideally, this is the same as the ship date.

customsInfo.invoiceNumber

Type: String
Description: The Commercial Invoice number, if the Commercial Invoice was generated by your organization

customsInfo.europeanUnionInfo.vendorIossNumber

Type: String
Description: 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

Type: String
Description: The name associated with the address of the person or company who receives the goods for end use

customsInfo.ultimateConsigneeAddress.phoneNumber

Type: String
Description: The phone number of the person or company who receives the goods for end use

customsInfo.ultimateConsigneeAddress .phoneNumberCountryCode

Type: String
Description: The phone number country code of the person or company who receives the goods for end use

customsInfo.ultimateConsigneeAddress.emailAddress

Type: String
Description: The email address of the person or company who receives the goods for end use

customsInfo.ultimateConsigneeAddress.company

Type: String
Description: The company name associated with the person or company who receives the goods for end use

customsInfo.ultimateConsigneeAddress.street1

Type: String
Description: The first address line of the person or company who receives the goods for end use

customsInfo.ultimateConsigneeAddress.street2

Type: String
Description: The second address line of the person or company who receives the goods for end use

customsInfo.ultimateConsigneeAddress.city

Type: String
Description: The name of the city for the address of the person or company who receives the goods for end use

customsInfo.ultimateConsigneeAddress.state

Type: String
Description: The state abbreviation for the address of the person or company who receives the goods for end use

customsInfo.ultimateConsigneeAddress.countryCode

Type: String
Description: The ISO 3166-1 country code for the address of the person or company who receives the goods for end use

customsInfo.ultimateConsigneeAddress.postalCode

Type: String
Description: A country code appropriate postal code for the address of the person or company who receives the goods for end use

customsInfo.ultimateConsigneeAddress.addressType

Type: String (enumeration)
Values: commercial, residential
Description: The type of location for this address

customsInfo.ultimateConsigneeAddress .addressLineComponents

Type: String
Description: The address line components for the address, used for some international shipments. The street1 and street2 fields should not be included if using addressLineComponents, or an error will be returned. Preferred for Mexican addresses.

customsInfo.ultimateConsigneeType

Type: String (enumeration)
Values: direct_consumer, government_entity, reseller
Description: The type of the ultimate consignee

customsInfo.aesInternalTransactionNumber

Type: String
Description: The number received if the Electronic Export Information (EEI) was filed and has been accepted in the Automated Export System (AES)

customsInfo.electronicExportInformation .exportDate

Type: String (local-date)
Example: 2019-10-29
Description: The date the goods will be exiting the country

customsInfo.electronicExportInformation .pointOfOrigin

Type: String
Description: The 2-character state abbreviation from which the goods were shipped to the port of export

customsInfo.b13AFilingOption

Type: String (enumeration)
Values: not_required, manually_attached, filed_electronically, summary_reporting, carrier_to_stamp
Description: 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

Type: String
Example: AESX20220714987654
Description: 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.

customsInfo.permitNumber

Type: String
Description: 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

Type: Float
Description: The value of each individual item to report to customs in customsValueCurrency

customsInfo.customsItems.customsValueCurrency

Type: String
Description: The ISO 4217 currency code representing the customsValue

customsInfo.customsItems.commodityDescription

Type: String
Description: A description of this product to be provided to customs

customsInfo.customsItems.countryOfManufacture

Type: String
Description: The ISO 3166 2-digit country code that manufactured the product

customsInfo.customsItems.customsWeight.weightUnit

Type: String (enumeration)
Values: g (gram), kg (kilogram), oz (ounce), lb (pound)
Description: The unit in which the weight is measured

customsInfo.customsItems.customsWeight.weight

Type: Float
Description: The actual weight in weight units

customsInfo.customsItems.quantity

Type: Integer (int32)
Description: The number of units of this customs item

customsInfo.customsItems.productId

Type: String
Description: A product ID for the customs item

customsInfo.customsItems.quantityUnitOfMeasurement

Type: String (enumeration)
Values: bag, barrel, box, case_of_goods, container, crate, cylinder, envelope, pallet, piece, roll, tube
Description: The unit of measurement of the item

customsInfo.customsItems.harmonizedTariffNumber

Type: String
Description: The 6- to 15-digit Harmonized System Tariff classification code

customsInfo.customsItems.commodityPartNumber

Type: String
Description: The part number or reference number for the product

customsInfo.customsItems.marksAndNumbers

Type: String
Description: Any special marks, codes, and numbers that may identify the package

customsInfo.customsItems .electronicExportCommodityInformation.exportType

Type: String (enumeration)
Values: domestic, foreign
Description: The type of the export

customsInfo.customsItems .electronicExportCommodityInformation .exportInformationCode

Type: String
Description: The 2-digit export information code for the commodity

customsInfo.customsItems .electronicExportCommodityInformation .scheduleBInformation.scheduleBNumber

Type: String
Description: The 10-digit Schedule B classification code for the item being exported

customsInfo.customsItems .electronicExportCommodityInformation .scheduleBInformation.scheduleBQuantity

Type: Integer
Description: The count of how many Schedule B units are in the shipment

customsInfo.customsItems .electronicExportCommodityInformation .scheduleBInformation.scheduleBUnitOfMeasurement

Type: String
Values: 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
Description: The unit of measure for the Schedule B quantity

customsInfo.customsItems .electronicExportCommodityInformation .eccnNumber

Type: String
Description: The 5-digit product ECCN number as issued by the Bureau of Industry and Security; the format is #A###.

customsInfo.customsItems .electronicExportCommodityInformation .exportLicenseInformation.licenseType

Type: String
Description: The standard license type code as published by the U.S. government

customsInfo.customsItems .electronicExportCommodityInformation .exportLicenseInformation.licenseExemptionCode

Type: String
Description: The license exemption code, if the license type does not require a license number

customsInfo.customsItems .electronicExportCommodityInformation .exportLicenseInformation.exportLicense .licenseNumber

Type: String
Description: The license number

customsInfo.customsItems .electronicExportCommodityInformation .exportLicenseInformation.exportLicense .licenseLineValue

Type: Integer
Description: The export monetary amount allowed per license

customsInfo.customsItems .electronicExportCommodityInformation .exportLicenseInformation.exportLicense .licenseExpiration

Type: String (local-date)
Example: 2019-10-29
Description: The license expiration date

customsInfo.customsItems.b13AFilingOption

Type: String (enumeration)
Values: not_required, manually_attached, filed_electronically, summary_reporting, carrier_to_stamp
Description: 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

Type: String
Description: 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.

customsInfo.incoterm

Type: String (enumeration)
Values: ddp (delivery duty paid), ddu (delivery duty unpaid), dap (delivered at place), dpu (delivered at place unloaded), fca (free carrier)
Description: The incoterm, or international commerce term, defines the delivery duty responsibility for buyers and sellers for any mode of transport

totalDeclaredValue.declaredValue

Type: Float
Description: 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

Type: String
Description: The ISO 4217 currency code for the declared value

orderFulfillmentParameters.saturdayDelivery

Type: Boolean
Values: true or false
Description: 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. If this flag is true, only carrier service methods that can deliver on Saturday will be considered.

orderFulfillmentParameters.thirdPartyBillingSetId

Type: String
Description: 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

Type: Boolean
Values: true or false
Description: 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.holdAtLocation .useHoldAtLocation

Type: Boolean
Values: true or false
Description: If true, this indicates that the package should be held at a carrier location for pickup.

orderFulfillmentParameters.holdAtLocation .holdAtLocationId

Type: String
Description: An optional unique identifier for the designated hold location

orderFulfillmentParameters .carrierServiceMethodAllowList

Type: Array of strings
Description: A list of carrierServiceMethodId values and/or carrier names to restrict the carrier service methods Shipium will consider during carrier selection. Only the specified methods will be evaluated. Refer to Supported Carriers for valid values.

orderFulfillmentParameters.referenceIdentifier

Type: String
Description: 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

Type: String
Description: A unique identifier string supplied by your organization, passed to carriers as a reference

orderFulfillmentParameters .partnerReferenceIdentifier2

Type: String
Description: A unique identifier string supplied by your organization, passed to carriers as a reference

orderFulfillmentParameters.packagingType .packagingMaterial

Type: String (enumeration)
Values: box, envelope, flat_pack, mailing_tube, parcel_pallet
Description: The type of packaging used to create the package for the shipment

orderFulfillmentParameters.packagingType .packagingSizeName

Type: String
Example: 13x12x10 box
Description: A custom name for the packaging

orderFulfillmentParameters.packagingType .packagingWeight.weightUnit

Type: String (enumeration)
Values: g (gram), kg (kilogram), lb (pound), oz (ounce)
Description: The unit in which weight values are provided

orderFulfillmentParameters.packagingType .packagingWeight.weight

Type: Number (float)
Example: 50
Description: The value of the weight

orderFulfillmentParameters.totalWeight .weightUnit

Type: String (enumeration)
Values: g (gram), kg (kilogram), lb (pound), oz (ounce)
Description: The unit in which weight values are provided

orderFulfillmentParameters.totalWeight.weight

Type: Number (float)
Example: 50
Description: The value of the weight

orderFulfillmentParameters.splitOrder

Type: Boolean
Values: true or false
Description: 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.deliveryParameters .applyToSplits

Type: Boolean
Values: true or false
Description: When false (default), delivery settings apply only to complete shipments. When true, settings also apply to split shipments. In general, split shipments have custom shipping fields set at runtime, so this defaults to false.

orderFulfillmentParameters.deliveryParameters .businessDaysOfTransit

Type: Integer (int32) Description: Number of business days for transit

orderFulfillmentParameters.deliveryParameters .deliveryNote

Type: String
Description: A delivery note for the order shipment

orderFulfillmentParameters.deliveryParameters .deliverySignatureOption

Type: String
Description: Type of delivery signature required; the default is none.

orderFulfillmentParameters.deliveryParameters .deliveryWindow

Type: Object
Description: Specifies the delivery window for the order shipment

orderFulfillmentParameters.deliveryParameters .desiredDeliveryDate

Type: String (date-time)
Description: ISO 8601 date-time representing the desired delivery date

orderFulfillmentParameters.deliveryParameters .desiredDeliveryDateOptions

Type: Object
Description: Options for desired delivery date including exactDateDelivery, guaranteedDateDelivery, upgradeCostDeltaMax, currencyCode, and timeInTransitSetting

orderFulfillmentParameters.deliveryParameters .lastMileDeliveryOptions

Type: Object
Description: Last mile delivery options for the order shipment

orderFulfillmentParameters.deliveryParameters .preferredCarrierDeliveryDateTime

Type: String
Description: Carrier-specific preferred delivery date-time

orderFulfillmentParameters.deliveryParameters .saturdayDelivery

Type: Boolean
Values: true or false
Description: When true, marks the shipment for Saturday delivery

Response attributes

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 attributeDescription
fulfillmentTypeFulfillment methodology of the shipment
orderSourceThe source of this order whether it is from the Shipium system or externally created
tenantIdEither 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.
shipiumOrderIdIdentification use to represent the group of delivery estimates purchased
partnerOrderIdThe unique identifier representing this order
orderedDateTimeThe timestamp for when the customer ordered the product; the timestamp is an ISO 8601 timestamp.
orderItemQuantitiesA list of order items comprising the shipment
orderItemQuantities.deliveryEstimateIdThe delivery estimate ID associated with the product
associatedIdentifiersAssociated identifiers that are indexed to identify this order; for example, this can be an LPN that is bound to the order.
shipOptionA high-level shipping option shown to or selected by a customer
originIdThe origin to which the order is assigned
shipFromAddressThe address of the location where the package is being shipped
destinationAddressThe address of the location where the package is being delivered
customsInfoCustoms information about the package for international shipping
totalDeclaredValueThe total monetary amount of the declared value for the package
orderFulfillmentParametersThese 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.
deliveryParametersDelivery settings stored on the order that are automatically applied at pack/ship label generation; these can be overridden by equivalent runtime parameters passed at the time of shipment creation.
orderStatusState 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 typeAPI 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 tables provide conditional and optional fields for calling the Pack App API to submit an order. You can find additional support in the Pack App API Reference.

Conditional fields

Field

Details

shipmentParameters.currencyCode

Type: String
Example: usd
Condition: Required if shipmentParameters is provided
Description: Currency in which all rates for shipping carrier selection costs will be calculated

packagingType.packagingTypeId

Type: String
Example: ebd94f8b-d390-4c9c-987f-b88343f5bf45
Condition: Required if linearDimensions is not provided
Description: 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

Type: String (enumeration)
Values: in (inch), cm (centimeter)
Condition: Required if linearDimensions is provided
Description: The unit in which linear dimensions are provided

packagingType.linearDimensions.length

Type: Number
Condition: Required if linearDimensions is provided
Description: The longest linear dimension (i.e., the longest side of a box or envelope)

packagingType.linearDimensions.width

Type: Number
Condition: Required if linearDimensions is provided
Description: The second longest linear dimension (i.e., the second longest side of a box or envelope)

packagingType.linearDimensions.height

Type: Number
Condition: Required if linearDimensions is provided
Description: 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

Type: String (enumeration)
Values: g (gram), kg (kilogram), oz (ounce), lb (pound)
Condition: Required if packagingWeight is provided
Description: The unit in which weight values are provided

packagingType.packagingWeight.weight

Type: Number
Condition: Required if packagingWeight is provided
Description: The value of the packaging weight

totalWeight.weightUnit

Type: String (enumeration)
Values: g (gram), kg (kilogram), oz (ounce), lb (pound)
Condition: Required if totalWeight is provided
Description: The unit in which weight values are provided

totalWeight.weight

Type: Number (float)
Condition: Required if totalWeight is provided
Description: The value of the weight

splitReferenceId

Type: String
Condition: Required when splitOrder is true and using pre-defined splits
Description: Reference to a pre-defined split parameter set on the order; use this OR splitParameters, but not both.

splitParameters

Type: Object
Condition: Required when splitOrder is true and defining runtime splits
Description: Runtime definition of split parameters; use this OR splitReferenceId, but not both.

splitParameters.orderItemQuantities.productId

Type: String
Condition: Required if splitParameters is provided
Description: A product ID for the product (e.g., SKU, UPC)

splitParameters.orderItemQuantities.quantity

Type: Integer (int32)
Condition: Required if splitParameters is provided
Description: The number of units of this product

Optional fields

Field

Details

generateLabel

Type: Boolean
Values: true or false
Description: 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

Type: String (enumeration)
Values: box, envelope, flat_pack, mailing_tube, parcel_pallet
Description: The type of packaging used

packagingType.packagingSizeName

Type: String
Example: 13x12x10 box
Description: A custom name for the packaging

labelParameters.labelFormats

Type: Array of strings
Values: pdf, png, zpl
Description: List of formats in which to generate the package label

labelParameters.includeLabelImagesInResponse

Type: Boolean
Values: true or false
Description: When true, the response includes raw image data of generated labels.

labelParameters.testMode

Type: Boolean
Values: true or false
Description: 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

Type: Boolean
Values: true or false
Description: 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.shippedDateTime

Type: String (date-time)
Description: Timestamp for when you shipped the product from your warehouse in ISO 8601 format

shipmentParameters.desiredDeliveryDate

Type: String (date-time)
Description: The date and time the package is intended to arrive to the customer in ISO 8601 date-time format

shipmentParameters.saturdayDelivery

Type: Boolean
Values: true or false
Description: 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. If this flag is true, only carrier service methods that can deliver on Saturday will be considered.

shipmentParameters.referenceIdentifier

Type: String
Description: 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

Type: String
Description: A unique identifier string supplied by your organization, passed to carriers as a reference

shipmentParameters.partnerReferenceIdentifier2

Type: String
Description: A unique identifier string supplied by your organization, passed to carriers as a reference

carrierSelectionOptions .carrierServiceMethodAllowList

Type: Array of strings
Description: List of carrierServiceMethodId and/or carriers that should be considered for selection

splitOrder

Type: Boolean
Values: true or false
Description: When true, this is a signal that the order submit will execute a split shipment. The default value is false.

splitParameters.reasonCode

Type: String (enumeration)
Values: customer_request, item_size, stock_not_available
Description: Defines the reason for breaking the order into multiple shipments

splitParameters.orderItemQuantities .orderItemReferenceIdentifier

Type: String
Description: An external identifier that can reference the order item

Response attributes

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.

FieldDescription
fulfillmentTypeFulfillment methodology of the shipment (customer, at_large, returns, hundredweight, reship, unknown)
orderSourceSource of the order (shipium, external)
tenantIdEither the Shipium tenant ID or the partner-provided tenant ID
shipiumOrderIdThe Shipium-generated unique identifier for the order
partnerOrderIdYour organization's own unique identifier for the order
orderedDateTimeTimestamp when the customer ordered the product (ISO-8601 format)
orderItemQuantitiesArray of all order items with quantities
associatedIdentifiersAssociated identifiers indexed to identify this order (e.g., LPN); can be searched but not interchangeable with orderId
destinationAddressShipping destination address information.
orderStatusCurrent state of the order (open, open_split, complete, complete_multiship, cancelled, partial_ship, error)
orderFulfillmentParameters .splitParameters.fulfilledWhen 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.
orderFulfillmentInfoInformation about shipments fulfilling the order and remaining items
orderFulfillmentInfo.shipmentsArray of shipments generated to fulfill order items
orderFulfillmentInfo.unfulfilledItemsArray 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 typeAPI endpoint
POSThttps://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-001-abc123",
        "partnerShipmentId": null,
        "shipiumOrderId": "4dc43fff-c3af-4d7b-8a18-e01f2b4cb312",
        "partnerOrderId": "partner-order:12345",
        "carrierTrackingId": "1Z999AA10123456784",
        "carrierName": "UPS",
        "carrierServiceMethodName": "UPS Ground",
        "shipmentStatus": "label_created",
        "labelInfo": {
          "shipiumLabelId": "label-001-xyz789",
          "labelFormats": ["pdf"],
          "labelImages": [
            {
              "labelFormat": "pdf",
              "labelBase64": "<BASE64_ENCODED_LABEL_DATA>"
            }
          ]
        },
        "itemsShipped": [
          {
            "productId": "SKU-12345",
            "quantity": 3
          }
        ]
      },
      {
        "shipiumShipmentId": "ship-002-def456",
        "partnerShipmentId": null,
        "shipiumOrderId": "4dc43fff-c3af-4d7b-8a18-e01f2b4cb312",
        "partnerOrderId": "partner-order:12345",
        "carrierTrackingId": "1Z999AA10123456785",
        "carrierName": "UPS",
        "carrierServiceMethodName": "UPS Ground",
        "shipmentStatus": "label_created",
        "labelInfo": {
          "shipiumLabelId": "label-002-xyz790",
          "labelFormats": ["pdf"],
          "labelImages": [
            {
              "labelFormat": "pdf",
              "labelBase64": "<BASE64_ENCODED_LABEL_DATA>"
            }
          ]
        },
        "itemsShipped": [
          {
            "productId": "SKU-12345",
            "quantity": 2
          }
        ]
      }
    ]
  }
}

Request and response fields for split shipments

The following tables provide required and conditional fields for split shipment functionality added to the standard submit request.

Required fields

Field

Details

splitOrder

Type: Boolean
Values: true or false
Description: Set to true to enable split shipment mode.

Conditional fields

Field

Details

splitReferenceId

Type: String
Condition: Required when splitOrder is true and using pre-defined splits
Description: Reference to a pre-defined split parameter set on the order; use this OR splitParameters, but not both.

splitParameters

Type: Object
Condition: Required when splitOrder is true and defining runtime splits
Description: Runtime definition of split parameters; use this OR splitReferenceId, but not both.

splitParameters.reasonCode

Type: String (enumeration)
Values: stock_not_available, item_size_exceeds_box_limits, customer_request
Condition: Required if using splitParameters
Description: The reason for splitting the shipment

splitParameters.orderItemQuantities

Type: Array of item quantity objects
Condition: Required if using splitParameters
Description: Items to include in this split shipment

splitParameters.orderItemQuantities .orderItemReferenceIdentifier

Type: String
Condition: Required if using splitParameters
Description: The order item reference identifier from the original order

splitParameters.orderItemQuantities.productId

Type: String
Condition: Required if splitParameters is provided
Description: 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

Type: Number
Condition: Required if splitParameters is provided
Description: The quantity of this item to include in the split shipment; must be greater than 0 and less than or equal to the remaining quantity on the referenced order item

Response attributes

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

AttributeDescription
typeWill be split for split shipments
referenceIdThe split reference ID if one was used
shipiumOrderIdThe original order ID that was split
orderItemQuantitiesItems 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 typeAPI endpoint
POSThttps://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 tables provides optional fields for calling the Pack App API to search an order. You can find additional support in the Pack App API Reference.

Optional fields

Field

Details

shipiumTenantId

Type: String
Description: If provided, this will be used to constrain the search to a specified Shipium tenant ID.

associatedIdentifiers

Type: String
Description: Search by associated identifiers. Identifiers are not constrained to be unique across orders.

fromDate

Type: String (date-time)
Example: 2019-10-29T01:12:33.123456Z
Description: Bounds of the oldest order date on which to search for orders

toDate

Type: String (date-time)
Example: 2019-10-29T01:12:33.123456Z
Description: Bounds of the newest order date on which to search for orders

orderStatuses

Type: String (enumeration)
Description: Order statuses by which to constrain results

anchor

Type: String
Description: Identifier for the current page of data

count

Type: Long
Description: The number of results to include on each page of the response

Response attributes

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 attributeDescription
fulfillmentTypeFulfillment methodology of the shipment
orderSourceThe source of this order whether it is from the Shipium system or externally created
tenantIdEither 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.
shipiumOrderIdIdentification use to represent the group of delivery estimates purchased
partnerOrderIdThe unique identifier representing this order
orderedDateTimeThe timestamp for when the customer ordered the product; the timestamp is an ISO 8601 timestamp.
orderItemQuantitiesA list of order items comprising the shipment
orderItemQuantities.deliveryEstimateIdThe delivery estimate ID associated with the product
associatedIdentifiersAssociated identifiers that are indexed to identify this order; for example, this can be an LPN that is bound to the order.
shipOptionA high-level shipping option shown to or selected by a customer
originIdThe origin to which the order is assigned
shipFromAddressThe address of the location where the package is being shipped
destinationAddressThe address of the location where the package is being delivered
customsInfoCustoms information about the package for international shipping
totalDeclaredValueThe total monetary amount of the declared value for the package
orderFulfillmentParametersThese 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.
orderStatusState of the order

Get an order

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

API typeAPI endpoint
POSThttps://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 attributeDescription
fulfillmentTypeFulfillment methodology of the shipment
orderSourceThe source of this order whether it is from the Shipium system or externally created
tenantIdEither 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.
shipiumOrderIdIdentification use to represent the group of delivery estimates purchased
partnerOrderIdThe unique identifier representing this order
orderedDateTimeThe timestamp for when the customer ordered the product; the timestamp is an ISO 8601 timestamp.
orderItemQuantitiesA list of order items comprising the shipment
orderItemQuantities.deliveryEstimateIdThe delivery estimate ID associated with the product
associatedIdentifiersAssociated identifiers that are indexed to identify this order; for example, this can be an LPN that is bound to the order.
shipOptionA high-level shipping option shown to or selected by a customer
originIdThe origin to which the order is assigned
shipFromAddressThe address of the location where the package is being shipped
destinationAddressThe address of the location where the package is being delivered
customsInfoCustoms information about the package for international shipping
totalDeclaredValueThe total monetary amount of the declared value for the package
orderFulfillmentParametersThese 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.
orderStatusState of the order
fulfillmentInfo.shipmentsAn array of shipment objects that have been created for the order
fulfillmentInfo.unfulfilledItemsAn 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:

Updated 2 days ago