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

Authenticating for Curl
Open Recipe

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 table provides the required and optional fields for calling the Batch Label Creation API.

Request field

Required/Optional

Field properties

Description

options.currencyCode

Optional

String

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

Optional

String

The default fulfillment context to be specified across all requests; if this is specified on the individual request's shipmen parameters payload, that value will be used instead for that shipment.

options.megaProcess
VersionOverride

Optional

String

Override for all-in-one carrier selection and label call process version; this will apply to all shipments in the request.

options.tenantId

Optional

String

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.includeFull
ShipmentResponses

Optional

String

Indicates whether to return the full shipment response; if not specified, the full payload will be returned by default.

shipmentRequests
  .currencyCode

Required

String
Ex.: usd

Currency in which all the rates for shipping carrier selection costs will be calculated

shipmentRequests
  .generateLabel

Optional

Boolean
true or false

When true, a request to the selected carrier will be sent to generate a label for the shipment based on the information provided in the labelParameters field of this object. When false, this step is skipped and the system will record what carrier service method would have generated a label for.

shipmentRequests
  .ignoreRuleSets

Optional

Boolean
true or false

When true, any configured rule sets will be ignored during carrier selection.

shipmentRequests
  .includeInjection
Profiles

Optional

Boolean
true or false

When true, service methods from the configured injection profiles will be considered during carrier selection.

shipmentRequests
  .injectionParameters
  .injectionProfileId

Conditional (optional, but required if providing an injectionSiteId)

String

The Shipium ID or the ID that your organization provided for an injection profile that should be considered during carrier selection

shipmentRequests
  .injectionParameters
  .injectionSiteId

Optional

String

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

Optional

String

Currency in which all the rates for shipping carrier selection costs will be calculated

shipmentRequests
  .labelParameters     
  .customLabelEntries
  .additionalProp1

Optional

String

List of formats in which to generate the package label

shipmentRequests
  .labelParameters
  .includeLabelImages
InResponse

Optional

Boolean
true or false

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

Optional

String enumeration
Values are:

  • pdf
  • png
  • zpl

List of formats in which to generate the package label

shipmentRequests
  .labelParameters
  .eligibleFor
  Manifest

Optional

Boolean
true or false

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
  .businessDays
OfTransit

Optional

Integer ($int32)

Indicates the number of business days from the ship time by when the shipment needs to be delivered

shipmentRequests
  .shipmentParameters
  .carrierName

Optional

String
Ex.: UPS

The carrier that was used for delivering the package to your customer

shipmentRequests
  .shipmentParameters
  .customsInfo

Conditional (optional, but some information is required for international shipments)

Object

Customs information about the package for international shipping; please refer to Customs Info for Shipments for details.

shipmentRequests
  .shipmentParameters
  .deliveredDateTime

Optional

String
Ex.: 2019-10-31T20:00:00Z

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

Optional

Boolean
true or false

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

Optional

String

String passed to carriers for a delivery note.

shipmentRequests
  .shipmentParameters
  .deliverySignature
Option

Optional

String enumeration
Values are:

  • none
  • signature
  • resident_signature
  • adult_signature
  • adult_resident_signature
  • unknown

A delivery signature option passed in the API request; defaults to none.

shipmentRequests
  .shipmentParameters
  .deliveryWindow
  .endWindow.hour

Required

String ($byte)

The end time hour for the delivery timeframe

shipmentRequests
  .shipmentParameters
  .deliveryWindow
  .endWindow.minute

Required

String ($byte)

The end time minute for the delivery timeframe

shipmentRequests
  .shipmentParameters
  .deliveryWindow
  .endWindow.nano

Required

Integer ($int32)

The end time nano for the delivery timeframe

shipmentRequests
  .shipmentParameters
  .deliveryWindow
  .endWindow.second

Required

String ($byte)

The end time second for the delivery timeframe

shipmentRequests
  .shipmentParameters
  .deliveryWindow
  .startWindow.hour

