> ## Documentation Index
> Fetch the complete documentation index at: https://api-docs.quivo.co/llms.txt
> Use this file to discover all available pages before exploring further.

# Manage Shipments

This guide shows you how to manually book shipments, retrieve shipping labels, track shipment status, schedule pickups, perform batch operations, and estimate shipment costs.

## Prerequisites

Before you start, make sure you have:

* **Session token:** A valid session token. See the [Authentication guide](/api-reference/authentication) to learn how to obtain one.
* **Seller ID:** Use the [`GET /sellers endpoint`](/api-reference/#tag/sellers) to find it.
* **Shipping service group ID:** Use the [`GET /shippingServiceGroups/{sellerId} endpoint`](/api-reference/#tag/shippingServiceGroups) to find available shipping service groups.

<Note>
  All API examples in this guide use `${BASE_URL}` as a placeholder. Replace it with the correct base URL configured for the correct environment. For more information see [Environments page](/api-reference/environments).
</Note>

## Estimate shipment costs

Estimate the price of shipment labels before booking using the [`POST /shipments/estimate endpoint`](/api-reference/#tag/shipments). Use the `requestUUID` field to match the estimate results to your requests.

<Tabs>
  <Tab title="Request">
    Use this request to estimate shipment costs:

    ```bash theme={null}
    curl -X POST "${BASE_URL}/shipments/estimate" \
      -H "X-Api-Key: <YOUR_STATIC_API_KEY>" \
      -H "Authorization: <YOUR_SESSION_TOKEN>" \
      -H "Content-Type: application/json" \
      -d '{
        "estimateRequests": [
          {
            "sellerId": <YOUR_SELLER_ID>,
            "shippingServiceGroupId": <SHIPPING_SERVICE_GROUP_ID>,
            "grossWeightKg": <WEIGHT_KG>,
            "shipTo": {
              "name": "<RECIPIENT_NAME>",
              "street": "<STREET_ADDRESS>",
              "city": "<CITY>",
              "zip": "<ZIP_CODE>",
              "countryIso2": "<COUNTRY_CODE>"
            },
            "requestUUID": "<REQUEST_UUID>"
          }
        ]
      }'
    ```
  </Tab>

  <Tab title="Response">
    A successful request returns a `200 OK` status code with an `EstimateResponse` object:

    ```json theme={null}
    {
      "estimateResults": [
        {
          "requestUUID": "<REQUEST_UUID>",
          "success": true,
          "currency": {
            "currencyCode": "<CURRENCY_CODE>",
            "symbol": "<CURRENCY_SYMBOL>"
          },
          "amountLabel": <AMOUNT_LABEL>,
          "amountInsurance": <AMOUNT_INSURANCE>
        }
      ]
    }
    ```

    The `amountLabel` field shows the cost for the shipping label. The `amountInsurance` field shows the cost for insurance, if applicable. Use the `requestUUID` to match each result to the corresponding estimate request.
  </Tab>
</Tabs>

## Book a shipment

Book a shipment label using the [`POST /shipments/book endpoint`](/api-reference/#tag/shipments). You must provide the seller ID, shipping service group ID, gross weight, and delivery address. The `shipFrom` address is optional.

The following example shows how to book a shipment:

<Tabs>
  <Tab title="Request">
    Use this request to book a shipment label:

    ```bash theme={null}
    curl -X POST "${BASE_URL}/shipments/book" \
      -H "X-Api-Key: <YOUR_STATIC_API_KEY>" \
      -H "Authorization: <YOUR_SESSION_TOKEN>" \
      -H "Content-Type: application/json" \
      -d '{
        "sellerId": <YOUR_SELLER_ID>,
        "shippingServiceGroupId": <SHIPPING_SERVICE_GROUP_ID>,
        "grossWeightKg": <WEIGHT_KG>,
        "shipTo": {
          "name": "<RECIPIENT_NAME>",
          "company": "<COMPANY_NAME>",
          "email": "<RECIPIENT_EMAIL>",
          "phone": "<RECIPIENT_PHONE>",
          "street": "<STREET_ADDRESS>",
          "street2": "<ADDRESS_LINE_2>",
          "city": "<CITY>",
          "zip": "<ZIP_CODE>",
          "state": "<STATE>",
          "countryIso2": "<COUNTRY_CODE>"
        },
        "shipFrom": {
          "name": "<SENDER_NAME>",
          "street": "<SENDER_STREET>",
          "city": "<SENDER_CITY>",
          "zip": "<SENDER_ZIP>",
          "countryIso2": "<SENDER_COUNTRY_CODE>"
        },
        "reference": "<REFERENCE>",
        "requestUUID": "<REQUEST_UUID>",
        "lengthM": <LENGTH_M>,
        "widthM": <WIDTH_M>,
        "heightM": <HEIGHT_M>,
        "trackingEnabled": true
      }'
    ```
  </Tab>

  <Tab title="Response">
    A successful request returns a `200 OK` status code with a `BookResponse` object:

    ```json theme={null}
    {
      "status": "OK",
      "message": "<MESSAGE>",
      "bookedShipmentId": <BOOKED_SHIPMENT_ID>,
      "trackingNumber": "<TRACKING_NUMBER>",
      "trackingLink": "<TRACKING_LINK>",
      "labelUrls": [
        "<LABEL_URL_1>",
        "<LABEL_URL_2>"
      ],
      "documentUrls": [
        "<DOCUMENT_URL>"
      ]
    }
    ```

    Save the `bookedShipmentId` from the response. You need this ID to retrieve shipment details, labels, or cancel the shipment later. The `labelUrls` array contains URLs where you can download the shipping labels. The `documentUrls` array contains URLs for additional documents such as export documents, if applicable.
  </Tab>
</Tabs>

### Request fields

The following table describes the key fields you can include when booking a shipment. The `shipTo` and `shipFrom` objects use the `ShipmentDeliveryAddress` schema. For complete field definitions, see the [API Reference](/api-reference/#tag/shipments):

| Field                                         | Type          | Description                                                                                                                                                             |
| --------------------------------------------- | ------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `sellerId`                                    | Integer       | The seller who is booking this shipment.                                                                                                                                |
| `shippingServiceGroupId`                      | Integer       | Shipping service group from which to load the shipping services to use.                                                                                                 |
| `grossWeightKg`                               | Number        | The total weight (kilograms) of the shipment including packaging. Must be greater than 0.                                                                               |
| `shipTo`                                      | Object        | Delivery address object. See address fields below.                                                                                                                      |
| `shipFrom`                                    | Object        | Sender address object. Optional.                                                                                                                                        |
| `reference`                                   | String        | A human readable reference for the request. Optional. If not included, the system generates a random reference.                                                         |
| `requestUUID`                                 | String        | A unique identifier for the request. Used for tracing and to prevent duplicate shipment bookings. Optional. If not included, the system generates a random requestUUID. |
| `lengthM`                                     | Number        | Optional length in meters of the shipment. Must be greater than 0.                                                                                                      |
| `widthM`                                      | Number        | Optional width in meters of the shipment. Must be greater than 0.                                                                                                       |
| `heightM`                                     | Number        | Optional height in meters of the shipment. Must be greater than 0.                                                                                                      |
| `trackingEnabled`                             | Boolean       | Optional value setting whether to turn on/off tracking for shipment. Additional charges apply when set to true.                                                         |
| `includeReturnLabel`                          | Boolean       | Optional value setting whether to include a return label along with the main label.                                                                                     |
| `shipmentDate`                                | String (date) | Optional future or today's date when the carrier picks up the shipment. If not specified, defaults to today.                                                            |
| `termsOfTrade`                                | String        | Optional terms of trade. If not specified, defaults to `DAP`. Valid values: `DAP`, `DDP`.                                                                               |
| `customsPositions`                            | Array         | Optional customs positions for the shipment. Only required if shipping to countries that require export documents.                                                      |
| `invoiceNumber`                               | String        | The invoice number for customs declaration.                                                                                                                             |
| `invoiceDate`                                 | String (date) | The invoice date for customs declaration.                                                                                                                               |
| `transportInsuranceAmount`                    | Number        | Optional amount to insure when booking the shipment. Setting this field to a non-null value books additional insurance.                                                 |
| `shipTo.name` / `shipFrom.name`               | String        | Name of the recipient. Usually the first and last name. You must provide either `name` or `company`.                                                                    |
| `shipTo.company` / `shipFrom.company`         | String        | Name of the company. You must provide either `name` or `company`.                                                                                                       |
| `shipTo.email` / `shipFrom.email`             | String        | Email address of the recipient.                                                                                                                                         |
| `shipTo.phone` / `shipFrom.phone`             | String        | Phone number of the recipient.                                                                                                                                          |
| `shipTo.street` / `shipFrom.street`           | String        | Street address (Address Line 1). Optional only when you provide latitude and longitude coordinates.                                                                     |
| `shipTo.street2` / `shipFrom.street2`         | String        | Address Line 2. Optional.                                                                                                                                               |
| `shipTo.city` / `shipFrom.city`               | String        | City. Optional only when you provide latitude and longitude coordinates.                                                                                                |
| `shipTo.zip` / `shipFrom.zip`                 | String        | ZIP or postal code. Optional for some countries, but required for most. Optional when you provide latitude and longitude coordinates.                                   |
| `shipTo.state` / `shipFrom.state`             | String        | State or province. Required for some countries (for example, United States).                                                                                            |
| `shipTo.countryIso2` / `shipFrom.countryIso2` | String        | Two-letter ISO country code. Optional only when you provide latitude and longitude coordinates.                                                                         |
| `shipTo.latitude` / `shipFrom.latitude`       | Number        | Latitude coordinate for the address. Optional, used for some carriers to optimize the delivery process.                                                                 |
| `shipTo.longitude` / `shipFrom.longitude`     | Number        | Longitude coordinate for the address. Optional, used for some carriers to optimize the delivery process.                                                                |

## Retrieve shipment details

Retrieve shipment details using the booked shipment ID. Use the [`GET /shipments/{bookedShipmentId} endpoint`](/api-reference/#tag/shipments) to get details by shipment ID:

<Tabs>
  <Tab title="Request">
    Use this request to retrieve the full details of a booked shipment by its ID:

    ```bash theme={null}
    curl -X GET "${BASE_URL}/shipments/<BOOKED_SHIPMENT_ID>" \
      -H "X-Api-Key: <YOUR_STATIC_API_KEY>" \
      -H "Authorization: <YOUR_SESSION_TOKEN>"
    ```
  </Tab>

  <Tab title="Response">
    A successful request returns a `200 OK` status code with the full shipment details as a `BookedShipmentGet` object, including tracking information, documents, and all shipment metadata.
  </Tab>
</Tabs>

## Retrieve shipping labels

You can retrieve shipping labels in two ways:

1. **From the booking response:** The `labelUrls` array in the `BookResponse` contains URLs where you can download the shipping labels.
2. **From shipment details:** Retrieve shipment details using the `GET /shipments/{bookedShipmentId}` endpoint. The response includes a `documents` array with document information. Use the `shipmentDocumentId` from each document to retrieve the download URL using the `GET /shipments/documentLink` endpoint.

To get a download link for a specific document, use the [`GET /shipments/documentLink endpoint`](/api-reference/#tag/shipments):

<Tabs>
  <Tab title="Request">
    Use this request to get a download link for a shipment document:

    ```bash theme={null}
    curl -X GET "${BASE_URL}/shipments/documentLink?shipmentDocumentId=<DOCUMENT_ID>" \
      -H "X-Api-Key: <YOUR_STATIC_API_KEY>" \
      -H "Authorization: <YOUR_SESSION_TOKEN>"
    ```
  </Tab>

  <Tab title="Response">
    A successful request returns a `200 OK` status code with a `Link` object containing the download URL:

    ```json theme={null}
    {
      "link": "<DOCUMENT_URL>"
    }
    ```
  </Tab>
</Tabs>

## Track shipment status

Search for booked shipments using the [`GET /shipments endpoint`](/api-reference/#tag/shipments). This endpoint supports query, sorting, and pagination parameters. Use the `query` parameter to filter results, `sort` to order them, and `pageSize` to limit the number of results.

<Tabs>
  <Tab title="Request">
    Use this request to search for shipments using query parameters:

    ```bash theme={null}
    curl -X GET "${BASE_URL}/shipments?query=trackingNumber:<TRACKING_NUMBER>&sort=created:desc&pageSize=50" \
      -H "X-Api-Key: <YOUR_STATIC_API_KEY>" \
      -H "Authorization: <YOUR_SESSION_TOKEN>"
    ```
  </Tab>

  <Tab title="Response">
    A successful request returns a `200 OK` status code with an array of `BookedShipmentSummary` objects:

    ```json theme={null}
    [
      {
        "bookedShipmentId": <BOOKED_SHIPMENT_ID>,
        "trackingNumber": "<TRACKING_NUMBER>",
        "trackingLink": "<TRACKING_LINK>",
        "carrierSlug": "<CARRIER_SLUG>",
        "reference": "<REFERENCE>",
        "created": "<YYYY-MM-DDTHH:mm:ssZ>"
      }
    ]
    ```
  </Tab>
</Tabs>

For detailed tracking information, retrieve the full shipment details using the `GET /shipments/{bookedShipmentId}` endpoint. The response includes a `trackingDetails` array with tracking information.

## Schedule a pickup

Book a pickup for booked shipments using the [`POST /shipments/pickups endpoint`](/api-reference/#tag/shipments). You must provide the seller ID, shipping service group ID, parcel count, and pickup date. The `pickupFrom` address is optional.

<Tabs>
  <Tab title="Request">
    Use this request to book a pickup:

    ```bash theme={null}
    curl -X POST "${BASE_URL}/shipments/pickups" \
      -H "X-Api-Key: <YOUR_STATIC_API_KEY>" \
      -H "Authorization: <YOUR_SESSION_TOKEN>" \
      -H "Content-Type: application/json" \
      -d '{
        "sellerId": <YOUR_SELLER_ID>,
        "shippingServiceGroupId": <SHIPPING_SERVICE_GROUP_ID>,
        "parcelCount": <PARCEL_COUNT>,
        "pickupDate": "<PICKUP_DATE>",
        "pickupFrom": {
          "name": "<PICKUP_CONTACT_NAME>",
          "street": "<PICKUP_STREET_ADDRESS>",
          "city": "<PICKUP_CITY>",
          "zip": "<PICKUP_ZIP>",
          "countryIso2": "<PICKUP_COUNTRY_CODE>",
          "phone": "<PICKUP_PHONE>"
        }
      }'
    ```
  </Tab>

  <Tab title="Response">
    A successful request returns a `200 OK` status code with an empty response body.
  </Tab>
</Tabs>

### Search for booked pickups

Search for booked pickups using the [`GET /shipments/pickups endpoint`](/api-reference/#tag/shipments). Use the `query` parameter to filter results by pickup date, seller, or other criteria.

<Tabs>
  <Tab title="Request">
    Use this request to search for booked pickups:

    ```bash theme={null}
    curl -X GET "${BASE_URL}/shipments/pickups?query=pickupDate:<PICKUP_DATE>&sort=created:desc&pageSize=50" \
      -H "X-Api-Key: <YOUR_STATIC_API_KEY>" \
      -H "Authorization: <YOUR_SESSION_TOKEN>"
    ```
  </Tab>

  <Tab title="Response">
    A successful request returns a `200 OK` status code with an array of `BookedPickupGet` objects:

    ```json theme={null}
    [
      {
        "id": <PICKUP_ID>,
        "sellerId": <YOUR_SELLER_ID>,
        "shippingServiceGroupId": <SHIPPING_SERVICE_GROUP_ID>,
        "parcelCount": <PARCEL_COUNT>,
        "pickupDate": "<PICKUP_DATE>",
        "created": "<YYYY-MM-DDTHH:mm:ssZ>"
      }
    ]
    ```
  </Tab>
</Tabs>

## Batch operations

Book a batch of shipment labels using the [`POST /shipments/bookBatchAsync endpoint`](/api-reference/#tag/shipments). This endpoint processes multiple shipment bookings asynchronously and sends the results via email. The `lineNumber` field represents the line number in the original batch file. Once the batch operation completes, the system sends a ZIP file with labels and export documents to the specified email address.

<Tabs>
  <Tab title="Request">
    Use this request to book a batch of shipments:

    ```bash theme={null}
    curl -X POST "${BASE_URL}/shipments/bookBatchAsync" \
      -H "X-Api-Key: <YOUR_STATIC_API_KEY>" \
      -H "Authorization: <YOUR_SESSION_TOKEN>" \
      -H "Content-Type: application/json" \
      -d '{
        "reference": "<BATCH_REFERENCE>",
        "email": "<EMAIL_ADDRESS>",
        "bookRequests": [
          {
            "lineNumber": <LINE_NUMBER>,
            "sellerId": <YOUR_SELLER_ID>,
            "shippingServiceGroupId": <SHIPPING_SERVICE_GROUP_ID>,
            "grossWeightKg": <WEIGHT_KG>,
            "shipTo": {
              "name": "<RECIPIENT_NAME_1>",
              "street": "<STREET_ADDRESS_1>",
              "city": "<CITY_1>",
              "zip": "<ZIP_CODE_1>",
              "countryIso2": "<COUNTRY_CODE_1>"
            },
            "reference": "<ORDER_REFERENCE>"
          },
          {
            "lineNumber": <LINE_NUMBER>,
            "sellerId": <YOUR_SELLER_ID>,
            "shippingServiceGroupId": <SHIPPING_SERVICE_GROUP_ID>,
            "grossWeightKg": <WEIGHT_KG>,
            "shipTo": {
              "name": "<RECIPIENT_NAME_2>",
              "street": "<STREET_ADDRESS_2>",
              "city": "<CITY_2>",
              "zip": "<ZIP_CODE_2>",
              "countryIso2": "<COUNTRY_CODE_2>"
            },
            "reference": "<ORDER_REFERENCE>"
          }
        ]
      }'
    ```
  </Tab>

  <Tab title="Response">
    A successful request returns a `200 OK` status code with an empty response body. The operation runs asynchronously, and the system sends results to the specified email address when complete.
  </Tab>
</Tabs>

## Cancel a shipment

Cancel a booked shipment using the [`DELETE /shipments/{bookedShipmentId} endpoint`](/api-reference/#tag/shipments):

<Tabs>
  <Tab title="Request">
    Use this request to cancel a booked shipment:

    ```bash theme={null}
    curl -X DELETE "${BASE_URL}/shipments/<BOOKED_SHIPMENT_ID>" \
      -H "X-Api-Key: <YOUR_STATIC_API_KEY>" \
      -H "Authorization: <YOUR_SESSION_TOKEN>"
    ```
  </Tab>

  <Tab title="Response">
    A successful cancellation returns a `200 OK` status code with an empty response body.
  </Tab>
</Tabs>

## Where to go next

Now that you can manage shipments, continue with these guides:

<CardGroup cols={2}>
  <Card title="Track an Order" icon="location-dot" href="/docs/quickstart/track-order">
    Monitor order status and retrieve tracking information when shipping occurs.
  </Card>

  <Card title="Manage Returns" icon="rotate-left" href="/docs/quickstart/manage-returns">
    Generate return labels and track returned items when customers need to send products back.
  </Card>
</CardGroup>