Delivery cost

Calculate delivery cost

post

https://api-stage.novapost.com/v.1.0https://api.novapost.com/v.1.0

/shipments/calculations

This API method allows you to calculate the estimated delivery cost and delivery time for your cargo. The delivery cost and delivery time are calculated based on factors such as weight, dimensions, destination, and shipping method. By providing the necessary details of your cargo and shipment, you can obtain an estimated cost for delivering the goods. The response will typically include the calculated cost and the scheduled delivery date based on the provided information.

🔹Description of control elements:

SCHEMA

Displays the full technical structure of the request or response, including field names, data types, required fields, allowed values, and validation rules.

• Single line description A description that fits into a single line; any text that does not fit remains hidden.

• Multiline description An expanded description that displays more than one line of text.

EXAMPLE

Shows a ready-made sample JSON with correctly formatted values to demonstrate how a valid request or response should look.

Authorizations

JWT

AuthorizationstringRequired

Authorization JWT-token with a lifetime of 1 hour in header

Body

application/json

payerTypestring · enumOptional

Identifies who is responsible for the payment of delivery services. The payer type determines which party bears the cost:

• Sender: The party sending the goods pays for the delivery.
• Recipient: The party receiving the goods is responsible for the delivery cost.
• ThirdPerson: A third party pays for delivery.
• For shipments within Europe or from Europe to Ukraine, the field payerContractNumber must be provided.
• For shipments from Ukraine, payerContractNumber is not required.

Example: SenderPossible values:

payerContractNumberstringOptional

Required when payerType is ThirdPerson for shipments within Europe or from Europe to Ukraine. Specifies the contract number of the third-party payer (e.g., CNPP-00001797).

Example: CNPP-00001797

deliveryTypesarray · enumOptional

Defines the list of tariff types to be used for shipment cost calculation. The calculation response returns pricing results for each submitted delivery type.

• standard: Standard international delivery tariff.
• economy: Economy international delivery tariff.
• express: Express international delivery tariff.

If the field is not provided, the applicable tariff is determined automatically according to current business rules, and the existing calculation behavior remains unchanged.

🔹This field is optional.

Possible values:

Responses

200

Successful cost calculation

application/json

scheduledDeliveryDatestring · date-time · nullableOptional

Estimated delivery date based on routing and service level, subject to change based on logistics and external factors. Date in ISO 8601 format.

Example: 2023-04-14T09:00:00Z

401

Unauthorized

application/json

404

The specified resource was not found

application/json

422

Validation error

application/json

503

Connection time-out

application/json

post

/shipments/calculations

HTTPcURLJavaScriptPython

POST /v.1.0/shipments/calculations HTTP/1.1
Host: api-stage.novapost.com/
Authorization: YOUR_API_KEY
Content-Type: application/json
Accept: */*
Content-Length: 522

{
  "payerType": "ThirdPerson",
  "payerContractNumber": "CNPP-00001797",
  "parcels": [
    {
      "cargoCategory": "parcel",
      "insuranceCost": 1.5,
      "rowNumber": 1,
      "width": 500,
      "length": 500,
      "height": 500,
      "actualWeight": 1000,
      "volumetricWeight": 1000
    }
  ],
  "sender": {
    "companyTin": "",
    "companyName": "",
    "countryCode": "PL",
    "divisionId": null,
    "addressParts": {
      "city": "Warsaw",
      "region": "Warszawa County",
      "street": "15 Sierpnia",
      "postCode": "000100",
      "building": "1",
      "flat": "",
      "block": "",
      "note": ""
    }
  },
  "recipient": {
    "countryCode": "CZ",
    "divisionId": 1834946,
    "addressParts": {}
  }
}

Example for shipments within Europe or from Europe to UkraineExample for shipments from Ukraine

{
  "scheduledDeliveryDate": "2023-04-14T09:00:00.000000Z",
  "sender": {
    "countryCode": "PL",
    "settlementId": null,
    "divisionId": null
  },
  "recipient": {
    "countryCode": "CZ",
    "settlementId": 142473,
    "divisionId": 1834946
  },
  "services": [
    {
      "shipmentId": null,
      "shipmentParcelRowNumber": null,
      "serviceId": "5637144594",
      "serviceType": "COD",
      "serviceName": "COD",
      "serviceCode": "COD",
      "amount": 1,
      "contractNumber": null,
      "payerType": "Recipient",
      "paymentStatus": "NeedPay",
      "divisionId": null,
      "price": 25,
      "discount": 0,
      "cost": 25,
      "user": "",
      "shipmentLockVersion": 1,
      "additionalParameters": {
        "cod": null,
        "date": null,
        "from": null,
        "to": null,
        "string": null,
        "fullName": null,
        "phone": null
      },
      "currencyCode": "PLN",
      "createdAt": null,
      "updatedAt": null,
      "deliveryType\"": "fe0a07b5-a212-11eb-94e4-b8830365bd14",
      "deliveryTypeName\"": "standard"
    },
    {
      "shipmentId": null,
      "shipmentParcelRowNumber": 1,
      "serviceId": "5637146076",
      "serviceType": "COD",
      "serviceName": "COD",
      "serviceCode": "COD",
      "amount": 1,
      "contractNumber": null,
      "payerType": "Recipient",
      "paymentStatus": "NeedPay",
      "divisionId": null,
      "price": 109.38,
      "discount": 0,
      "cost": 109.38,
      "user": "",
      "shipmentLockVersion": 1,
      "additionalParameters": {
        "cod": null,
        "date": null,
        "from": null,
        "to": null,
        "string": null,
        "fullName": null,
        "phone": null
      },
      "createdAt": null,
      "updatedAt": null,
      "deliveryType\"": "fe0a07b5-a212-11eb-94e4-b8830365bd14",
      "deliveryTypeName\"": "standard"
    }
  ]
}