Required

String ($byte)

The start time hour for the delivery timeframe

shipmentRequests
  .shipmentParameters
  .deliveryWindow
  .startWindow.minute

Required

String ($byte)

The start time minute for the delivery timeframe

shipmentRequests
  .shipmentParameters
  .deliveryWindow
  .startWindow.nano

Required

Integer ($int32)

The start time nano for the delivery timeframe

shipmentRequests
  .shipmentParameters
  .deliveryWindow
  .startWindow.second

Required

String ($byte)

The start time second for the delivery timeframe

shipmentRequests
  .shipmentParameters
  .deliveryWindow
  .timeZone.id

Optional

String

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

Optional

Boolean
true or false

If true, this indicates there is a fixed offset.

shipmentRequests
  .shipmentParameters
  .deliveryWindow
  .timeZone.rules
  .transitionRules
  .dayOfMonth
Indicator

Optional

Integer ($int32)

The day of the month for the transition rule(s)

shipmentRequests
  .shipmentParameters
  .deliveryWindow
  .timeZone.rules
  .transitionRules
  .dayOfWeek

Optional

String enumeration
Values are:

  • Monday
  • Tuesday
  • Wednesday
  • Thursday
  • Friday
  • Saturday
  • Sunday

The day of the week for the transition rule(s)

shipmentRequests
  .shipmentParameters
  .deliveryWindow
  .timeZone.rules
  .transitionRules
  .localTime.hour

Optional

Integer ($int32)

The local time hour for the transition rule(s)

shipmentRequests
  .shipmentParameters
  .deliveryWindow
  .timeZone.rules
  .transitionRules
  .localTime.minute

Optional

Integer ($int32)

The local time minute for the transition rule(s)

shipmentRequests
  .shipmentParameters
  .deliveryWindow
  .timeZone.rules
  .transitionRules
  .localTime.nano

Optional

Integer ($int32)

The local time nano for the transition rule(s)

shipmentRequests
  .shipmentParameters
  .deliveryWindow
  .timeZone.rules
  .transitionRules
  .localTime.second

Optional

Integer ($int32)

The local time second for the transition rule(s)

shipmentRequests
  .shipmentParameters
  .deliveryWindow
  .timeZone.rules
  .transitionRules
  .midnightEndOfDay

Optional

Boolean
true or false

If true, midnight is considered end of day.

shipmentRequests
  .shipmentParameters
  .deliveryWindow
  .timeZone.rules
  .transitionRules
  .month

Optional

String enumeration
Values are:

  • January
  • February
  • March
  • April
  • May
  • June
  • July
  • August
  • September
  • October
  • November
  • December

The month for the transition rule(s)

shipmentRequests
  .shipmentParameters
  .deliveryWindow
  .timeZone.rules
  .transitionRules
  .offsetAfter.id

Optional

String

The identifier for the offset after

shipmentRequests
  .shipmentParameters
  .deliveryWindow
  .timeZone.rules
  .transitionRules
  .offsetAfter.rules

Optional

String

The rules for the offset after

shipmentRequests
  .shipmentParameters
  .deliveryWindow
  .timeZone.rules
  .transitionRules
  .offsetAfter
  .totalSeconds

Optional

Integer ($int32)

The total seconds for the offset after

shipmentRequests
  .shipmentParameters
  .deliveryWindow
  .timeZone.rules
  .transitionRules
  .offsetBefore.id

Optional

String

The identifier for the offset before

shipmentRequests
  .shipmentParameters
  .deliveryWindow
  .timeZone.rules
  .transitionRules
  .offsetBefore.rules

Optional

String

The rules for the offset before

shipmentRequests
  .shipmentParameters
  .deliveryWindow
  .timeZone.rules
  .transitionRules
  .offsetBefore
  .totalSeconds

Optional

Integer ($int32)

The total seconds for the offset before

