Get started

Creating shipping labels in batches is possible through the Batch Label Creation API, which enables your organization to retrieve labels for up to 150 shipments in one API call to Shipium's Carrier and Method Selection service.

This document provides guidance for using the Batch Label Creation API. The Carrier and Method Selection & Shipment Labels document provides more information about setting up your organization's account to use the Carrier and Method Selection service and print labels.

Retrieve batch shipping labels from the Batch Label Creation API

The Shipium Batch Label Creation API assumes you're using one of the authentication mechanisms detailed in our authentication documentation. The endpoint for Batch Label Creation API calls, to create new shipments and generate labels in bulk, is included in the table below.

API type	API endpoint
POST	`https://api.shipium.com/api/v1/shipment/bulkprocessing/labels`

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

Test the API call

The ping endpoint for testing your API call is included in the following table.

API type	API endpoint
PING	`https://api.shipium.com/api/v1/shipment/bulkprocessing/ping`

Successfully calling the API endpoint will result in the following 200 response.

{
    "info": "pong",
    "status": 1
}

An error calling the API endpoint will result in the following 400 response.

{
    "statusCode": 401,
    "code": "ERR_BAD_REQUEST",
    "error": "Unauthorized",
    "message": "Request failed with status code 401"
}

👍
Test mode
Want to run some examples and not charge any real money against your account?
You can add testMode: true to the data passed to any label call to retrieve labels without charging money in a carrier-specific manner. Most carriers will mark their labels in a way to make clear that they are void, such as inserting "VOID" throughout the label or using a predefined ID.
The example below contains the testMode flag to err on the side of caution – remove it to make production calls.

Example cURL call

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

Example request body

You have the option to request full shipment details with the API response when calling the Batch Label Creation API, but the default setting is to exclude those details from the response. To include full shipment details, the value for includeFullShipmentResponses should be set to true.

{
  "shipmentRequests": [
    {
      "currencyCode": "USD",
      "shipmentParameters": {
        "partnerShipmentId": "ORDER-2025-001-PKG-1",
        "orderedDateTime": "2025-10-06T08:00:00Z",
        "destinationAddress": {
          "name": "Jane Smith",
          "street1": "123 Main Street",
          "city": "Seattle",
          "state": "WA",
          "postalCode": "98101",
          "countryCode": "US",
          "addressType": "residential"
        },
        "shipFromAddress": {
          "name": "ACME Warehouse",
          "street1": "500 Industrial Blvd",
          "city": "Portland",
          "state": "OR",
          "postalCode": "97201",
          "countryCode": "US",
          "addressType": "commercial"
        },
        "orderItemQuantities": [
          {
            "productId": "SKU-12345",
            "quantity": 2
          }
        ],
        "packagingType": {
          "packagingMaterial": "box",
          "linearDimensions": {
            "length": 12,
            "width": 10,
            "height": 8,
            "linearUnit": "in"
          }
        },
        "totalWeight": {
          "weight": 5.5,
          "weightUnit": "lb"
        },
        "desiredDeliveryDate": "2025-10-10T20:00:00Z"
      },
      "generateLabel": true,
      "labelParameters": {
        "labelFormats": ["pdf", "zpl"],
        "includeLabelImagesInResponse": true
      }
    },
    {
      "currencyCode": "USD",
      "shipmentParameters": {
        "partnerShipmentId": "ORDER-2025-002-PKG-1",
        "orderedDateTime": "2025-10-06T09:15:00Z",
        "destinationAddress": {
          "name": "John Doe",
          "company": "Tech Corp",
          "street1": "456 Business Ave",
          "street2": "Suite 200",
          "city": "San Francisco",
          "state": "CA",
          "postalCode": "94105",
          "countryCode": "US",
          "addressType": "commercial"
        },
        "shipFromAddress": {
          "name": "ACME Warehouse",
          "street1": "500 Industrial Blvd",
          "city": "Portland",
          "state": "OR",
          "postalCode": "97201",
          "countryCode": "US",
          "addressType": "commercial"
        },
        "orderItemQuantities": [
          {
            "productId": "SKU-67890",
            "quantity": 1
          }
        ],
        "packagingType": {
          "packagingMaterial": "box",
          "linearDimensions": {
            "length": 16,
            "width": 12,
            "height": 6,
            "linearUnit": "in"
          }
        },
        "totalWeight": {
          "weight": 3.2,
          "weightUnit": "lb"
        },
        "saturdayDelivery": false,
        "deliverySignatureOption": "Signature"
      },
      "generateLabel": true,
      "labelParameters": {
        "labelFormats": ["pdf"],
        "includeLabelImagesInResponse": false
      }
    }
  ],
  "options": {
    "currencyCode": "USD",
    "includeFullShipmentResponses": false //false by default or if not included, will include full shipment responses on each result if toggled on
  }
}

Example standard response without full shipment details

