Guides
Start typing to search…

Batch Label Creation API

Generate multiple shipment labels in one call with Shipium's Batch Label Creation API.

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 typeAPI endpoint
POSThttps://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.

Authenticating for Curl
Open Recipe

Test the API call

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

API typeAPI endpoint
PINGhttps://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
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: String
Example: perishable, limited_quantity
Condition: Optional, but required for international shipments and shipments containing hazardous materials
Description: A list of properties that may affect the shipping of the product

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
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
Description: The date-time after the transition rule(s)

shipmentRequests.shipmentParameters .deliveryWindow.timeZone.rules .transitions.dateTimeBefore

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

Updated 3 days ago