Guides

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 register one webhook per event type you want to receive. Carrier selection and label generation each have created, updated, and deleted event types, so full coverage of both services takes six registrations. Once a webhook is registered and active, the next matching shipment update sends a notification to the API endpoint you configured for it.

This document guides you through the steps to register a webhook for your organization for either carrier selection or label generation. Repeat the process for each event type you want to receive. To start, you’ll need to access the Shipium Console. To register a webhook for tracking shipments with Shipium, you can refer to 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 webhooks for Customer A, Customer B, and Customer C, pointing at three unique API endpoints. Because each registration carries a single event type, the number of registrations is the number of endpoints multiplied by the number of event types each endpoint needs.

🎣

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. The option is unchecked by default. When it is unchecked, the payload contains the standard fields only.

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 as label_created events.
  4. You can view imported labels in the Shipium Console with the status "imported".

Key differences for imported labels

  • Console status. Imported labels appear in the Shipium Console with the status "imported" rather than "created". The webhook payload contains no status field, and imported labels arrive as label_created events, the same event type used for labels Shipium generates.
  • 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
🚧

How fields are sent when they have no value

This webhook uses different conventions for fields with no value, and your endpoint's validation schema must handle each one. The Sent value in the field tables below tells you which convention applies to a given field:

  • Omitted fields. When the field has no value, the key is left out of the payload entirely. Mark these as not required in your schema.
  • Fields sent null. The key is always present, and its value is a literal null when there is no value. For these, your schema must allow null in the type, for example "type": ["string", "null"]. Marking the field not required is not enough on its own, because the key is still present with a null value.
  • Omitted or null. These fields arrive only when you enable the matching extended data option for your webhook (see Step 6). When the option is off, the key is absent from the payload. When it is on, the key is present and holds a literal null if that shipment has no value for it. Mark these not required and allow null in the type.

The shipment-level fields are omitted when empty, as are the fields of carrierSelection, carrierLabel, and orderItemQuantities. Weight, packaging, and address objects are the exception: wherever one of these objects appears, its own inner fields are sent as null when empty rather than omitted. This includes calculatedBillableWeight inside carrierSelection. Always check the Sent value on the individual field.

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
              "partnerId": "string", // Your organization's unique ID
              "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.

ElementDetails
eventsType: Array
Sent: Always
Description: List of events in the webhook call; may contain a single event or multiple events (from one or more shipments)
events[].metadataType: Object
Sent: Always
Description: Object containing metadata about a particular update
events[].metadata.eventIdType: UUID
Sent: Always
Description: A unique identifier associated with this event
events[].metadata.eventTimestampType: String (date-time)
Sent: Always
Description: Timestamp of when the event occurred, in ISO 8601 date-time format
events[].metadata.eventTypeType: String (enumeration)
Sent: Always
Values: carrier_selection_created, carrier_selection_deleted, carrier_selection_updated, label_created, label_deleted, label_updated
Description: The type of event this message represents
events[].metadata.partnerIdType: String
Sent: Always
Description: Your organization's unique ID
events[].metadata.payloadSchemaVersionType: String
Sent: Always
Description: The version ID for this published message (useful for debugging)
events[].metadata.testEventType: Boolean
Sent: Always
Values: true or false
Description: If true, the published event was a test event, not a real event.
events[].payloadType: Object
Sent: Always
Description: Object 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",
                "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
            }
        }
    ]
}

This example is illustrative. Optional fields that have no value are either omitted or sent as null per the Sent column in the field tables below.

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",
                "fulfillmentContextId": "9ba10640-600a-4d3e-842f-4b6a6c535be6",
                "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
                    },
                    "packagingWeight": {
                        "weightUnit": "lb",
                        "weight": 0.5
                    }
                },
                "totalWeight": {
                    "weightUnit": "lb",
                    "weight": 2.58
                },
                "desiredDeliveryDate": "2025-04-10T03:59:59.999Z",
                "shipFromAddress": {
                    "name": "Wile E. Coyote",
                    "address1": "1500 Yahoohoohooee Dr.",
                    "address2": "Suite 15",
                    "city": "Fernley",
                    "countryCode": "US",
                    "region": "NV",
                    "postalCode": "89408",
                    "addressType": "commercial"
                },
                "destinationAddress": {
                    "name": "Wally Gator",
                    "address1": "101 Twiddle Street",
                    "address2": "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
            }
        }
    ]
}