{
  "orchestratedAssetMetadata": {
    "orchestrationId": "batch-20251006-abc123", //This orchestrationId can be used to pass to us for support to help trace back what happened for a specific request
    "orchestrationTimeStamp": "2025-10-06T14:30:22.123456Z"
  },
  "results": [
    {
      "shipiumShipmentId": "a1b2c3d4-e5f6-4a7b-8c9d-0e1f2a3b4c5d",
      "partnerShipmentId": "ORDER-2025-001-PKG-1",
      "carrierSelectionId": "cs-f1e2d3c4-b5a6-4978-8899-aabbccddeeff",
      "shipiumLabelId": "lbl-9a8b7c6d-5e4f-3210-abcd-ef1234567890",
      "carrier": "fedex",
      "carrierServiceMethodId": "fedex-ground-service-method",
      "carrierTrackingId": "123456789012",
      "carrierTrackingLink": "https://www.fedex.com/track?tracknumber=123456789012",
      "labelStatus": "success",
      "labelUrls": {
        "pdf": "https://cdn.shipium.com/labels/lbl-9a8b7c6d-5e4f-3210-abcd-ef1234567890.pdf",
        "zpl": "https://cdn.shipium.com/labels/lbl-9a8b7c6d-5e4f-3210-abcd-ef1234567890.zpl"
      },
      "estimatedDeliveryDate": "2025-10-10T20:00:00Z",
      "totalCost": 12.45,
      "currencyCode": "USD"
    },
    {
      "shipiumShipmentId": "b2c3d4e5-f6a7-4b8c-9d0e-1f2a3b4c5d6e",
      "partnerShipmentId": "ORDER-2025-002-PKG-1",
      "carrierSelectionId": "cs-a9b8c7d6-e5f4-3210-9876-543210fedcba",
      "shipiumLabelId": "lbl-8b7c6d5e-4f3a-2109-bcde-f01234567891",
      "carrier": "ups",
      "carrierServiceMethodId": "ups-ground-service-method",
      "carrierTrackingId": "1Z999AA10123456784",
      "carrierTrackingLink": "https://www.ups.com/track?tracknum=1Z999AA10123456784",
      "labelStatus": "success",
      "labelUrls": {
        "pdf": "https://cdn.shipium.com/labels/lbl-8b7c6d5e-4f3a-2109-bcde-f01234567891.pdf"
      },
      "estimatedDeliveryDate": "2025-10-11T18:00:00Z",
      "totalCost": 9.87,
      "currencyCode": "USD"
    }
  ],
  "failures": []
}

Example response with full shipment details

To include full shipment details in the response, the value for includeFullShipmentResponses in your call request should be set to true.

