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.

POST/shipments

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 marked order-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 422 IDEMPOTENCY_KEY_REUSED; while the first call is running, 409 IDEMPOTENCY_KEY_IN_USE. Keys expire after 24 hours. Missing: 400 IDEMPOTENCY_KEY_REQUIRED.

    length ≥ 1, length ≤ 255.

Request body ShipmentFromOffer | ShipmentDirect

The body must match one of the models in its type.

Responses

  • 201Shipment created.Shipment
  • 400Malformed or invalid request. Codes: VALIDATION_ERROR (with details.errors), INVALID_JSON, IDEMPOTENCY_KEY_REQUIRED, UNSUPPORTED_VERSION.Error
  • 401Missing, invalid or expired API key. Codes: API_KEY_MISSING, API_KEY_INVALID, API_KEY_EXPIRED.Error
  • 403Authenticated 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.Error
  • 404The resource does not exist or is not visible to the caller. Codes: NOT_FOUND and resource-specific ones (SHIPMENT_NOT_FOUND, QUOTATION_NOT_FOUND, CUSTOMER_NOT_FOUND, ...). Resources of other customers are reported as not found.Error
  • 409State conflict. Codes: OFFER_ALREADY_ORDERED, CUSTOMER_ALREADY_EXISTS (email or tax code already registered), INVITATION_ALREADY_ACCEPTED, IDEMPOTENCY_KEY_IN_USE.Error
  • 410Version retired. Code VERSION_RETIRED.Error
  • 422The request is well formed but a business rule refuses it. Codes: INSUFFICIENT_CREDIT, SERVICE_NOT_AVAILABLE, CARRIER_NOT_AVAILABLE, IDEMPOTENCY_KEY_REUSED, ...Error
  • 429Daily or burst limit exceeded. Code DAILY_LIMIT_EXCEEDED or RATE_LIMIT_EXCEEDED. Wait Retry-After seconds.Error
  • 500Unexpected error. Code SERVER_ERROR; details.correlation_id repeats the correlation id.Error
  • 502The carrier or an internal dependency failed. Code UPSTREAM_ERROR. Safe to retry reads; retry writes with the same Idempotency-Key.Error

Request

POST
/shipments
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"
}
GET/shipments

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.ShipmentList
  • 400Malformed or invalid request. Codes: VALIDATION_ERROR (with details.errors), INVALID_JSON, IDEMPOTENCY_KEY_REQUIRED, UNSUPPORTED_VERSION.Error
  • 401Missing, invalid or expired API key. Codes: API_KEY_MISSING, API_KEY_INVALID, API_KEY_EXPIRED.Error
  • 403Authenticated 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.Error
  • 410Version retired. Code VERSION_RETIRED.Error
  • 429Daily or burst limit exceeded. Code DAILY_LIMIT_EXCEEDED or RATE_LIMIT_EXCEEDED. Wait Retry-After seconds.Error
  • 500Unexpected error. Code SERVER_ERROR; details.correlation_id repeats the correlation id.Error
  • 502The carrier or an internal dependency failed. Code UPSTREAM_ERROR. Safe to retry reads; retry writes with the same Idempotency-Key.Error

Request

GET
/shipments
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/shipments/{shipment_id}

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.Shipment
  • 401Missing, invalid or expired API key. Codes: API_KEY_MISSING, API_KEY_INVALID, API_KEY_EXPIRED.Error
  • 403Authenticated 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.Error
  • 404The resource does not exist or is not visible to the caller. Codes: NOT_FOUND and resource-specific ones (SHIPMENT_NOT_FOUND, QUOTATION_NOT_FOUND, CUSTOMER_NOT_FOUND, ...). Resources of other customers are reported as not found.Error
  • 410Version retired. Code VERSION_RETIRED.Error
  • 429Daily or burst limit exceeded. Code DAILY_LIMIT_EXCEEDED or RATE_LIMIT_EXCEEDED. Wait Retry-After seconds.Error
  • 500Unexpected error. Code SERVER_ERROR; details.correlation_id repeats the correlation id.Error
  • 502The carrier or an internal dependency failed. Code UPSTREAM_ERROR. Safe to retry reads; retry writes with the same Idempotency-Key.Error

Request

GET
/shipments/{shipment_id}
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/shipments/{shipment_id}/waybill

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.Waybill
  • 401Missing, invalid or expired API key. Codes: API_KEY_MISSING, API_KEY_INVALID, API_KEY_EXPIRED.Error
  • 403Authenticated 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.Error
  • 404The resource does not exist or is not visible to the caller. Codes: NOT_FOUND and resource-specific ones (SHIPMENT_NOT_FOUND, QUOTATION_NOT_FOUND, CUSTOMER_NOT_FOUND, ...). Resources of other customers are reported as not found.Error
  • 410Version retired. Code VERSION_RETIRED.Error
  • 429Daily or burst limit exceeded. Code DAILY_LIMIT_EXCEEDED or RATE_LIMIT_EXCEEDED. Wait Retry-After seconds.Error
  • 500Unexpected error. Code SERVER_ERROR; details.correlation_id repeats the correlation id.Error
  • 502The carrier or an internal dependency failed. Code UPSTREAM_ERROR. Safe to retry reads; retry writes with the same Idempotency-Key.Error

Request

GET
/shipments/{shipment_id}/waybill
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-Key to 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. On recipient: deliver there. On sender: 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. EXTRA can 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: A4 PDF, 1011 PDF 10x11 cm, ZPL thermal 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. Default false; fetch it later with GET /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_reference as 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-Key to 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: see POST /refund-requests.

    Allowed values: ANOMALY, PROCESSING, PROCESSED, ARCHIVED, REFUND_REQUESTED, CANCELLED.

  • Name
    livemode
    Type
    boolean
    required
    Italian alias: live
    Description

    false for 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 the shipment.waybill_ready webhook. 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.inline was 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 status is FAILED.

  • 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

  • Name
    data
    Type
    array of Shipment
    required
    Description
  • Name
    meta
    Type
    PageMeta
    required
    Description

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.

Was this page helpful?