Sign in

v1

latestOpenAPI 3.0.12026-07-2481208369.3 KB
label-generation

Import a batch of labels into Shipium's system that were created outside of Shipium. There must be a shipment and a carrier selection already created within Shipium's system that each label can be associated with.

post/api/v1/deliveryexperience/shipment/carrierSelection/batchLabelImport

Headers

X-DELEGATED-PARTNER-IDstring

Request body

Example request

{
  "labels": [
    {
      "effectiveShipDateTime": "2024-10-31T10:50:11.123456Z",
      "estimatedDeliveryDate": "2024-11-07T10:50:11.123456Z",
      "estimatedInjectionDateTime": "2024-11-07T10:50:11.123456Z",
      "labelCreationDateTime": "2024-10-30T10:50:11.123456Z",
      "manifestDateTime": "2024-10-30T21:50:11.123456Z",
      "carrierAccountNumber": "XYZ987654321",
      "billableWeight": {
        "weightUnit": "lb",
        "weight": 50
      },
      "billableCubicVolume": {
        "cubicVolumeUnit": "ft",
        "cubicVolume": 0.8
      },
      "internationalDocuments": [
        {
          "documentType": "commercial_invoice",
          "documentImage": {
            "documentEncoding": "base64"
          },
          "electronicallySubmitted": true
        }
      ],
      "hazardousMaterialsDocuments": [
        {
          "documentType": "commercial_invoice",
          "documentImage": {
            "documentEncoding": "base64"
          },
          "electronicallySubmitted": true
        }
      ],
      "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

Labels imported successfully.

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": "commercial_invoice",
        "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"
        }
      ]
    }
  }
]