{
  "orchestratedAssetMetadata": {
    "orchestrationId": "batch-20251006-xyz789", //This orchestrationId can be used to pass to us for support to help trace back what happened for a specific request
    "orchestrationTimeStamp": "2025-10-06T14:30:22.123456Z"
  },
  "results": [
    {
      "shipiumShipmentId": "a1b2c3d4-e5f6-4a7b-8c9d-0e1f2a3b4c5d",
      "partnerShipmentId": "ORDER-2025-001-PKG-1",
      "orderedDateTime": "2025-10-06T08:00:00Z",
      "effectiveShipDateTime": "2025-10-06T14:30:22Z",
      "estimatedDeliveryDate": "2025-10-10T20:00:00Z",
      "desiredDeliveryDate": "2025-10-10T20:00:00Z",
      "destinationAddress": {
        "name": "Jane Smith",
        "street1": "123 Main Street",
        "city": "Seattle",
        "state": "WA",
        "postalCode": "98101",
        "countryCode": "US",
        "addressType": "residential"
      },
      "shipFromAddress": {
        "name": "ACME Warehouse",
        "street1": "500 Industrial Blvd",
        "city": "Portland",
        "state": "OR",
        "postalCode": "97201",
        "countryCode": "US",
        "addressType": "commercial"
      },
      "orderItemQuantities": [
        {
          "productId": "SKU-12345",
          "quantity": 2
        }
      ],
      "packagingType": {
        "packagingMaterial": "box",
        "packagingSizeName": "Medium Box",
        "linearDimensions": {
          "length": 12,
          "width": 10,
          "height": 8,
          "linearUnit": "in"
        }
      },
      "totalWeight": {
        "weight": 5.5,
        "weightUnit": "lb"
      },
      "carrierSelection": {
        "carrierSelectionId": "cs-f1e2d3c4-b5a6-4978-8899-aabbccddeeff",
        "shipiumShipmentId": "a1b2c3d4-e5f6-4a7b-8c9d-0e1f2a3b4c5d",
        "partnerShipmentId": "ORDER-2025-001-PKG-1",
        "carrierSelectionDateTime": "2025-10-06T14:30:22.123456Z",
        "carrierDecision": {
          "status": "success",
          "partnerId": "partner-12345",
          "carrierAccountId": "acct-fedex-001",
          "serviceMethodIdentifier": "urn:carrierrate:fedex-ground:v1",
          "carrier": "fedex",
          "carrierServiceName": "FedEx Ground",
          "carrierServiceMethodId": "fedex-ground-service-method",
          "serviceMethodName": "FedEx Ground",
          "thirdPartyBilling": false,
          "effectiveShipDateTime": "2025-10-06T14:30:22Z",
          "estimatedDeliveryDate": "2025-10-10T20:00:00Z",
          "carrierZoneId": "fedex-zone-7"
        }
      },
      "carrierLabel": {
        "shipiumShipmentId": "a1b2c3d4-e5f6-4a7b-8c9d-0e1f2a3b4c5d",
        "partnerShipmentId": "ORDER-2025-001-PKG-1",
        "carrierSelectionId": "cs-f1e2d3c4-b5a6-4978-8899-aabbccddeeff",
        "shipiumLabelId": "lbl-9a8b7c6d-5e4f-3210-abcd-ef1234567890",
        "status": "success",
        "carrier": "fedex",
        "carrierServiceName": "FedEx Ground",
        "serviceMethodName": "FedEx Ground",
        "carrierServiceMethodId": "fedex-ground-service-method",
        "carrierShipmentId": "fedex-ship-987654321",
        "carrierTrackingId": "123456789012",
        "carrierTrackingLink": "https://www.fedex.com/track?tracknumber=123456789012",
        "packageScannableId": "123456789012",
        "labelCreationDateTime": "2025-10-06T14:30:23.456789Z",
        "effectiveShipDateTime": "2025-10-06T14:30:22Z",
        "estimatedDeliveryDate": "2025-10-10T20:00:00Z",
        "serviceMethodIdentifier": "urn:carrierrate:fedex-ground:v1",
        "carrierLabelCurrencyCode": "USD",
        "carrierLabelPrice": 12.45,
        "billableWeight": {
          "weight": 6,
          "weightUnit": "lb"
        },
        "documents": [
          {
            "labelFormat": "pdf",
            "labelUrl": "https://cdn.shipium.com/labels/lbl-9a8b7c6d-5e4f-3210-abcd-ef1234567890.pdf",
            "labelExpiration": "2025-10-13T14:30:23Z",
            "carrierTrackingId": "123456789012",
            "packageScannableId": "123456789012"
          },
          {
            "labelFormat": "zpl",
            "labelUrl": "https://cdn.shipium.com/labels/lbl-9a8b7c6d-5e4f-3210-abcd-ef1234567890.zpl",
            "labelExpiration": "2025-10-13T14:30:23Z",
            "carrierTrackingId": "123456789012",
            "packageScannableId": "123456789012"
          }
        ],
        "testMode": false,
        "details": {
          "labelCreateParams": {
            "currencyCode": "USD",
            "labelFormats": ["pdf", "zpl"],
            "includeLabelImagesInResponse": true
          },
        }
      }
    },
    {
      "shipiumShipmentId": "b2c3d4e5-f6a7-4b8c-9d0e-1f2a3b4c5d6e",
      "partnerShipmentId": "ORDER-2025-002-PKG-1",
      "orderedDateTime": "2025-10-06T09:15:00Z",
      "effectiveShipDateTime": "2025-10-06T14:30:24Z",
      "estimatedDeliveryDate": "2025-10-11T18:00:00Z",
      "deliverySignatureOption": "Signature",
      "saturdayDelivery": false,
      "destinationAddress": {
        "name": "John Doe",
        "company": "Tech Corp",
        "street1": "456 Business Ave",
        "street2": "Suite 200",
        "city": "San Francisco",
        "state": "CA",
        "postalCode": "94105",
        "countryCode": "US",
        "addressType": "commercial"
      },
      "shipFromAddress": {
        "name": "ACME Warehouse",
        "street1": "500 Industrial Blvd",
        "city": "Portland",
        "state": "OR",
        "postalCode": "97201",
        "countryCode": "US",
        "addressType": "commercial"
      },
      "orderItemQuantities": [
        {
          "productId": "SKU-67890",
          "quantity": 1
        }
      ],
      "packagingType": {
        "packagingMaterial": "box",
        "packagingSizeName": "Large Box",
        "linearDimensions": {
          "length": 16,
          "width": 12,
          "height": 6,
          "linearUnit": "in"
        }
      },
      "totalWeight": {
        "weight": 3.2,
        "weightUnit": "lb"
      },
      "carrierSelection": {
        "carrierSelectionId": "cs-a9b8c7d6-e5f4-3210-9876-543210fedcba",
        "shipiumShipmentId": "b2c3d4e5-f6a7-4b8c-9d0e-1f2a3b4c5d6e",
        "partnerShipmentId": "ORDER-2025-002-PKG-1",
        "carrierSelectionDateTime": "2025-10-06T14:30:24.234567Z",
        "carrierDecision": {
          "status": "success",
          "partnerId": "partner-12345",
          "carrierAccountId": "acct-ups-001",
          "serviceMethodIdentifier": "urn:carrierrate:ups-ground:v1",
          "carrier": "ups",
          "carrierServiceName": "UPS Ground",
          "carrierServiceMethodId": "ups-ground-service-method",
          "serviceMethodName": "UPS Ground",
          "thirdPartyBilling": false,
          "effectiveShipDateTime": "2025-10-06T14:30:24Z",
          "estimatedDeliveryDate": "2025-10-11T18:00:00Z",
          "carrierZoneId": "ups-zone-6"
        }
      },
      "carrierLabel": {
        "shipiumShipmentId": "b2c3d4e5-f6a7-4b8c-9d0e-1f2a3b4c5d6e",
        "partnerShipmentId": "ORDER-2025-002-PKG-1",
        "carrierSelectionId": "cs-a9b8c7d6-e5f4-3210-9876-543210fedcba",
        "shipiumLabelId": "lbl-8b7c6d5e-4f3a-2109-bcde-f01234567891",
        "status": "success",
        "carrier": "ups",
        "carrierServiceName": "UPS Ground",
        "serviceMethodName": "UPS Ground",
        "carrierServiceMethodId": "ups-ground-service-method",
        "carrierShipmentId": "ups-ship-876543210",
        "carrierTrackingId": "1Z999AA10123456784",
        "carrierTrackingLink": "https://www.ups.com/track?tracknum=1Z999AA10123456784",
        "packageScannableId": "1Z999AA10123456784",
        "labelCreationDateTime": "2025-10-06T14:30:25.678901Z",
        "effectiveShipDateTime": "2025-10-06T14:30:24Z",
        "estimatedDeliveryDate": "2025-10-11T18:00:00Z",
        "serviceMethodIdentifier": "urn:carrierrate:ups-ground:v1",
        "carrierLabelCurrencyCode": "USD",
        "carrierLabelPrice": 9.87,
        "billableWeight": {
          "weight": 4,
          "weightUnit": "lb"
        },
        "documents": [
          {
            "labelFormat": "pdf",
            "labelUrl": "https://cdn.shipium.com/labels/lbl-8b7c6d5e-4f3a-2109-bcde-f01234567891.pdf",
            "labelExpiration": "2025-10-13T14:30:25Z",
            "carrierTrackingId": "1Z999AA10123456784",
            "packageScannableId": "1Z999AA10123456784"
          }
        ],
        "testMode": false,
        "details": {
          "labelCreateParams": {
            "currencyCode": "USD",
            "labelFormats": ["pdf"],
            "includeLabelImagesInResponse": false
          },
        }
      }
    }
  ],
  "failures": []
}

