SHshipium
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}

Request

Path parameters

shipiumShipmentIdstring required
carrierSelectionIdstring required
shipiumLabelIdstring required

Request body

eligibleForManifestboolean

Whether this shipment can be manifested (true, null), or is being held (false) so that it should not be manifested.

manifestDateTimestring date-time

Client-supplied date time for when the label was manifested in their system or by an end-of-day process.

shipiumTrackingIdstring

Shipium's tracking identification for the package.

customLabelEntriesobject

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.

Example request

{
  "trackingInfo": {
    "shippedDateTime": "2019-10-28T14:34:55.123456Z",
    "deliveredDateTime": "2019-10-28T14:34:55.123456Z",
    "currentStatus": {
      "eventDateTime": "2019-10-28T14:34:55.123456Z"
    },
    "events": [
      {
        "eventDateTime": "2019-10-28T14:34:55.123456Z"
      }
    ]
  }
}

Response

Updated carrier label.

shipiumShipmentIdstring

The unique identifier for this shipment.

partnerShipmentIdstring

The optional unique identifier that may be used for this shipment.

carrierSelectionIdstring

Unique id of the carrier selection for later lookup.

shipiumTenantIdstring

The shipium generated tenant ID. When present, this is used to indicate the tenant associated with the shipment.

partnerTenantIdstring

The partner provided tenant ID. When present, this is used to indicate the tenant associated with the shipment.

shipiumLabelIdstring

Unique id of the shipium label for later lookup.

eligibleForManifestboolean

Whether this shipment can be manifested (true, null), or is being held (false) so that it should not be manifested.

partnerManifestIdstring

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

statusDetailsstring

Details explaining the result status. Pertinent when the status is "partial" or "failed".

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

estimatedDeliveryDatestring date-time

The date and time by when the package is estimated to be delivered to the customer.

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

labelCreationDateTimestring date-time

The timestamp that the label object was created. This is used primarily for explaining future dated shipments.

cancellationDateTimestring date-time

The timestamp for when a label was cancelled. This field will default to null when the label is not cancelled.

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

serviceMethodIdentifierstring

The urn used to identify the service method for this partner

serviceMethodUrnstring

Specific version of the service level of the shipping carrier selected

carrierstring

Unique ID of the carrier

carrierServiceNamestring

Name of the carrier which the label was generated for.

serviceMethodNamestring

Name of the service method the label was generated for.

carrierServiceMethodIdstring

Maps to the unique internal Shipium ID which represents a carrier service method definition.

carrierShipmentIdstring

Carrier's identification for the shipment.

carrierTrackingIdstring

Carrier's tracking identification for the package.

carrierTrackingLinkstring

Carrier's direct tracking Link (URL) for the package

customLabelEntriesobject

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.

shipiumTrackingIdstring

Shipium's tracking identification for the package.

carrierGroupIdstring

Carrier's identification for grouping multiple packages together. For example, Canada Post groups shipments for manifesting.

packageScannableIdstring

Identifier provided that matches the scannable barcode on the label

partnerThirdPartyBillingAccountIdstring

The partner-provided ID the third party billing account that was used if the label was billed to a third party.

shipiumThirdPartyBillingAccountIdstring

The shipium generated ID of the third party billing account that was used if the label was billed to a third party.

thirdPartyBillingForShippingCostsboolean

Whether or not the third party paid the shipping costs.

thirdPartyBillingForDutiesAndTaxesboolean

Whether or not the third party paid the taxes and duties.

carrierLabelCurrencyCodestring

Currency code which the price of the label is in.

carrierLabelPricenumber float

Cost charged by the carrier for shipping the package at the chosen service level.

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

fulfilledByCarrierstring

The carrier that will fulfill the shipment, if different from the primary carrier (e.g., for proxy carriers like Amazon SFP).

fulfilledByServiceMethodstring

The service method of the fulfilling carrier (e.g., 'fedex-ground-service-method' when Amazon SFP selects FedEx Ground).

fulfilledByCarrierTrackingIdstring

The tracking ID of the fulfilling carrier for proxy carriers like Amazon SFP (e.g., the UPS or FedEx tracking number).

labelFailoverOccurredboolean

When "true" signifies that label creation failover logic was exercised.

testModeboolean

A flag denoting whether the label is a test label

failureTypestring

A code denoting the cause of the failure

multiParcelboolean

Example response

{
  "cancellationDateTime": "2024-10-31T10:50:11.123456Z",
  "manifestDateTime": "2024-10-30T10:50:11.123456Z",
  "billableWeight": {
    "weightUnit": "lb",
    "weight": 50
  },
  "billableCubicVolume": {
    "cubicVolumeUnit": "ft",
    "cubicVolume": 0.8
  },
  "internationalDocuments": [
    {
      "documentType": "commercial_invoice",
      "documentImage": {
        "documentEncoding": "base64"
      },
      "electronicallySubmitted": true
    }
  ],
  "hazardousMaterialsDocuments": [
    {
      "documentType": "OP_900LG",
      "documentImage": {
        "documentEncoding": "base64"
      },
      "electronicallySubmitted": true
    }
  ],
  "laneMatch": {
    "laneId": "asdqwdq-qwd123ds-123asdwd-123asd",
    "partnerLaneId": "custom partner provided id"
  },
  "trackingInfo": {
    "shippedDateTime": "2019-10-28T14:34:55.123456Z",
    "deliveredDateTime": "2019-10-28T14:34:55.123456Z",
    "currentStatus": {
      "eventDateTime": "2019-10-28T14:34:55.123456Z"
    },
    "events": [
      {
        "eventDateTime": "2019-10-28T14:34:55.123456Z"
      }
    ]
  }
}

Changes

No recorded changes to this operation across all 2 revisions of this API.