--- title: "Get Shipment Events" method: GET path: "/api/v1/deliveryexperience/shipment/{shipmentId}/events" tags: ["delivery-experience"] --- # Get Shipment Events `GET /api/v1/deliveryexperience/shipment/{shipmentId}/events` Get a Shipment, in each possible webhook event format, using the shipiumShipmentId or the partnerShipmentId if one was provided. ## Path parameters - `shipmentId` string, required ## Query parameters - `eventTypes` string[] ## Headers - `X-DELEGATED-PARTNER-ID` string ## Response `200` Shipment event retrieval successful. - Events - `events` EventWrapper[] — A batch of events - `metadata` EventMetadata — Information about the event - `eventId` string — Shipium-generated identifier for the event. - `eventTimestamp` string, date-time — When the event was created. - `eventType` 'carrier_selection_created' | 'carrier_selection_deleted' | 'carrier_selection_updated' | 'label_created' | 'label_deleted' | 'label_updated' | 'order_cancelled' | 'order_completed' | 'order_created' | 'order_shipped' | 'order_updated' | 'tracking_updated' — The type of event. - `partnerId` string — Unique id of the partner. - `payloadSchemaVersion` 'v1' — The version of the event schema used to model the event. - `testEvent` boolean — True if the event is test data. False or null indicates that the event is for a real label or carrier selection. - `payload` union — Top level definition of a event in the shiptime system. - object — Information about any new or updated carrier selection or label creation. - `eventId` string, required — ID of the event. - `eventType` 'carrier_selection_created' | 'carrier_selection_deleted' | 'carrier_selection_updated' | 'label_created' | 'label_deleted' | 'label_updated' | 'order_cancelled' | 'order_completed' | 'order_created' | 'order_shipped' | 'order_updated' | 'tracking_updated', required — The type of the event, determines which fields can appear in the event. - `shipiumShipmentId` string, required — The Shipium-generated unique identifier for the shipment. - `partnerShipmentId` string — The partner-provided, optional, unique identifier that may be used for the shipment. - `shipiumTenantId` string — The Shipium-generated unique identifier for the tenant. When present, this is used to indicate the tenant associated with the shipment. - `partnerTenantId` string — The partner-provided, optional, unique identifier for the tenant. When present, this is used to indicate the tenant associated with the shipment. - `fulfillmentContextId` string — The Shipium-generated unique identifier for the fulfillment context that was, or will be, used to select a carrier and generate a label for this shipment. - `partnerFulfillmentContextId` string — The partner-provided, optional, unique identifier for the fulfillment context that was, or will be, used to select a carrier and generate a label for this shipment. - `fulfillmentContext` string — The alias or tag for the fulfillment context that was supplied in the request to determine which fulfillment context to use. - `shippedDateTime` string, date-time, required — The timestamp for when you (or your fulfillment partner) shipped the product from your (or their) warehouse. - `shipmentTags` string[] — A collection of partner-proved, optional, free-form tags that may be added to this shipment. - `orderedDateTime` string, date-time, required — The timestamp for when the customer placed an order for the product. - `estimatedDeliveryDate` string, date-time — The date and time by when the package is estimated to be delivered to the customer. - `testMode` boolean, required — true if the label was produced in testMode, false otherwise. - `packagingType` EventPackagingType, required — The packaging that was used for the shipment. - `packagingMaterial` 'box' | 'envelope' | 'flat_pack' | 'parcel_pallet' | 'mailing_tube' | 'tire', required — The type of packaging used to create the package for the shipment. - `linearDimensions` LinearDimensions, required — Dimensions describing the size of the packaging. - `linearUnit` 'in' | 'cm' — The unit that linear dimensions are provided in, either in for inches or cm for centimeters. - `length` number, float — The longest linear dimension (e.g. the longest side of a box or envelope). - `width` number, float — The second longest linear dimension (e.g. the second-longest side of a box of envelope. - `height` number, float — The least long linear dimension (e.g. the shortest side of a box or envelope. Note on envelopes: This height should represent the highest product you would reasonably put in this envelope before losing more than 10% of the length of the envelope in other dimensions. - `packagingWeight` Weight — The weight of this type of packaging empty. - `weightUnit` 'g' | 'kg' | 'oz' | 'lb' — The unit that weight values are provided in. g for grams kg for kilograms oz for ounces lb for pounds - `weight` number, float — The value of the weight. - `totalWeight` Weight, required — The weight of this type of packaging empty. - `weightUnit` 'g' | 'kg' | 'oz' | 'lb' — The unit that weight values are provided in. g for grams kg for kilograms oz for ounces lb for pounds - `weight` number, float — The value of the weight. - `desiredDeliveryDate` string, date-time — The string representation of either an ISO-8601 date or a LocalDate: yyyy-mm-dd. The date or datetime the package is intended to arrive to the customer. This will be used to determine the most appropriate service method when generating a label - `businessDaysOfTransit` integer — Indicates the number of business days from the ship time by when the shipment needs to be delivered. - `shipFromAddress` EventAddress, required — Address structure representing where the shipment was sent to. - `name` string — Full name of the individual or company sending the shipment. - `address1` string — Primary street address of the shipper's location. - `address2` string — Secondary street for the shipper's address - `city` string — City portion of the shipper’s address - `countryCode` string, required — The ISO 3166-1 alpha-2 country code for the address - `region` string — The 2-letter abbreviation of the location's state, for the US; for other countries, this will be province, region, etc. and may be more than 2 characters - `postalCode` string — A country appropriate postal code for the address - `addressType` 'residential' | 'commercial' — The type of location - `destinationAddress` EventAddress, required — Address structure representing where the shipment was sent to. - `name` string — Full name of the individual or company sending the shipment. - `address1` string — Primary street address of the shipper's location. - `address2` string — Secondary street for the shipper's address - `city` string — City portion of the shipper’s address - `countryCode` string, required — The ISO 3166-1 alpha-2 country code for the address - `region` string — The 2-letter abbreviation of the location's state, for the US; for other countries, this will be province, region, etc. and may be more than 2 characters - `postalCode` string — A country appropriate postal code for the address - `addressType` 'residential' | 'commercial' — The type of location - `carrierServiceMethodAllowList` string[] — If a customer restricts the carrier selection to only a specific subset of potential carrier methods, that will be captured here. The array will contain one or more carrierServiceMethodId values. - `orderItemQuantities` EventOrderItemQuantities[] — Information about item quantities in the order, including order and product identifiers - `productId` string — Partner-provided product identifier (e.g., SKU) - `shipiumOrderId` string — Shipium-generated order identifier - `partnerOrderId` string — Partner-provided order number - `carrierSelection` CarrierSelectionEvent — Structure representing details of the carrier selection - `carrierSelectionId` string, required — Unique 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. - `carrier` string, required — A string representing the parcel carrier that was selected for this shipment (though not necessarily what was shipped). - `carrierServiceMethodId` string, required — A string representing the parcel carrier’s specific ship method that was selected for this shipment (though not necessarily what was shipped). - `serviceMethodName` string, required — A more human-readable representation of the carrierServiceMethodId. - `carrierZoneId` string, required — A string representing the parcel carrier’s specific zone id for the origin / destination pair. - `calculatedBillableWeight` Weight, required — The weight of this type of packaging empty. - `weightUnit` 'g' | 'kg' | 'oz' | 'lb' — The unit that weight values are provided in. g for grams kg for kilograms oz for ounces lb for pounds - `weight` number, float — The value of the weight. - `currencyCode` string — The currency code for the estimated cost of the carrier selection in ISO-4217 format. This may not be present for uncosted rate sheets. - `totalCost` number, float — The total estimated cost at billing of the shipment in currencyCode units. This may not be present for uncosted rate sheets. - `carrierCompareCost` number, float — The total estimated cost of the shipment, at shipping time, in currencyCode units. This may not be present for uncosted rate sheets. - `lineItems` EventLineItem[] — All line items that comprise the total estimated cost of the shipment, in currencyCode units. This may not be present for uncosted rate sheets. This is deprecated and being replaced by `integratedLineItems`. - `name` string, required — The name of the rate modification. - `rate` number, float, required — The amount of the rate modification. - `integratedLineItems` EventLineItemIntegrated[] — All line items that comprise the total estimated cost of the shipment, in currencyCode units. This may not be present for uncosted rate sheets. - `name` string, required — The name of the surcharge or base rate. - `rate` number, float, required — The amount of the surcharge, or base rate, after its modifications. - `unmodifiedRate` number, float, required — The initial amount of the surcharge, or base rate, without any modifications. - `surchargeType` string, required — The category of the surcharge, as defined by Shipium. - `surchargeModifiers` EventLineItemModifier[] — Any modifications to the surcharge or base rate. - … - `carrierAccountNumber` string — The account number for the selected carrier, which will be billed the cost of the label, unless a third party account was configured to be used instead. - `thirdPartyBilling` boolean, required — true if the shipment was billed using third-party billing account and false otherwise. - `partnerThirdPartyBillingAccountId` string — A billing account identifier associated with the selected carrier, if available. - `partnerThirdPartyBillingAccountNumber` string — The 3rd-party billing account number for the selected carrier, which will be billed the cost of the label. - `timeInTransitModel` '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 model. Note that it will represent the model used for the selected carrier and method only. This may not be present if the request does not contain either desired delivery date or business days of transit. - `carrierLabel` CarrierLabelEvent — Structure representing details of the carrier selection - `shipiumLabelId` string, required — The unique identifier for the Shipium label entity. - `carrier` string, required — A string representing the parcel carrier that was used for shipping for this shipment (though not necessarily what was originally selected). - `carrierServiceMethodId` string, required — A string representing the parcel carrier’s specific ship method that was used for shipping for this shipment (though not necessarily what was originally selected). - `carrierTrackingId` string, required — The carrier's tracking identifier for the package. - `labelCreationDateTime` string, date-time, required — The timestamp for when the label was created. - `carrierLabelPrice` number, float — The total cost at shipping for the shipment returned from the carrier in currencyCode units. This may not be present if the carrier's API does not supply it, or we retrieve it asynchronously. - `carrierLabelCurrencyCode` string — The currency code for the carrier label cost in ISO-4217 format. This may not be present if the carrier's API does not supply it, or we retrieve it asynchronously. - `carrierFailoverOccurred` boolean, required — true if the preferred carrier that was selected was unable to get a label and another carrier was selected, false for all other cases. - `carrierFailoverReason` 'slow_carrier_api_response' | 'failed_carrier_api_response' | 'other' — 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. Note that this list may grow over time so be prepared for unexpected outputs beyond those listed. - `carrierTrackingLink` string — Carrier's direct tracking link (URL) for the package. - `carrierAccountId` string — The Shipium carrier account identifier used for label generation. - `carrierAccountNumber` string — The account number for the carrier that was used, which will be billed the cost of the label, unless a third party account was configured to be used instead. - `partnerThirdPartyBillingAccountId` string — A billing account identifier associated with the carrier used for shipping the shipment. This will typically match the value in 'carrierSelection', unless there was a failover. - `partnerThirdPartyBillingAccountNumber` string — The 3rd-party billing account number for the successful carrier, which will be billed the cost of the label. - `isReturnLabel` boolean, required — true if the label is a return label, false otherwise. - object — Information about a carrier selection or label deletion. - `eventId` string, required — ID of the event. - `eventType` 'carrier_selection_created' | 'carrier_selection_deleted' | 'carrier_selection_updated' | 'label_created' | 'label_deleted' | 'label_updated' | 'order_cancelled' | 'order_completed' | 'order_created' | 'order_shipped' | 'order_updated' | 'tracking_updated', required — The type of the event, determines which fields can appear in the event. - `shipiumShipmentId` string, required — The Shipium-generated unique identifier for the shipment. - `partnerShipmentId` string — The partner-provided, optional, unique identifier that may be used for the shipment. - `shipiumTenantId` string — The Shipium-generated unique identifier for the tenant. When present, this is used to indicate the tenant associated with the shipment. - `partnerTenantId` string — The partner-provided, optional, unique identifier for the tenant. When present, this is used to indicate the tenant associated with the shipment. - `fulfillmentContextId` string — The Shipium-generated unique identifier for the fulfillment context that was, or will be, used to select a carrier and generate a label for this shipment. - `partnerFulfillmentContextId` string — The partner-provided, optional, unique identifier for the fulfillment context that was, or will be, used to select a carrier and generate a label for this shipment. - `fulfillmentContext` string — The alias or tag for the fulfillment context that was supplied in the request to determine which fulfillment context to use. - `shippedDateTime` string, date-time, required — The timestamp for when you (or your fulfillment partner) shipped the product from your (or their) warehouse. - `carrierSelectionId` string — Unique 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. - `shipiumLabelId` string — The unique identifier for the Shipium label entity. Only present when a label is deleted. - `carrier` string — A string representing the parcel carrier that was either selected (when a carrier selection is deleted), or used for shipping for this shipment (when a label is deleted). - `carrierTrackingId` string — The carrier's tracking identifier for the package. Only present when a label is deleted. - `deleteDateTime` string, date-time, required — The date/time at which the delete of the impacted shipment was deleted. ## Other responses - `403` — Not authenticated / authorized via OAuth. - `404` — Unable to find the shipment. --- [API](https://skmtc.net/shipium/apis/shipium-api.md) · [All operations](https://skmtc.net/shipium/apis/shipium-api/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/shipium/shipium-api/versions/7ef5dbd6a025/schema)