Shipments
A shipment is what you buy: from a quoted offer, or directly from a carrier. An order and its shipment are one resource with one id.
Create a shipment
Coming soon The contract is published ahead of the implementation. This operation is not available yet and its shape may still change.
Buys a shipment. Two ways, exactly one of offer_code or carrier_code:
- From an offer (
offer_code): orders an offer from a previous quotation. Postal data and packages come from the quotation. - Direct (
carrier_code): quotation, order and waybill in one call (legacy Order-Fast, Order-Faster and Order-Direct). Order-Direct customers use the direct carriers and the services markedorder-direct.
The price is charged to your prepaid credit (nothing is charged with a test key, livemode: false). The waybill is generated asynchronously: if waybill_status is PENDING, the shipment exists anyway; read it later with GET /shipments/{shipment_id}/waybill or wait for the shipment.waybill_ready webhook. Set label.inline to receive the label in the response.
Authentication: your API key in the X-API-Key header.
Parameters
- Name
Idempotency-Key- Type
- string
- required
- Description
Unique key (UUID recommended, max 255 characters) that makes the write safe to retry. A retry with the same key and body returns the first response with
Idempotent-Replayed: true; same key with a different body is 422IDEMPOTENCY_KEY_REUSED; while the first call is running, 409IDEMPOTENCY_KEY_IN_USE. Keys expire after 24 hours. Missing: 400IDEMPOTENCY_KEY_REQUIRED.length ≥ 1, length ≤ 255.
Request body ShipmentFromOffer | ShipmentDirect
The body must match one of the models in its type.
Responses
201Shipment created.Shipment400Malformed or invalid request. Codes:VALIDATION_ERROR(withdetails.errors),INVALID_JSON,IDEMPOTENCY_KEY_REQUIRED,UNSUPPORTED_VERSION.Error401Missing, invalid or expired API key. Codes:API_KEY_MISSING,API_KEY_INVALID,API_KEY_EXPIRED.Error403Authenticated but not allowed. Codes:FEATURE_NOT_ENABLED(reserved feature not enabled for the customer),IP_NOT_ALLOWED(the key is restricted to other addresses),ACCOUNT_INACTIVE,CUSTOMER_OUT_OF_SCOPE.Error404The resource does not exist or is not visible to the caller. Codes:NOT_FOUNDand resource-specific ones (SHIPMENT_NOT_FOUND,QUOTATION_NOT_FOUND,CUSTOMER_NOT_FOUND, ...). Resources of other customers are reported as not found.Error409State conflict. Codes:OFFER_ALREADY_ORDERED,CUSTOMER_ALREADY_EXISTS(email or tax code already registered),INVITATION_ALREADY_ACCEPTED,IDEMPOTENCY_KEY_IN_USE.Error410Version retired. CodeVERSION_RETIRED.Error422The request is well formed but a business rule refuses it. Codes:INSUFFICIENT_CREDIT,SERVICE_NOT_AVAILABLE,CARRIER_NOT_AVAILABLE,IDEMPOTENCY_KEY_REUSED, ...Error429Daily or burst limit exceeded. CodeDAILY_LIMIT_EXCEEDEDorRATE_LIMIT_EXCEEDED. WaitRetry-Afterseconds.Error500Unexpected error. CodeSERVER_ERROR;details.correlation_idrepeats the correlation id.Error502The carrier or an internal dependency failed. CodeUPSTREAM_ERROR. Safe to retry reads; retry writes with the sameIdempotency-Key.Error
Request
Loading...
Direct purchase with customs data
{
"carrier_code": "SDAM",
"shipment_type": "EXPORT",
"goods_type": "GOODS",
"content_description": "Various goods",
"client_reference": "CLIENT-REF-0001",
"packages": [
{
"quantity": 1,
"total_weight_kg": 1,
"length_cm": 22,
"width_cm": 20,
"height_cm": 24
}
],
"services": {
"cash_on_delivery": {
"amount": 1000,
"payment_method": "CASH"
},
"insurance": {
"amount": 500
}
},
"sender": {
"name": "Test Sender",
"address": "Via Esempio 1",
"postal_code": "00175",
"city": "Roma",
"province": "RM",
"country_code": "IT",
"email": "sender@example.com",
"mobile": "0000000001",
"contact_name": "Test Sender",
"tax_code": "AAAAAA00A00A000A"
},
"recipient": {
"name": "Test Recipient",
"address": "Via Esempio 2",
"postal_code": "10001",
"city": "New York",
"province": "--",
"country_code": "US",
"email": "recipient@example.com",
"mobile": "0000000002",
"state_code": "NY"
},
"customs": {
"items": [
{
"hs_code": "3004.90.10",
"description": "Generic medicine",
"quantity": 2,
"value": 15,
"weight_kg": 0.1,
"export_reason": "SALE"
}
]
},
"label": {
"format": "A4",
"inline": true
}
}Response 201
{
"id": "1234567",
"status": "PROCESSING",
"livemode": true,
"offer_code": "offer_example_0001",
"client_reference": "REF-0001",
"customer_notes": "Test purchase",
"content_description": "Biscuits",
"customer_id": null,
"carrier": {
"code": "SDAM",
"family": "SDA",
"name": "SDA",
"logo_url": "https://assets.example.com/carriers/sda.png"
},
"delivery_type": "ECONOMY",
"shipment_type": "DOMESTIC",
"goods_type": "GOODS",
"waybill_status": "READY",
"waybill_number": "EX0000000002",
"child_waybill_numbers": [],
"tracking_url": "https://tracking.example.com/EX0000000002",
"sender": {
"name": "Test Sender",
"address": "Via Esempio 1",
"postal_code": "00175",
"city": "Roma",
"province": "RM",
"country_code": "IT",
"email": "sender@example.com",
"mobile": "0000000001"
},
"recipient": {
"name": "Test Recipient",
"address": "Via Esempio 2",
"postal_code": "20121",
"city": "Milano",
"province": "MI",
"country_code": "IT",
"email": "recipient@example.com",
"mobile": "0000000002"
},
"packages": [
{
"quantity": 1,
"total_weight_kg": 3,
"length_cm": 20,
"width_cm": 30,
"height_cm": 15
}
],
"services": {
"advanced_tracking": true
},
"pickup": {
"requested": true,
"status": "BOOKED",
"booking_code": "PK0000000001",
"message": null
},
"price": {
"list_price": {
"amount": "10.62",
"currency": "EUR"
},
"total": {
"amount": "6.90",
"currency": "EUR"
},
"vat_rate": 22
},
"documents": {
"waybill_url": "https://files.example.com/waybills/EX0000000002.pdf",
"manifest_url": "https://files.example.com/manifests/EX0000000002.pdf",
"expires_at": "2026-12-09T10:35:12+00:00"
},
"created_at": "2026-12-09T09:35:12+00:00"
}List shipments
Coming soon The contract is published ahead of the implementation. This operation is not available yet and its shape may still change.
Lists your shipments, newest first. Without dates it returns today's. Use offer_code, client_reference or waybill_number to find a single shipment (the legacy getorder).
Authentication: your API key in the X-API-Key header.
Parameters
- Name
created_from- Type
- string (date)
- Description
First day (inclusive),
YYYY-MM-DD. Default: today.
- Name
created_to- Type
- string (date)
- Description
Last day (inclusive),
YYYY-MM-DD. Default: today.
- Name
customer_id- Type
- string
- Description
Only shipments of this customer of your network.
- Name
offer_code- Type
- string
- Description
Find by offer code.
- Name
client_reference- Type
- string
- Description
Find by your reference.
- Name
waybill_number- Type
- string
- Description
Find by waybill.
- Name
status- Type
- array of string
- Description
Filter by status (repeat or comma-separate).
- Name
page- Type
- integer
- Description
Page number, starting at 1.
Default:
1. ≥ 1.
- Name
per_page- Type
- integer
- Description
Items per page, 1 to 100.
Default:
15. ≥ 1, ≤ 100.
Responses
200A page of shipments.ShipmentList400Malformed or invalid request. Codes:VALIDATION_ERROR(withdetails.errors),INVALID_JSON,IDEMPOTENCY_KEY_REQUIRED,UNSUPPORTED_VERSION.Error401Missing, invalid or expired API key. Codes:API_KEY_MISSING,API_KEY_INVALID,API_KEY_EXPIRED.Error403Authenticated but not allowed. Codes:FEATURE_NOT_ENABLED(reserved feature not enabled for the customer),IP_NOT_ALLOWED(the key is restricted to other addresses),ACCOUNT_INACTIVE,CUSTOMER_OUT_OF_SCOPE.Error410Version retired. CodeVERSION_RETIRED.Error429Daily or burst limit exceeded. CodeDAILY_LIMIT_EXCEEDEDorRATE_LIMIT_EXCEEDED. WaitRetry-Afterseconds.Error500Unexpected error. CodeSERVER_ERROR;details.correlation_idrepeats the correlation id.Error502The carrier or an internal dependency failed. CodeUPSTREAM_ERROR. Safe to retry reads; retry writes with the sameIdempotency-Key.Error
Request
Loading...
Response 200
{
"data": [
{
"id": "1234567",
"status": "PROCESSING",
"livemode": true,
"offer_code": "offer_example_0001",
"client_reference": "REF-0001",
"customer_notes": "Test purchase",
"content_description": "Biscuits",
"customer_id": null,
"carrier": {
"code": "SDAM",
"family": "SDA",
"name": "SDA",
"logo_url": "https://assets.example.com/carriers/sda.png"
},
"delivery_type": "ECONOMY",
"shipment_type": "DOMESTIC",
"goods_type": "GOODS",
"waybill_status": "READY",
"waybill_number": "EX0000000002",
"child_waybill_numbers": [],
"tracking_url": "https://tracking.example.com/EX0000000002",
"sender": {
"name": "Test Sender",
"address": "Via Esempio 1",
"postal_code": "00175",
"city": "Roma",
"province": "RM",
"country_code": "IT",
"email": "sender@example.com",
"mobile": "0000000001"
},
"recipient": {
"name": "Test Recipient",
"address": "Via Esempio 2",
"postal_code": "20121",
"city": "Milano",
"province": "MI",
"country_code": "IT",
"email": "recipient@example.com",
"mobile": "0000000002"
},
"packages": [
{
"quantity": 1,
"total_weight_kg": 3,
"length_cm": 20,
"width_cm": 30,
"height_cm": 15
}
],
"services": {
"advanced_tracking": true
},
"pickup": {
"requested": true,
"status": "BOOKED",
"booking_code": "PK0000000001",
"message": null
},
"price": {
"list_price": {
"amount": "10.62",
"currency": "EUR"
},
"total": {
"amount": "6.90",
"currency": "EUR"
},
"vat_rate": 22
},
"documents": {
"waybill_url": "https://files.example.com/waybills/EX0000000002.pdf",
"manifest_url": "https://files.example.com/manifests/EX0000000002.pdf",
"expires_at": "2026-12-09T10:35:12+00:00"
},
"created_at": "2026-12-09T09:35:12+00:00"
}
],
"meta": {
"total": 38,
"page": 1,
"per_page": 15
}
}Get a shipment
Coming soon The contract is published ahead of the implementation. This operation is not available yet and its shape may still change.
Returns one shipment with sender, recipient, packages, services, price and document links.
Authentication: your API key in the X-API-Key header.
Parameters
- Name
shipment_id- Type
- string
- required
- Description
Shipment id.
Responses
200The shipment.Shipment401Missing, invalid or expired API key. Codes:API_KEY_MISSING,API_KEY_INVALID,API_KEY_EXPIRED.Error403Authenticated but not allowed. Codes:FEATURE_NOT_ENABLED(reserved feature not enabled for the customer),IP_NOT_ALLOWED(the key is restricted to other addresses),ACCOUNT_INACTIVE,CUSTOMER_OUT_OF_SCOPE.Error404The resource does not exist or is not visible to the caller. Codes:NOT_FOUNDand resource-specific ones (SHIPMENT_NOT_FOUND,QUOTATION_NOT_FOUND,CUSTOMER_NOT_FOUND, ...). Resources of other customers are reported as not found.Error410Version retired. CodeVERSION_RETIRED.Error429Daily or burst limit exceeded. CodeDAILY_LIMIT_EXCEEDEDorRATE_LIMIT_EXCEEDED. WaitRetry-Afterseconds.Error500Unexpected error. CodeSERVER_ERROR;details.correlation_idrepeats the correlation id.Error502The carrier or an internal dependency failed. CodeUPSTREAM_ERROR. Safe to retry reads; retry writes with the sameIdempotency-Key.Error
Request
Loading...
Response 200
{
"id": "1234567",
"status": "PROCESSING",
"livemode": true,
"offer_code": "offer_example_0001",
"client_reference": "REF-0001",
"customer_notes": "Test purchase",
"content_description": "Biscuits",
"customer_id": null,
"carrier": {
"code": "SDAM",
"family": "SDA",
"name": "SDA",
"logo_url": "https://assets.example.com/carriers/sda.png"
},
"delivery_type": "ECONOMY",
"shipment_type": "DOMESTIC",
"goods_type": "GOODS",
"waybill_status": "READY",
"waybill_number": "EX0000000002",
"child_waybill_numbers": [],
"tracking_url": "https://tracking.example.com/EX0000000002",
"sender": {
"name": "Test Sender",
"address": "Via Esempio 1",
"postal_code": "00175",
"city": "Roma",
"province": "RM",
"country_code": "IT",
"email": "sender@example.com",
"mobile": "0000000001"
},
"recipient": {
"name": "Test Recipient",
"address": "Via Esempio 2",
"postal_code": "20121",
"city": "Milano",
"province": "MI",
"country_code": "IT",
"email": "recipient@example.com",
"mobile": "0000000002"
},
"packages": [
{
"quantity": 1,
"total_weight_kg": 3,
"length_cm": 20,
"width_cm": 30,
"height_cm": 15
}
],
"services": {
"advanced_tracking": true
},
"pickup": {
"requested": true,
"status": "BOOKED",
"booking_code": "PK0000000001",
"message": null
},
"price": {
"list_price": {
"amount": "10.62",
"currency": "EUR"
},
"total": {
"amount": "6.90",
"currency": "EUR"
},
"vat_rate": 22
},
"documents": {
"waybill_url": "https://files.example.com/waybills/EX0000000002.pdf",
"manifest_url": "https://files.example.com/manifests/EX0000000002.pdf",
"expires_at": "2026-12-09T10:35:12+00:00"
},
"created_at": "2026-12-09T09:35:12+00:00"
}Get the waybill of a shipment
Coming soon The contract is published ahead of the implementation. This operation is not available yet and its shape may still change.
Returns the waybill (LDV) number and links. Add include_content to get the PDF base64 encoded and include_parcels for the single parcel waybills of multi-parcel shipments. The waybill and manifest links are signed and valid for one hour (expires_at), like the links in documents: they are not static file URLs.
Authentication: your API key in the X-API-Key header.
Parameters
- Name
shipment_id- Type
- string
- required
- Description
Shipment id.
- Name
include_content- Type
- boolean
- Description
Return the waybill PDF base64 encoded.
Default:
false.
- Name
include_parcels- Type
- boolean
- Description
Return the single parcel waybills base64 encoded.
Default:
false.
Responses
200The waybill.Waybill401Missing, invalid or expired API key. Codes:API_KEY_MISSING,API_KEY_INVALID,API_KEY_EXPIRED.Error403Authenticated but not allowed. Codes:FEATURE_NOT_ENABLED(reserved feature not enabled for the customer),IP_NOT_ALLOWED(the key is restricted to other addresses),ACCOUNT_INACTIVE,CUSTOMER_OUT_OF_SCOPE.Error404The resource does not exist or is not visible to the caller. Codes:NOT_FOUNDand resource-specific ones (SHIPMENT_NOT_FOUND,QUOTATION_NOT_FOUND,CUSTOMER_NOT_FOUND, ...). Resources of other customers are reported as not found.Error410Version retired. CodeVERSION_RETIRED.Error429Daily or burst limit exceeded. CodeDAILY_LIMIT_EXCEEDEDorRATE_LIMIT_EXCEEDED. WaitRetry-Afterseconds.Error500Unexpected error. CodeSERVER_ERROR;details.correlation_idrepeats the correlation id.Error502The carrier or an internal dependency failed. CodeUPSTREAM_ERROR. Safe to retry reads; retry writes with the sameIdempotency-Key.Error
Request
Loading...
Response 200
{
"shipment_id": "1234567",
"client_reference": "REF-0002",
"waybill_number": "EX0000000003",
"waybill_url": "https://files.example.com/waybills/EX0000000003.pdf",
"manifest_url": "https://files.example.com/manifests/EX0000000003.pdf",
"pickup_code": "PK0000000001",
"expires_at": "2026-12-09T10:35:12+00:00"
}Models
Objects used by the requests and responses on this page.
ShipmentFromOffer
Buy a quoted offer. Postal data and packages come from the quotation; send the names, street addresses and contacts. Legacy order.
- Name
offer_code- Type
- string
- required
- Italian alias:
codice_offerta - Description
Offer to buy, from a previous
POST /quotations. An offer can be ordered once.
- Name
client_reference- Type
- string
- Italian alias:
custom - Description
Your own reference for the shipment. Returned in the response and by webhooks; filterable. Not unique: use
Idempotency-Keyto deduplicate.length ≤ 64.
- Name
customer_notes- Type
- string
- Italian alias:
note_cliente - Description
Note visible to you on the order.
- Name
customer_id- Type
- string
- Italian alias:
idcustomer - Description
Customer in your network the shipment is bought for.
- Name
coupon_code- Type
- string
- Italian alias:
coupon - Description
Discount coupon. Check it first with
POST /coupon-checks.
- Name
sender- Type
- Party
- required
- Italian alias:
mittente - Description
Sender.
- Name
recipient- Type
- Party
- required
- Italian alias:
destinatario - Description
Recipient.
- Name
services- Type
- Services
- Italian alias:
accessori - Description
Services to buy.
- Name
pickup- Type
- Pickup
- Italian alias:
ritiro - Description
Courier pickup.
- Name
customs- Type
- Customs
- Italian alias:
dogana - Description
Customs data for international shipments.
- Name
label- Type
- LabelOptions
- Italian alias:
etichetta - Description
Label options.
Party
Sender or recipient of a shipment.
- Name
name- Type
- string
- required
- Italian alias:
nominativo - Description
Person or company name.
- Name
contact_name- Type
- string
- Italian alias:
contatto - Description
Contact person, if different from
name.
- Name
address- Type
- string
- required
- Italian alias:
indirizzo - Description
Street and house number.
- Name
postal_code- Type
- string
- required
- Italian alias:
cap - Description
Postal code.
- Name
city- Type
- string
- required
- Italian alias:
localita - Description
City or town.
- Name
province- Type
- string
- Italian alias:
provincia - Description
Italian province code. Use
--for foreign addresses.
- Name
state_code- Type
- string
- Italian alias:
codice_stato - Description
State or province code, required for US and CA.
- Name
country_code- Type
- string
- required
- Italian alias:
nazione - Description
ISO 3166-1 alpha-2 country code.
- Name
email- Type
- string (email)
- Italian alias:
email - Description
Email address. Trimmed and lower-cased by the server.
- Name
phone- Type
- string
- Italian alias:
telefono - Description
Landline phone number.
- Name
mobile- Type
- string
- Italian alias:
cellulare - Description
Mobile phone number.
- Name
tax_code- Type
- string
- Italian alias:
codicefiscale - Description
Tax code or VAT number.
- Name
service_point_code- Type
- string
- Italian alias:
codice_punto - Description
Code of a service point (PUDO) from
GET /service-points. Onrecipient: deliver there. Onsender: drop-off point, or origin of a reverse shipment.
Services
Optional services. Availability and price depend on the carrier; an unavailable service is refused with SERVICE_NOT_AVAILABLE.
- Name
cash_on_delivery- Type
- object
- Italian alias:
contrassegno - Description
Cash on delivery. Presence of the object requests the service; omit it to not buy it.
- Name
insurance- Type
- object
- Italian alias:
assicurazione - Description
Insurance. Presence requests the service.
- Name
floor_delivery- Type
- boolean
- Italian alias:
consegnaalpiano - Description
Delivery to the floor.
- Name
appointment_delivery- Type
- boolean
- Italian alias:
consegnasuappuntamento - Description
Delivery by appointment.
- Name
prior_notice- Type
- boolean
- Italian alias:
priornotice - Description
Prior notice. QUESTION FOR CLAUDIO: the legacy docs disagree (quotation/order: FDA prior notice for the USA only; order-fast: prior phone notice). Keep one meaning.
- Name
advanced_tracking- Type
- boolean
- Italian alias:
trackingavanzato - Description
Advanced tracking.
- Name
assigned_port- Type
- boolean
- Italian alias:
porto_assegnato - Description
Assigned port: charges paid by the recipient.
- Name
reverse- Type
- boolean
- Italian alias:
reso - Description
Reverse shipment (return).
- Name
paperless- Type
- boolean
- Italian alias:
paperless - Description
No printed label: QR code only. Forces the label format to
A4.
MoneyAmount
Amount in EUR sent in a request, as a JSON number with a dot as decimal separator (never a comma). Up to two decimals.
Pickup
Courier pickup request.
- Name
requested- Type
- boolean
- required
- Italian alias:
prenotazione - Description
Book a courier pickup. Must be requested together with the shipment; it cannot be added later. Not available from service points: send
false.
- Name
location- Type
- string
- Italian alias:
ritirodove - Description
Where the courier collects.
Allowed values:
SENDER,SERVICE_POINT. Default:SENDER.
- Name
address- Type
- Party
- Italian alias:
indirizzo_ritiro - Description
Pickup address when it differs from
sender.
- Name
available_from- Type
- string (date)
- Italian alias:
disponibile_dal - Description
Date from which the goods are available.
- Name
available_time- Type
- string
- Italian alias:
disponibile_ora - Description
Time from which the goods are available (HH:MM, Europe/Rome).
- Name
time_slot- Type
- string
- Italian alias:
fascia - Description
Coarse slot (order-direct style).
Allowed values:
ALL_DAY,MORNING,AFTERNOON.
- Name
morning_from- Type
- string
- Italian alias:
ritiro_mattina_dalle - Description
Morning window start (HH:MM).
- Name
morning_to- Type
- string
- Italian alias:
ritiro_mattina_alle - Description
Morning window end (HH:MM).
- Name
afternoon_from- Type
- string
- Italian alias:
ritiro_pomeriggio_dalle - Description
Afternoon window start (HH:MM).
- Name
afternoon_to- Type
- string
- Italian alias:
ritiro_pomeriggio_alle - Description
Afternoon window end (HH:MM).
- Name
notes- Type
- string
- Italian alias:
note - Description
Notes for the courier.
Customs
Customs data for international shipments.
- Name
items- Type
- array of CustomsItem
- Italian alias:
hscodes - Description
Goods declared. Required for destinations with customs (non-EU).
- Name
documents- Type
- array of CustomsDocument
- Italian alias:
documenti - Description
Customs documents.
CustomsItem
- Name
hs_code- Type
- string
- required
- Italian alias:
hscode - Description
HS or TARIC code, 6 to 10 digits, dots allowed. The first 6 digits are validated against the WCO database. Find one with
GET /tariff-codes.
- Name
description- Type
- string
- required
- Italian alias:
descrizione - Description
Description of the goods.
- Name
quantity- Type
- integer
- required
- Italian alias:
quantita - Description
Number of items.
≥ 1.
- Name
value- Type
- MoneyAmount
- required
- Italian alias:
importo - Description
Value of the goods in EUR (line total).
- Name
weight_kg- Type
- number
- required
- Italian alias:
peso - Description
Weight of the goods in kg.
> 0.
- Name
export_reason- Type
- string
- required
- Italian alias:
motivo_esportazione - Description
Reason for export.
Allowed values:
SALE,GIFT,SAMPLE,RETURN,REPAIR,PERSONAL_EFFECTS.
CustomsDocument
- Name
type- Type
- string
- required
- Italian alias:
tipo_documento - Description
Document type.
EXTRAcan be repeated. For UPS and DHL the documents are attached to the shipment automatically (paperless).Allowed values:
EXPORT_DECLARATION,PROFORMA_INVOICE,COMMERCIAL_INVOICE,EXTRA.
- Name
file_name- Type
- string
- Italian alias:
nome_file - Description
File name (useful for
EXTRA).
- Name
content_base64- Type
- string
- required
- Italian alias:
contenuto_base64 - Description
PDF content, base64 encoded, max 15 MB.
LabelOptions
How to produce the label.
- Name
format- Type
- string
- Italian alias:
formato - Description
Label format:
A4PDF,1011PDF 10x11 cm,ZPLthermal printers.Allowed values:
A4,1011,ZPL. Default:A4.
- Name
inline- Type
- boolean
- Italian alias:
incluso - Description
Return the label content in the response as
label.content_base64. Defaultfalse; fetch it later withGET /shipments/{shipment_id}/waybill.Default:
false.
- Name
printed_note- Type
- string
- Italian alias:
nota_stampata - Description
Note printed on the label, upper-cased by the server.
length ≤ 20.
- Name
print_reference_barcode- Type
- boolean
- Italian alias:
barcode_riferimento - Description
Print
client_referenceas a barcode on the label.
ShipmentDirect
Buy directly from a carrier without a prior quotation. Legacy order-fast, order-faster and order-direct. Order-Direct customers use direct carriers (for example PDB-P2H) and the services marked order-direct.
- Name
carrier_code- Type
- string
- required
- Italian alias:
vettore - Description
Carrier service code. Quotation, order and waybill happen in one call.
- Name
shipment_type- Type
- string
- required
- Italian alias:
tipo_spedizione - Description
Shipment direction.
Allowed values:
DOMESTIC,EXPORT,IMPORT.
- Name
goods_type- Type
- string
- required
- Italian alias:
cosa_spedire - Description
What is shipped.
Allowed values:
GOODS,DOCUMENTS,PALLETS.
- Name
content_description- Type
- string
- required
- Italian alias:
contenuto - Description
Description of the contents.
- Name
packages- Type
- array of Package
- required
- Italian alias:
colli - Description
Packages.
items ≥ 1.
- Name
client_reference- Type
- string
- Italian alias:
custom - Description
Your own reference for the shipment. Returned in the response and by webhooks; filterable. Not unique: use
Idempotency-Keyto deduplicate.length ≤ 64.
- Name
customer_notes- Type
- string
- Italian alias:
note_cliente - Description
Note visible to you on the order.
- Name
customer_id- Type
- string
- Italian alias:
idcustomer - Description
Customer in your network the shipment is bought for.
- Name
coupon_code- Type
- string
- Italian alias:
coupon - Description
Discount coupon. Check it first with
POST /coupon-checks.
- Name
sender- Type
- Party
- required
- Italian alias:
mittente - Description
Sender.
- Name
recipient- Type
- Party
- required
- Italian alias:
destinatario - Description
Recipient.
- Name
services- Type
- Services
- Italian alias:
accessori - Description
Services to buy.
- Name
pickup- Type
- Pickup
- Italian alias:
ritiro - Description
Courier pickup.
- Name
customs- Type
- Customs
- Italian alias:
dogana - Description
Customs data for international shipments.
- Name
label- Type
- LabelOptions
- Italian alias:
etichetta - Description
Label options.
Package
A line of identical packages. For packages with different sizes or weights send several lines.
- Name
quantity- Type
- integer
- Italian alias:
nr_colli - Description
Number of identical packages in this line.
Default:
1. ≥ 1.
- Name
total_weight_kg- Type
- number
- required
- Italian alias:
peso - Description
TOTAL weight in kg of all packages in this line (not per package). Example: 3 packages of 5 kg each is
15.> 0.
- Name
length_cm- Type
- integer
- required
- Italian alias:
profondita - Description
Length of one package in cm (legacy
profondita/depth).≥ 1.
- Name
width_cm- Type
- integer
- required
- Italian alias:
larghezza - Description
Width of one package in cm.
≥ 1.
- Name
height_cm- Type
- integer
- required
- Italian alias:
altezza - Description
Height of one package in cm.
≥ 1.
ParceLabsVersion
CorrelationId
KeyLocale
Location
Postal location used to price a shipment.
- Name
postal_code- Type
- string
- required
- Italian alias:
cap - Description
Postal code.
- Name
city- Type
- string
- required
- Italian alias:
localita - Description
City or town.
- Name
province- Type
- string
- Italian alias:
provincia - Description
Italian province code. Use
--for foreign addresses.
- Name
state_code- Type
- string
- Italian alias:
codice_stato - Description
State or province code. Required for US and CA destinations, otherwise omit.
- Name
country_code- Type
- string
- required
- Italian alias:
nazione - Description
ISO 3166-1 alpha-2 country code.
IdempotentReplayed
Shipment
- Name
id- Type
- string
- required
- Italian alias:
id_ordine - Description
Shipment identifier (opaque string, currently the order id).
- Name
status- Type
- string
- required
- Italian alias:
stato - Description
Order status.
PROCESSING: paid, to be processed.ANOMALY: entered with anomalies.REFUND_REQUESTED: seePOST /refund-requests.Allowed values:
ANOMALY,PROCESSING,PROCESSED,ARCHIVED,REFUND_REQUESTED,CANCELLED.
- Name
livemode- Type
- boolean
- required
- Italian alias:
live - Description
falsefor a test key: nothing was charged.
- Name
offer_code- Type
- string · nullable
- Italian alias:
codice_offerta - Description
Offer the shipment was bought from.
- Name
client_reference- Type
- string · nullable
- Italian alias:
custom - Description
Your reference.
- Name
customer_notes- Type
- string · nullable
- Italian alias:
note_cliente - Description
Order note.
- Name
content_description- Type
- string · nullable
- Italian alias:
contenuto - Description
Contents.
- Name
customer_id- Type
- string · nullable
- Italian alias:
idcustomer - Description
Customer in your network.
- Name
carrier- Type
- Carrier
- required
- Italian alias:
corriere - Description
Carrier.
- Name
delivery_type- Type
- string · nullable
- Italian alias:
consegna - Description
Service level.
Allowed values:
ECONOMY,EXPRESS,null.
- Name
shipment_type- Type
- string
- Italian alias:
tipo_spedizione - Description
Direction.
Allowed values:
DOMESTIC,EXPORT,IMPORT.
- Name
goods_type- Type
- string
- Italian alias:
cosa_spedire - Description
Goods type.
Allowed values:
GOODS,DOCUMENTS,PALLETS.
- Name
waybill_status- Type
- string
- required
- Italian alias:
stato_ldv - Description
The waybill is generated asynchronously.
PENDING: retry later or wait for theshipment.waybill_readywebhook. The shipment exists anyway.Allowed values:
PENDING,READY.
- Name
waybill_number- Type
- string · nullable
- Italian alias:
lettera_vettura - Description
Carrier waybill (LDV) number, null while
PENDING.
- Name
child_waybill_numbers- Type
- array of string
- Italian alias:
ldv_figlie - Description
Waybills of the single parcels of a multi-parcel shipment.
- Name
tracking_url- Type
- string (uri) · nullable
- Italian alias:
url_tracking - Description
Public tracking link.
- Name
sender- Type
- Party
- Italian alias:
mittente - Description
Sender.
- Name
recipient- Type
- Party
- Italian alias:
destinatario - Description
Recipient.
- Name
packages- Type
- array of Package
- Italian alias:
colli - Description
Packages.
- Name
services- Type
- ServicesResult
- Italian alias:
accessori - Description
Services bought.
- Name
pickup- Type
- PickupResult
- Italian alias:
ritiro - Description
Pickup outcome.
- Name
price- Type
- object
- Italian alias:
prezzo - Description
What the shipment cost.
- Name
documents- Type
- object
- Italian alias:
documenti - Description
Document links.
- Name
label- Type
- LabelResult
- Italian alias:
etichetta - Description
Label content, present only when
label.inlinewas true.
- Name
created_at- Type
- string (date-time)
- required
- Italian alias:
data - Description
Creation time.
Carrier
- Name
code- Type
- string
- required
- Italian alias:
vettore - Description
Carrier service code, for example
SDAM,PDBT4,INPOST.
- Name
family- Type
- string
- Italian alias:
famiglia - Description
Carrier family, for example
SDA,PDB.
- Name
name- Type
- string
- Italian alias:
nome_vettore - Description
Display name.
- Name
logo_url- Type
- string (uri)
- Italian alias:
logo_vettore - Description
Logo image URL.
ServicesResult
Services bought, as returned in a response: amounts are Money objects.
- Name
cash_on_delivery- Type
- object
- Italian alias:
contrassegno - Description
Cash on delivery. Presence of the object requests the service; omit it to not buy it.
- Name
insurance- Type
- object
- Italian alias:
assicurazione - Description
Insurance. Presence requests the service.
- Name
floor_delivery- Type
- boolean
- Italian alias:
consegnaalpiano - Description
Delivery to the floor.
- Name
appointment_delivery- Type
- boolean
- Italian alias:
consegnasuappuntamento - Description
Delivery by appointment.
- Name
prior_notice- Type
- boolean
- Italian alias:
priornotice - Description
Prior notice. QUESTION FOR CLAUDIO: the legacy docs disagree (quotation/order: FDA prior notice for the USA only; order-fast: prior phone notice). Keep one meaning.
- Name
advanced_tracking- Type
- boolean
- Italian alias:
trackingavanzato - Description
Advanced tracking.
- Name
assigned_port- Type
- boolean
- Italian alias:
porto_assegnato - Description
Assigned port: charges paid by the recipient.
- Name
reverse- Type
- boolean
- Italian alias:
reso - Description
Reverse shipment (return).
- Name
paperless- Type
- boolean
- Italian alias:
paperless - Description
No printed label: QR code only. Forces the label format to
A4.
Money
An amount of money. Responses always use this object; requests send a plain number (see MoneyAmount).
- Name
amount- Type
- string
- required
- Italian alias:
importo - Description
Decimal amount as a string with exactly two decimals. Never a float.
- Name
currency- Type
- string
- required
- Italian alias:
valuta - Description
ISO 4217 currency. v1 is EUR only.
Allowed values:
EUR.
PickupResult
Pickup outcome with the requested window echoed.
- Name
requested- Type
- boolean
- required
- Italian alias:
prenotazione - Description
Whether a pickup was requested.
- Name
status- Type
- string
- required
- Italian alias:
stato - Description
PENDING: requested, booking code not available yet.Allowed values:
NOT_REQUESTED,PENDING,BOOKED,FAILED.
- Name
booking_code- Type
- string · nullable
- Italian alias:
codice_ritiro - Description
Pickup booking code, when booked.
- Name
message- Type
- string · nullable
- Italian alias:
messaggio - Description
Explanation when
statusisFAILED.
- Name
location- Type
- string
- Italian alias:
ritirodove - Description
Where the courier collects.
Allowed values:
SENDER,SERVICE_POINT. Default:SENDER.
- Name
available_from- Type
- string (date)
- Italian alias:
disponibile_dal - Description
Date from which the goods are available.
- Name
available_time- Type
- string
- Italian alias:
disponibile_ora - Description
Time from which the goods are available (HH:MM, Europe/Rome).
- Name
morning_from- Type
- string
- Italian alias:
ritiro_mattina_dalle - Description
Morning window start (HH:MM).
- Name
morning_to- Type
- string
- Italian alias:
ritiro_mattina_alle - Description
Morning window end (HH:MM).
- Name
afternoon_from- Type
- string
- Italian alias:
ritiro_pomeriggio_dalle - Description
Afternoon window start (HH:MM).
- Name
afternoon_to- Type
- string
- Italian alias:
ritiro_pomeriggio_alle - Description
Afternoon window end (HH:MM).
LabelResult
- Name
format- Type
- string
- required
- Italian alias:
formato - Description
Format of the content.
Allowed values:
A4,1011,ZPL.
- Name
content_base64- Type
- string
- required
- Italian alias:
ldv_base64 - Description
Label file, base64 encoded.
BadRequest
Unauthorized
Forbidden
NotFound
Conflict
Gone
Unprocessable
TooManyRequests
ServerError
BadGateway
ShipmentList
PageMeta
Pagination metadata.
- Name
total- Type
- integer
- required
- Description
Total number of items matching the filters.
- Name
page- Type
- integer
- required
- Description
Current page, starting at 1.
- Name
per_page- Type
- integer
- required
- Description
Items per page.
Waybill
- Name
shipment_id- Type
- string
- required
- Italian alias:
id_ordine - Description
Shipment identifier.
- Name
client_reference- Type
- string · nullable
- Italian alias:
custom - Description
Your reference.
- Name
waybill_number- Type
- string
- required
- Italian alias:
waybill_number - Description
Waybill (LDV) number.
- Name
waybill_url- Type
- string (uri)
- required
- Italian alias:
url_ldv - Description
Signed link to the waybill PDF, valid for one hour.
- Name
manifest_url- Type
- string (uri) · nullable
- Italian alias:
url_bordero - Description
Signed link to the pickup manifest PDF, valid for one hour.
- Name
expires_at- Type
- string (date-time) · nullable
- Italian alias:
scade_il - Description
When the links stop working.
- Name
pickup_code- Type
- string · nullable
- Italian alias:
pickup_code - Description
Pickup booking code.
- Name
content_base64- Type
- string
- Italian alias:
waybill_base64 - Description
Waybill PDF, base64 encoded. Only with
include_content=true.
- Name
parcel_waybills- Type
- array of object
- Italian alias:
single_waybills - Description
Single parcel waybills. Only with
include_parcels=true.
- Name
documents- Type
- array of object
- Italian alias:
documenti - Description
Attached customs documents.