# Get started

To use the Shipment Label API, you can follow the instructions on this page. To establish preferred label settings, you can refer to the [Label Configuration](https://docs.shipium.com/docs/label-configuration) documentation, which provides guidance for setting up label preferences and any desired label augmentations in the [Shipium Console](https://partner.shipium.com/login).

> 👍
>
> ### Test mode for label generation
>
> Including `testMode` = "true" in your call to the Shipment Label API enables generation of labels for testing purposes, so that your account will not be charged.

Information about carrier and method selection and shipment labels within the Shipium platform can be found in the [Carrier and Method Selection & Shipment Labels](https://docs.shipium.com/docs/carrier-method-selection-label-single-call) and [Shipment Labels](https://docs.shipium.com/docs/carrier-shipment-label-flow) documentation.

# Manage labels with the Shipment Label API

The Shipium Shipment Label API assumes you're using one of the authentication mechanisms detailed in our [authentication documentation](https://docs.shipium.com/docs/authentication).

> 🔐
>
> ### Authentication for API Calls
>
> In the cURL example on this page, the environment variable `AUTHSTRING` is used to handle authorization. The recipe below shows how to set it correctly for both API Key and OAuth users.

## Request fields for API calls

The following tables provide required and optional fields for calling the Shipment Label API. Path elements are described for each use case in the sections that follow.

### Required fields

| Field                  | Details                                                                                                                                                                                                                                                                                                                   |
|------------------------|---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| `currencyCode`        | **Type:** String<br>**Example:**`usd`<br>**Description:** Currency in which all the rates for shipping carrier selection costs will be calculated                                                                                                                                                               |
| `labelFormats`         | **Type:** String (enumeration)<br>**Values:**`pdf`, `png`, `zpl`<br>**Description:** List of formats in which to generate the package [label](https://docs.shipium.com/docs/carrier-shipment-label-flow)                                                                                                                                           |
| `eligibleForManifest`  | **Type:** Boolean<br>**Values:**`true` or `false`<br>**Description:** When `true`, or null, this label will be included in end-of-day and scheduled [manifests](https://docs.shipium.com/docs/shipment-manifesting). `False` indicates that the label should not be included in any manifests. While manifesting is optional, this field value must be provided. |

### Optional fields

| Field                                  | Details                                                                                                                                                                                     |
|---------------------------------------|---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| `includeLabelImagesInResponse`       | **Type:** Boolean<br>**Values:**`true` or `false`<br>**Description:** When `true`, the response will include the raw image data of the [labels](https://docs.shipium.com/docs/carrier-shipment-label-flow) that were requested to be generated by the carrier. |
| `customLabelEntries.additionalProp1` | **Type:** String<br>**Description:** Additional properties to be associated with the [label](https://docs.shipium.com/docs/carrier-shipment-label-flow), beginning with number 1                                                        |
| `testMode`                           | **Type:** Boolean<br>**Values:**`true` or `false`<br>**Description:** When `true`, calls to generate the labels will be made to the carrier sandbox servers. [No actual labels](https://docs.shipium.com/docs/understanding-carrier-selection-label-test-mode) are created, only a representation of the label. No money is charged to the underlying account. |

## Generate a shipment label

### Path

**POST**`https://api.shipium.com/api/v1/deliveryexperience/shipment/{shipiumShipmentId}/carrierSelection/{carrierSelectionId}/label`

**Required path element:**`shipiumShipmentId` or `partnerShipmentId` (Replace this with either Shipium's shipment identifier or your own, if provided when the shipment was created.)

**Required path element:**`carrierSelectionId`

### Example cURL call

This example shows a request to generate a label for an existing shipment:

```curl
curl --request POST \
  --url https://api.shipium.com/api/v1/deliveryexperience/shipment/{shipiumShipmentId}/carrierSelection/{carrierSelectionId}/label \
  --header 'accept: application/json' \
  --header $AUTHSTRING \
  --header 'content-type: application/json' \
  --data 'INSERT REQUEST BODY FROM BELOW'
```

### Example request body

This example shows the JSON request:

```json
{
  "currencyCode": "usd",
  "labelFormats": [
    "zpl"
  ],
  "eligibleForManifest": true,
  "includeLabelImagesInResponse": true,
  "customLabelEntries": {
    "additionalProp1": "Gift enclosed",
    "additionalProp2": "Sporting goods"
  },
  "testMode": true
}
```

### Example response body

JSON

```json
{
  "shipiumLabelId": "3049babf-f766-4490-be89-fa781168b8f8",
  "effectiveShipDateTime": "2022-11-28T03:00:00Z",
  "carrier": "usps",
  "carrierServiceName": "ground",
  "carrierLabelCurrency": "usd",
  "carrierLabelPrice": 7.45,
  "billableWeight": {
    "weight": 6.0,
    "weightUnit": "lb"
  },
  "carrierSelectionId": "2dc48065-89cf-4cd2-88be-ba6c69b3768e",
  "carrierTrackingId": "92612999916518543481369406",
  "carrierTrackingLink": "https://tools.usps.com/go/TrackConfirmAction?tLabels=92612999916518543481369406",
  "documents": [
    {
      "labelExpiration": "2020-11-19T21:11:42.628Z",
      "labelFormat": "zpl",
      "labelImage": {
        "imageEncoding": "base64",
        "imageContents": "iVBORw0KGgoAAAANSUhEUgAAACAAAAAgCAYAAABzenr0AAAABGdBTUEAALGPC/xhBQAAADhlWElmTU0AKgAAAAgAAYdpAAQAAAABAAAAGgAAAAAAAqACAAQAAAABAAAAIKADAAQAAAABAAAAIAAAAACPTkDJAAACJElEQVRYCe1Vz0sbURCe2XWbiNZKRaxgEipIKYVSqFR7SuJRCipSDz1JD1Io4j/goe2l9xYPxYu9FLoRz/aUaCmUYKFee4hiKSg0ovVHY0x2nCe85e3GmM2Kl3bf5c3Mm/fN976ZZQGCFSgQKPC/K4AXEeDu6qemP9uHRi2M9eTITrUcXwS6l+Z7SmSZRHCvGrAzjnnQ6PnP+NhHZxxAcwe8+MdkvfFeXCBSGxLMda+Y19z4De6A8GPp1DQBdLVfvTm5s5eLFRFeslStMhcRZwHxrfTV3SJ6B0RdakzYTDhMh3CLzax6VkFAsDzeh1d8A3/v595zoUdsP2FC9tLDV56u9Q9t2QHFiKbNAzVXOQIq6xWKVxDI9Y7tRjOpKS7c+SBO2W9f6JdVQn492QpQoTgYWzKPVHBpM+8W8Vyvy9cQ8is3uUSH1yIyTwf94Xpy9Kv0xe6Q5AWRw1cTL8u2FYik53tZ5kVEWNhIPJ6IZFIz7D8DcpIURBoaQzfUGYh+Nu9TCVZqkTxXAUTrNhdsI6B+AYRAibOK1ypS77k9hH1x+JBd1vIhw1oVIHo4NEB/i0nSKttSKhRfRzJmSBajMlyXdr273YJ6Ll7aEHomwf3xnKskol62FPfU9DX1/JmftskNdp7Pw12gsvHDneOLgKFpkwz43Q1W3cc8IYyf9Vf0NQOy0J202XwAhj3IMu7e1xLDu/z/8NU2N1bgBwoECvx7CpwAEhquciKZh7kAAAAASUVORK5CYII="
      },
      "labelUrl": "https://api.shipium.com/labels/1a486afc-2ffc-4c37-928f-8d6aa014b35b.zpl"
    }
  ],
  "status": "success",
  "statusDetails": "Label created successfully"
}
```

## Retrieve details of a previously created label

Your organization can retrieve details of a label you've previously created by calling the API and passing the elements required to retrieve the label details, as described in this section.

### Path

**GET**

`https://api.shipium.com/api/v1/deliveryexperience/shipment/{shipiumShipmentId}/carrierSelection/{carrierSelectionId}/label/{shipiumLabelId}`

**Required path element:**`carrierSelectionId` (Replace this with the ID that was returned in a prior carrier selection call response.)

**Required path element:**`shipiumLabelId` (Replace this with the ID that was returned in a prior label call response.)

**Required path element:**`includeLabelImagesInResponse` (You'll provide a boolean value of _true_ or _false_ to either include the label images or not.)

### Specific example

The following request retrieves exactly the same contents as shown above. The sample request includes a **true** value for the `includeLabelImagesInResponse` query. To not include the label images in your response, you'll need to change this value from **true** to **false**.

```curl
curl --request GET \
  --url <<api_url>>/api/v1/deliveryexperience/shipment/a69be08c-f3f5-4c26-ab16-46cbfdf9004e/carrierselection/2dc48065-89cf-4cd2-88be-ba6c69b3768e/label/d838f2a6-4abd-499a-a5d1-186ea7f90184?includeLabelImagesInResponse=true \
  --header 'accept: application/json' \
  --header $AUTHSTRING \
  --header 'content-type: application/json'
```

### Short form call

If you're performing an integration with Shipium without storing the order and shipment information, you can make a shorter call using only the `shipiumLabelId` to retrieve a previously created label. The sample request includes a **true** value for the `includeLabelImagesInResponse` query. To not include the label images in your response, you'll need to change this value from **true** to **false**.

#### Path

**GET**

`https://api.shipium.com/api/v1/deliveryexperience/shipment/carrierselection/label/{shipiumLabelId}?includeLabelImagesInResponse=true`

**Required parameter:**`shipiumLabelId` (Replace this with the ID returned in a previous label response.)

```curl
curl --request GET \
  --url <<api_url>>/api/v1/deliveryexperience/shipment/carrierselection/label/{shipiumLabelId}?includeLabelImagesInResponse=true \
  --header 'accept: application/json' \
  --header $AUTHSTRING
```

## Retrieve a label image only

If you need to retrieve just a label image in a particular form, you can make a call to retrieve only the stream of data for that format. For any format, you'll provide the required `shipiumLabelId` parameter in the request.

**PNG**

This cURL request gets the image as a PNG file:

```curl
curl --request GET \
  --url <<api_url>>/api/v1/deliveryexperience/shipment/carrierselection/label/{shipiumLabelId}/png \
  --header 'accept: application/json' \
  --header 'content-type: image/png' \
  --header $AUTHSTRING
```

**ZPL**

This cURL request gets the image as ZPL code:

```curl
curl --request GET \
  --url <<api_url>>/api/v1/deliveryexperience/shipment/carrierselection/label/{shipiumLabelId}/zpl \
  --header 'accept: application/json' \
  --header 'content-type: application/octet-stream' \
  --header $AUTHSTRING
```

**PDF**

This cURL request gets the image as a PDF file:

```curl
curl --request GET \
  --url <<api_url>>/api/v1/deliveryexperience/shipment/carrierselection/label/{shipiumLabelId}/pdf \
  --header 'accept: application/json' \
  --header 'content-type: application/pdf' \
  --header $AUTHSTRING
```

## Void a label

Shipium recommends calling the cancellation endpoint in the cURL example below to void a shipment label. This example uses the `shipiumLabelId`. You can include only one of the unique IDs associated with your cancellation request: either the `shipmentId`, `carrierSelectionId`, `shipiumLabelId`, or `carrierTrackingId`.

```curl
curl --request POST \
     --url https://api.shipium.com/api/v1/deliveryexperience/cancel \
     --header 'accept: application/json' \
     --header 'content-type: application/json' \
     --data '{
        "shipiumLabelId": "198edb20-1076-42d8-8723-830dd6f27ef4",
        "cancellationDateTime": "2024-08-21T18:30:55.558Z"
      }'
```

For details on canceling a shipment and the associated carrier selection while voiding a label, you can refer to [Cancel a Shipment](https://docs.shipium.com/docs/cancel-a-shipment).

Alternatively, you can use the following path to void a label.

**POST**

`https://api.shipium.com/api/v1/deliveryexperience/shipment/{shipiumShipmentId}/carrierSelection/{carrierSelectionId}/label/{shipiumLabelId}/void`

**Required path element:**`shipiumShipmentId` | `partnerShipmentId` (Replace this with either Shipium's shipment identifier or your own, if provided when the shipment was created.)

### Update a label after creation

After a label has been generated, you can update it by sending a PATCH request to the [Update a label](https://docs.shipium.com/reference/patchlabelv1) endpoint. The most common use case is updating `customLabelEntries` to add or change metadata — such as route, stop, or driver details — that wasn't available at the time the label was first created.