Configurable Ship Options

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.

  1. Once logged into the Shipium platform, you'll select Configure and then Configurable Ship Options.

  2. To add a new ship option, you'll select the + Add Ship Option button. After completing the fields in the popup window, you'll select OK.

    • 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.
    • Ship Option Name. This is the human-readable name you wish to assign to this ship option. Its value has no limitations.
    • 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.

  3. 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. The Configuration Events column captures the creation of your new ship option as well as the most recent modification.

  4. For successful configuration, you'll need to add origins (warehouses, fulfillment centers, etc.) and carrier service methods. Select the Add button within Carrier Service Methods.

  5. Once you've selected the Add button, a new popup 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 may select the global option for all origins or include only select origins.

    • Most frequent use case: Select ALL Origins and then Next.
    • Advanced use case: Select ONLY specific Origins, check the box next to each desired origin, and then select Next.

  6. After establishing origin scope, you'll select carrier service methods. Check the box next to each carrier service method you wish to associate with this ship option, and then select Next. You can see the number of origins selected and the number of carrier service methods at the top of the workflow.

  7. Review your selections in the Configuration Summary window before selecting the Save button.

  8. You can make revisions before saving by selecting the Previous button or clicking on Select Origin Scope or Select Carrier Service Methods.

  9. After saving, the ship option will be displayed, allowing you to select desired origin scopes to edit, delete, and add carrier service methods. You can also use the Edit button to make changes to the Ship Option Name and optional description.

Use ship options when creating a shipment

When creating a shipment, you may specify your desired ship option through the Carrier and Method Selection & Shipment Label API or the Carrier and Method Selection API. When you provide a ship option, eligible service methods will be restricted to the associated service methods.

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, visit Shipium Default Ship Options.

Authentication for API Calls

In the cURL examples, the environment variable AUTHSTRING is used to handle authorization. See the recipe below for correct setup for both API Key and OAuth users.

Request fields for ship options

Request field Details
shipOption Type: String (enumeration)
Values: Limited to available configurable ship options set up by your organization and to Shipium's default ship options
Description: Dictate the ship options considered when creating a shipment.

Shipium assumptions for using ship options

Request example for carrier and method selection and label generation

If your organization doesn't separate carrier/method selection from label generation, you can use this API to combine the calls into a single call.

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

{
  "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": [
      "fragile"
    ],
    "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": "https://api.shipium.com/labels/1a486afc-2ffc-4c37-928f-8d6aa014b35b.zpl"
      }
    ],
    "partnerShipmentId": "myCustomPartnerShipmentId123",
    "shipiumShipmentId": "49cf130d-b297-4c12-aa7d-82ea80208fde",
    "shipiumLabelId": "5b37704e-130e-4893-82e7-600843475bbb",
    "status": "success",
    "statusDetails": "Label created successfully"
  },
  "orderItemQuantities": [
    {
      "productDetails": [
        "lio"
      ],
      "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": [
    "fragile"
  ],
  "shippedDateTime": "2019-10-29T09:12:33.123456Z",
  "totalWeight": {
    "weight": 6.58,
    "weightUnit": "lb"
  }
}

FAQ

Q: Can I include a desired delivery date (DDD) in addition to passing a ship option?

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.