Webhooks for Carrier Selection & Label Updates

Automatically receive updates for carrier selection and/or label generation events.

About webhooks for event updates with Shipium

Webhooks are a convenient way for your organization to be notified automatically of shipment event updates. You can register for a webhook to be notified of events for each service:

  • Carrier selection
  • Label generation

You'll need to register a separate webhook for each service – one for carrier selection and one for labels – for which you wish to receive notifications. Once you register a webhook for your organization, the next shipment update for your event will send notifications to the API endpoint for events matching your selected data fields (e.g., eventType). You will receive webhook notifications whenever a carrier selection or label is created, updated, or deleted, depending on the webhooks you register.

This document guides you through the steps to register a webhook for your organization for either carrier selection or label generation. You can register for both webhooks to receive updates for both carrier selection and label generation. To start, you’ll need to access the Shipium Console. To register a webhook for tracking shipments with Shipium, you can refer to Use Webhooks for Tracking.

One webhook registered per application to be notified with carrier selection or label generation (or both) event updates

Your organization can use a Shipium webhook to receive shipment event updates to one API endpoint (or application), and then manage those updates via your internal processing system or pass them to your internal customers.

For example, if you have customers A, B, and C that need to receive shipment event updates automatically, you would register one Shipium webhook for Customer A, one for Customer B, and one for Customer C, with three unique API endpoints.

🎣

One webhook per application to be notified with updates

Shipium suggests creating one webhook per desired application for which your organization needs to receive shipment event updates.

Once you've registered your organization's webhook, you can disable, delete, and enable it via the Shipium Console. You also can view a summary of all your registered webhooks within the console.

Steps to register your webhook

Within the Shipium Console, you'll follow these instructions to register your organization's webhook.

Step 1. Navigate to Carrier Selection Webhooks

In the navigation pane at left, navigate to Carrier Selection, and then Carrier Selection Webhooks.

Step 2. Add new webhook

Select the Add Webhook button to the far right of your screen, located near your organization's user account profile information. Any existing webhooks your organization has previously registered will appear on the Carrier Selection Webhooks screen. If your organization has no existing registered webhooks, this screen will contain no webhooks until you've registered your first one.

Step 3. Provide settings information

Complete the required Settings fields shown in the Webhook Detail screen.

  1. Name. Provide a descriptive name for your webhook. We suggest using a simple naming convention that uses the underscore symbol to separate each element of your webhook's intended use, such as {organization}_{action}_{app}_{version}.

    1. Use a descriptive name so it's easy to determine the nature of your webhook (e.g., OrganizationName_eastCostTrackingBroker_app1_v1 vs. service_123).
    2. If this webhook is being used as a test or is meant to be short lived, indicate such in the name (e.g., OrganizationName_eastCostTrackingBroker_app1_v1_**Test**).
    3. Avoid using abbreviations in your name if possible, for greater clarity (e.g., OrganizationNameeastCostTrackingBroker_app1_v1 vs. OrganizationName_ectBroker_app1_v1).
  2. Payload URL. Create a web app with a Uniform Resource Locator (URL) to use as your webhook to receive shipment event notifications. This is the endpoint deployed on your server to receive incoming webhook shipment events your organization has selected. Enter your Hypertext Transfer Protocol Secure (HTTPS) URL endpoint into the Payload URL field.

  3. Status. You'll use the toggle to set the webhook's status as Active or Inactive to determine if your new webhook will immediately be active once created. Shipium automatically sets new webhooks to inactive by default. This allows your organization to test your webhook before activating it as well as create a webhook that you may not be ready to activate. The benefit to your organization is a safe testing environment before the webhook starts sending shipment event notifications to your organization's server.

  4. Tenants. This field will only appear if your organization uses Shipium's Tenant feature.

    1. If your organization doesn't use Tenants, you can disregard this step.

    2. If you use Tenants, you may want to receive shipment updates for all tenants, only one tenant, or a subset of tenants. This field allows you to determine how to set up automatic shipment updates by tenant.

      • In the first screenshot that follows, All has been selected from the dropdown menu, meaning no further action is required to receive shipment updates for all your organization's tenants.

      • In the second screenshot that follows, individual tenants have been selected from the dropdown menu. The list continues to populate horizontally across the data field as you add desired tenants, whether just one or multiple.

Step 4. Add optional headers

For Headers you may optionally add custom HTTP endpoint headers to be sent in the webhook event by providing the key and value for the header.

Step 5. Select event types for notifications

In the Event Type Select section, you'll select the event type for which you wish to be notified via the webhook you're creating. You must register a webhook separately for each event type.

Step 6. Add optional extended data fields

Some carrier selection webhooks can optionally include extended data fields, providing additional context about the shipment. This is particularly useful if you use Shipium for carrier selection but generate labels externally.