Request fields for API calls

The following tables provide the required, conditional, and optional fields for calling the Batch Label Creation API. You can find more guidance in the Batch Label Creation API Reference.

Required request fields

Request field	Details
`shipmentRequests.currencyCode`	Type: String Example: `usd` Description: Currency in which all the rates for shipping carrier selection costs will be calculated
`shipmentRequests.shipmentParameters .deliveryWindow.endWindow.hour`	Type: String (byte) Description: The end time hour for the delivery timeframe
`shipmentRequests.shipmentParameters .deliveryWindow.endWindow.minute`	Type: String (byte) Description: The end time minute for the delivery timeframe
`shipmentRequests.shipmentParameters .deliveryWindow.endWindow.nano`	Type: Integer (int32) Description: The end time nano for the delivery timeframe
`shipmentRequests.shipmentParameters .deliveryWindow.endWindow.second`	Type: String (byte) Description: The end time second for the delivery timeframe
`shipmentRequests.shipmentParameters .deliveryWindow.startWindow.hour`	Type: String (byte) Description: The start time hour for the delivery timeframe
`shipmentRequests.shipmentParameters .deliveryWindow.startWindow.minute`	Type: String (byte) Description: The start time minute for the delivery timeframe
`shipmentRequests.shipmentParameters .deliveryWindow.startWindow.nano`	Type: Integer (int32) Description: The start time nano for the delivery timeframe
`shipmentRequests.shipmentParameters .deliveryWindow.startWindow.second`	Type: String (byte) Description: The start time second for the delivery timeframe
`shipmentRequests.shipmentParameters .destinationAddress.countryCode`	Type: String Example: `US` Description: The ISO 3166-1 country code for the destination address
`shipmentRequests.shipmentParameters .destinationAddress.postalCode`	Type: String Description: A country code appropriate postal code for the destination address
`shipmentRequests.shipmentParameters .orderedDateTime`	Type: String (date-time) Description: The timestamp for when a customer placed an order for this product; the timestamp must be a valid ISO 8601 timestamp.

Conditional request fields