shipmentRequests
  .shipmentParameters
  .deliveryWindow
  .timeZone.rules
  .transitionRules
  .standardOffset.id

Optional

String

The identifier for the standard offset

shipmentRequests
  .shipmentParameters
  .deliveryWindow
  .timeZone.rules
  .transitionRules
  .standardOffset
  .rules

Optional

String

The rules for the standard offset

shipmentRequests
  .shipmentParameters
  .deliveryWindow
  .timeZone.rules
  .transitionRules
  .standardOffset
  .totalSeconds

Optional

Integer ($int32)

The total seconds for the standard offset

shipmentRequests
  .shipmentParameters
  .deliveryWindow
  .timeZone.rules
  .transitionRules
  .timeDefinition

Optional

String enumeration
Values are:

  • utc
  • wall
  • standard

The type of time for the transition rule(s)

shipmentRequests
  .shipmentParameters
  .deliveryWindow
  .timeZone.rules
  .transitions
  .dateTimeAfter

Optional

String

The date-time after the transition rule(s)

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

Optional

String

The date-time before the transition rule(s)

shipmentRequests
  .shipmentParameters
  .deliveryWindow
  .timeZone.rules
  .transitions
  .duration.nano

Optional

Integer ($int32)

The nano value for the duration of the transition

shipmentRequests
  .shipmentParameters
  .deliveryWindow
  .timeZone.rules
  .transitions
  .duration.negative

Optional

Boolean
true or false

If true, the duration is a negative value.

shipmentRequests
  .shipmentParameters
  .deliveryWindow
  .timeZone.rules
  .transitions
  .duration.seconds

Optional

Integer ($int32)

The seconds value for the duration of the transition

shipmentRequests
  .shipmentParameters
  .deliveryWindow
  .timeZone.rules
  .transitions
  .duration.units
  .dateBased

Optional

Boolean
true or false

If true, the duration units are based on date.

shipmentRequests
  .shipmentParameters
  .deliveryWindow
  .timeZone.rules
  .transitions
  .duration.units
  .duration

Optional

String

The duration of the transition

shipmentRequests
  .shipmentParameters
  .deliveryWindow
  .timeZone.rules
  .transitions
  .duration.units
  .durationEstimated

Optional

Boolean
true or false

If true, the duration is estimated.

shipmentRequests
  .shipmentParameters
  .deliveryWindow
  .timeZone.rules
  .transitions
  .duration.units
  .timeBased

Optional

Boolean
true or false

If true, the duration units are based on time.

shipmentRequests
  .shipmentParameters
  .deliveryWindow
  .timeZone.rules
  .transitions
  .duration.zero

Optional

Boolean
true or false

If true, the duration value is zero.

shipmentRequests
  .shipmentParameters
  .deliveryWindow
  .timeZone.rules
  .transitions.gap

Optional

Boolean
true or false

If true, there is a gap in the duration.

shipmentRequests
  .shipmentParameters
  .deliveryWindow
  .timeZone.rules
  .transitions
  .instant

Optional

String

The instant of the transition

shipmentRequests
  .shipmentParameters
  .deliveryWindow
  .timeZone.rules
  .transitions
  .offsetAfter.id

Optional

String

The identifier for the offset after

shipmentRequests
  .shipmentParameters
  .deliveryWindow
  .timeZone.rules
  .transitions
  .offsetAfter.rules

Optional

String

The rules for the offset after

shipmentRequests
  .shipmentParameters
  .deliveryWindow
  .timeZone.rules
  .transitions
  .offsetAfter
  .totalSeconds

Optional

Integer ($32)

The total seconds for the offset after

shipmentRequests
  .shipmentParameters
  .deliveryWindow
  .timeZone.rules
  .transitions
  .offsetBefore.id

Optional

String

The identifier for the offset before

shipmentRequests
  .shipmentParameters
  .deliveryWindow
  .timeZone.rules
  .transitions
  .offsetBefore.rules

Optional

