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 to learn how to obtain one.
Seller ID: Use the GET /sellers endpoint to find it.
Shipping service group ID: Use the GET /shippingServiceGroups/{sellerId} endpoint to find available shipping service groups.

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.

Estimate shipment costs

Estimate the price of shipment labels before booking using the POST /shipments/estimate endpoint. Use the requestUUID field to match the estimate results to your requests.

Request
Response

Use this request to estimate shipment costs:

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>"
      }
    ]
  }'

A successful request returns a 200 OK status code with an EstimateResponse object:

{
  "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.

Book a shipment

Book a shipment label using the POST /shipments/book endpoint. 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:

Request
Response

Use this request to book a shipment label:

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

A successful request returns a 200 OK status code with a BookResponse object:

{
  "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.

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:

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 to get details by shipment ID:

Request
Response

Use this request to retrieve the full details of a booked shipment by its ID:

curl -X GET "${BASE_URL}/shipments/<BOOKED_SHIPMENT_ID>" \
  -H "X-Api-Key: <YOUR_STATIC_API_KEY>" \
  -H "Authorization: <YOUR_SESSION_TOKEN>"

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.

Retrieve shipping labels

You can retrieve shipping labels in two ways:

From the booking response: The labelUrls array in the BookResponse contains URLs where you can download the shipping labels.
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:

Request
Response

Use this request to get a download link for a shipment document:

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

A successful request returns a 200 OK status code with a Link object containing the download URL:

{
  "link": "<DOCUMENT_URL>"
}

Track shipment status

Search for booked shipments using the GET /shipments endpoint. 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.

Request
Response

Use this request to search for shipments using query parameters:

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>"

A successful request returns a 200 OK status code with an array of BookedShipmentSummary objects:

[
  {
    "bookedShipmentId": <BOOKED_SHIPMENT_ID>,
    "trackingNumber": "<TRACKING_NUMBER>",
    "trackingLink": "<TRACKING_LINK>",
    "carrierSlug": "<CARRIER_SLUG>",
    "reference": "<REFERENCE>",
    "created": "<YYYY-MM-DDTHH:mm:ssZ>"
  }
]

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. You must provide the seller ID, shipping service group ID, parcel count, and pickup date. The pickupFrom address is optional.

Request
Response

Use this request to book a pickup:

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>"
    }
  }'

A successful request returns a 200 OK status code with an empty response body.

Search for booked pickups

Search for booked pickups using the GET /shipments/pickups endpoint. Use the query parameter to filter results by pickup date, seller, or other criteria.

Request
Response

Use this request to search for booked pickups:

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>"

A successful request returns a 200 OK status code with an array of BookedPickupGet objects:

[
  {
    "id": <PICKUP_ID>,
    "sellerId": <YOUR_SELLER_ID>,
    "shippingServiceGroupId": <SHIPPING_SERVICE_GROUP_ID>,
    "parcelCount": <PARCEL_COUNT>,
    "pickupDate": "<PICKUP_DATE>",
    "created": "<YYYY-MM-DDTHH:mm:ssZ>"
  }
]

Batch operations

Book a batch of shipment labels using the POST /shipments/bookBatchAsync endpoint. 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.

Request
Response

Use this request to book a batch of shipments:

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>"
      }
    ]
  }'

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.

Cancel a shipment

Cancel a booked shipment using the DELETE /shipments/{bookedShipmentId} endpoint:

Request
Response

Use this request to cancel a booked shipment:

curl -X DELETE "${BASE_URL}/shipments/<BOOKED_SHIPMENT_ID>" \
  -H "X-Api-Key: <YOUR_STATIC_API_KEY>" \
  -H "Authorization: <YOUR_SESSION_TOKEN>"

A successful cancellation returns a 200 OK status code with an empty response body.

Where to go next

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

Track an Order

Monitor order status and retrieve tracking information when shipping occurs.

Manage Returns

Generate return labels and track returned items when customers need to send products back.

Introduction

Quickstart

Quivo Flows

Webhooks

Prerequisites

Estimate shipment costs

Book a shipment

Request fields

Retrieve shipment details

Retrieve shipping labels

Track shipment status

Schedule a pickup

Search for booked pickups

Batch operations

Cancel a shipment

Where to go next

Track an Order

Manage Returns

Introduction

Quickstart

Quivo Flows

Webhooks

​Prerequisites

​Estimate shipment costs

​Book a shipment

​Request fields

​Retrieve shipment details

​Retrieve shipping labels

​Track shipment status

​Schedule a pickup

​Search for booked pickups

​Batch operations

​Cancel a shipment

​Where to go next

Track an Order

Manage Returns

Prerequisites

Estimate shipment costs

Book a shipment

Request fields

Retrieve shipment details

Retrieve shipping labels

Track shipment status

Schedule a pickup

Search for booked pickups

Batch operations

Cancel a shipment

Where to go next