Skip to main content
POST
/
shipments
/
book
Book shipment
curl --request POST \
  --url https://api.quivo.co/shipments/book \
  --header 'Content-Type: application/json' \
  --data '
{
  "shippingServiceGroupId": 123,
  "grossWeightKg": 1,
  "shipTo": {
    "name": "<string>",
    "company": "<string>",
    "phone": "<string>",
    "email": "<string>",
    "zip": "<string>",
    "city": "<string>",
    "state": "<string>",
    "countryIso2": "<string>",
    "street": "<string>",
    "street2": "<string>",
    "latitude": 123,
    "longitude": 123
  },
  "sellerId": 123,
  "requestUUID": "<string>",
  "reference": "<string>",
  "shipFrom": {
    "name": "<string>",
    "company": "<string>",
    "phone": "<string>",
    "email": "<string>",
    "zip": "<string>",
    "city": "<string>",
    "state": "<string>",
    "countryIso2": "<string>",
    "street": "<string>",
    "street2": "<string>",
    "latitude": 123,
    "longitude": 123
  },
  "lengthM": 1,
  "widthM": 1,
  "heightM": 1,
  "customsPositions": [
    {
      "description": "<string>",
      "quantity": 1,
      "pieceNetWeightKg": 1,
      "pieceNetCustomsValue": 1,
      "originCountryIso2": "AF",
      "currency": "<string>",
      "tariffNumber": "<string>",
      "orderedSku": "<string>",
      "unNumber": "<string>"
    }
  ],
  "invoiceNumber": "<string>",
  "invoiceDate": "2023-12-25",
  "transportInsuranceAmount": 1,
  "includeReturnLabel": true,
  "trackingEnabled": true,
  "shipmentDate": "2023-12-25",
  "termsOfTrade": "DAP",
  "additionalParcels": [
    {
      "weight": 1,
      "length": 123,
      "width": 123,
      "height": 123,
      "reference": "<string>"
    }
  ],
  "userIdentifier": "<string>",
  "shopOrderIdentifier": "<string>",
  "contentDescription": "<string>",
  "systemReference": "<string>",
  "shipmentAttachments": [
    {
      "fileName": "<string>",
      "fileKey": "<string>",
      "mimeType": "<string>"
    }
  ],
  "cashOnDeliveryAmount": 123,
  "cashOnDeliveryCurrency": "<string>"
}
'
{
  "status": "OK",
  "message": "<string>",
  "bookedShipmentId": 123,
  "trackingNumber": "<string>",
  "trackingLink": "<string>",
  "labelUrls": [
    "<string>"
  ],
  "documentUrls": [
    "<string>"
  ]
}

Body

application/json

Request body data for Book shipment

Request payload for booking a shipment and generating shipping labels. Contains delivery addresses, package dimensions, weight, shipping service selection, and optional customs information.

​
shippingServiceGroupId
integer<int64>
required

shipping service group from which to load the shipping services to use.

​
grossWeightKg
number
required

The total weight (kilograms) of the shipment including packaging.

Required range: x > 0
​
shipTo
object
required

The

​
sellerId
integer<int64>
required

The seller who is booking this shipment (required).
The booked shipment will show up in the history of this seller.

​
requestUUID
string

A unique identifier for the request.
Used for tracing and to prevent duplicate shipment bookings.
This value is optional, if not included, a random requestUUID is generated.

​
reference
string

A human readable reference for the request.
This will be included in the mail that is sent once the operation completes.
This value is optional, if not included, a random reference will be generated.

​
shipFrom
object

The

​
lengthM
number

Optional length (in meters) of the shipment.

Required range: x > 0
​
widthM
number

Optional width (in meters) of the shipment.

Required range: x > 0
​
heightM
number

Optional height (in meters) of the shipment.

Required range: x > 0
​
customsPositions
object[]

Optional customs positions for the shipment. Only required if shipping to countries for which export documents are required.

​
invoiceNumber
string

The invoice number to be used for customs declaration.

Required string length: 1 - 50
​
invoiceDate
string<date>

The invoice date to be used for customs declaration.

​
transportInsuranceAmount
number

Optional amount which should get insured when booking the shipment.
Note that most shipping services already have a basic insurance included. To use the already included insurance, you must not set this field to any value other than null.
Setting this field to a non null value will book an additional insurance.

Required range: x > 0
​
includeReturnLabel
boolean

Optional value setting whether a return labels should be included in addition to the main label or not.

​
trackingEnabled
boolean

Optional value setting whether to turn on/off tracking functionality for shipment. Additional charges will apply when set to true.

​
shipmentDate
string<date>

Optional future or today's date when the shipment will be handed over to the carrier. If not specified, default's to today.

​
termsOfTrade
enum<string>

Optional terms of trade. If not specified, default's DAP.

Available options:
DAP,
DDP
​
additionalParcels
object[]

Optional additional parcels for the shipment. Note that by default the request represent the primary parcel/package for this shipment, use this field only if is needed to add more packages for the shipment.

​
userIdentifier
string

The userId of a third party app who booked the shipment.

​
shopOrderIdentifier
string

Optional value. Identifies the order in the customer's shop.

​
contentDescription
string

Optional description of the shipment contents.

​
systemReference
string

Optional system reference, can be used to trace the shipment

​
shipmentAttachments
object[]

Optional attachments parameter

​
cashOnDeliveryAmount
number

Optional COD total amount parameter. If the amount is greater than 0, it will be processed as a COD shipment

​
cashOnDeliveryCurrency
string

The currency in which COD amount is specified.

Response

Returns the booking result including tracking numbers, label URLs, and shipment identifiers.

Response from booking a shipment operation. Contains booking status, shipment identifier, tracking information, and label/document references.

​
status
enum<string>

Indicates whether the operation was successful or not.

Available options:
OK,
ERROR
​
message
string

Optional additional information about the operation's result.
When the operation failed, this field includes more information about the error.

​
bookedShipmentId
integer<int64>

ID of booked shipment

​
trackingNumber
string

The tracking number of the booked shipment.

​
trackingLink
string

The tracking link of the booked shipment. Note that some carriers do not immediately recognize shipments after they have been created

​
labelUrls
string[]

List of URLs where the labels can be downloaded.

​
documentUrls
string[]

List of URLs where additional documents, such as export documents, can be downloaded.