String

The rules for the offset before

shipmentRequests
  .shipmentParameters
  .deliveryWindow
  .timeZone.rules
  .transitions
  .offsetBefore
  .totalSeconds

Optional

Integer ($int32)

The total seconds for the offset before

shipmentRequests
  .shipmentParameters
  .deliveryWindow
  .timeZone.rules
  .transitions
  .overlap

Optional

Boolean
true or false

If true, there is overlap for the transition.

shipmentRequests
  .shipmentParameters
  .desiredDelivery
Date

Optional

String
Ex.: 2019-10-31T20:00:00Z

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

Conditional

String

Either the Shipium-generated origin ID or your organization's own origin ID, used to identify the origin where the shipment will be processed; if you include the optional originId in your call, the shipFromAddress should not be included.

shipmentRequests
  .shipmentParameters
  .destinationAddress
  .addressType

Optional

String enumeration
Values are:

  • commercial
  • residential

The type of location for the destination address

shipmentRequests
  .shipmentParameters
  .destinationAddress
  .city

Optional

String

The name of the city for the destination address

shipmentRequests
  .shipmentParameters
  .destinationAddress
  .company

Optional

String

The company name for the destination address

shipmentRequests
  .shipmentParameters
  .destinationAddress
  .countryCode

Required

String
Ex.: US

The ISO 3166-1 country code for the destination address

shipmentRequests
  .shipmentParameters
  .destinationAddress
  .emailAddress

Optional

String

The email address of the contact for the destination address

shipmentRequests
  .shipmentParameters
  .destinationAddress
  .name

Optional

String

The name associated with the destination address

shipmentRequests
  .shipmentParameters
  .destinationAddress
  .phoneNumber

Optional

String

The phone number of the contact for the destination address

shipmentRequests
  .shipmentParameters
  .destinationAddress
  .phoneNumber
CountryCode

Optional

String

The phone number country code of the contact for the destination address

shipmentRequests
  .shipmentParameters
  .destinationAddress
  .postalCode

Required

String

A country code appropriate postal code for the destination address

shipmentRequests
  .shipmentParameters
  .destinationAddress
  .state

Optional

String

The name of the state for the destination address

shipmentRequests
  .shipmentParameters
  .destinationAddress
  .street1

Optional

String

The first address line

shipmentRequests
  .shipmentParameters
  .destinationAddress
  .street2

Optional

String

The second address line

shipmentRequests
  .shipmentParameters
  .forceThirdParty
Billing

Optional

Boolean
true or false

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

Optional

String

When present, this is used to limit carrier selection to carrier accounts that contain a matching fulfillment context.

shipmentRequests
  .shipmentParameters
  .fulfillmentType

Optional

String enumeration
Values are:

  • customer
  • at_large
  • returns
  • hundredweight
  • reship
  • unknown

Fulfillment methodology of the shipment

shipmentRequests
  .shipmentParameters
  .ignoreUpgradeSpend
Limits

Optional

Boolean
true or false

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

Optional

String
Ex.: 0b3d140a-525b-43a7-896c-cdc381580d61

Delivery estimate ID associated with this product

shipmentRequests
  .shipmentParameters
  .orderItemQuantities
  .hazmat

Optional

Boolean
true or false

If true, this indicates that the item is hazmat. The default value is false.

shipmentRequests
  .shipmentParameters
  .orderItemQuantities
  .hazmatInfo
  .category

Conditional (optional, but required if including hazmatInfo)

String enumeration
Values are:

  • 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

Hazmat category for this order item; use defined to specify detailed information.

shipmentRequests
  .shipmentParameters
  .orderItemQuantities
  .hazmatInfo
  .containerType

Conditional (optional, but required if category is defined)