When you register or manage a webhook in the Shipium Console, you'll see an Additional Data Fields section. This option defaults to unchecked, ensuring existing webhook configurations continue to receive the standard payload without changes.

When you enable the option to include extended data, your webhook payload includes additional fields you select:

  • Carton weight. The total weight of the shipping carton and its contents and the unit of weight measurement
  • Recipient PII. Name and address information for the shipment recipient
  • Shipper information. Name and address information for the shipment shipper
  • Order ID. Order identification numbers
  • Product ID. Product identification numbers

Step 7. Test webhook

Finally, send a test payload to your endpoint. You'll select the Send Test button. Refer to the Final Steps and Sample Webhook Call Content section below for confirmation information.

👍

How will I know I've successfully completed registration?

Upon your next successful carrier selection rating or label generation API call, depending on the event types selected, you will automatically begin to receive webhooks to your registered endpoint.

Shipment event types for your webhook

The following table includes the event metadata event types that can be returned for a carrier selection or label event notification. Each event type needs its own webhook registration; however, you can point all registered webhooks at the same API.

Event type for webhookDescription
Carrier Selection CreatedRepresents a carrier selection creation
Carrier Selection UpdatedRepresents an update to a created carrier selection
Carrier Selection DeletedRepresents deletion of a carrier selection
Label CreatedRepresents a label creation
Label UpdatedRepresents an update to a created label
Label DeletedRepresents deletion of a label

Imported labels for external label generation

If your organization generates labels externally (outside of Shipium) but uses Shipium's Carrier Selection service, webhooks can be configured to receive updates when your external label data is imported and matched to carrier selection criteria.

How it works

  1. You provide historical shipment data through file transfers.
  2. Shipium imports and matches your label data to existing carrier selections.
  3. Webhook notifications are sent with the "imported" label status.
  4. You can view imported labels in the Shipium Console with the status "imported".

Key differences for imported labels

  • Status. Shows as "imported" instead of "created"
  • Timing. Webhooks are sent after data import processing (typically within 24 hours).
  • Matching. Labels are matched to carrier selections using your partnerShipmentId.

Final steps and sample webhook call content

This section provides instructions for responding successfully to your webhook's initial call as well as sample webhook messages as they would appear as incoming shipment event updates.

How to respond to your first webhook call

Once you've successfully registered your organization's webhook, you will start receiving webhook calls. Upon receipt of your webhook call, you'll need to respond with an appropriate Hypertext Transfer Protocol (HTTP) status code to acknowledge successful receipt of your webhook call. Your response must:

  • be an HTTP status code within the 200-299 range; and
  • be delivered within 3 seconds of receiving the webhook call.

Shipium's automated response to your newly registered webhook

Once you've registered your organization's webhook, Shipium:

  • will retry the webhook three times if a 200-level HTTP code response is not received within 3 seconds, as required;
  • will log this as an error; and
  • may decide to mark your API endpoint as broken if multiple errors are received.

Webhook retry logic

If a webhook push fails to deliver to the target location, the Shipium platform employs automated retry logic. This is not the same as guaranteed delivery of webhooks. If your organization’s system or webhook endpoint is down for an extended period, retries may not deliver the payload. Our webhooks have the below retry/backoff policy for new webhook setups. We will configure separate policies if there are recurring performance issues with a managed endpoint we are publishing to.

Backoff Policy for Webhooks

  • Maximum Delivery Attempt Count = 4
  • Backoffs per Attempt:
    • Attempt #1 = No backoff
    • Attempt #2 Backoff = 1 hour
    • Attempt #3 Backoff = 4 hours
    • Attempt #4 Backoff = 16 hours
  • Maximum Backoff Time/Expires After = 24 hours

Sample webhook messages

This section provides sample expected webhook messages as they would appear when delivering shipment event updates, for both carrier selection and label events.

This sample JavaScript Object Notation (JSON) message demonstrates the push event sent to your organization's endpoint for your registered webhook. When a webhook is published regarding a carrier selection or label event, it will contain an array with one or more updates.

"events": [ // List of events
      {
          "metadata": { // The metadata associated with this event
              "eventId": "string", // UUID identifying this event for debugging/idempotency purposes
              "eventTimestamp": "date-time", // UTC timestamp of when this event was generated in our system
              "eventType": "string", // Indicates what event occurred in our system
              "payloadSchemaVersion": "string", // The schema version of this event's payload (major)
              "testEvent": boolean // Indicates if this is a test notification instead of a real event
          },
          "payload": { // The actual event data associated with this event
            // eventType specific payload 
          }
      }
  ]

The elements in the above sample webhook message are described in the following table.

ElementElement typeDescription
eventsArrayList of events in the webhook call; the events array may contain a single event, or multiple events (from one or more shipments).
events[].metadataObjectObject containing metadata about a particular update
events[].metadata.eventIdUUIDA unique identifier associated with this event
events[].metadata.eventTimestampStringTimestamp of when the event in question occurred in ISO-8601 date-time format
events[].metadata.eventTypeString enumeration
Values are:

- carrier_selection_created
- carrier_selection_deleted
- carrier_selection_updated
- label_created
- label_deleted
- label_updated
The type of event this message represents (Carrier Selection Created, Carrier Selection Updated, Carrier Selection Deleted, Label Created, Label Updated, Label Deleted)
events[].metadata.partnerIdStringYour organization's unique ID
events[].metadata.payloadSchemaVersionStringThe version ID for this published message (useful for debugging purposes)
events[].metadata.testEventBoolean
true or false
If true, the published event was a test event, not a real event.
events[].payloadObjectObject containing the contents of the message; see the payload data structures below for details.

Sample webhook message for carrier selection or label create/update event

This sample JSON message demonstrates the example model of the push event for the carrier selection create and update event types sent to your organization's endpoint for your registered webhook. The same payload is used for the label create and update event types, with additional carrier label information populated.

⚠️ Note: This example contains only a single event; in production, multiple events in a single message may be common.

{
    "events": [
        {
            "metadata": {
                "eventId": "f8a2e5b7-c3d9-4f16-a7e8-b9c12d34e5f6",
                "eventTimestamp": "2025-04-11T04:10:17.309452085Z",
                "eventType": "carrier_selection_created",
                "partnerId": "7b9c8d6e-5f4a-4321-b0c9-8e7f6a5b4c3d",
                "payloadSchemaVersion": "v1",
                "testEvent": true
            },
            "payload": {
                "eventType": "carrier_selection_created",
                "shipiumShipmentId": "a1b2c3d4-e5f6-47g8-h9i0-j1k2l3m4n5o6",
                "partnerShipmentId": "PARTNER-CUSTOMID-123",
                "fulfillmentContextId": "9ba10640-600a-4d3e-842f-4b6a6c535be6",
                "partnerFulfillmentContextId": null,
                "fulfillmentContext": "warehouse",
                "shippedDateTime": "2025-04-05T02:33:10.884Z",
                "shipmentTags": [],
                "orderedDateTime": "2025-04-05T01:33:10.83Z",
                "estimatedDeliveryDate": "2025-04-10T00:00:00Z",
                "testMode": false,
                "packagingType": {
                    "packagingMaterial": "box",
                    "linearDimensions": {
                        "linearUnit": "in",
                        "length": 9.0,
                        "width": 6.0,
                        "height": 3.0
                    }
                },
                "totalWeight": {
                    "weightUnit": "lb",
                    "weight": 2.58
                },
                "desiredDeliveryDate": "2025-04-10T03:59:59.999Z",
                "shipFromAddress": {
                    "countryCode": "US",
                    "region": "NV",
                    "postalCode": "89408",
                    "addressType": "commercial"
                },
                "destinationAddress": {
                    "countryCode": "US",
                    "region": "FL",
                    "postalCode": "33131",
                    "addressType": "residential"
                },
                "carrierSelection": {
                    "carrierSelectionId": "5e4d3c2b-1a9f-48e7-b6d5-c4f3e2d1b0a9",
                    "carrier": "lasership",
                    "carrierServiceMethodId": "lasership-routed-delivery-service-method-id",
                    "serviceMethodName": "LaserShip",
                    "carrierZoneId": "lasership-zone-5",
                    "calculatedBillableWeight": {
                        "weightUnit": "lb",
                        "weight": 3.0
                    },
                    "currencyCode": "usd",
                    "totalCost": 6.43,
                    "carrierCompareCost": 6.43,
                    "lineItems": [
                        {
                            "name": "base rate",
                            "rate": 6.00
                        },
                        {
                            "name": "LaserShip residential delivery surcharge",
                            "rate": 2.65
                        },
                        {
                            "name": "Residential Ground Surcharge Modifier",
                            "rate": -2.65
                        },
                        {
                            "name": "LaserShip fuel surcharge",
                            "rate": 0.86
                        },
                        {
                            "name": "Ground Fuel Surcharge Modifier",
                            "rate": -0.43
                        }
                    ],
                    "integratedLineItems": [
                        {
                            "name": "LaserShip residential delivery surcharge",
                            "rate": 0.0,
                            "unmodifiedRate": 2.65,
                            "surchargeType": "residential_ground",
                            "surchargeModifiers": [
                                {
                                    "name": "Residential Ground Surcharge Modifier",
                                    "rate": -2.65,
                                    "modifierType": "surcharge_adjustment"
                                }
                            ]
                        },
                        {
                            "name": "base rate",
                            "rate": 6.00,
                            "unmodifiedRate": 6.00,
                            "surchargeType": "base",
                            "surchargeModifiers": []
                        },
                        {
                            "name": "LaserShip fuel surcharge",
                            "rate": 0.43,
                            "unmodifiedRate": 0.86,
                            "surchargeType": "fuel_ground",
                            "surchargeModifiers": [
                                {
                                    "name": "Ground Fuel Surcharge Modifier",
                                    "rate": -0.43,
                                    "modifierType": "surcharge_adjustment"
                                }
                            ]
                        }
                    ],
                    "thirdPartyBilling": false,
                    "timeInTransitModel": "shipium_ml_model"
                },
                "isReturnLabel": false
            }
        },

    ]
}

