Quotations

Price a shipment and get one offer per carrier. Every offer has an offer code that you order once with a shipment.

POST/quotations

Create a quotation

Coming soon The contract is published ahead of the implementation. This operation is not available yet and its shape may still change.

Prices a shipment across the carriers available to you and returns one offer per carrier. Every offer has an offer_code you can order once with POST /shipments. Offers are returned best price first.

Authentication: your API key in the X-API-Key header.

Parameters

  • Name
    Idempotency-Key
    Type
    string
    Description

    Optional idempotency key, same rules as on the other writes.

    length ≥ 1, length ≤ 255.

Request body QuotationCreate

  • Name
    shipment_type
    Type
    string
    required
    Italian alias: tipo_spedizione
    Description

    Direction of the shipment.

    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
    customer_id
    Type
    string
    Italian alias: idcustomer
    Description

    Customer in your network whose price list applies. Omit for your own.

  • Name
    services
    Type
    Services
    Italian alias: accessori
    Description

    Services to price (cash on delivery, insurance, floor delivery, ...).

  • Name
    packages
    Type
    array of Package
    required
    Italian alias: colli
    Description

    Packages.

    items ≥ 1.

  • Name
    sender
    Type
    Location
    required
    Italian alias: mittente
    Description

    Origin.

  • Name
    recipient
    Type
    Location
    required
    Italian alias: destinatario
    Description

    Destination.

Responses

  • 201Quotation created.Quotation
  • 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

POST
/quotations
Loading...

Response 201

{
  "id": "q_example_0001",
  "created_at": "2026-12-09T09:30:00+00:00",
  "livemode": true,
  "shipment_type": "DOMESTIC",
  "goods_type": "GOODS",
  "offers": [
    {
      "offer_code": "offer_example_0001",
      "carrier": {
        "code": "SDAM",
        "family": "SDA",
        "name": "SDA",
        "logo_url": "https://assets.example.com/carriers/sda.png"
      },
      "delivery_type": "ECONOMY",
      "transit_time": "24/48 hours",
      "rate_message": null,
      "list_price": {
        "amount": "10.62",
        "currency": "EUR"
      },
      "total": {
        "amount": "6.90",
        "currency": "EUR"
      },
      "vat_rate": 22,
      "volumetric_weight_kg": 3,
      "flags": {
        "national_discount": null,
        "remote_area": false,
        "outlying_area": false,
        "time_critical": false
      },
      "optional_services": {
        "cash_on_delivery": {
          "available": true,
          "fee": {
            "amount": "5.00",
            "currency": "EUR"
          },
          "max_amount": {
            "amount": "1999.99",
            "currency": "EUR"
          },
          "payment_methods": [
            "C",
            "A"
          ]
        },
        "insurance": {
          "available": true,
          "fee": {
            "amount": "7.70",
            "currency": "EUR"
          },
          "max_amount": {
            "amount": "3000.00",
            "currency": "EUR"
          },
          "simulated_value": {
            "amount": "500.00",
            "currency": "EUR"
          }
        },
        "pickup": {
          "available": true,
          "fee": {
            "amount": "0.00",
            "currency": "EUR"
          }
        }
      }
    }
  ]
}
GET/quotations/{quotation_id}

Get a quotation

Coming soon The contract is published ahead of the implementation. This operation is not available yet and its shape may still change.

Returns a quotation created earlier, with its offers. NEW capability: the legacy API had no read-back.

Authentication: your API key in the X-API-Key header.

Parameters

  • Name
    quotation_id
    Type
    string
    required
    Description

    Quotation id.

Responses

  • 200The quotation.Quotation
  • 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
  • 501Planned but not built yet. Code FEATURE_NOT_IMPLEMENTED.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
/quotations/{quotation_id}
Loading...

Response 200