This example is illustrative. Optional fields that have no value are either omitted or sent as null per the Sent column in the field tables below.

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.

{
  "events": [
    {
      "metadata": {
        "eventId": "f8a2e5b7-c3d9-4f16-a7e8-b9c12d34e5f6",
        "eventTimestamp": "2024-08-27T18:00:00Z",
        "eventType": "carrier_selection_deleted",
        "partnerId": "7b9c8d6e-5f4a-4321-b0c9-8e7f6a5b4c3d",
        "payloadSchemaVersion": "v1",
        "testEvent": false
      },
      "payload": {
        "eventType": "carrier_selection_deleted",
        "shipiumShipmentId": "ea284495-efe3-4dd2-80bd-d9c269e5286b",
        "partnerShipmentId": "CUS-123456",
        "carrierSelectionId": "a38578c5-e8ba-4023-8fb0-663e7394733e",
        "carrier": "ups",
        "shippedDateTime": "2024-08-27T08:07:34-07:00",
        "deleteDateTime": "2024-08-27T11:00:00-07:00"
      }
    }
  ]
}

This example is illustrative. Optional fields that have no value are omitted per the Sent column in the field tables below.

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.

{
  "events": [
    {
      "metadata": {
        "eventId": "c3d9f8a2-4f16-b7e8-a7e8-e5f6b9c12d34",
        "eventTimestamp": "2024-08-27T18:00:00Z",
        "eventType": "label_deleted",
        "partnerId": "7b9c8d6e-5f4a-4321-b0c9-8e7f6a5b4c3d",
        "payloadSchemaVersion": "v1",
        "testEvent": false
      },
      "payload": {
        "eventType": "label_deleted",
        "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"
      }
    }
  ]
}

This example is illustrative. Optional fields that have no value are omitted per the Sent column in the field tables below.

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",
        "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",
          "labelCreationDateTime": "2025-08-27T10:15:30.123Z",
          "carrierLabelPrice": 8.95,
          "carrierLabelCurrencyCode": "usd",
          "carrierFailoverOccurred": false,
          "carrierAccountNumber": "123456789"
        },
        "isReturnLabel": false
      }
    }
  ]
}

This example is illustrative. Optional fields that have no value are either omitted or sent as null per the Sent column in the field tables below.

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

Shipment-level fields

Every field in this group is omitted when it has no value. Fields that are always populated are marked Always.

