---
title: "Patch a previously generated shipment label. Fields that are present in the patch will be upserted against the existing label."
method: PATCH
path: "/api/v1/deliveryexperience/shipment/{shipiumShipmentId}/carrierSelection/{carrierSelectionId}/label/{shipiumLabelId}"
tags: ["label-generation"]
---

# Patch a previously generated shipment label. Fields that are present in the patch will be upserted against the existing label.

`PATCH /api/v1/deliveryexperience/shipment/{shipiumShipmentId}/carrierSelection/{carrierSelectionId}/label/{shipiumLabelId}`

## Path parameters

- `shipiumShipmentId` string, required
- `carrierSelectionId` string, required
- `shipiumLabelId` string, required

## Request body

- CarrierLabelPatchParameters
  - `eligibleForManifest` boolean — Whether this shipment can be manifested (true, null), or is being held (false) so that it should not be manifested.
  - `manifestDateTime` string, date-time — Client-supplied date time for when the label was manifested in their system or by an end-of-day process.
  - `trackingInfo` TrackingInfo — Details of the tracking history and status of the package.
    - `carrier` string — Defines the carrier that provide the tracking information.
    - `trackingId` string — ID unique to the carrier used to identify the shipment the tracking information provides status for.
    - `shippedDateTime` string, date-time — Date which the possession of the shipment was taken by the carrier, null if shipment is still at the customer's shipping origin location.
    - `deliveredDateTime` string, date-time — Date which the carrier delivered the shipment to it expected destination, null if shipment is not delivered yet.
    - `currentStatus` TrackingEvent — Status history of the shipment as reported by the carrier as of the time of the call.
      - `deliveryStep` 'InfoReceived' | 'InTransit' | 'OutForDelivery' | 'Delivered' | 'Exception' | 'Unknown' — High level status of this shipment event as reported by the carrier.
      - `shipmentStatus` 'InfoReceived' | 'PickedUp' | 'ArrivedCarrierFacility' | 'DepartedCarrierFacility' | 'InTransit' | 'Hold' | 'OutForDelivery' | 'Delivered' | 'Exception' | 'Unknown' — Detailed status of this shipment event as reported by the carrier. A shipment can have many statuses within a deliveryStep, and the granularity is carrier dependent.
      - `statusMessage` string — Human readable shipment status message as reported by the carrier.
      - `eventDateTime` string, date-time — Date time which the carrier recorded this event for the shipment.
      - `eventCity` string — City where the carrier recorded the event.
      - `eventRegion` string — Region (State/Province/Territory where the carrier recorded the event.
      - `eventPostalCode` string — Postal code of location the carrier recorded the event.
      - `eventCountry` string — Country where the carrier recorded the event.
    - `events` TrackingEvent[] — Status history of the shipment as reported by the carrier as of the time of the call.
      - `deliveryStep` 'InfoReceived' | 'InTransit' | 'OutForDelivery' | 'Delivered' | 'Exception' | 'Unknown' — High level status of this shipment event as reported by the carrier.
      - `shipmentStatus` 'InfoReceived' | 'PickedUp' | 'ArrivedCarrierFacility' | 'DepartedCarrierFacility' | 'InTransit' | 'Hold' | 'OutForDelivery' | 'Delivered' | 'Exception' | 'Unknown' — Detailed status of this shipment event as reported by the carrier. A shipment can have many statuses within a deliveryStep, and the granularity is carrier dependent.
      - `statusMessage` string — Human readable shipment status message as reported by the carrier.
      - `eventDateTime` string, date-time — Date time which the carrier recorded this event for the shipment.
      - `eventCity` string — City where the carrier recorded the event.
      - `eventRegion` string — Region (State/Province/Territory where the carrier recorded the event.
      - `eventPostalCode` string — Postal code of location the carrier recorded the event.
      - `eventCountry` string — Country where the carrier recorded the event.
  - `shipiumTrackingId` string — Shipium's tracking identification for the package.
  - `customLabelEntries` object — A free-form map of string key-value pairs to be applied to the label. When provided, the label will be regenerated incorporating the new metadata. Uses full-replacement semantics — the entire set of entries will be replaced with whatever is provided in the request.

## Response `200`

Updated carrier label.

- CarrierLabel — This is populated if a label generated for the carrier and service determined by carrier selection this field contains the information on the labels and the formats they were generated in.
  - `shipiumShipmentId` string — The unique identifier for this shipment.
  - `partnerShipmentId` string — The optional unique identifier that may be used for this shipment.
  - `carrierSelectionId` string — Unique id of the carrier selection for later lookup.
  - `shipiumTenantId` string — The shipium generated tenant ID. When present, this is used to indicate the tenant associated with the shipment.
  - `partnerTenantId` string — The partner provided tenant ID. When present, this is used to indicate the tenant associated with the shipment.
  - `shipiumLabelId` string — Unique id of the shipium label for later lookup.
  - `eligibleForManifest` boolean — Whether this shipment can be manifested (true, null), or is being held (false) so that it should not be manifested.
  - `partnerManifestId` string — The partner provided identifier for the manifest that includes this shipment. This will be present for labels that have been updated via the `/api/v1/deliveryexperience/shipment/carrierSelection/labels/endOfDayManifest` endpoint, regardless of whether the carrier's API supports manifesting.
  - `status` 'success' | 'failure' | 'voided' | 'failover' | 'generated' | 'imported' | 'label_created' | 'manifesting' | 'manifested' | 'manifest_failure' | 'not_set' | 'carrier_selection_failure' — Defines the result of the carrier label call. Values returned will be success, partial, and failed
  - `statusDetails` string — Details explaining the result status. Pertinent when the status is "partial" or "failed".
  - `effectiveShipDateTime` string, date-time — Shipium's calculation for the effective ship date time that a shipment will ship out. This date time will be used for the carrier label and for limits.
  - `estimatedDeliveryDate` string, date-time — The date and time by when the package is estimated to be delivered to the customer.
  - `estimatedInjectionDateTime` string, date-time — Shipium's calculation for the date time that a shipment will arrive at the injection site. If present, this date time will be used for the carrier label.
  - `labelCreationDateTime` string, date-time — The timestamp that the label object was created. This is used primarily for explaining future dated shipments.
  - `cancellationDateTime` string, date-time — The timestamp for when a label was cancelled. This field will default to null when the label is not cancelled.
  - `manifestDateTime` string, date-time — The timestamp that the label was manifested by the partner. This should be present for labels that have eligibleForManifest=true. If this was true at label creation time, it will use the shipDateTime from the request for this value. Otherwise, this can be updated via the patchLabelV1 endpoint.
  - `serviceMethodIdentifier` string — The urn used to identify the service method for this partner
  - `serviceMethodUrn` string — Specific version of the service level of the shipping carrier selected
  - `carrier` string — Unique ID of the carrier
  - `carrierServiceName` string — Name of the carrier which the label was generated for.
  - `serviceMethodName` string — Name of the service method the label was generated for.
  - `carrierServiceMethodId` string — Maps to the unique internal Shipium ID which represents a carrier service method definition.
  - `carrierShipmentId` string — Carrier's identification for the shipment.
  - `carrierTrackingId` string — Carrier's tracking identification for the package.
  - `carrierTrackingLink` string — Carrier's direct tracking Link (URL) for the package
  - `customLabelEntries` object — A free-form map of string key-value pairs applied to the label. These entries are used during label augmentation to substitute placeholders in label templates.
  - `shipiumTrackingId` string — Shipium's tracking identification for the package.
  - `carrierGroupId` string — Carrier's identification for grouping multiple packages together. For example, Canada Post groups shipments for manifesting.
  - `packageScannableId` string — Identifier provided that matches the scannable barcode on the label
  - `partnerThirdPartyBillingAccountId` string — The partner-provided ID the third party billing account that was used if the label was billed to a third party.
  - `shipiumThirdPartyBillingAccountId` string — The shipium generated ID of the third party billing account that was used if the label was billed to a third party.
  - `thirdPartyBillingForShippingCosts` boolean — Whether or not the third party paid the shipping costs.
  - `thirdPartyBillingForDutiesAndTaxes` boolean — Whether or not the third party paid the taxes and duties.
  - `carrierLabelCurrencyCode` string — Currency code which the price of the label is in.
  - `carrierLabelPrice` number, float — Cost charged by the carrier for shipping the package at the chosen service level.
  - `estimatedLabelCost` number, float — Shipium's estimated shipping cost for the service method the label was actually created on. When label failover occurs this reflects the failover carrier the label was generated with, not the originally-selected carrier described by the carrierSelection block. Unlike carrierLabelPrice (which the carrier reports and may omit), this is derived from Shipium's own rating; it is omitted only when Shipium cannot determine the created method's cost. It is an estimate and may differ from the carrier's invoiced amount.
  - `billableWeight` 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.
  - `billableCubicVolume` CubicVolume — Cubic volume that was used to generate the rate
    - `cubicVolumeUnit` 'in' | 'ft' | 'cm' | 'm' — The unit for the cubic volume
    - `cubicVolume` number, float — The value of the cubic volume.
  - `documents` CarrierLabelInfo[] — List of links to labels generated by format for the shipment.
    - `labelExpiration` string, date-time — Date time when the label expires and is no longer valid.
    - `labelFormat` string — Defines the format the shipment label was generated in by the carrier.
    - `labelProperties` ShiptimeLabelProperties — Metadata describing the label.
      - `height` number, float, required — Top to bottom measurement of the label in linearUnits
      - `width` number, float, required — Right to left measurement of the label in linearUnits
      - `linearUnits` string, required — The linear units representing the labelHeight and labelWidth
      - `dpi` integer, required — The dpi (Dots Per Inch) used by the label printer
      - `labelOrientation` string, required — The direction that the label will be printed
      - `nonZplLabelDimensions` ShiptimeLabelDimensions — The dimensions used to print non-ZPL labels, if they need to be different than ZPL dimensions
        - `height` number, float — Top to bottom measurement of the label in linearUnits, required if width is present
        - `width` number, float — Right to left measurement of the label in linearUnits, required if height is present
        - `linearUnits` string — The linear units representing the label height and width. If this is present, both the height and width are required in the LabelDimensions. If this is missing, the linearUnits from LabelProperties will be used.
    - `labelImage` CarrierLabelImage — Base64 encoded ZPL as generated by the carrier before label sanitation and augmentations are performed.
      - `imageEncoding` string — Format in which the "imageContents" field is encoded e.g. base64.
      - `imageContents` string — Raw contents of the shipment label image encoded in Base64. End users will need to decode this data using the format information supplied in the "labelInfo" field.
      - `imageFormat` string — Image format e.g. jpeg, png. Only populated for printerless labels.
    - `labelUrl` string — Url with is the link to the shipment label file on the Shipium CDN.
    - `carrierTrackingId` string — The tracking id associated with this label.
    - `carrierTrackingLink` string — The tracking link associated with this label.
    - `packageReferenceIdentifier` string — The package reference id that was passed in by the customer to be associated with this package.Most frequently used for multi parcel shipments. This can be used to cross reference internation documents and carrier labels.
    - `shipiumPackageReferenceId` string — The package reference Identifier created by shipium.
    - `packageScannableId` string — The package scannable id associated with this label.
    - `carrierShipmentId` string — The carrier shipment id associated with the label.
    - `printerlessInfo` PrinterlessInfo — Printerless label information. Only present when labelFormat is 'printerless'.
      - `type` string — Type of printerless label. Examples: qrcode, barcode, nfc, rfid.
      - `valueRepresented` string — The value embedded in the QR code or barcode. This is typically a public URL or tracking identifier.
  - `internationalDocuments` InternationalDocumentInfo[] — List of international customs documents generated by the carrier for the shipment.
    - `documentType` 'commercial_invoice' | 'electronic_export_information' | 'ps_2976' | 'air_waybill' | 'multiple' | 'unknown' — The type of international document. For 'multiple', there will be multiple types of forms
    - `documentExpiration` string, date-time — Date time when the document expires and is no longer valid.
    - `documentFormat` string — Defines the format the document was generated in by the carrier.
    - `documentImage` DocumentImage — The generated document image contents and encoding.
      - `documentEncoding` string — Format in which the "documentContents" field is encoded
      - `documentContents` string — Raw contents of the encoded document. End users will need to decode this data using the format information supplied in the "documentEncoding" field.
    - `electronicallySubmitted` boolean — Indication of whether or not this international document has been electronically submitted by the carrier
    - `packageReferenceIdentifier` string — The package reference id that was passed in by the customer to be associated with a package.Most frequently used for multi parcel shipments. This can be used to cross reference internation documents and labels.
  - `hazardousMaterialsDocuments` HazardousMaterialsDocumentInfo[] — List of hazardous materials documents generated by the carrier for the shipment.
    - `documentType` 'OP_900LG' | 'OP_900LL' — The type of international document. For 'multiple', there will be multiple types of forms
    - `documentExpiration` string, date-time — Date time when the document expires and is no longer valid.
    - `documentFormat` string — Defines the format the document was generated in by the carrier.
    - `documentImage` DocumentImage — The generated document image contents and encoding.
      - `documentEncoding` string — Format in which the "documentContents" field is encoded
      - `documentContents` string — Raw contents of the encoded document. End users will need to decode this data using the format information supplied in the "documentEncoding" field.
    - `electronicallySubmitted` boolean — Indication of whether or not this international document has been electronically submitted by the carrier
    - `packageReferenceIdentifier` string — The package reference id that was passed in by the customer to be associated with a package.Most frequently used for multi parcel shipments. This can be used to cross reference internation documents and labels.
  - `fulfilledByCarrier` string — The carrier that will fulfill the shipment, if different from the primary carrier (e.g., for proxy carriers like Amazon SFP).
  - `fulfilledByServiceMethod` string — The service method of the fulfilling carrier (e.g., 'fedex-ground-service-method' when Amazon SFP selects FedEx Ground).
  - `fulfilledByCarrierTrackingId` string — The tracking ID of the fulfilling carrier for proxy carriers like Amazon SFP (e.g., the UPS or FedEx tracking number).
  - `laneMatch` LaneMatch — The matched lane for the carrier that was selected. This will be empty if nothing is configured for lanes.
    - `laneId` string — The laneId that was matched on and used.
    - `partnerLaneId` string — The lane sort match name that was configured on the lane.
  - `labelFailoverOccurred` boolean — When "true" signifies that label creation failover logic was exercised.
  - `trackingInfo` TrackingInfo — Details of the tracking history and status of the package.
    - `carrier` string — Defines the carrier that provide the tracking information.
    - `trackingId` string — ID unique to the carrier used to identify the shipment the tracking information provides status for.
    - `shippedDateTime` string, date-time — Date which the possession of the shipment was taken by the carrier, null if shipment is still at the customer's shipping origin location.
    - `deliveredDateTime` string, date-time — Date which the carrier delivered the shipment to it expected destination, null if shipment is not delivered yet.
    - `currentStatus` TrackingEvent — Status history of the shipment as reported by the carrier as of the time of the call.
      - `deliveryStep` 'InfoReceived' | 'InTransit' | 'OutForDelivery' | 'Delivered' | 'Exception' | 'Unknown' — High level status of this shipment event as reported by the carrier.
      - `shipmentStatus` 'InfoReceived' | 'PickedUp' | 'ArrivedCarrierFacility' | 'DepartedCarrierFacility' | 'InTransit' | 'Hold' | 'OutForDelivery' | 'Delivered' | 'Exception' | 'Unknown' — Detailed status of this shipment event as reported by the carrier. A shipment can have many statuses within a deliveryStep, and the granularity is carrier dependent.
      - `statusMessage` string — Human readable shipment status message as reported by the carrier.
      - `eventDateTime` string, date-time — Date time which the carrier recorded this event for the shipment.
      - `eventCity` string — City where the carrier recorded the event.
      - `eventRegion` string — Region (State/Province/Territory where the carrier recorded the event.
      - `eventPostalCode` string — Postal code of location the carrier recorded the event.
      - `eventCountry` string — Country where the carrier recorded the event.
    - `events` TrackingEvent[] — Status history of the shipment as reported by the carrier as of the time of the call.
      - `deliveryStep` 'InfoReceived' | 'InTransit' | 'OutForDelivery' | 'Delivered' | 'Exception' | 'Unknown' — High level status of this shipment event as reported by the carrier.
      - `shipmentStatus` 'InfoReceived' | 'PickedUp' | 'ArrivedCarrierFacility' | 'DepartedCarrierFacility' | 'InTransit' | 'Hold' | 'OutForDelivery' | 'Delivered' | 'Exception' | 'Unknown' — Detailed status of this shipment event as reported by the carrier. A shipment can have many statuses within a deliveryStep, and the granularity is carrier dependent.
      - `statusMessage` string — Human readable shipment status message as reported by the carrier.
      - `eventDateTime` string, date-time — Date time which the carrier recorded this event for the shipment.
      - `eventCity` string — City where the carrier recorded the event.
      - `eventRegion` string — Region (State/Province/Territory where the carrier recorded the event.
      - `eventPostalCode` string — Postal code of location the carrier recorded the event.
      - `eventCountry` string — Country where the carrier recorded the event.
  - `testMode` boolean — A flag denoting whether the label is a test label
  - `failureType` string — A code denoting the cause of the failure
  - `multiParcel` boolean

## Other responses

- `404` — Unable to find Carrier Label

---

[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)