About configurable ship options

Your organization may wish to determine when specific carriers and their service methods are considered for a given shipment. You can configure a group of service methods for consideration, which we call a configurable ship option. When a ship option is provided in a call to Shipium's application programming interfaces (APIs), Shipium restricts the eligible service methods to the list of service methods associated with that ship option.

Shipium manages a list of ship options that you may reference when using our Carrier Selection service.

Configure and maintain your ship options

To set up your organization's ship options, you'll need to complete the following steps. First, you must access the Shipium Console.

Once logged into the Shipium platform, you'll select Configure and then Configurable Ship Options from the lefthand navigation menu.
To add a new ship option, you'll select the + Add Ship Option button in the upper right of the screen. After completing the following three fields in the popup window, you'll select OK.
1. Ship Option Identifier. This value is the one you'll use as the shipOption value in the API call. It's limited to alphanumeric characters, hyphens, and underscores. You may not override any Shipium default ship options with your own ship option. This value must be unique and not duplicate one of the Shipium Default Ship Options. This unique ID is case sensitive.
2. Ship Option Name. This is the human readable name you wish to assign to this ship option. Its value has no limitations.
3. Ship Option Description. This is an optional description of what the ship option is meant to do that you may enter to help organize your ship options.

After you select OK, the new ship option will open for editing, with the name, identifier, and description (if provided) appearing at the top left. Note that the Configuration Events column at right captures the creation of your new ship option as well as the most recent modification.

For a successful configuration of your ship option, you'll need to add origins (warehouses, fulfillment centers, etc.) and carrier service methods. To do so, you'll select the Add button within Carrier Service Methods.

Once you've selected the Add button, a new popup window will prompt you to select the origin scope, which means the origins within your fulfillment network that will be applicable to this ship option. You most likely will select the global option for all origins to be included in the ship option. However, you sometimes may choose to include only select origins.
1. Most frequent use case. If this ship option will apply to all origins within your network, you'll select ALL Origins and then Next.
2. Advanced use case. If this ship option will apply only to certain origins within your network, you'll select ONLY specific Origins, check the box next to each desired origin from the list of origins, and then select Next.

After establishing origin scope, you'll select carrier service methods. To do so, you'll check the box next to each carrier service method you wish to associate with this ship option, and then select Next. Note that you can see the number of origins you selected in the first step as well as the number of carrier service methods for this step at the top of the workflow. For this example, all 12 expedited service methods are selected in the example screenshot.

Next you'll be able to review all your selections in the Configuration Summary window before selecting the Save button.

You can make revisions to your Configurable Ship Option before saving it by selecting the Previous button or by clicking on Select Origin Scope or Select Carrier Service Methods at the top of the Configuration Summary window.
After saving your Configurable Ship Option, the ship option will be displayed on screen, allowing you to select desired origin scopes to edit, delete, and add carrier service methods. You can also use the Edit button at the top right to make changes to the Ship Option Name and optional Ship Option Description.

Use ship options when creating a shipment

When creating a shipment, you may specify your desired ship option, either using the Carrier and Method Selection & Shipment Label API mechanism or using the standard Shipment construction. When you provide a ship option, eligible service methods will be restricted to the list of service methods associated with that ship option.

You can provide your organization's own ship option or one of Shipium's default ship options for the shipOption field. To view the default ship options that Shipium manages, please visit Shipium Default Ship Options.

📘
Authentication for API Calls
In the cURL examples 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

The following table provides all required and optional fields for passing ship option information in the API call.

Request field	Required/Optional	Field properties	Description
`shipOption`	Optional	String enumeration Limited to available configurable ship options set up by your organization and to Shipium's default ship options	Dictate the ship options considered when creating a shipment.

Shipium assumptions for using ship options

Inactive status
An inactive configurable ship option will not be considered.

Request example for carrier and method selection and label generation

If your organization doesn't implement Shipium's shipment methods and your physical process doesn't separate carrier/method selection from label generation, you can use this API to combine the two separate calls into a single call.

The endpoint for the Carrier and Method Selection with Label Single Call API is included in the table below.

API type	API endpoint
POST	/api/v1/shipment/carrierselection/label

Example cURL call

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

Example request body

The following JSON request body demonstrates inclusion of the company-x-expedited-shipments ship option identifier value from the example in the Configure and Maintain Your Ship Options section above. You would include your organization's ship option identifier value, or alternately one of Shipium's default values, in your API call.