ElementDetails
eventTypeType: String (enumeration)
Sent: Always
Values: carrier_selection_created, carrier_selection_updated, label_created, label_updated
Description: The type of event this payload represents; also present in the event metadata
shipiumShipmentIdType: String
Sent: Always
Description: The unique identifier for the shipment
partnerShipmentIdType: String
Sent: Omitted if null
Description: The optional unique identifier that may be used for the shipment
shipiumTenantIdType: String
Sent: Omitted if null
Description: The Shipium-generated identifier for the tenant, when the shipment is associated with a tenant
partnerTenantIdType: String
Sent: Omitted if null
Description: Your organization's tenant identifier, when provided for the shipment
fulfillmentContextIdType: String
Sent: Omitted if null
Description: The Shipium-generated identifier for the fulfillment context, when the shipment is associated with one
partnerFulfillmentContextIdType: String
Sent: Omitted if null
Description: An optional specific value provided by your organization for the fulfillmentContextId
fulfillmentContextType: String
Sent: Omitted if null
Description: The value passed into the API via the same-named field; generally maps to the fulfillmentContextId, partnerFulfillmentContextId, or a tag associated with the fulfillment context
orderedDateTimeType: String (date-time)
Sent: Always
Description: The timestamp for when the customer placed the order, in ISO 8601 format
shippedDateTimeType: String (date-time)
Sent: Always
Description: The timestamp for when the product shipped from the warehouse, in ISO 8601 format
estimatedDeliveryDateType: String (date-time)
Sent: Omitted if null
Description: The date and time by when the package is estimated to be delivered, in ISO 8601 format
desiredDeliveryDateType: String
Sent: Omitted if null
Description: An ISO 8601 date or local date (yyyy-mm-dd) for when the package is intended to arrive
businessDaysOfTransitType: Integer
Sent: Omitted if null
Description: The number of business days from ship time by when the shipment needs to be delivered
testModeType: Boolean
Sent: Always
Values: true or false
Description: If true, the label was produced in test mode. Default is false.
isReturnLabelType: Boolean
Sent: Always
Values: true or false
Description: If true, the label is a return label. Default is false.
shipmentTagsType: Array of strings
Sent: Omitted if null
Description: An optional list of arbitrary string tags associated with this shipment; commonly an empty array []
carrierServiceMethodAllowListType: Array of strings
Sent: Omitted if null
Description: One or more carrierServiceMethodId values that constrained selection; see Specify Carrier Service and Method.
packagingTypeType: Object
Sent: Always
Description: An object representing the packaging used for the shipment; see its fields below.
totalWeightType: Object
Sent: Always
Description: An object representing the total shipment weight; see its fields below
shipFromAddressType: Object
Sent: Always
Description: The shipper address object; see its fields below.
destinationAddressType: Object
Sent: Always
Description: The recipient address object; see its fields below.
carrierSelectionType: Object
Sent: Omitted if null
Description: The carrier selection object; present for carrier selection and label events. See its fields below.
carrierLabelType: Object
Sent: Omitted if null
Description: The carrier label object; present for label events. See its fields below.

Packaging and weight

The packagingType and totalWeight objects are always present on create/update events, and their inner string and enum fields are sent as null when empty; numeric dimensions and weights are always numbers. The packagingWeight object is the exception: it is absent unless you enable the Carton weight extended data option.

ElementDetails
packagingType.packagingMaterialType: String (enumeration)
Sent: Null if empty
Values: box, envelope, flat_pack, mailing_tube, parcel_pallet
Description: The type of packaging used
packagingType.linearDimensionsType: Object
Sent: Null if empty
Description: The linear dimensions object; when present, its fields follow below.
packagingType.linearDimensions.linearUnitType: String (enumeration)
Sent: Null if empty
Values: cm, in
Description: The unit for the linear dimensions
packagingType.linearDimensions.lengthType: Float
Sent: Always
Description: The longest linear dimension
packagingType.linearDimensions.widthType: Float
Sent: Always
Description: The second longest linear dimension
packagingType.linearDimensions.heightType: Float
Sent: Always
Description: The shortest linear dimension
packagingType.packagingWeightType: Object
Sent: Omitted or null
Description: The packaging weight object (available only with extended data enabled)
packagingType.packagingWeight.weightUnitType: String (enumeration)
Sent: Null if empty
Values: g, kg, lb, oz
Description: The unit for packaging weight (available only with extended data enabled)
packagingType.packagingWeight.weightType: Float
Sent: Always
Description: The weight of the packaging when the packaging weight object is present (available only with extended data enabled)
totalWeight.weightUnitType: String (enumeration)
Sent: Null if empty
Values: g, kg, lb, oz
Description: The unit for the total weight
totalWeight.weightType: Float
Sent: Always
Description: The value of the total weight in the units specified

Ship-from and destination addresses

The address objects are always present. The countryCode, region, postalCode, and addressType fields are always present as well, and are sent as null when empty. The name, address1, address2, and city fields are absent unless you enable the matching extended data option, and when enabled they are sent as null if the address has no value for that line. These fields are governed by two separate extended data options, one for the shipper address and one for the recipient address (see Step 6), so one address can carry them while the other does not.