{
  "id": "q_example_0001",
  "created_at": "2026-12-09T09:30:00+00:00",
  "livemode": true,
  "shipment_type": "DOMESTIC",
  "goods_type": "GOODS",
  "offers": [
    {
      "offer_code": "offer_example_0001",
      "carrier": {
        "code": "SDAM",
        "family": "SDA",
        "name": "SDA",
        "logo_url": "https://assets.example.com/carriers/sda.png"
      },
      "delivery_type": "ECONOMY",
      "transit_time": "24/48 hours",
      "rate_message": null,
      "list_price": {
        "amount": "10.62",
        "currency": "EUR"
      },
      "total": {
        "amount": "6.90",
        "currency": "EUR"
      },
      "vat_rate": 22,
      "volumetric_weight_kg": 3,
      "flags": {
        "national_discount": null,
        "remote_area": false,
        "outlying_area": false,
        "time_critical": false
      },
      "optional_services": {
        "cash_on_delivery": {
          "available": true,
          "fee": {
            "amount": "5.00",
            "currency": "EUR"
          },
          "max_amount": {
            "amount": "1999.99",
            "currency": "EUR"
          },
          "payment_methods": [
            "C",
            "A"
          ]
        },
        "insurance": {
          "available": true,
          "fee": {
            "amount": "7.70",
            "currency": "EUR"
          },
          "max_amount": {
            "amount": "3000.00",
            "currency": "EUR"
          },
          "simulated_value": {
            "amount": "500.00",
            "currency": "EUR"
          }
        },
        "pickup": {
          "available": true,
          "fee": {
            "amount": "0.00",
            "currency": "EUR"
          }
        }
      }
    }
  ]
}
POST/coupon-checks

Check a discount coupon

Coming soon The contract is published ahead of the implementation. This operation is not available yet and its shape may still change.

Checks whether a coupon applies to a shipment, without changing anything. It is a POST only because it carries a body. Check the coupon before putting it in POST /shipments as coupon_code.

Authentication: your API key in the X-API-Key header.

Request body CouponCheckCreate

  • Name
    customer_id
    Type
    string
    required
    Italian alias: idcustomer
    Description

    Customer who owns the coupon.

  • Name
    carrier_code
    Type
    string
    required
    Italian alias: vettore
    Description

    Carrier code.

  • Name
    total_weight_kg
    Type
    number
    required
    Italian alias: peso_totale
    Description

    Total weight of the shipment in kg.

  • 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
    province
    Type
    string
    required
    Italian alias: provincia
    Description

    Italian province of origin (of destination for imports).

  • Name
    country_code
    Type
    string
    required
    Italian alias: nazione
    Description

    Destination country (origin for imports).

  • Name
    coupon_code
    Type
    string
    required
    Italian alias: coupon
    Description

    Coupon code to check.

Responses

  • 200Check result. A coupon that does not apply is a normal valid: false answer, not an error.CouponCheck
  • 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

POST
/coupon-checks
Loading...

Response 200

{
  "valid": true,
  "message": "Discount of 5% applies"
}

Models

Objects used by the requests and responses on this page.

QuotationCreate

  • Name
    shipment_type
    Type
    string
    required
    Italian alias: tipo_spedizione
    Description

    Direction of the shipment.

    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
    customer_id
    Type
    string
    Italian alias: idcustomer
    Description

    Customer in your network whose price list applies. Omit for your own.

  • Name
    services
    Type
    Services
    Italian alias: accessori
    Description

    Services to price (cash on delivery, insurance, floor delivery, ...).

  • Name
    packages
    Type
    array of Package
    required
    Italian alias: colli
    Description

    Packages.

    items ≥ 1.

  • Name
    sender
    Type
    Location
    required
    Italian alias: mittente
    Description

    Origin.

  • Name
    recipient
    Type
    Location
    required
    Italian alias: destinatario
    Description

    Destination.

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.

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.

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.

ParceLabsVersion

CorrelationId

KeyLocale

IdempotentReplayed

Quotation

  • Name
    id
    Type
    string
    required
    Italian alias: id
    Description

    Quotation identifier.

  • Name
    created_at
    Type
    string (date-time)
    required
    Italian alias: creato_il
    Description

    Creation time.

  • Name
    livemode
    Type
    boolean
    Italian alias: live
    Description

    false for a test key.

  • Name
    shipment_type
    Type
    string
    Italian alias: tipo_spedizione
    Description

    Echo of the request.

    Allowed values: DOMESTIC, EXPORT, IMPORT.

  • Name
    goods_type
    Type
    string
    Italian alias: cosa_spedire
    Description

    Echo of the request.

    Allowed values: GOODS, DOCUMENTS, PALLETS.

  • Name
    offers
    Type
    array of Offer
    required
    Italian alias: quotation
    Description

    Offers from the carriers. Empty if no carrier can serve the route.