String enumeration
Values are:

  • fiberboard_box
  • wooden_box
  • plastic_jerrican
  • metal_box
  • steel_drum
  • other
  • plastic_box
  • plastic_drum
  • styrofoam_box
  • cylinder
  • envirotainer
  • plywood_box
  • aluminum_drum
  • aluminum_cylinder
  • plastic_pail
  • plywood_drum
  • fiber_drum
  • steel_jerrican
  • aluminum_jerrican
  • steel_box
  • carton
  • aluminum_box

The material in which the hazardous material is packaged

shipmentRequests
  .shipmentParameters
  .orderItemQuantities
  .hazmatInfo
  .hazardClass

Conditional (optional, but required if category is defined)

String enumeration
Values are:

  • class_1_explosive
  • class_2_flammable_gas
  • class_3_flammable_liquid
  • class_4_flammable_solid
  • class_5_organic_peroxide
  • class_6_poisonous_material
  • class_7_radioactive
  • class_8_corrosive_material
  • class_9_miscellaneous

The hazard class of the hazmat

shipmentRequests
  .shipmentParameters
  .orderItemQuantities
  .hazmatInfo
  .hazmatId

Conditional (optional, but required if category is defined)

String
Ex.: UN1755

The International Air Transport Association (IATA) or U.S. Department of Transportation (DOT) regulatory identifier for the commodity as appropriate

shipmentRequests
  .shipmentParameters
  .orderItemQuantities
  .hazmatInfo
  .packingGroup

Optional

String enumeration
Values are:

  • i
  • ii
  • iii

The packing group code for the hazardous material

shipmentRequests
  .shipmentParameters
  .orderItemQuantities
  .hazmatInfo
  .packingInstruction
Code

Optional

String
Ex.: 967

The packing instruction code used for air transport

shipmentRequests
  .shipmentParameters
  .orderItemQuantities
  .hazmatInfo
  .properShippingName

Conditional (optional, but required if category is defined)

String
Ex.: chromic acid solution

Proper shipping name that is associated with the specified hazmat ID

shipmentRequests
  .shipmentParameters
  .orderItemQuantities
  .hazmatInfo
  .quantity

Conditional (optional, but required if category is defined)

Number ($float)
Ex.: 2.1

The amount of quantity type material in quantity units

shipmentRequests
  .shipmentParameters
  .orderItemQuantities
  .hazmatInfo
  .quantityType

Conditional (optional, but required if category is defined)

String enumeration
Values are:

  • gross
  • net

Determines whether the quantity includes the raw material (net) or also includes the material housing (gross)

shipmentRequests
  .shipmentParameters
  .orderItemQuantities
  .hazmatInfo
  .quantityUnits

Conditional (optional, but required if category is defined)

String enumeration
Values are:

  • g (gram)
  • kg (kilogram)
  • lb (pound)
  • oz (ounce)
  • ml (milliliter)
  • l (liter)

The units of measure for the quantity of hazardous materials specified

shipmentRequests
  .shipmentParameters
  .orderItemQuantities
  .hazmatInfo
  .subsidiaryClasses

Optional

String
Ex.: 8.1

The appropriate IATA/DOT subsidiary classes associated with the material and the hazard class

shipmentRequests
  .shipmentParameters
  .orderItemQuantities
  .hazmatInfo
  .transportMode

Conditional (optional, but required if category is defined)

String enumeration
Values are:

  • ground
  • passenger_and_cargo_aircraft
  • cargo_aircraft_only

Declares that a package was prepared according to ground, passenger aircraft, or cargo aircraft only

shipmentRequests
  .shipmentParameters  
  .orderItemQuantities
  .partnerOrderId

Optional

String
Ex.: myCustomPartnerOrderId123

The unique identifier representing this order

shipmentRequests
  .shipmentParameters  
  .orderItemQuantities
  .productDetails

Conditional (optional, but required for international shipments and shipments containing hazardous materials)

String
Ex.: perishable, limited_quantity

A list of properties that may affect the shipping of the product

shipmentRequests
  .shipmentParameters  
  .orderItemQuantities
  .productId