{
  "currencyCode": "usd",
  "generateLabel": true,
  "labelParameters": {
    "currencyCode": "usd",
    "labelFormats": [
      "zpl"
    ],
    "manifest": true,
    "includeLabelImagesInResponse": true
  },
  "shipmentParameters": {
    "partnerShipmentId": "myCustomPartnerShipmentId123",
    "shipiumShipmentId": "49cf130d-b297-4c12-aa7d-82ea80208fde",
    "orderedDateTime": "2019-10-29T09:12:33.123456Z",
    "shippedDateTime": "2019-11-01T12:11:33Z",
    "shipOption": "company-x-expedited-shipments",
    "referenceIdentifier": "yourCustomIdentifier",
    "testMode": true,
    "shipmentTags": [
      "string"
    ],
    "destinationAddress": {
      "addressType": "residential",
      "name": "Wile E. Coyote",
      "company": "ACME",
      "street1": "123 Warehouse St.",
      "street2": "Suite 42",
      "city": "Albuquerque",
      "state": "NM",
      "countryCode": "US",
      "postalCode": "87121"
    },
    "orderItemQuantities": [
      {
        "productDetails": [
          "ormd",
          "lio"
        ],
        "productId": "PRODUCTID001",
        "quantity": 3
      }
    ],
    "packagingType": {
        "packagingMaterial": "box",
        "linearDimensions": {
            "linearUnit": "in",
            "length": 9,
            "width": 6,
            "height": 3
        },
        "packagingWeight": {
            "weight": 6.58,
            "weightUnit": "lb"
        }
    },
    "totalWeight": {
      "weight": 6.58,
      "weightUnit": "lb"
    },
    "shipFromAddress": {
      "addressType": "commercial",
      "city": "Albuquerque",
      "company": "ACME",
      "countryCode": "US",
      "name": "L. Merfudd",
      "postalCode": "87121",
      "state": "NM",
      "street1": "123 Main St.",
      "street2": "Suite 42"
    }
  }
}

Example response

{
  "carrierSelection": {
    "carrier": "ups",
    "carrierAccountId": "4be237e4-eeb2-4e8a-94ea-6db695313ca6",
    "carrierSelectionDateTime": "2020-11-19T21:08:54.305Z",
    "carrierSelectionId": "5b0514bc-3cae-4311-af44-a95e64003631",
    "partnerId": "96ddb56a-18ba-4034-a14e-3fab072478f4",
    "serviceMethodName": "ground",
    "serviceMethodUrn": "c645ea83-d161-4e28-b8cb-39bf1a620cd3:4e14aaa3-198b-4861-b658-faf51031c84c:83fe5227-a765-45b2-bc2a-cb919ddce922:1",
    "totalCost": 7.53
  },
  "carrierName": "ups",
  "carrierTrackingId": "1Z999AA10123456784",
  "deliveredDateTime": "2020-10-31T10:50:11.123456Z",
  "estimatedDeliveryDate": "2022-12-02T03:00:00Z",
  "destinationAddress": {
    "addressType": "residential",
    "name": "Wile E. Coyote",
    "company": "ACME",
    "street1": "123 Warehouse St.",
    "street2": "Suite 42",
    "city": "Albuquerque",
    "state": "NM",
    "postalCode": "87121",
    "countryCode": "US"
  },
  "fulfillmentCenterId": "74065136-85c2-499b-b893-bd812ac0c00f",
  "carrierLabel": {
    "effectiveShipDateTime": "2022-11-28T03:00:00Z",
    "carrier": "ups",
    "carrierLabelCurrency": "usd",
    "carrierLabelPrice": 7.53,
    "billableWeight": {
      "weight": 6.0,
      "weightUnit": "lb"
    },
    "carrierSelectionId": "5b0514bc-3cae-4311-af44-a95e64003631",
    "carrierServiceName": "ground",
    "carrierTrackingId": "1Z999AA10123456784",
    "carrierTrackingLink": "https://www.ups.com/track?tracknum=%2B1Z999AA10123456784",
    "documents": [
      {
        "labelExpiration": "2020-11-19T21:08:54.305Z",
        "labelFormat": "zpl",
        "labelImage": {
          "imageContents": "BASE64LOOKINGSTUFFANDWHATHAVEYOUETCETCETC",
          "imageEncoding": "base64"
        },
        "labelUrl": "string"
      }
    ],
    "partnerShipmentId": "myCustomPartnerShipmentId123",
    "shipiumShipmentId": "49cf130d-b297-4c12-aa7d-82ea80208fde",
    "shipiumLabelId": "5b37704e-130e-4893-82e7-600843475bbb",
    "status": "success",
    "statusDetails": "Label created successfully"
  },
  "orderItemQuantities": [
    {
      "productDetails": [
        "string"
      ],
      "productId": "PRODUCTID001",
      "quantity": 3
    }
  ],
  "orderedDateTime": "2019-10-29T09:12:33.123456Z",
  "packagingType": {
        "packagingMaterial": "box",
        "linearDimensions": {
            "linearUnit": "in",
            "length": 9,
            "width": 6,
            "height": 3
        },
        "packagingWeight": {
            "weight": 6.58,
            "weightUnit": "lb"
        }          
  },
  "partnerShipmentId": "myCustomPartnerShipmentId123",
  "shipFromAddress": {
    "addressType": "commercial",
    "city": "Albuquerque",
    "company": "ACME",
    "countryCode": "US",
    "name": "L. Merfudd",
    "postalCode": "87121",
    "state": "NM",
    "street1": "123 Main St.",
    "street2": "Suite 42"
  },
  "shipOption": "company-x-expedited-shipments",
  "referenceIdentifier": "yourCustomIdentifier",
  "shipiumShipmentId": "0840c7a2-e6ab-4755-8aa2-9a986297ad6d",
  "shipmentTags": [
    "string"
  ],
  "shippedDateTime": "2019-10-29T09:12:33.123456Z",
  "totalWeight": {
    "weight": 6.58,
    "weightUnit": "lb"
  }
}