ElementDetails
shipFromAddress.nameType: String
Sent: Omitted or null
Description: The name of the shipper (populated only with extended data enabled)
shipFromAddress.address1Type: String
Sent: Omitted or null
Description: The first line of the shipper's address (populated only with extended data enabled)
shipFromAddress.address2Type: String
Sent: Omitted or null
Description: The second line of the shipper's address (populated only with extended data enabled)
shipFromAddress.cityType: String
Sent: Omitted or null
Description: The city of the shipper (populated only with extended data enabled)
shipFromAddress.countryCodeType: String (enumeration)
Sent: Null if empty
Description: The 2-character ISO 3166 country code of the shipper
shipFromAddress.regionType: String
Sent: Null if empty
Description: The state (2-letter for the U.S.) or province/region for other countries from which the package ships
shipFromAddress.postalCodeType: String
Sent: Null if empty
Description: A country-appropriate postal code for the origin
shipFromAddress.addressTypeType: String (enumeration)
Sent: Null if empty
Values: commercial, residential
Description: The location type of the origin; defaults to commercial when unknown on live events, and can arrive null on test events.
destinationAddress.nameType: String
Sent: Omitted or null
Description: The name of the recipient (populated only with extended data enabled)
destinationAddress.address1Type: String
Sent: Omitted or null
Description: The first line of the recipient's address (populated only with extended data enabled)
destinationAddress.address2Type: String
Sent: Omitted or null
Description: The second line of the recipient's address (populated only with extended data enabled)
destinationAddress.cityType: String
Sent: Omitted or null
Description: The city of the recipient (populated only with extended data enabled)
destinationAddress.countryCodeType: String (enumeration)
Sent: Null if empty
Description: The 2-character ISO 3166-1 country code for the destination
destinationAddress.regionType: String
Sent: Null if empty
Description: The state (2-letter for the U.S.) or province/region for other countries to which the package ships
destinationAddress.postalCodeType: String
Sent: Null if empty
Description: A country-appropriate postal code for the destination
destinationAddress.addressTypeType: String (enumeration)
Sent: Null if empty
Values: commercial, residential
Description: The location type of the destination; defaults to commercial when unknown on live events, and can arrive null on test events.

Order item quantities (extended data)

The orderItemQuantities array appears only with extended data enabled, and is omitted when null or empty. Order ID and Product ID are selected independently in Step 6, so the array can arrive carrying only the identifiers matching the options you enabled.

ElementDetails
orderItemQuantitiesType: Array
Sent: Omitted if null or empty
Description: Order line item detail (available only with extended data enabled)
orderItemQuantities.productIdType: String
Sent: Omitted if null or empty
Description: The SKU or product identifier (available only with extended data enabled)
orderItemQuantities.shipiumOrderIdType: String
Sent: Omitted if null or empty
Description: The Shipium-generated order ID (available only with extended data enabled)
orderItemQuantities.partnerOrderIdType: String
Sent: Omitted if null or empty
Description: Your organization's internal order ID (available only with extended data enabled)

Carrier selection

Everything inside carrierSelection is omitted when null or empty. The core identifiers are always populated when the object is present. Note that if calculatedBillableWeight is present, its inner weightUnit follows the weight object's own rule and can be null.