Conditional (optional, but required for international shipments and shipments containing hazardous materials)

String
Ex.: RN03947-Z43121

A product ID for the product being checked, such as ISBN and UPC

shipmentRequests
  .shipmentParameters  
  .orderItemQuantities
  .quantity

Conditional (optional, but required for international shipments and shipments containing hazardous materials)

Integer($int32)
Ex.: 3

The number of units of this product

shipmentRequests
  .shipmentParameters  
  .orderItemQuantities
  .shipiumOrderId

Optional

String
Ex.: 4dc43fff-c3af-4d7b-8a18-e01f2b4cb312

Identification use to represent the group of delivery estimates purchased

shipmentRequests
  .shipmentParameters
  .orderedDateTime

Required

String

The timestamp for when a customer placed an order for this product; the timestamp must be a valid ISO 8601 timestamp

shipmentRequests
  .shipmentParameters
  .packagingType
  .linearDimensions
  .height

Conditional

Number ($float)
Example: 10

The least long linear dimension (i.e., the shortest side of a box or envelope).
Note on envelopes: This height should represent the highest product you would reasonably put in this envelope before losing more than 10% of the length of the envelope in other dimensions.

  • *REQUIRED when packagingTypeId is not provided.** OPTIONAL when packagingTypeId is provided; in this case, the value from the request will be used as a fallback if dimensions are not defined in the pre-configured packaging.
shipmentRequests
  .shipmentParameters
  .packagingType
  .linearDimensions
  .length

Conditional

Number ($float)
Example: 13

The longest linear dimension (i.e., the longest side of a box or envelope)

  • *REQUIRED when packagingTypeId is not provided.** OPTIONAL when packagingTypeId is provided; in this case, the value from the request will be used as a fallback if dimensions are not defined in the pre-configured packaging.
shipmentRequests
  .shipmentParameters
  .packagingType
  .linearDimensions
  .linearUnit

Conditional

String enumeration
Values are:

  • cm (centimeter)
  • in (inch)

The unit in which linear dimensions are provided

  • *REQUIRED when packagingTypeId is not provided.** OPTIONAL when packagingTypeId is provided; in this case, the value from the request will be used as a fallback if dimensions are not defined in the pre-configured packaging.
shipmentRequests
  .shipmentParameters
  .packagingType
  .linearDimensions
  .width

Conditional

Number ($float)
Example: 12

The second longest linear dimension (i.e., the second longest side of a box or envelope)

  • *REQUIRED when packagingTypeId is not provided.** OPTIONAL when packagingTypeId is provided; in this case, the value from the request will be used as a fallback if dimensions are not defined in the pre-configured packaging.
shipmentRequests
  .shipmentParameters
  .packagingType
  .packagingMaterial

Conditional

String enumeration
Values are:

  • box
  • envelope
  • flat_pack
  • mailing_tube
  • parcel_pallet

The material type of the packaging. REQUIRED whenpackagingTypeId is not provided. OPTIONAL when packagingTypeId is provided; in this case, the value from the request will be used as a fallback if the packagingMaterial is not defined in the pre-configured packaging associated with the packagingTypeId.

shipmentRequests
  .shipmentParameters
  .packagingType
  .packagingSizeName

Optional

String
Ex.: 13x12x10 box

A custom name for the packaging

shipmentRequests
  .shipmentParameters
  .packagingType
  .packagingTypeId

Conditional

String
Ex.: ebd94f8b-d390-4c9c-987f-b88343f5bf45

The unique identifier for 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. When this value is present, linearDimensions and packagingMaterial become optional as fallback fields. When this value is absent, linearDimensions and packagingMaterial are required.

shipmentRequests
  .shipmentParameters
  .packagingType
  .packagingWeight
  .weight

Optional

Number ($float)
Example: 50

The value of the weight

shipmentRequests
  .shipmentParameters
  .packagingType
  .packagingWeight
  .weightUnit

Optional