Request example for standard shipment creation

There are two ways to create a new shipment entry. The most common use case is to ship out exactly the set of items that your customer purchased in their order. You can simply POST to the order ship API's endpoint to create a shipment with the exact contents of the original order.

API type	API endpoint
POST	/deliveryexperience/order/{customerOrderId}/shipment

The more complex case is when you combine items from multiple orders for a given customer and ship them together. For this, you can specify the contents of the shipment more precisely using the shipment API's POST endpoint. This allows you to define a shipment that is composed of the contents of one or more orders, or portions of an order if you are shipping out a portion of an order.

API type	API endpoint
POST	deliveryexperience/shipment

Example cURL call

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

Example request body

{
  "carrierName": "ups",
  "carrierTrackingId": "1ZHHDHKAHB01271929",
  "shipFromAddress": {
    "addressType": "commercial",
    "city": "Albuquerque",
    "company": "ACME",
    "countryCode": "US",
    "name": "L. Merfudd",
    "postalCode": "87121",
    "state": "NM",
    "street1": "123 Main St.",
    "street2": "Suite 42"
  },
  "shippedDateTime": "2020-03-29T22:59+0000",
  "shipmentParameters": {
    "partnerShipmentID": "myCustomPartnerShipmentId123",
    "shipiumShipmentId": "49cf130d-b297-4c12-aa7d-82ea80208fde",
    "orderedDateTime": "2019-10-29T09:12:33.123456Z",
    "shippedDateTime": "2019-11-01T12:11:33Z",
    "shipOption": "company-x-expedited-shipments",
    "referenceIdentifier": "yourCustomIdentifier",
    "shipmentTags": [
      "string"
    ]
  }
}

Example response body

{
  "carrierName": "ups",
  "carrierTrackingId": "1ZHHDHKAHB01271929",
  "customerCountryCode":"US",
  "customerPostalCode":"98101",
  "orderedDateTime": "2020-03-27T22:14+0000",
  "referenceIdentifier": "yourCustomIdentifier",
  "orderItemQuantities": [
    { "productId": "9780345028853",
      "deliveryEstimateId": "1d02bca8-2008-4f79-9203-48acaf3cad54",
      "shipiumOrderId": "4dc43fff-c3af-4d7b-8a18-e01f2b4cb312",
      "partnerOrderId": "POID-12345",
      "quantity": 1
    },
    {
      "productId": "9780374533557",
      "deliveryEstimateId": "a6aae036-c7c2-40d7-b15d-f50c7d7e7950",
      "shipiumOrderId": "4dc43fff-c3af-4d7b-8a18-e01f2b4cb312",
      "partnerOrderId": "POID-12345",
      "quantity": 1
    }
  ],
  "shipiumShipmentId": "6b77f2d3-c292-4e28-9891-61daff1e5686",
  "shippedDateTime": "2020-03-29T22:59+0000",
      "shipFromAddress": {
          "addressType": "commercial",
          "city": "Albuquerque",
          "company": "ACME",
          "countryCode": "US",
          "name": "L. Merfudd",
          "postalCode": "87121",
          "state": "NM",
          "street1": "123 Main St.",
          "street2": "Suite 42"
      },
  "shipOption": "company-x-expedited-shipments",
  "shipmentTags": [
    "string"
  ]
}

FAQ

Q: Can I include a desired delivery date (DDD) in addition to passing a ship option when using the all-in-one shipment and label method?

A: Yes. For example, shipOption: standard, desiredDeliveryDate: 2023-11-15 limits the carrier selection search to only those methods that are marked as standard and for which the DDD of 2023-11-15 can be met. If the DDD of 2023-11-15 cannot be met, Shipium will return the cheapest service method on 2023-11-16, and so on.

Resources

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

About configurable ship options

Configure and maintain your ship options

Use ship options when creating a shipment

📘Authentication for API Calls

Shipium assumptions for using ship options

Request example for carrier and method selection and label generation

Example cURL call

Example request body

Example response

Request example for standard shipment creation

Example cURL call

Example request body

Example response body

FAQ

Resources

📘
Authentication for API Calls