Request field	Details
`shipmentRequests.injectionParameters .injectionProfileId`	Type: String Condition: Optional, but required if providing an `injectionSiteId` Description: The Shipium ID or the ID that your organization provided for an injection profile that should be considered during carrier selection
`shipmentRequests.shipmentParameters .customsInfo`	Type: Object Condition: Optional, but some information is required for international shipments. Description: Customs information about the package for international shipping; please refer to Customs Info for Shipments for details.
`shipmentRequests.shipmentParameters .originId`	Type: String Condition: If you include `originId` in your call, the `shipFromAddress` should not be included. Description: Either the Shipium-generated origin ID or your organization's own origin ID, used to identify the origin where the shipment will be processed
`shipmentRequests.shipmentParameters .orderItemQuantities.hazmatInfo.category`	Type: String (enumeration) Values: `defined`, `aerosols_flammable`, `contains_lithium_ion`, `packaged_lithium_ion`, `lithium_ion_battery_only`, `contains_lithium_metal`, `packaged_lithium_metal`, `lithium_metal_battery_only`, `dry_ice` Condition: Optional, but required if including `hazmatInfo` Description: Hazmat category for this order item; use `defined` to specify detailed information.
`shipmentRequests.shipmentParameters .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: Optional, but required if `category` is defined Description: The material in which the hazardous material is packaged
`shipmentRequests.shipmentParameters .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: Optional, but required if `category` is defined Description: The hazard class of the hazmat
`shipmentRequests.shipmentParameters .orderItemQuantities.hazmatInfo.hazmatId`	Type: String Example: `UN1755` Condition: Optional, but 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
`shipmentRequests.shipmentParameters .orderItemQuantities.hazmatInfo .properShippingName`	Type: String Example: `chromic acid solution` Condition: Optional, but required if `category` is defined Description: Proper shipping name that is associated with the specified hazmat ID
`shipmentRequests.shipmentParameters .orderItemQuantities.hazmatInfo.quantity`	Type: Number (float) Example: `2.1` Condition: Optional, but required if `category` is defined Description: The amount of quantity type material in quantity units
`shipmentRequests.shipmentParameters .orderItemQuantities.hazmatInfo .quantityType`	Type: String (enumeration) Values: `gross`, `net` Condition: Optional, but required if `category` is defined Description: Determines whether the quantity includes the raw material (net) or also includes the material housing (gross)
`shipmentRequests.shipmentParameters .orderItemQuantities.hazmatInfo .quantityUnits`	Type: String (enumeration) Values: `g` (gram), `kg` (kilogram), `lb` (pound), `oz` (ounce), `ml` (milliliter), `l` (liter) Condition: Optional, but required if `category` is defined Description: The units of measure for the quantity of hazardous materials specified
`shipmentRequests.shipmentParameters .orderItemQuantities.hazmatInfo .transportMode`	Type: String (enumeration) Values: `ground`, `passenger_and_cargo_aircraft`, `cargo_aircraft_only` Condition: Optional, but required if `category` is defined Description: Declares that a package was prepared according to ground, passenger aircraft, or cargo aircraft only
`shipmentRequests.shipmentParameters .orderItemQuantities.productDetails`	Type: Array of strings Values: `limited_quantity` (preferred for LQ/ORM-D; alias: `lq`), `limited_quantity_air`, `excepted_quantity`, `small_battery_exception_air`, `small_battery_exception_ground`, `bound_printed_matter` (alias: `bpm`), `perishable`, `ormd` (legacy; alias: `orm-d`) Condition: Required for international shipments and shipments containing hazardous materials Description: A list of product properties that affect carrier selection and handling; see productDetails Reference for details.
`shipmentRequests.shipmentParameters .orderItemQuantities.productId`	Type: String Example: `RN03947-Z43121` Condition: Optional, but required for international shipments and shipments containing hazardous materials Description: A product ID for the product being checked, such as ISBN and UPC
`shipmentRequests.shipmentParameters .orderItemQuantities.quantity`	Type: Integer (int32) Example: `3` Condition: Optional, but required for international shipments and shipments containing hazardous materials Description: The number of units of this product
`shipmentRequests.shipmentParameters .packagingType.linearDimensions.height`	Type: Number (float) Example: `10` Condition: Required when `packagingTypeId` is not provided; optional when `packagingTypeId` is provided (applied when dimensions are not defined in the pre-configured packaging) Description: The least long linear dimension (i.e., the shortest side of a box or envelope)
`shipmentRequests.shipmentParameters .packagingType.linearDimensions.length`	Type: Number (float) Example: `13` Condition: Required when `packagingTypeId` is not provided; optional when `packagingTypeId` is provided (applied when dimensions are not defined in the pre-configured packaging) Description: The longest linear dimension (i.e., the longest side of a box or envelope)
`shipmentRequests.shipmentParameters .packagingType.linearDimensions .linearUnit`	Type: String (enumeration) Values: `cm` (centimeter), `in` (inch) Condition: Required when `packagingTypeId` is not provided; optional when `packagingTypeId` is provided (applied when dimensions are not defined in the pre-configured packaging) Description: The unit in which linear dimensions are provided
`shipmentRequests.shipmentParameters .packagingType.linearDimensions.width`	Type: Number (float) Example: `12` Condition: Required when `packagingTypeId` is not provided; optional when `packagingTypeId` is provided (applied when dimensions are not defined in the pre-configured packaging) Description: The second longest linear dimension (i.e., the second longest side of a box or envelope)
`shipmentRequests.shipmentParameters .packagingType.packagingMaterial`	Type: String (enumeration) Values: `box`, `envelope`, `flat_pack`, `mailing_tube`, `parcel_pallet` Condition: Required when `packagingTypeId` is not provided; optional when `packagingTypeId` is provided (applied when `packagingMaterial` is not defined in the pre-configured packaging) Description: The material type of the packaging
`shipmentRequests.shipmentParameters .packagingType.packagingTypeId`	Type: String Example: `ebd94f8b-d390-4c9c-987f-b88343f5bf45` Condition: When provided, `linearDimensions` and `packagingMaterial` become optional and are used only if not defined in the pre-configured packaging; when absent, `linearDimensions` and `packagingMaterial` are required. Description: The unique identifier for a a pre-configured packaging type defined in the Shipium Console. When provided, the system uses the pre-configured packaging properties (dimensions, material, weight) associated with this ID.
`shipmentRequests.shipmentParameters .shipFromAddress.countryCode`	Type: String Condition: If you include the optional `originId` in your call, the `shipFromAddress` should not be included. Description: The ISO 3166-1 country code for the origin address
`shipmentRequests.shipmentParameters .shipFromAddress.postalCode`	Type: String Condition: If you include the optional `originId` in your call, the `shipFromAddress` should not be included. Description: A country-code-appropriate postal code for the origin address

Optional request fields