Sample webhook message for carrier selection or label create/update event, with extended data enabled

This sample JSON message demonstrates the example model of the push event for the carrier selection create and update event types sent to your organization's endpoint for your registered webhook, with all possible extended data included.

{
    "events": [
        {
            "metadata": {
                "eventId": "f8a2e5b7-c3d9-4f16-a7e8-b9c12d34e5f6",
                "eventTimestamp": "2025-04-11T04:10:17.309452085Z",
                "eventType": "carrier_selection_created",
                "partnerId": "7b9c8d6e-5f4a-4321-b0c9-8e7f6a5b4c3d",
                "payloadSchemaVersion": "v1",
                "testEvent": true
            },
            "payload": {
                "eventType": "carrier_selection_created",
                "shipiumShipmentId": "a1b2c3d4-e5f6-47g8-h9i0-j1k2l3m4n5o6",
                "partnerShipmentId": "PARTNER-CUSTOMID-123",
                "shippedDateTime": "2025-04-05T02:33:10.884Z",
                "shipmentTags": [],
                "orderedDateTime": "2025-04-05T01:33:10.83Z",
                "estimatedDeliveryDate": "2025-04-10T00:00:00Z",
                "testMode": false,
                "packagingType": {
                    "packagingMaterial": "box",
                    "linearDimensions": {
                        "linearUnit": "in",
                        "length": 9.0,
                        "width": 6.0,
                        "height": 3.0
                    },
                  "packagingWeight": {
                    "weightUnit": "lb", 
                    "weight": 0.5 
                  } 
                },
                "totalWeight": {
                    "weightUnit": "lb",
                    "weight": 2.58
                },
                "desiredDeliveryDate": "2025-04-10T03:59:59.999Z",
                "shipFromAddress": {
                    "name": "Wile E. Coyote", 
                    "street1": "1500 Yahoohoohooee Dr.", 
                    "street2": "Suite 15", 
                    "city": "Fernley", 
                    "countryCode": "US",
                    "region": "NV",
                    "postalCode": "89408",
                    "addressType": "commercial"
                },
                "destinationAddress": {
                    "name": "Wally Gator", 
                    "street1": "101 Twiddle Street",
                    "street2": "Suite 25",
                    "city": "Miami", 
                    "countryCode": "US",
                    "region": "FL",
                    "postalCode": "33131",
                    "addressType": "residential"
                },
              "orderItemQuantities": [ 
               { 
                    "productId": "SKU12345", 
                    "shipiumOrderId": "142669ce-833c-4a33-ba52-792a3f3901b7",
                    "partnerOrderId": "ORDER12345" 
               }
 ],

                "carrierSelection": {
                    "carrierSelectionId": "5e4d3c2b-1a9f-48e7-b6d5-c4f3e2d1b0a9",
                    "carrier": "lasership",
                    "carrierServiceMethodId": "lasership-routed-delivery-service-method-id",
                    "serviceMethodName": "LaserShip",
                    "carrierZoneId": "lasership-zone-5",
                    "calculatedBillableWeight": {
                        "weightUnit": "lb",
                        "weight": 3.0
                    },
                    "currencyCode": "usd",
                    "totalCost": 6.43,
                    "carrierCompareCost": 6.43,
                    "lineItems": [
                        {
                            "name": "base rate",
                            "rate": 6.00
                        },
                        {
                            "name": "LaserShip residential delivery surcharge",
                            "rate": 2.65
                        },
                        {
                            "name": "Residential Ground Surcharge Modifier",
                            "rate": -2.65
                        },
                        {
                            "name": "LaserShip fuel surcharge",
                            "rate": 0.86
                        },
                        {
                            "name": "Ground Fuel Surcharge Modifier",
                            "rate": -0.43
                        }
                    ],
                    "integratedLineItems": [
                        {
                            "name": "LaserShip residential delivery surcharge",
                            "rate": 0.0,
                            "unmodifiedRate": 2.65,
                            "surchargeType": "residential_ground",
                            "surchargeModifiers": [
                                {
                                    "name": "Residential Ground Surcharge Modifier",
                                    "rate": -2.65,
                                    "modifierType": "surcharge_adjustment"
                                }
                            ]
                        },
                        {
                            "name": "base rate",
                            "rate": 6.00,
                            "unmodifiedRate": 6.00,
                            "surchargeType": "base",
                            "surchargeModifiers": []
                        },
                        {
                            "name": "LaserShip fuel surcharge",
                            "rate": 0.43,
                            "unmodifiedRate": 0.86,
                            "surchargeType": "fuel_ground",
                            "surchargeModifiers": [
                                {
                                    "name": "Ground Fuel Surcharge Modifier",
                                    "rate": -0.43,
                                    "modifierType": "surcharge_adjustment"
                                }
                            ]
                        }
                    ],
                    "thirdPartyBilling": false,
                    "timeInTransitModel": "shipium_ml_model"
                },
                "isReturnLabel": false
            }
        }
    ]
}