ElementDetails
carrierSelection.carrierSelectionIdType: String
Sent: Always
Description: Unique identifier for this carrier selection; required to retrieve a label by shipment, carrier selection, and label IDs
carrierSelection.carrierType: String (enumeration)
Sent: Always
Description: The carrier selected for this shipment (not necessarily what shipped); see Supported Carriers.
carrierSelection.carrierServiceMethodIdType: String (enumeration)
Sent: Always
Description: The carrier service method selected; see Supported Carriers.
carrierSelection.serviceMethodNameType: String (enumeration)
Sent: Always
Description: A human-readable representation of the carrierServiceMethodId
carrierSelection.carrierZoneIdType: String (enumeration)
Sent: Always
Description: The carrier's zone ID for the origin-destination pair
carrierSelection.calculatedBillableWeightType: Object
Sent: Omitted if null or empty
Description: The calculated billable weight object; when present, its fields follow the weight object rules below.
carrierSelection.calculatedBillableWeight
.weightUnit		Type: String (enumeration)
Sent: Null if empty
Values: g, kg, lb, oz
Description: The unit for the calculated billable weight (present when the weight object is present)
carrierSelection.calculatedBillableWeight
.weight		Type: Float
Sent: Always
Description: The calculated billable weight value (present when the weight object is present)
carrierSelection.currencyCodeType: String (enumeration)
Sent: Omitted if null or empty
Description: The currency code for the estimated cost in ISO 4217 format
carrierSelection.totalCostType: Float
Sent: Omitted if null or empty
Description: The total estimated cost at billing in currencyCode units
carrierSelection.carrierCompareCostType: Float
Sent: Omitted if null or empty
Description: The total estimated cost at shipping time in currencyCode units
carrierSelection.lineItemsType: Array
Sent: Omitted if null or empty
Description: A flat list of rate line items; may be absent for uncosted rate sheets. For full detail, use integratedLineItems.
carrierSelection.lineItems.nameType: String
Sent: Omitted if null or empty
Example: base rate
Description: The name of the rate modification
carrierSelection.lineItems.rateType: Number (float)
Sent: Omitted if null or empty
Example: 1.23
Description: The amount of the rate modification in currencyCode units
carrierSelection.integratedLineItemsType: Array
Sent: Omitted if null or empty
Description: The complete structured rate breakdown; see fields below.
carrierSelection.integratedLineItems.nameType: String
Sent: Omitted if null or empty
Description: The name of the fee or surcharge
carrierSelection.integratedLineItems.rateType: Float
Sent: Omitted if null or empty
Description: The rate with all modifiers applied
carrierSelection.integratedLineItems
.unmodifiedRate		Type: Float
Sent: Omitted if null or empty
Description: The rate without modifiers applied
carrierSelection.integratedLineItems
.surchargeType		Type: String (enumeration)
Sent: Omitted if null or empty
Description: The type of surcharge being modified (e.g., residential_ground)
carrierSelection.integratedLineItems
.surchargeModifiers		Type: Array
Sent: Omitted if null or empty
Description: Array of surcharge modifier elements; see fields below.
carrierSelection.integratedLineItems
.surchargeModifiers.name		Type: String
Sent: Omitted if null or empty
Description: The human-readable name of the surcharge modifier
carrierSelection.integratedLineItems
.surchargeModifiers.modifierType		Type: String (enumeration)
Sent: Omitted if null or empty
Values: surcharge_replacement, surcharge_adjustment
Description: The type of modifier applied to the surcharge
carrierSelection.integratedLineItems
.surchargeModifiers.rate		Type: Float
Sent: Omitted if null or empty
Description: The amount of the surcharge modifier applied to the unmodifiedRate
carrierSelection.carrierAccountNumberType: String
Sent: Omitted if null or empty
Example: 999999999
Description: The carrier account number for which the selection was made
carrierSelection.thirdPartyBillingType: Boolean
Sent: Always
Values: true or false
Description: If true, the shipment used a third-party billing account. Default is false.
carrierSelection
.partnerThirdPartyBillingAccountId		Type: String
Sent: Omitted if null or empty
Description: A partner-supplied billing account identifier for the selected carrier, if available
carrierSelection
.partnerThirdPartyBillingAccountNumber		Type: String
Sent: Omitted if null or empty
Description: The third-party billing number configured for the selected carrier
carrierSelection.timeInTransitModelType: String (enumeration)
Sent: Omitted if null or empty
Values: carrier_default_postal, partner_provided_postal, partner_provided_zone, shipium_calculated_postal, shipium_ml_model, time_in_transit_not_calculated
Description: The time in transit model used for the selected carrier and method

Carrier label

Everything inside carrierLabel is omitted when null or empty. Core identifiers are always populated when the object is present.

