> ## 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.
# Book shipment
> Book a shipment and generate shipping labels or documents.
## OpenAPI
````yaml /openapi.json post /shipments/book
openapi: 3.0.1
info:
title: Connector
version: 80f7edc, 2026-01-23T12:01:00Z
description: Enhanced Quivo API documentation with additional descriptions and examples
contact:
name: Quivo Support
email: support@quivo.co
url: https://quivo.co
license:
name: Proprietary
url: https://quivo.co/terms
termsOfService: https://quivo.co/terms
servers:
- url: https://api.quivo.co/
description: Production API server for Quivo Connector
security: []
tags:
- name: addresses
description: Manage stored addresses in the seller's address book
- name: apiKeyRequests
description: Request and manage API keys
- name: articles
description: Create and manage product articles
- name: audits
description: Access audit logs and history
- name: bundles
description: Manage product bundles
- name: carriers
description: Get carrier information
- name: contacts
description: Manage contact information
- name: countries
description: Get country information
- name: currencies
description: Get currency information
- name: customerInquiries
description: Manage customer inquiries
- name: dashboards
description: Access dashboard data
- name: files
description: Manage file uploads and downloads
- name: fulfillmentPlans
description: Manage fulfillment plans
- name: inbounds
description: Manage inbound shipments
- name: items
description: Monitor and manage inventory items
- name: languages
description: Get language information
- name: notifications
description: Manage notifications
- name: orders
description: Create and manage fulfillment orders
- name: ping
description: Health check endpoint
- name: returnApp
description: Manage return applications
- name: returnLinks
description: Manage return links
- name: returns
description: Manage returns
- name: sellers
description: Get seller information
- name: shipments
description: Book and manage shipments
- name: shippingServiceGroups
description: Get shipping service groups
- name: shopOrders
description: Manage shop orders
- name: shops
description: Manage shops
- name: status
description: Get system status
- name: storedAddresses
description: Manage stored addresses
- name: subscriptionPackages
description: Manage subscription packages
- name: subscriptions
description: Manage webhook subscriptions
- name: track
description: Track shipments
- name: transports
description: Manage transport services
- name: users
description: Manage users
- name: warehouses
description: Get warehouse information
paths:
/shipments/book:
post:
tags:
- shipments
summary: Book shipment
description: Book a shipment and generate shipping labels or documents.
operationId: shipmentsBook
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/BookRequest'
required: false
description: Request body data for Book shipment
responses:
'200':
description: >-
Returns the booking result including tracking numbers, label URLs,
and shipment identifiers.
content:
application/json:
schema:
$ref: '#/components/schemas/BookResponse'
'400':
description: >-
Bad request - the request payload is invalid, missing required
fields, or contains invalid data.
'401':
description: >-
Unauthorized - authentication credentials are missing, invalid, or
expired.
'404':
description: >-
Not found - the requested resource does not exist or is not
accessible.
'500':
description: Internal server error - an unexpected error occurred on the server.
components:
schemas:
BookRequest:
required:
- grossWeightKg
- sellerId
- shipTo
- shippingServiceGroupId
type: object
properties:
requestUUID:
type: string
description: >-
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:
type: string
description: >-
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.
shippingServiceGroupId:
type: integer
description: >-
shipping service group from which to load the shipping services to
use.
format: int64
shipFrom:
$ref: '#/components/schemas/ShipmentDeliveryAddress'
lengthM:
minimum: 0
exclusiveMinimum: true
type: number
description: Optional length (in meters) of the shipment.
widthM:
minimum: 0
exclusiveMinimum: true
type: number
description: Optional width (in meters) of the shipment.
heightM:
minimum: 0
exclusiveMinimum: true
type: number
description: Optional height (in meters) of the shipment.
grossWeightKg:
minimum: 0
exclusiveMinimum: true
type: number
description: >-
The total weight (kilograms) of the shipment including
packaging.
shipTo:
$ref: '#/components/schemas/ShipmentDeliveryAddress'
customsPositions:
type: array
description: >-
Optional customs positions for the shipment. Only required if
shipping to countries for which export documents are required.
items:
$ref: '#/components/schemas/CustomsPosition'
sellerId:
type: integer
description: >-
The seller who is booking this shipment (required).
The booked
shipment will show up in the history of this seller.
format: int64
invoiceNumber:
maxLength: 50
minLength: 1
type: string
description: The invoice number to be used for customs declaration.
invoiceDate:
type: string
description: The invoice date to be used for customs declaration.
format: date
transportInsuranceAmount:
minimum: 0
exclusiveMinimum: true
type: number
description: >-
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.
includeReturnLabel:
type: boolean
description: >-
Optional value setting whether a return labels should be included in
addition to the main label or not.
trackingEnabled:
type: boolean
description: >-
Optional value setting whether to turn on/off tracking functionality
for shipment. Additional charges will apply when set to true.
shipmentDate:
type: string
description: >-
Optional future or today's date when the shipment will be handed
over to the carrier. If not specified, default's to today.
format: date
termsOfTrade:
type: string
description: >-
Optional terms of trade. If not specified, default's
DAP.
enum:
- DAP
- DDP
additionalParcels:
type: array
description: >-
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.
items:
$ref: '#/components/schemas/ShipmentParcelGet'
userIdentifier:
type: string
description: The userId of a third party app who booked the shipment.
shopOrderIdentifier:
type: string
description: Optional value. Identifies the order in the customer's shop.
contentDescription:
type: string
description: Optional description of the shipment contents.
systemReference:
type: string
description: Optional system reference, can be used to trace the shipment
shipmentAttachments:
type: array
description: Optional attachments parameter
items:
$ref: '#/components/schemas/ShipmentAttachmentPost'
cashOnDeliveryAmount:
type: number
description: >-
Optional COD total amount parameter. If the amount is greater than
0, it will be processed as a COD shipment
cashOnDeliveryCurrency:
type: string
description: The currency in which COD amount is specified.
description: >-
Request payload for booking a shipment and generating shipping labels.
Contains delivery addresses, package dimensions, weight, shipping
service selection, and optional customs information.
BookResponse:
type: object
properties:
status:
type: string
description: Indicates whether the operation was successful or not.
enum:
- OK
- ERROR
message:
type: string
description: >-
Optional additional information about the operation's result.
When the operation failed, this field includes more information
about the error.
bookedShipmentId:
type: integer
description: ID of booked shipment
format: int64
trackingNumber:
type: string
description: The tracking number of the booked shipment.
trackingLink:
type: string
description: >-
The tracking link of the booked shipment. Note that some carriers do
not immediately recognize shipments after they have been created
labelUrls:
type: array
description: List of URLs where the labels can be downloaded.
items:
type: string
documentUrls:
type: array
description: >-
List of URLs where additional documents, such as export documents,
can be downloaded.
items:
type: string
description: >-
Response from booking a shipment operation. Contains booking status,
shipment identifier, tracking information, and label/document
references.
ShipmentDeliveryAddress:
type: object
properties:
name:
type: string
description: >-
Name of the recipient.
Usually this is the first and lastname of
the recipient.
company:
type: string
description: Name of the company.
phone:
type: string
description: >-
Phone number of the recipient.
The phone number is usually
optional.
email:
type: string
description: E-Mail address of the recipient.
zip:
type: string
description: >-
ZIP Code of the recipient
The ZIP code is optional for some
countries, but required for most. It is optional when latitude and
longitude coordinates are provided.
city:
type: string
description: >-
City of the recipient.
This field is optional only when latitude
and longitude coordinates are provided.
state:
type: string
description: >-
State of the recipient.
This is not required for most countries,
but required in some (eg: United States).
countryIso2:
type: string
description: >-
Country Code.
This field is optional only when latitude and
longitude coordinates are provided.
street:
type: string
description: >-
Street (or Address Line 1) of the recipient.
This field is
optional only when latitude and longitude coordinates are provided.
street2:
type: string
description: >-
Street (or Address Line 2) of the recipient.
This field is
optional.
latitude:
type: number
description: >-
Latitude of the address.
This field is optional and used for
some carriers to optimize the delivery process.
format: double
longitude:
type: number
description: >-
Longitude of the address.
This field is optional and used for
some carriers to optimize the delivery process.
format: double
description: 'The '
CustomsPosition:
required:
- description
- pieceNetCustomsValue
- pieceNetWeightKg
- quantity
type: object
properties:
description:
type: string
description: Name or short description of product.
quantity:
minimum: 0
exclusiveMinimum: true
type: integer
description: Number of pieces in shipment of product.
format: int32
pieceNetWeightKg:
minimum: 0
exclusiveMinimum: true
type: number
description: Net weight in kg per piece.
pieceNetCustomsValue:
minimum: 0
exclusiveMinimum: true
type: number
description: Net customs value per piece in the currency.
originCountryIso2:
type: string
description: The country of origin of the product.
enum:
- AF
- AX
- AL
- DZ
- AS
- AD
- AO
- AI
- AQ
- AG
- AR
- AM
- AW
- AU
- AT
- AZ
- BS
- BH
- BD
- BB
- BY
- BE
- BZ
- BJ
- BM
- BT
- BO
- BA
- BW
- BV
- BR
- IO
- BN
- BG
- BF
- BI
- KH
- CM
- CA
- CV
- KY
- CF
- TD
- CL
- CN
- CX
- CC
- CO
- KM
- CG
- CD
- CK
- CR
- CI
- HR
- CU
- CY
- CZ
- DK
- DJ
- DM
- DO
- EC
- EG
- SV
- GQ
- ER
- EE
- ET
- FK
- FO
- FJ
- FI
- FR
- GF
- PF
- TF
- GA
- GM
- GE
- DE
- GH
- GI
- GR
- GL
- GD
- GP
- GU
- GT
- GG
- GN
- GW
- GY
- HT
- HM
- VA
- HN
- HK
- HU
- IS
- IN
- ID
- IR
- IQ
- IE
- IM
- IL
- IT
- JM
- JP
- JE
- JO
- KZ
- KE
- KI
- KP
- KR
- XK
- KW
- KG
- LA
- LV
- LB
- LS
- LR
- LY
- LI
- LT
- LU
- MO
- MK
- MG
- MW
- MY
- MV
- ML
- MT
- MH
- MQ
- MR
- MU
- YT
- MX
- FM
- MD
- MC
- MN
- ME
- MS
- MA
- MZ
- MM
- NA
- NR
- NP
- NL
- NC
- NZ
- NI
- NE
- NG
- NU
- NF
- MP
- 'NO'
- OM
- PK
- PW
- PS
- PA
- PG
- PY
- PE
- PH
- PN
- PL
- PT
- PR
- QA
- RE
- RO
- RU
- RW
- BL
- SH
- KN
- LC
- MF
- PM
- VC
- WS
- SM
- ST
- SA
- SN
- RS
- SC
- SL
- SG
- SK
- SI
- SB
- SO
- ZA
- GS
- ES
- LK
- SD
- SR
- SJ
- CW
- BQ
- SX
- SZ
- SE
- CH
- SY
- TW
- TJ
- TZ
- TH
- TL
- TG
- TK
- TO
- TT
- TN
- TR
- TM
- TC
- TV
- UG
- UA
- AE
- GB
- US
- UM
- UY
- UZ
- VU
- VE
- VN
- VG
- VI
- WF
- EH
- YE
- ZM
- ZW
currency:
type: string
description: The currency in which customs values are specified.
tariffNumber:
type: string
description: The tariff number (customs number).
orderedSku:
type: string
description: Optional value. The SKU of the position.
unNumber:
type: string
description: Optional value. The UN number of the position.
description: Customs declaration position data
ShipmentParcelGet:
required:
- weight
type: object
properties:
weight:
minimum: 0
exclusiveMinimum: true
type: number
description: Parcel weight (kilograms) including packaging.
length:
type: number
description: >-
Parcel package length (meters)
This field will be
considered only if width and height are filled as
well.
width:
type: number
description: >-
Parcel package width (meters)
This field will be
considered only if length and height are filled as
well.
height:
type: number
description: >-
Parcel package height (meter)
This field will be
considered only if length and width are filled as
well.
reference:
type: string
description: Parcel package reference for the current shipment (meter)
description: Response object containing shipmentparcel details
ShipmentAttachmentPost:
type: object
properties:
fileName:
type: string
description: Name for the attachment
fileKey:
type: string
description: Identifier of the file to be attached.
mimeType:
type: string
description: Mime type of the file
description: Request object for creating shipmentattachment
````