Sample webhook message for carrier selection delete event

This sample JSON message demonstrates the example model of the push event for the carrier selection delete event type sent to your organization's endpoint for your registered webhook.

{
  "shipiumShipmentId": "ea284495-efe3-4dd2-80bd-d9c269e5286b",
  "partnerShipmentId": "CUS-123456",
  "carrierSelectionId": "a38578c5-e8ba-4023-8fb0-663e7394733e",
  "shipiumLabelId": null,
  "carrier": "ups",
  "carrierTrackingId": null,
  "shippedDateTime": "2024-08-27T08:07:34-07:00",
  "deleteDateTime": "2024-08-27T11:00:00-07:00"
}

Sample webhook message for label delete event

This sample JSON message demonstrates the example model of the push event for the label delete event type sent to your organization's endpoint for your registered webhook.

{
  "shipiumShipmentId": "ea284495-efe3-4dd2-80bd-d9c269e5286b",
  "partnerShipmentId": "CUS-123456",
  "carrierSelectionId": "a38578c5-e8ba-4023-8fb0-663e7394733e",
  "shipiumLabelId": "6ddf5809-7acb-4590-831e-7ce2773f9e45",
  "carrier": "ups",
  "carrierTrackingId": "1Z123456789",
  "shippedDateTime": "2024-08-27T08:07:34-07:00",
  "deleteDateTime": "2024-08-27T11:00:00-07:00"
}

Sample webhook message for label imported event

This sample JSON message demonstrate the example model of the push event for the label import event type sent to your organization's endpoint for your registered webhook. The imported label is represented by the label_created event type.

{
  "events": [
    {
      "metadata": {
        "eventId": "a1b2c3d4-e5f6-47g8-h9i0-j1k2l3m4n5o6",
        "eventTimestamp": "2025-08-27T10:15:30.123Z",
        "eventType": "label_created",
        "partnerId": "7b9c8d6e-5f4a-4321-b0c9-8e7f6a5b4c3d",
        "payloadSchemaVersion": "v1",
        "testEvent": false
      },
      "payload": {
        "eventType": "label_created",
        "shipiumShipmentId": "a1b2c3d4-e5f6-47g8-h9i0-j1k2l3m4n5o6",
        "partnerShipmentId": "PARTNER-CUSTOMID-123",
        "fulfillmentContextId": "9ba10640-600a-4d3e-842f-4b6a6c535be6",
        "partnerFulfillmentContextId": null,
        "fulfillmentContext": "warehouse",
        "shippedDateTime": "2025-08-25T14:33:10.884Z",
        "shipmentTags": [],
        "orderedDateTime": "2025-08-25T13:33:10.83Z",
        "estimatedDeliveryDate": "2025-08-28T00:00:00Z",
        "testMode": false,
        "packagingType": {
          "packagingMaterial": "box",
          "linearDimensions": {
            "linearUnit": "in",
            "length": 12.0,
            "width": 8.0,
            "height": 4.0
          }
        },
        "totalWeight": {
          "weightUnit": "lb",
          "weight": 3.25
        },
        "desiredDeliveryDate": "2025-08-28T03:59:59.999Z",
        "shipFromAddress": {
          "countryCode": "US",
          "region": "CA",
          "postalCode": "90210",
          "addressType": "commercial"
        },
        "destinationAddress": {
          "countryCode": "US",
          "region": "NY",
          "postalCode": "10001",
          "addressType": "residential"
        },
        "carrierSelection": {
          "carrierSelectionId": "5e4d3c2b-1a9f-48e7-b6d5-c4f3e2d1b0a9",
          "carrier": "fedex",
          "carrierServiceMethodId": "fedex-ground-service-method-id",
          "serviceMethodName": "FedEx Ground",
          "carrierZoneId": "fedex-zone-3",
          "calculatedBillableWeight": {
            "weightUnit": "lb",
            "weight": 4.0
          },
          "currencyCode": "usd",
          "totalCost": 8.95,
          "carrierCompareCost": 8.95,
          "lineItems": [
            {
              "name": "base rate",
              "rate": 7.50
            },
            {
              "name": "FedEx residential delivery surcharge",
              "rate": 2.85
            },
            {
              "name": "FedEx fuel surcharge",
              "rate": 1.12
            },
            {
              "name": "Residential Ground Surcharge Modifier",
              "rate": -2.52
            }
          ],
          "integratedLineItems": [
            {
              "name": "base rate",
              "rate": 7.50,
              "unmodifiedRate": 7.50,
              "surchargeType": "base",
              "surchargeModifiers": []
            },
            {
              "name": "FedEx residential delivery surcharge",
              "rate": 0.33,
              "unmodifiedRate": 2.85,
              "surchargeType": "residential_ground",
              "surchargeModifiers": [
                {
                  "name": "Residential Ground Surcharge Modifier",
                  "rate": -2.52,
                  "modifierType": "surcharge_adjustment"
                }
              ]
            },
            {
              "name": "FedEx fuel surcharge",
              "rate": 1.12,
              "unmodifiedRate": 1.12,
              "surchargeType": "fuel_ground",
              "surchargeModifiers": []
            }
          ],
          "thirdPartyBilling": false,
          "timeInTransitModel": "shipium_ml_model"
        },
        "carrierLabel": {
          "shipiumLabelId": "6ddf5809-7acb-4590-831e-7ce2773f9e45",
          "carrier": "fedex",
          "carrierServiceMethodId": "fedex-ground-service-method-id",
          "carrierTrackingId": "1234567890123",
          "labelImportDateTime": "2025-08-27T10:15:30.123Z",
          "carrierLabelPrice": 8.95,
          "carrierLabelCurrencyCode": "usd",
          "carrierFailoverOccurred": false,
          "carrierFailoverReason": null,
          "carrierAccountNumber": "123456789",
          "partnerThirdPartyBillingAccountId": null,
          "partnerThirdPartyBillingNumber": null
        },
        "isReturnLabel": false
      }
    }
  ]
}