String enumeration
Values are:

  • g (gram)
  • kg (kilogram)
  • lb (pound)
  • oz (ounce)

The unit in which weight values are provided

shipmentRequests
  .shipmentParameters  
  .partnerShipmentId

Optional

String

An optional unique identifier that may be used for the shipment

shipmentRequests
  .shipmentParameters  
  .purchaseOrder
Identifier

Optional

String

String passed to carriers as a purchase order identifier

shipmentRequests
  .shipmentParameters  
  .reference
Identifier

Optional

String

String passed to carriers as a reference; this field can be expanded to include multiple reference identifiers by adding sequential numbers to the field name: referenceIdentifier2 (up to 5 reference identifiers)

shipmentRequests
  .shipmentParameters  
  .saturdayDelivery

Optional

Boolean
true or false

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

Optional

String
Values are:

  • commercial
  • residential

The type of location for the origin address

shipmentRequests
  .shipmentParameters  
  .shipFromAddress
  .city

Optional

String

The name of the city for the origin address

shipmentRequests
  .shipmentParameters  
  .shipFromAddress
  .company

Optional

String

The company name for the origin address

shipmentRequests
  .shipmentParameters  
  .shipFromAddress
  .countryCode

Conditional

String

The ISO 3166-1 country code for the origin address; if you include the optional originId in your call, the shipFromAddress should not be included.

shipmentRequests
  .shipmentParameters  
  .shipFromAddress
  .emailAddress

Optional

String

The email address of the contact for the origin address

shipmentRequests
  .shipmentParameters  
  .shipFromAddress
  .name

Optional

String

The name of the contact for the origin address

shipmentRequests
  .shipmentParameters  
  .shipFromAddress
  .phoneNumber

Optional

String

The phone number of the contact for the origin address

shipmentRequests
  .shipmentParameters
  .shipFromAddress
  .phoneNumber
CountryCode

Optional

String

The phone number country code of the contact for the origin address

shipmentRequests
  .shipmentParameters  
  .shipFromAddress
  .postalCode

Conditional

String

A country-code-appropriate postal code for the origin address; if you include the optional originId in your call, the shipFromAddress should not be included.

shipmentRequests
  .shipmentParameters  
  .shipFromAddress
  .state

Optional

String

The 2-letter postal abbreviation of the state for the origin address

shipmentRequests
  .shipmentParameters  
  .shipFromAddress
  .street1

Optional

String

The first address line

shipmentRequests
  .shipmentParameters  
  .shipFromAddress
  .street2

Optional

String

The second address line

shipmentRequests
  .shipmentParameters
  .useShipFromAddress
  InRequest

Optional

Boolean
true or false

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 carrierLaserShip, use caution with this flag as the carrier's strict address matching could result in an error.

shipmentRequests
  .shipmentParameters  
  .shipOption

Optional

String
Ex.: standard

A high-level shipping option shown to or selected by a customer

shipmentRequests
  .shipmentParameters  
  .shipmentTags

Optional

String

A collection of free-form tags that may be added to the shipment

shipmentRequests
  .shipmentParameters  
  .shippedDateTime

Optional

String ($date-time)

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

Optional

String

Either the Shipium Tenant ID or the Tenant ID provided by your organization (Partner Provided ID). When present, this is used to indicate the tenant associated with the shipment.

shipmentRequests
  .shipmentParameters  
  .thirdPartyBilling
SetId

Optional

String

Either the Shipium third party billing set ID or the third party billing set ID provided by your organization. When present, this is used to indicate the third party billing set that should be used for the billing of the shipment.

shipmentRequests
  .shipmentParameters  
  .totalWeight.weight

Optional

Number ($float)

The value of the weight

shipmentRequests
  .shipmentParameters  
  .totalWeight
  .weightUnit

Optional

String enumeration
Values are:

  • g (gram)
  • kg (kilogram)
  • lb (pound)
  • oz (ounce)

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 7 days ago