ElementDetails
carrierLabel.shipiumLabelIdType: String
Sent: Always
Description: The unique identifier for the Shipium label entity
carrierLabel.carrierType: String (enumeration)
Sent: Always
Description: The carrier for the label; see Supported Carriers.
carrierLabel.carrierServiceMethodIdType: String (enumeration)
Sent: Always
Description: The carrier service method for the label; see Supported Carriers.
carrierLabel.carrierTrackingIdType: String
Sent: Always
Description: The carrier's tracking identifier for the package
carrierLabel.labelCreationDateTimeType: String (date-time)
Sent: Always
Description: The timestamp for when the label was created, in ISO 8601 format
carrierLabel.carrierLabelPriceType: Float
Sent: Omitted if null or empty
Description: The total cost at shipping returned from the carrier in currencyCode units
carrierLabel.carrierLabelCurrencyCodeType: String
Sent: Omitted if null or empty
Description: The currency code for the carrier label cost in ISO 4217 format
carrierLabel.carrierFailoverOccurredType: Boolean
Sent: Always
Values: true or false
Description: If true, the preferred carrier could not produce a label and another carrier was selected.
carrierLabel.carrierFailoverReasonType: String (enumeration)
Sent: Omitted if null or empty
Values: slow_carrier_api_response, failed_carrier_api_response, other
Description: Present only when carrierFailoverOccurred is true; the key is omitted otherwise. When present, it holds one of the enumerated reasons for the failover.
carrierLabel.carrierTrackingLinkType: String
Sent: Omitted if null or empty
Description: The carrier's direct tracking link (URL) for the package; present only when the carrier supplies one
carrierLabel.carrierAccountIdType: String
Sent: Omitted if null or empty
Description: The Shipium carrier account identifier used for label generation; distinct from carrierAccountNumber
carrierLabel.carrierAccountNumberType: String
Sent: Omitted if null or empty
Example: 99X111
Description: The carrier account number for the label; may differ from the carrierSelection value in a failover
carrierLabel
.partnerThirdPartyBillingAccountId		Type: String
Sent: Omitted if null or empty
Description: Your organization's billing account identifier; may differ from the carrierSelection value in a failover
carrierLabel
.partnerThirdPartyBillingAccountNumber		Type: String
Sent: Omitted if null or empty
Description: The third-party billing number; may differ from the carrierSelection value in a failover

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. Optional fields on delete events are omitted when they have no value.

ElementDetails
eventTypeType: String (enumeration)
Sent: Always
Values: carrier_selection_deleted, label_deleted
Description: The type of delete event; also present in the event metadata
shipiumShipmentIdType: String
Sent: Always
Description: The unique identifier for the shipment
partnerShipmentIdType: String
Sent: Omitted if null
Description: The optional unique identifier that may be used for the shipment
shipiumTenantIdType: String
Sent: Omitted if null
Description: The Shipium-generated identifier for the tenant, when the shipment is associated with a tenant
partnerTenantIdType: String
Sent: Omitted if null
Description: Your organization's tenant identifier, when provided for the shipment
fulfillmentContextIdType: String
Sent: Omitted if null
Description: The Shipium-generated identifier for the fulfillment context, when the shipment is associated with one
partnerFulfillmentContextIdType: String
Sent: Omitted if null
Description: An optional specific value provided by your organization for the fulfillmentContextId
fulfillmentContextType: String
Sent: Omitted if null
Description: The value passed into the API for the fulfillment context
carrierSelectionIdType: String
Sent: Omitted if null
Description: Unique identifier for a carrier selection
shipiumLabelIdType: String
Sent: Omitted if null
Description: Unique Shipium identifier for a label. Present only on label_deleted events; not included on carrier_selection_deleted events, which have no associated label
carrierType: String (enumeration)
Sent: Omitted if null
Description: The carrier selected for this shipment; see Supported Carriers.
carrierTrackingIdType: String
Sent: Omitted if null
Description: The carrier's tracking identifier. Present only on label_deleted events; not included on carrier_selection_deleted events
shippedDateTimeType: String (date-time)
Sent: Always
Description: The timestamp for when the product shipped, in ISO 8601 format
deleteDateTimeType: String (date-time)
Sent: Always
Description: The date-time at which the carrier selection or label was deleted, in ISO 8601 format

FAQ

Q: Why are there two line item elements, lineItems and integratedLineItems?
A: Both are returned when a carrier selection has calculated rate line items. integratedLineItems provides the complete structured breakdown, showing each charge with its surcharge type and any surcharge modifiers applied. lineItems provides a simpler flat list of the same charges. For full detail on how surcharges and modifiers are applied, use integratedLineItems.

Related documentation

Resources

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


Updated about 1 month ago

Did this page help you?