Offer

  • Name
    offer_code
    Type
    string
    required
    Italian alias: codice_offerta
    Description

    Code to order this offer with POST /shipments.

  • Name
    carrier
    Type
    Carrier
    required
    Italian alias: corriere
    Description

    Carrier of the offer.

  • Name
    delivery_type
    Type
    string
    Italian alias: consegna
    Description

    Service level. QUESTION FOR CLAUDIO: legacy consegna is E in the quotation example; confirm E/X meaning.

    Allowed values: ECONOMY, EXPRESS.

  • Name
    transit_time
    Type
    string
    Italian alias: tempiconsegna
    Description

    Indicative delivery time.

  • Name
    rate_message
    Type
    string · nullable
    Italian alias: messaggio_tariffa
    Description

    Message attached to the rate.

  • Name
    list_price
    Type
    Money
    Italian alias: importo_tariffa
    Description

    Price before discounts.

  • Name
    total
    Type
    Money
    required
    Italian alias: totale_dovuto
    Description

    Total due for the shipment. QUESTION FOR CLAUDIO: is it net or gross of VAT?

  • Name
    vat_rate
    Type
    number
    Italian alias: percentualeiva
    Description

    VAT rate in percent.

  • Name
    volumetric_weight_kg
    Type
    number
    Italian alias: peso_volumetrico
    Description

    Volumetric weight in kg.

  • Name
    flags
    Type
    object
    Italian alias: indicatori
    Description

    Rate flags.

  • Name
    optional_services
    Type
    OfferServices
    Italian alias: serviziopzionali
    Description

    Optional services.

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.

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.

OfferServices

Optional services this offer supports, with their price.

  • Name
    cash_on_delivery
    Type
    OptionalService
    Italian alias: contrassegno
    Description

    Cash on delivery.

  • Name
    insurance
    Type
    OptionalService
    Italian alias: assicurazione
    Description

    Insurance.

  • Name
    floor_delivery
    Type
    OptionalService
    Italian alias: consegnaalpiano
    Description

    Floor delivery.

  • Name
    appointment_delivery
    Type
    OptionalService
    Italian alias: consegnasuappuntamento
    Description

    Delivery by appointment.

  • Name
    advanced_tracking
    Type
    OptionalService
    Italian alias: trackingavanzato
    Description

    Advanced tracking.

  • Name
    pickup
    Type
    OptionalService
    Italian alias: ritiro
    Description

    Courier pickup.

OptionalService

  • Name
    available
    Type
    boolean
    required
    Italian alias: attivabile
    Description

    Whether the service can be bought with this offer.

  • Name
    fee
    Type
    Money
    Italian alias: importo
    Description

    Price of the service.

  • Name
    max_amount
    Type
    Money
    Italian alias: limite_massimo
    Description

    Maximum insured or collectable amount.

  • Name
    simulated_value
    Type
    Money
    Italian alias: valore_simulato
    Description

    Value used to simulate the price.

  • Name
    payment_methods
    Type
    array of string
    Italian alias: servizi
    Description

    Cash on delivery only: payment methods the carrier accepts. QUESTION FOR CLAUDIO: legacy returns C-A; confirm the meaning.

BadRequest

Unauthorized

Forbidden

Gone

TooManyRequests

ServerError

BadGateway

NotFound

NotImplemented

CouponCheckCreate

  • Name
    customer_id
    Type
    string
    required
    Italian alias: idcustomer
    Description

    Customer who owns the coupon.

  • Name
    carrier_code
    Type
    string
    required
    Italian alias: vettore
    Description

    Carrier code.

  • Name
    total_weight_kg
    Type
    number
    required
    Italian alias: peso_totale
    Description

    Total weight of the shipment in kg.

  • 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
    province
    Type
    string
    required
    Italian alias: provincia
    Description

    Italian province of origin (of destination for imports).

  • Name
    country_code
    Type
    string
    required
    Italian alias: nazione
    Description

    Destination country (origin for imports).

  • Name
    coupon_code
    Type
    string
    required
    Italian alias: coupon
    Description

    Coupon code to check.

CouponCheck

  • Name
    valid
    Type
    boolean
    required
    Italian alias: valido
    Description

    Whether the coupon applies to this shipment.

  • Name
    message
    Type
    string
    Italian alias: errordetails
    Description

    Discount description or the reason the coupon does not apply.

Was this page helpful?