Request field	Details
`options.currencyCode`	Type: String Description: The default currency in which all the rates for shipping carrier selection costs will be calculated; if this is specified on an individual shipment request, that value will be used instead for that shipment.
`options.fulfillmentContext`	Type: String Description: The default fulfillment context to be specified across all requests; if this is specified on the individual request's shipment parameters payload, that value will be used instead for that shipment.
`options.megaProcessVersionOverride`	Type: String Description: Override for all-in-one carrier selection and label call process version; this will apply to all shipments in the request.
`options.tenantId`	Type: String Description: The default tenant ID to be specified across all requests; if this is specified on the individual request's shipment parameters payload, that value will be used instead for that shipment.
`options.includeFullShipmentResponses`	Type: String Description: Indicates whether to return the full shipment response; if not specified, the full payload will be returned by default.
`shipmentRequests.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.
`shipmentRequests.ignoreRuleSets`	Type: Boolean Values: `true` or `false` Description: When `true`, any configured rule sets will be ignored during carrier selection.
`shipmentRequests.includeInjectionProfiles`	Type: Boolean Values: `true` or `false` Description: When `true`, service methods from the configured injection profiles will be considered during carrier selection.
`shipmentRequests.injectionParameters .injectionSiteId`	Type: String Description: The Shipium ID or the ID that your organization provided for an injection site that should be considered during carrier selection; if an `injectionSiteId` is specified, it must be accompanied by an `injectionProfileId`.
`shipmentRequests.labelParameters .currencyCode`	Type: String Description: Currency in which all the rates for shipping carrier selection costs will be calculated
`shipmentRequests.labelParameters .customLabelEntries.additionalProp1`	Type: String Description: List of formats in which to generate the package label
`shipmentRequests.labelParameters .includeLabelImagesInResponse`	Type: Boolean Values: `true` or `false` Description: When `true`, the response will include the raw image data of the labels that were requested to be generated by the carrier.
`shipmentRequests.labelParameters .labelFormats`	Type: String (enumeration) Values: `pdf`, `png`, `zpl` Description: List of formats in which to generate the package label
`shipmentRequests.labelParameters .eligibleForManifest`	Type: Boolean Values: `true` or `false` Description: When `true`, or null, this label will be included in end-of-day and scheduled manifests. `False` indicates that the label should not be included in any manifests.
`shipmentRequests.shipmentParameters .businessDaysOfTransit`	Type: Integer (int32) Description: Indicates the number of business days from the ship time by when the shipment needs to be delivered
`shipmentRequests.shipmentParameters .carrierName`	Type: String Example: `ups` Description: The carrier that was used for delivering the package to your customer
`shipmentRequests.shipmentParameters .deliveredDateTime`	Type: String (date-time) Example: `2019-10-31T20:00:00Z` Description: Either an ISO-8601 date or a local date: `yyyy-mm-dd;` the date or date-time the package is intended to arrive to the customer; this will be used to determine the most appropriate service method when generating a label.
`shipmentRequests.shipmentParameters .testMode`	Type: Boolean Values: `true` or `false` Description: If `true`, a test mode shipment will be created. Carrier selection will consider carriers and service methods in test mode, and label generation will generate a test label.
`shipmentRequests.shipmentParameters .deliveryNote`	Type: String Description: String passed to carriers for a delivery note
`shipmentRequests.shipmentParameters .deliverySignatureOption`	Type: String (enumeration) Values: `none`, `signature`, `resident_signature`, `adult_signature`, `adult_resident_signature`, `unknown` Description: A delivery signature option passed in the API request; defaults to `none`
`shipmentRequests.shipmentParameters .deliveryWindow.timeZone.id`	Type: String Description: The time zone identifier for this delivery window; if no time zone is passed, time zone will be taken from the destination address.
`shipmentRequests.shipmentParameters .deliveryWindow.timeZone.rules.fixedOffset`	Type: Boolean Values: `true` or `false` Description: If `true`, this indicates there is a fixed offset.
`shipmentRequests.shipmentParameters .deliveryWindow.timeZone.rules .transitionRules.dayOfMonthIndicator`	Type: Integer (int32) Description: The day of the month for the transition rule(s)
`shipmentRequests.shipmentParameters .deliveryWindow.timeZone.rules .transitionRules.dayOfWeek`	Type: String (enumeration) Values: `Monday`, `Tuesday`, `Wednesday`, `Thursday`, `Friday`, `Saturday`, `Sunday` Description: The day of the week for the transition rule(s)
`shipmentRequests.shipmentParameters .deliveryWindow.timeZone.rules .transitionRules.localTime.hour`	Type: Integer (int32) Description: The local time hour for the transition rule(s)
`shipmentRequests.shipmentParameters .deliveryWindow.timeZone.rules .transitionRules.localTime.minute`	Type: Integer (int32) Description: The local time minute for the transition rule(s)
`shipmentRequests.shipmentParameters .deliveryWindow.timeZone.rules .transitionRules.localTime.nano`	Type: Integer (int32) Description: The local time nano for the transition rule(s)
`shipmentRequests.shipmentParameters .deliveryWindow.timeZone.rules .transitionRules.localTime.second`	Type: Integer (int32) Description: The local time second for the transition rule(s)
`shipmentRequests.shipmentParameters .deliveryWindow.timeZone.rules .transitionRules.midnightEndOfDay`	Type: Boolean Values: `true` or `false` Description: If `true`, midnight is considered end of day.
`shipmentRequests.shipmentParameters .deliveryWindow.timeZone.rules .transitionRules.month`	Type: String (enumeration) Values: `January`, `February`, `March`, `April`, `May`, `June`, `July`, `August`, `September`, `October`, `November`, `December` Description: The month for the transition rule(s)
`shipmentRequests.shipmentParameters .deliveryWindow.timeZone.rules .transitionRules.offsetAfter.id`	Type: String Description: The identifier for the offset after
`shipmentRequests.shipmentParameters .deliveryWindow.timeZone.rules .transitionRules.offsetAfter.rules`	Type: String Description: The rules for the offset after
`shipmentRequests.shipmentParameters .deliveryWindow.timeZone.rules .transitionRules.offsetAfter.totalSeconds`	Type: Integer (int32) Description: The total seconds for the offset after
`shipmentRequests.shipmentParameters .deliveryWindow.timeZone.rules .transitionRules.offsetBefore.id`	Type: String Description: The identifier for the offset before
`shipmentRequests.shipmentParameters .deliveryWindow.timeZone.rules .transitionRules.offsetBefore.rules`	Type: String Description: The rules for the offset before
`shipmentRequests.shipmentParameters .deliveryWindow.timeZone.rules .transitionRules.offsetBefore.totalSeconds`	Type: Integer (int32) Description: The total seconds for the offset before
`shipmentRequests.shipmentParameters .deliveryWindow.timeZone.rules .transitionRules.standardOffset.id`	Type: String Description: The identifier for the standard offset
`shipmentRequests.shipmentParameters .deliveryWindow.timeZone.rules .transitionRules.standardOffset.rules`	Type: String Description: The rules for the standard offset
`shipmentRequests.shipmentParameters .deliveryWindow.timeZone.rules .transitionRules.standardOffset .totalSeconds`	Type: Integer (int32) Description: The total seconds for the standard offset
`shipmentRequests.shipmentParameters .deliveryWindow.timeZone.rules .transitionRules.timeDefinition`	Type: String (enumeration) Values: `utc`, `wall`, `standard` Description: The type of time for the transition rule(s)
`shipmentRequests.shipmentParameters .deliveryWindow.timeZone.rules .transitions.dateTimeAfter`	Type: String (date-time) Description: The date-time after the transition rule(s)
`shipmentRequests.shipmentParameters .deliveryWindow.timeZone.rules .transitions.dateTimeBefore`	Type: String (date-time) Description: The date-time before the transition rule(s)
`shipmentRequests.shipmentParameters .deliveryWindow.timeZone.rules .transitions.duration.nano`	Type: Integer (int32) Description: The nano value for the duration of the transition
`shipmentRequests.shipmentParameters .deliveryWindow.timeZone.rules .transitions.duration.negative`	Type: Boolean Values: `true` or `false` Description: If `true`, the duration is a negative value.
`shipmentRequests.shipmentParameters .deliveryWindow.timeZone.rules .transitions.duration.seconds`	Type: Integer (int32) Description: The seconds value for the duration of the transition
`shipmentRequests.shipmentParameters .deliveryWindow.timeZone.rules .transitions.duration.units.dateBased`	Type: Boolean Values: `true` or `false` Description: If `true`, the duration units are based on date.
`shipmentRequests.shipmentParameters .deliveryWindow.timeZone.rules .transitions.duration.units.duration`	Type: String Description: The duration of the transition
`shipmentRequests.shipmentParameters .deliveryWindow.timeZone.rules .transitions.duration.units .durationEstimated`	Type: Boolean Values: `true` or `false` Description: If `true`, the duration is estimated.
`shipmentRequests.shipmentParameters .deliveryWindow.timeZone.rules .transitions.duration.units.timeBased`	Type: Boolean Values: `true` or `false` Description: If `true`, the duration units are based on time.
`shipmentRequests.shipmentParameters .deliveryWindow.timeZone.rules .transitions.duration.zero`	Type: Boolean Values: `true` or `false` Description: If `true`, the duration value is zero.
`shipmentRequests.shipmentParameters .deliveryWindow.timeZone.rules .transitions.gap`	Type: Boolean Values: `true` or `false` Description: If `true`, there is a gap in the duration.
`shipmentRequests.shipmentParameters .deliveryWindow.timeZone.rules .transitions.instant`	Type: String Description: The instant of the transition
`shipmentRequests.shipmentParameters .deliveryWindow.timeZone.rules .transitions.offsetAfter.id`	Type: String Description: The identifier for the offset after
`shipmentRequests.shipmentParameters .deliveryWindow.timeZone.rules .transitions.offsetAfter.rules`	Type: String Description: The rules for the offset after
`shipmentRequests.shipmentParameters .deliveryWindow.timeZone.rules .transitions.offsetAfter.totalSeconds`	Type: Integer (int32) Description: The total seconds for the offset after
`shipmentRequests.shipmentParameters .deliveryWindow.timeZone.rules .transitions.offsetBefore.id`	Type: String Description: The identifier for the offset before
`shipmentRequests.shipmentParameters .deliveryWindow.timeZone.rules .transitions.offsetBefore.rules`	Type: String Description: The rules for the offset before
`shipmentRequests.shipmentParameters .deliveryWindow.timeZone.rules .transitions.offsetBefore.totalSeconds`	Type: Integer (int32) Description: The total seconds for the offset before
`shipmentRequests.shipmentParameters .deliveryWindow.timeZone.rules .transitions.overlap`	Type: Boolean Values: `true` or `false` Description: If `true`, there is overlap for the transition.
`shipmentRequests.shipmentParameters .desiredDeliveryDate`	Type: String (date-time) Example: `2019-10-31T20:00:00Z` Description: Either an ISO-8601 date or a local date: `yyyy-mm-dd`; the date or date-time the package is intended to arrive to the customer; this will be used to determine the most appropriate service method when generating a label.
`shipmentRequests.shipmentParameters .destinationAddress.addressType`	Type: String (enumeration) Values: `commercial`, `residential` Description: The type of location for the destination address
`shipmentRequests.shipmentParameters .destinationAddress.city`	Type: String Description: The name of the city for the destination address
`shipmentRequests.shipmentParameters .destinationAddress.company`	Type: String Description: The company name for the destination address
`shipmentRequests.shipmentParameters .destinationAddress.emailAddress`	Type: String Description: The email address of the contact for the destination address
`shipmentRequests.shipmentParameters .destinationAddress.name`	Type: String Description: The name associated with the destination address
`shipmentRequests.shipmentParameters .destinationAddress.phoneNumber`	Type: String Description: The phone number of the contact for the destination address
`shipmentRequests.shipmentParameters .destinationAddress.phoneNumberCountryCode`	Type: String Description: The phone number country code of the contact for the destination address
`shipmentRequests.shipmentParameters .destinationAddress.state`	Type: String Description: The name of the state for the destination address
`shipmentRequests.shipmentParameters .destinationAddress.street1`	Type: String Description: The first address line
`shipmentRequests.shipmentParameters .destinationAddress.street2`	Type: String Description: The second address line
`shipmentRequests.shipmentParameters .forceThirdPartyBilling`	Type: Boolean Values: `true` or `false` Description: If `true`, this indicates that third party billing is a requirement for this shipment and that no service method should be selected that does not support third party billing.
`shipmentRequests.shipmentParameters .fulfillmentContext`	Type: String Description: When present, this is used to limit carrier selection to carrier accounts that contain a matching fulfillment context.
`shipmentRequests.shipmentParameters .fulfillmentType`	Type: String (enumeration) Values: `customer`, `at_large`, `returns`, `hundredweight`, `reship`, `unknown` Description: Fulfillment methodology of the shipment
`shipmentRequests.shipmentParameters .ignoreUpgradeSpendLimits`	Type: Boolean Values: `true` or `false` Description: If `true`, this indicates that this shipment can ignore all of your organization's configured upgrade limits for the potential upgrade required to deliver the shipment by the desired delivery date.
`shipmentRequests.shipmentParameters .orderItemQuantities.deliveryEstimateId`	Type: String Example: `0b3d140a-525b-43a7-896c-cdc381580d61` Description: Delivery estimate ID associated with this product
`shipmentRequests.shipmentParameters .orderItemQuantities.hazmat`	Type: Boolean Values: `true` or `false` Description: If `true`, this indicates that the item is hazmat. The default value is `false`.
`shipmentRequests.shipmentParameters .orderItemQuantities.hazmatInfo .packingGroup`	Type: String (enumeration) Values: `i`, `ii`, `iii` Description: The packing group code for the hazardous material
`shipmentRequests.shipmentParameters .orderItemQuantities.hazmatInfo .packingInstructionCode`	Type: String Example: `967` Description: The packing instruction code used for air transport
`shipmentRequests.shipmentParameters .orderItemQuantities.hazmatInfo .subsidiaryClasses`	Type: String Example: `8.1` Description: The appropriate IATA/DOT subsidiary classes associated with the material and the hazard class
`shipmentRequests.shipmentParameters .orderItemQuantities.partnerOrderId`	Type: String Example: `myCustomPartnerOrderId123` Description: The unique identifier representing this order
`shipmentRequests.shipmentParameters .orderItemQuantities.shipiumOrderId`	Type: String Example: `4dc43fff-c3af-4d7b-8a18-e01f2b4cb312` Description: Identification use to represent the group of delivery estimates purchased
`shipmentRequests.shipmentParameters .packagingType.packagingSizeName`	Type: String Example: `13x12x10 box` Description: A custom name for the packaging
`shipmentRequests.shipmentParameters .packagingType.packagingWeight.weight`	Type: Number (float) Example: `50` Description: The value of the weight
`shipmentRequests.shipmentParameters .packagingType.packagingWeight.weightUnit`	Type: String (enumeration) Values: `g` (gram), `kg` (kilogram), `lb` (pound), `oz` (ounce) Description: The unit in which weight values are provided
`shipmentRequests.shipmentParameters .partnerShipmentId`	Type: String Description: An optional unique identifier that may be used for the shipment
`shipmentRequests.shipmentParameters .purchaseOrderIdentifier`	Type: String Description: String passed to carriers as a purchase order identifier
`shipmentRequests.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).
`shipmentRequests.shipmentParameters .saturdayDelivery`	Type: Boolean Values: `true` or `false` Description: If you pass `saturdayDelivery`, you can specify whether or not you want Saturday delivery to be an option for this package. Note: This does not guarantee a Saturday delivery.
`shipmentRequests.shipmentParameters .shipFromAddress.addressType`	Type: String (enumeration) Values: `commercial`, `residential` Description: The type of location for the origin address
`shipmentRequests.shipmentParameters .shipFromAddress.city`	Type: String Description: The name of the city for the origin address
`shipmentRequests.shipmentParameters .shipFromAddress.company`	Type: String Description: The company name for the origin address
`shipmentRequests.shipmentParameters .shipFromAddress.emailAddress`	Type: String Description: The email address of the contact for the origin address
`shipmentRequests.shipmentParameters .shipFromAddress.name`	Type: String Description: The name of the contact for the origin address
`shipmentRequests.shipmentParameters .shipFromAddress.phoneNumber`	Type: String Description: The phone number of the contact for the origin address
`shipmentRequests.shipmentParameters .shipFromAddress.phoneNumberCountryCode`	Type: String Description: The phone number country code of the contact for the origin address
`shipmentRequests.shipmentParameters .shipFromAddress.state`	Type: String Description: The 2-letter postal abbreviation of the state for the origin address
`shipmentRequests.shipmentParameters .shipFromAddress.street1`	Type: String Description: The first address line
`shipmentRequests.shipmentParameters .shipFromAddress.street2`	Type: String Description: The second address line
`shipmentRequests.shipmentParameters .useShipFromAddressInRequest`	Type: Boolean Values: `true` or `false` Description: When `true`, this optional field overrides the shipper's contact name and address configured for the shipping origin in the Shipium Console, opting to use the `shipFromAddress` information passed in the API call. Note: If shipping with carrier LaserShip, use caution with this flag as the carrier's strict address matching could result in an error.
`shipmentRequests.shipmentParameters .shipOption`	Type: String Example: `standard` Description: A high-level shipping option shown to or selected by a customer
`shipmentRequests.shipmentParameters .shipmentTags`	Type: String Description: A collection of free-form tags that may be added to the shipment
`shipmentRequests.shipmentParameters .shippedDateTime`	Type: String (date-time) Description: The timestamp for when you shipped the product from your warehouse; the timestamp must be a valid ISO 8601 timestamp. If not provided, this value defaults to `orderedDateTime`.
`shipmentRequests.shipmentParameters .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.
`shipmentRequests.shipmentParameters .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.
`shipmentRequests.shipmentParameters .totalWeight.weight`	Type: Number ($float) Description: The value of the weight
`shipmentRequests.shipmentParameters .totalWeight.weightUnit`	Type: String (enumeration) Values: `g` (gram), `kg` (kilogram), `lb` (pound), `oz` (ounce) Description: The unit in which weight values are provided

Resources

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