Carrier selection and label create/update webhook payload elements defined

Data elements for carrier selection and label create and update shipment event types are defined in the following table.

ElementElement typeDescription
shipiumShipmentIdStringThe unique identifier for the shipment
partnerShipmentIdStringThe optional unique identifier that may be used for the shipment
shipiumTenantIdStringThe Shipium-generated unique identifier for the tenant; when present, this is used to indicate the tenant associated with the shipment.
fulfillmentContextIdStringThe Shipium-generated unique identifier for the Fulfillment Context; when present, this is used to indicate the fulfillment context associated with the call.
partnerFulfillmentContextIdStringThis is an optional field allowing a partner-specific value to be used for the fulfillmentContextId above.
fulfillmentContextStringThis is the value that was passed into the API via the same-named field. It generally maps to either the fulfillmentContextId, partnerFulfillmentContextId, or tag associated with the fulfillment context.
orderedDateTimeStringThe timestamp for when the customer placed an order for the product in ISO 8601 date-time format
shippedDateTimeStringThe timestamp for when you (or your fulfillment partner) shipped the product from your (or their) warehouse in ISO 8601 date-time format
estimatedDeliveryDateStringThe date and time by when the package is estimated to be delivered to the customer in ISO 8601 date-time format
testModeBoolean
true or false
If true, the label was produced in test mode. The default value is false.
isReturnLabelBoolean
true or false
If true, the label is a return label. The default value is false.
shipmentTagsStringAn optional list of arbitrary string tags associated with this shipment
packagingTypeObjectAn object representing the packaging that was used for the shipment
packagingType .packagingMaterialString enumeration
Values are:

- box
- envelope
- flat_pack
- mailing_tube
- parcel_pallet
The type of packaging used to create the package for the shipment
packagingType.linearDimensions .linearUnitString enumeration
Values are:

- cm (centimeter)
- in (inch)
The unit in which linear dimensions are provided
packagingType.linearDimensions .lengthFloatThe longest linear dimension (i.e., the longest side of a box or envelope)
packagingType.linearDimensions .widthFloatThe second longest linear dimension (i.e., the second longest side of a box or envelope)
packagingType.linearDimensions .heightFloatThe least long linear dimension (i.e., the shortest side of a box or envelope)
packagingType.packagingWeight .weightFloatThe weight of the packaging (available only with extended data enabled)
packagingType.packagingWeight .weightUnitString enumeration
Values are:

- g (gram)
- kg (kilogram)
- lb (pound)
- oz (ounce)
The unit of measurement for packaging weight (available only with extended data enabled)
orderItemQuantities.productIdStringThe SKU or product identifier (available only with extended data enabled)
orderItemQuantities .shipiumOrderIdStringThe Shipium-generated order ID (available only with extended data enabled)
orderItemQuantities .partnerOrderIdStringYour organization's internal order ID (available only with extended data enabled)
totalWeight.weightUnitString enumeration
Values are:

- g (gram)
- kg (kilogram)
- lb (pound)
- oz (ounce)
The unit in which weight values are provided
totalWeight.weightFloatThe value of the weight in the units specified
desiredDeliveryDateStringThe string representation of either an ISO 8601 date or a local date for desired delivery: yyyy-mm-dd; the date or date-time the package is intended to arrive to the customer
shipFromAddress.nameStringThe name of the shipper (available only with extended data enabled)
shipFromAddress.street1StringThe first line of the shipper's address (available only with extended data enabled)
shipFromAddress.street2StringThe second line of the shipper's address (available only with extended data enabled)
shipFromAddress.cityStringThe city of the shipper (available only with extended data enabled)
shipFromAddress.countryCodeString enumerationThe ISO 3166-1 country code for the address of the location from which the package is being shipped
shipFromAddress.regionStringThe 2-letter abbreviation of the location's state from which the package is being shipped, for the U.S.; for other countries, this will be province, region, etc. and may be more than 2 characters.
shipFromAddress.postalCodeStringA country-appropriate postal code for the address of the location from which the package is being shipped
shipFromAddress.addressTypeString enumeration
Values are:

- commercial
- residential
The type of location for the location from which the package is being shipped
destinationAddress.nameStringThe name of the recipient (available only with extended data enabled)
destinationAddress.street1StringThe first line of the recipient's address (available only with extended data enabled)
destinationAddress.street2StringThe second line of the recipient's address (available only with extended data enabled)
destinationAddress.cityStringThe city of the recipient (available only with extended data enabled)
destinationAddress.countryCodeString enumerationThe ISO 3166-1 country code for the address of the location to which the package is being shipped
destinationAddress.regionStringThe 2-letter abbreviation of the location's state to which the package is being shipped, for the U.S.; for other countries, this will be province, region, etc. and may be more than 2 characters.
destinationAddress.postalCodeStringA country-appropriate postal code for the address of the location to which the package is being shipped
destinationAddress.addressTypeString enumeration
Values are:

- commercial
- residential
The type of location for the address to which the package is being shipped
carrierServiceMethodAllowListArray of stringsThe carrierServiceMethodAllowList takes one or more of the carrierServiceMethodId values from the Supported Carriers document provided in an array as its value. Based on that value, it chooses the best carrier and ship method from that list that meets the other criteria specified in the API call. You can find more details in Specify Carrier Service and Method.
carrierSelection .carrierSelectionIdStringUnique identifier for this carrier selection; used to distinguish between multiple carrier selections for the same shipment; required to retrieve a label by shipment, carrier selection, and label IDs
carrierSelection.carrierString enumerationA string representing the carrier that was selected for this shipment (though not necessarily what was shipped); carrier IDs for Shipium's supported carriers are listed in Supported Carriers.
carrierSelection .carrierServiceMethodIdString enumerationA string representing the carrier service method that was selected for this shipment (though not necessarily what was shipped); carrier service method IDs for Shipium's supported carriers are listed in Supported Carriers.
carrierSelection .serviceMethodNameString enumerationA more human-readable representation of the carrierServiceMethodId
carrierSelection.carrierZoneIdString enumerationA string representing the carrier’s specific zone ID for the origin-destination pair
carrierSelection .calculatedBillableWeight .weightUnitString enumeration
Values are:

- g (gram)
- kg (kilogram)
- lb (pound)
- oz (ounce)
The unit in which weight values are provided for the calculated billable weight of the shipment
carrierSelection .calculatedBillableWeight .weightFloatThe value in weight units for the calculated billable weight of the shipment
carrierSelection.currencyCodeString enumerationThe currency code for the estimated cost of the carrier selection in ISO 4217 format
carrierSelection.totalCostFloatThe total estimated cost at billing of the shipment in currencyCode units
carrierSelection .carrierCompareCostFloatThe total estimated cost of the shipment at shipping time in currencyCode units
carrierSelection.lineItems .nameString
Ex.: base rate
The name of the rate modification for the shipment; this may not be present for uncosted rate sheets.
carrierSelection.lineItems .rateNumber ($float)
Ex.: 1.23
The amount of the rate modification in currencyCode units for this shipment; this may not be present for uncosted rate sheets.
carrierSelection.integratedLineItemsArray of integrated line item elements. See below for details.
carrierSelection.integratedLineItems .nameStringThe name of the fee or surcharge in question. Every carrierSelection or label that has a cost will have a base element, but all others are carrier and method dependent.
carrierSelection.integratedLineItems .rateFloatThe rate for the named rate line item with all modifiers applied
carrierSelection.integratedLineItems .unmodifiedRateFloatThe rate for the named rate line item without modifiers applied
carrierSelection.integratedLineItems .surchargeTypeString enumerationThe type of the surcharge being modified, based on individual carrier and method rules, though some apply to multiple carriers and methods, such as residential_ground.
carrierSelection.integratedLineItems .surchargeModifiersArray of surcharge modifier elements. See below for details.
carrierSelection.integratedLineItems .surchargeModifiers .nameStringThe human-readable name of the surcharge modifier being applied
carrierSelection.integratedLineItems .surchargeModifiers .modifierTypeString enumeration
Values are:

- surcharge_replacement
- surcharge_adjustment
The type of the surcharge modifier being applied: surcharge_replacement means the value replaces the standard value; surcharge_adjustment means that the value is being added or subtracted from the value in question.
carrierSelection.integratedLineItems .surchargeModifiers .rateFloatThe amount of surcharge modifier being applied to the unmodifiedRate
carrierSelection .carrierAccountNumberString
Ex.: 999999999
The account number for the carrier for which the carrier selection was made
carrierSelection .thirdPartyBillingBoolean
true or false
If true, the shipment was billed using a third-party billing account; the default value is false.
carrierSelection .partnerThirdPartyBilling AccountIdStringA billing account identifier provided by your organization associated with the selected carrier, if available
carrierSelection .partnerThirdPartyBilling NumberStringThe third party billing number configured for your organization for the selected carrier
carrierSelection .timeInTransitModelString enumeration
Values are:

- carrier_default_postal
- partner_provided_postal
- partner_provided_zone
- shipium_calculated_postal
- shipium_ml_model
-time_in_transit_not_calculated
A string enumeration representing which model type was used for estimating this particular carrier selection’s time in transit (TNT) model; it will represent the model used for the selected carrier and method only.
carrierLabel.shipiumLabelIdStringThe unique identifier for the Shipium label entity
carrierLabel.carrierString enumerationA string representing the carrier that was selected for this shipment (though not necessarily what was shipped); carrier IDs for Shipium's supported carriers are listed in Supported Carriers.
carrierLabel .carrierServiceMethodIdString enumerationA string representing the carrier service method that was selected for this shipment (though not necessarily what was shipped); carrier service method IDs for Shipium's supported carriers are listed in Supported Carriers.
carrierLabel.carrierTrackingIdStringThe carrier's tracking identifier for the package
carrierLabel .labelCreationDateTimeStringThe timestamp for when the label was created in ISO 8601 date-time format
carrierLabel.carrierLabelPriceFloatThe total cost at shipping for the shipment returned from the carrier in currencyCode units
carrierLabel .carrierLabelCurrencyCodeStringThe currency code for the carrier label cost in ISO 4217 format
carrierLabel .carrierFailoverOccurredBoolean
true or false
If true, the preferred carrier that was selected was unable to get a label and another carrier was selected; this value is false for all other cases.
carrierLabel .carrierFailoverReasonString enumeration
Values are:

- slow_carrier_api_response
- failed_carrier_api_response
- other
This value is null if carrierFailoverOccurred is false. If carrierFailoverOccurred is true, then this value will be populated with one of the enumerated values representing the reason for the failover. This list may grow over time, so you may see unexpected outputs beyond those listed.
carrierLabel .carrierAccountNumberString
Ex.: 99X111
The account number for the carrier for which the label (if any) was produced; this value may be different than the carrierSelection value for cases such as failover.
carrierLabel .partnerThirdPartyBilling AccountIdStringA billing account identifier provided by your organization associated with the selected carrier, if available; this may be different than the carrierSelection in the event of a carrierFailover.
carrierLabel .partnerThirdPartyBilling NumberStringThe third party billing number configured for your organization for the selected carrier; this may be different than the carrierSelection in the event of a carrierFailover.
carrierLabel.labelImportDateTimeStringISO-8601 timestamp when the external label was imported into Shipium (for imported labels)
carrierLabel.labelStatusString enumeration
Values are:

- created
- updated
- imported
Status of the label

Carrier selection and label delete webhook payload elements defined

The following table includes descriptions of data elements for carrier selection and label delete shipment event types.

ElementElement typeDescription
shipiumShipmentIdStringThe unique identifier for the shipment
partnerShipmentIdStringThe optional unique identifier that may be used for the shipment
carrierSelectionIdStringUnique identifier for a carrier selection (useful if you are recording Shipium carrier selection IDs)
shipiumLabelIdStringUnique Shipium identifier for a label (useful if you are recording Shipium label IDs during carrier selection)
carrierString enumerationA string representing the carrier that was selected for this shipment (though not necessarily what was shipped); carrier IDs for Shipium's supported carriers are listed in Supported Carriers.
carrierTrackingIdStringThe carrier's tracking identifier for the package
shippedDateTimeStringThe timestamp for when you (or your fulfillment partner) shipped the product from your (or their) warehouse in ISO 8601 date-time format
deleteDateTimeStringThe date-time at which the carrier selection or label of the impacted shipment was deleted in ISO 8601 date-time format

FAQ

Q: Why are there two line item elements, called lineItems and integratedLineItems respectively?
A: The integratedLineItems element contains more detail and has a structure that makes it easier to understand how surcharges and surcharge modifiers are applied. You should consider the lineItems element to be deprecated.

Resources

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