# Delivery cost ## Calculate delivery cost > 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.
```json {"openapi":"3.0.0","info":{"title":"API Nova Post","version":"1.0.0"},"tags":[{"name":"Shipments"}],"servers":[{"description":"sandbox","url":"https://api-stage.novapost.pl/v.1.0/"},{"description":"production","url":"https://api.novapost.com/v.1.0/"}],"security":[{"JWT":[]}],"components":{"securitySchemes":{"JWT":{"type":"apiKey","in":"header","name":"Authorization","description":"Authorization JWT-token with a lifetime of 1 hour in header"}},"responses":{"Unauthorized":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"NotFound":{"description":"The specified resource was not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"Validation":{"description":"Validation error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"Time-out":{"description":"Connection time-out","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"schemas":{"Error":{"type":"object","properties":{"errors":{"type":"object","properties":{"":{"type":"string"}}}}}}},"paths":{"/shipments/calculations":{"post":{"tags":["Shipments"],"description":"This API method allows you to calculate the estimated delivery cost and delivery time for your cargo.\nThe delivery cost and delivery time are calculated based on factors such as weight, dimensions, destination, and shipping method.\nBy providing the necessary details of your cargo and shipment, you can obtain an estimated cost for delivering the goods.\nThe response will typically include the calculated cost and the scheduled delivery date based on the provided information.
\n\n🔹**Description of control elements:**\n\n**SCHEMA**
\nDisplays the full technical structure of the request or response, including field names, data types, required fields, allowed values, and validation rules.\n- **Single line description**
\n A description that fits into a single line; any text that does not fit remains hidden.\n- **Multiline description**
\n An expanded description that displays more than one line of text.\n\n**EXAMPLE**
\nShows a ready-made sample JSON with correctly formatted values to demonstrate how a valid request or response should look.\n","requestBody":{"description":"Optional description in *Markdown*","required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"payerType":{"type":"string","description":"Identifies who is responsible for the payment of delivery services. The payer type determines which party bears the cost:\n - `Sender`: The party sending the goods pays for the delivery.\n - `Recipient`: The party receiving the goods is responsible for the delivery cost.\n - `ThirdPerson`: A third party pays for delivery. \n - For shipments within Europe or from Europe to Ukraine, the field `payerContractNumber` must be provided. \n - For shipments from Ukraine, `payerContractNumber` is not required.\n","enum":["Sender","Recipient","ThirdPerson"]},"payerContractNumber":{"type":"string","description":"Required when `payerType` is `ThirdPerson` for shipments within Europe or from Europe to Ukraine. \nSpecifies the contract number of the third-party payer (e.g., `CNPP-00001797`).\n"},"deliveryTypes":{"type":"array","items":{"type":"string"},"description":"Defines the list of tariff types to be used for shipment cost calculation.\nThe calculation response returns pricing results for each submitted delivery type.\n\n - `standard`: Standard international delivery tariff.\n - `economy`: Economy international delivery tariff.\n - `express`: Express international delivery tariff.\n\nIf the field is not provided, the applicable tariff is determined automatically according to current business rules, and the existing calculation behavior remains unchanged.\n\n**🔹This field is optional.**\n","enum":["standard","economy","express"]},"invoice":{"type":"object","description":"Information for calculating shipping costs and customs payments.","properties":{"incoterm":{"type":"string","description":"Type of tax calculation.\n- `DAP` – Delivered At Place\n- `DDP` – Delivered Duty Paid\n","enum":["DAP","DDP"]},"currency":{"type":"string","description":"Currency code in ISO 4217 format (e.g., USD, EUR, GBP)."},"cost":{"type":"number","description":"Total declared invoice value in the original currency, which must equal the sum of all invoice items calculated as **(amount × cost)** for each item.\nDeclared value of the shipment used for customs duty calculation.\nAlso indicates the maximum compensation in case of loss or damage.\nRequired if incoterm = `DDP`.\n","minimum":1},"payerFeesCustoms":{"type":"string","description":"Identifies who is responsible for the customs payments.\nDetermines which party bears the cost: `Sender`, `Recipient`, or `ThirdPerson`.\n","enum":["Sender","Recipient","ThirdPerson"]}}},"parcels":{"type":"array","description":"An array of parcel objects, each representing a distinct package within the shipment. This parameter is essential for calculating the delivery cost as it includes details about each parcel's dimensions, weight, and other specific attributes. Each object in this array provides the necessary information to accurately assess shipping fees based on the parcel's size, weight, and possibly the type of goods it contains, which may affect the shipping method and pricing.","items":{"type":"object","properties":{"cargoCategory":{"type":"string","description":"Specifies the type of the shipment, helping to categorize the goods for logistics and customs processing. The category impacts how the shipment is handled, its shipping cost, and the required documentation. Available categories are:\n - parcel: Small to medium-sized packages, typically for consumer goods and retail items.\n - documents: Postal shipments containing documents such as letters, contracts, and official papers. This category is specifically for items that weigh no more than 1 kg and have dimensions not exceeding 35 cm in length, 25 cm in width, and 2 cm in height.\n","enum":["parcel","documents","pallet"]},"insuranceCost":{"type":"number","format":"float","description":"Represents the declared value of the shipment for insurance coverage, in the currency of the sender's country. This value indicates the maximum compensation amount in the event of damage or loss during transit. Setting this value appropriately is crucial for ensuring adequate insurance protection. It is important to accurately declare this value to match the actual worth of the shipment contents, as underdeclaring can result in insufficient compensation.\n","minimum":0,"exclusiveMinimum":true},"rowNumber":{"type":"integer","description":"Sequential identifier for each parcel within a shipment, used to organize and track individual packages, especially when multiple items are involved. If the shipment contains only one package, the value should be 1.","minimum":1},"width":{"type":"integer","description":"The parcel's width measured in millimeters, used alongside length and height to compute the total volume for logistical planning.","minimum":1},"length":{"type":"integer","description":"The parcel's length measured in millimeters, used alongside height and width to compute the total volume for logistical planning.","minimum":1},"height":{"type":"integer","description":"The parcel's height measured in millimeters, used alongside length and width to compute the total volume for logistical planning.","minimum":1},"actualWeight":{"type":"integer","description":"Actual total weight of all units of the item in grams (g), critical for shipping cost calculations and compliance with carrier weight limits.\nExpected unit: grams (g)\nOnly precision up to 10 grams (0.01 kg) is supported. Values not divisible by 10 g will be rounded down to the nearest lower multiple of 10 g.\n\n⚠️IMPORTANT: Please round weight values to the nearest 10 g before sending, to avoid unexpected adjustments.\n","minimum":1,"maximum":2147483647},"volumetricWeight":{"type":"integer","description":"Calculated weight based on parcel dimensions, used for billing purposes where volume impacts cost more than actual weight. Represents the dimensional weight of the parcel.","minimum":0,"maximum":2147483647}}}},"sender":{"type":"object","description":"Contains essential information about the party sending the shipment. The information provided here is used to manage the shipment's origin details for logistics planning and affect the calculation of shipping costs based on the sender's location and applicable shipping regulations. If the payer is the Sender and the shipment is from a Legal entity, the parameters \"companyTin\" and \"companyName\" are used to apply the counterparty's individual discount. If there's no applicable discount or it doesn't need to be considered, these parameters can be left blank or removed from the request.","properties":{"companyTin":{"type":"string","description":"The tax identification number or equivalent identifier (EDRPOU, TIN, NIP, IČO) of a legal entity. \n\n🔹**Required for legal and customs documentation when the sender is a legal entity.**\n","maxLength":20,"nullable":true},"companyName":{"type":"string","description":"The official name of the sender's company. This field is used when the sender is a business entity, helping to identify the sending organization in documentation and records. Insert \"Private person\" if the sender is not a company.","maxLength":100,"nullable":true},"countryCode":{"type":"string","description":"A two-letter code representing the sender's country, following the ISO 3166-1 Alpha-2 standard, indicating the country of origin for the shipment.","pattern":"^[A-Z]{2}$"},"divisionNumber":{"type":"string","description":"Optional identifier used to specify the unique number of the post office division or parcel locker from which the shipment is dispatched. It is relevant when the shipment originates from a specific postal division. This field is interchangeable with 'divisionId', and providing one of these identifiers is sufficient when the shipment originates from a division. Leave this field null when shipping from a non-division-specific address.","nullable":true},"divisionId":{"type":"integer","description":"Optional identifier representing the unique code for the post office division from which the shipment originates. This identifier is crucial when the shipment needs specific division handling at the origin. It can be used alternatively to 'divisionNumber'; providing just one of these identifiers is enough for identifying the dispatch division. This field should be left null if the shipment is from a direct address that is not associated with a specific division.","nullable":true},"addressParts":{"type":"object","description":"This array of fields is required when shipping directly from an address, detailing the specific components of the location from which the parcel is dispatched. It includes detailed address information, ensuring the accurate identification of the pickup location.","properties":{"city":{"type":"string","description":"The name of the city from which the shipment is dispatched. It helps pinpoint the exact urban location for pickup or shipping.","maxLength":100},"region":{"type":"string","description":"Specifies the broader administrative area, like a state or province, encompassing the city, providing additional context for the shipment's origin.","maxLength":100},"street":{"type":"string","description":"Identifies the specific street address for the sender's location, crucial for accurate pickup or delivery operations.","maxLength":100},"postCode":{"type":"string","description":"The postal or ZIP code corresponding to the sender's address. It's essential for sorting and routing the shipment efficiently.","maxLength":10},"building":{"type":"string","description":"The building number or name at the specified street address, pinpointing the precise location for shipment collection.","maxLength":100},"flat":{"type":"string","description":"If applicable, the apartment or suite number within a building from which the shipment originates, ensuring pickup personnel can locate the sender's exact unit.","maxLength":10},"block":{"type":"string","description":"Indicates a specific block or section within a larger residential area or complex, if relevant, aiding in locating the sender's precise starting point for the shipment.","maxLength":100,"nullable":true},"note":{"type":"string","description":"Allows for the inclusion of additional details or instructions about the sender's address that might facilitate the pickup process, such as gate codes, specific entry points, or preferred contact times.","maxLength":100}}}}},"recipient":{"type":"object","description":"Information about the party receiving the shipment, detailing either an individual or an organization responsible for receiving the dispatched goods.","properties":{"countryCode":{"type":"string","description":"A two-letter code that identifies the recipient's country, adhering to the ISO 3166-1 Alpha-2 standard, which specifies the shipment's destination country.","pattern":"^[A-Z]{2}$"},"divisionNumber":{"type":"string","description":"Optional identifier used to specify the unique number of the post office division or parcel locker where the shipment is to be collected. It is relevant when the shipment is routed to a specific postal division. This field is interchangeable with 'divisionId', and providing one of these identifiers is sufficient when the shipment is destined for a division. This field should be left null when the shipment is directly addressed to a non-division-specific location.","nullable":true},"divisionId":{"type":"integer","description":"Optional identifier representing the unique code for the post office division where the shipment is to be delivered. Like recipientDivisionNumber, this identifier is crucial when the shipment involves specific division handling at the destination. It can be used alternatively to 'divisionNumber'; providing just one of these identifiers is enough for identifying the receiving division. This field should also be left null if the shipment is to a direct address not associated with a specific division.","nullable":true},"addressParts":{"type":"object","description":"This array of fields is necessary when the shipment is directed to a specific address, outlining the precise location details to which the parcel is to be delivered. It encompasses comprehensive address information to ensure the exact identification of the delivery location.","properties":{"city":{"type":"string","description":"The city to which the shipment is being delivered. This detail ensures the parcel is directed to the correct urban area for the recipient.","maxLength":100},"region":{"type":"string","description":"Specifies the recipient's state or province within the destination country, crucial for accurate shipment routing and delivery. When sending to the USA, it's essential to include a two-letter state code, such as \"WA\" for Washington or \"DC\" for the District of Columbia, according to the ISO 3166-2:US standard.","maxLength":100},"street":{"type":"string","description":"The street name of the recipient's address, vital for pinpointing the exact delivery spot.","maxLength":100},"postCode":{"type":"string","description":"The postal or ZIP code for the recipient's address, critical for the precise sorting and routing of the parcel to its final destination.","maxLength":10},"building":{"type":"string","description":"Specifies the building number or name at the recipient's address, guiding the delivery to the exact building within a given street.","maxLength":100},"flat":{"type":"string","description":"The apartment or suite number, if the delivery is to a multi-unit building, ensuring the parcel reaches the specific unit of the recipient.","maxLength":10},"block":{"type":"string","description":"Identifies a block or section within a larger complex or residential area for the recipient, useful in large housing developments to further narrow down the delivery point.","maxLength":100,"nullable":true},"note":{"type":"string","description":"The space for any additional recipient-related address instructions or details that might assist in the delivery process, such as security instructions, specific doors for delivery, or preferred delivery times.","maxLength":100}}}}}}}}}},"responses":{"200":{"description":"Successful cost calculation","content":{"application/json":{"schema":{"type":"object","properties":{"scheduledDeliveryDate":{"type":"string","format":"date-time","description":"Estimated delivery date based on routing and service level, subject to change based on logistics and external factors. Date in ISO 8601 format.","nullable":true},"sender":{"type":"object","description":"Provides the sender's basic geographical information as part of the shipment's origin details in the response. This object outlines the sender’s country and may include additional location identifiers like settlement and division IDs if available.","properties":{"countryCode":{"type":"string","description":"A two-letter code representing the sender's country, following the ISO 3166-1 Alpha-2 standard, indicating the country of origin for the shipment.","pattern":"^[A-Z]{2}$"},"settlementId":{"type":"integer","description":"Identifier for the settlement (town or city) from which the shipment originates, if 'divisionId' was specified. If the sender's home address was specified, this field will be null.","nullable":true},"divisionId":{"type":"integer","description":"Unique identifier for the sender's division from which the shipment originates, which was specified. If the sender's home address was specified, this field will be null.","nullable":true}}},"recipient":{"type":"object","description":"Provides the recipient's basic geographical information as part of the shipment's delivery details in the response. This object outlines the recipient’s country and may include additional location identifiers like settlement and division IDs if available.","properties":{"countryCode":{"type":"string","description":"A two-letter code representing the recipient's country, following the ISO 3166-1 Alpha-2 standard, indicating the destination country of the shipment.","pattern":"^[A-Z]{2}$"},"settlementId":{"type":"integer","description":"Identifier for the settlement (town or city) to which the shipment is being sent if 'divisionId' was specified. If the recipient's home address was specified, this field will be null.","nullable":true},"divisionId":{"type":"integer","description":"Unique identifier for the recipient's division or branch, which was specified. If the recipient's home address was specified, this field will be null.","nullable":true}}},"services":{"type":"array","description":"A collection of services associated with the shipment, each entry detailing specific services applied or requested for the shipment. This objects encompasses various service details such as type of service, amount, and contractual details, along with any additional parameters that specify further service-related requirements or conditions.","items":{"type":"object","properties":{"shipmentId":{"type":"integer","description":"Unique identifier for the shipment that this service is part of. It helps in linking the service to the specific shipment within the system. This field may be null or zero if the service is being pre-configured or if the shipment has not yet been created or assigned in the system.","nullable":true},"shipmentParcelRowNumber":{"type":"string","description":"Identifies the parcel within a shipment to which the service is applied, helping in organizing and managing multiple parcels under a single shipment.","nullable":true},"serviceId":{"type":"string","description":"A unique identifier assigned to the specific service being described, essential for service tracking and management."},"serviceType":{"type":"string","description":"Service type.
\n**🔹This field is optional.**\n"},"serviceName":{"type":"string","description":"Service name.
\n**🔹This field is optional.**\n"},"serviceCode":{"type":"string","description":"Service code.
\n**🔹This field is optional.**\n"},"amount":{"type":"number","description":"Represents the total quantity of items or units included in this particular service.","minimum":0},"contractNumber":{"type":"string","description":"If applicable, the contract number under which the service is rendered. This is often used in B2B or B2C contexts where services are governed by specific contractual agreements.","minLength":2,"maxLength":20,"nullable":true},"payer_type":{"type":"string","description":"Indicates who is responsible for paying for the service. Typical values include 'Sender', 'Recipient', or 'Third Party'."},"paymentStatus":{"type":"string","description":"Payment status for the delivery services (e.g. 'Paid', 'NeedPay', 'ContractAfterPayment', 'FreeOfCharge', 'Holded')."},"divisionId":{"type":"string","description":"Unique identifier for the division or branch, if applicable.","nullable":true},"price":{"type":"number","description":"The cost associated with the service before any discounts.","minimum":0},"discount":{"type":"number","description":"Any discount applied to the service, reducing the overall cost.","minimum":0},"cost":{"type":"number","format":"float","description":"The total cost of the service after applying discounts.","minimum":0},"user":{"type":"string","description":"Specifies the type of user interacting with the service. For internal use.","maxLength":50},"shipmentLockVersion":{"type":"integer","description":"Version of the shipment data for concurrency control"},"additional_parameters":{"type":"object","description":"This object holds a variety of supplementary details that provide critical information for ensuring accurate processing and delivery of the shipment.","properties":{"cod":{"type":"number","description":"Cash on delivery amount, if applicable. This specifies the amount to be collected upon delivery, which is crucial for transactions requiring payment at the time of delivery.","nullable":true},"date":{"type":"integer","description":"The estimated date of delivery, calculated based on the logistics and routing information. If the route's delivery date cannot be calculated due to insufficient data in the chosen direction, this field may hold a zero value.","nullable":true},"from":{"type":"integer","description":"Represents the estimated start time of the delivery window. This field can be zero if there is not enough information to determine a starting time for the delivery.","nullable":true},"to":{"type":"integer","description":"Represents the estimated end time of the delivery window. Similar to the 'from' parameter, this field can also be zero if there is insufficient data to define an ending time for delivery.","nullable":true},"string":{"type":"integer","description":"Represents the cargo category as specified in the cargoCategory parameter. This can include values such as 'Parcel', 'Documents', 'Cargo', or 'Pallet' reflecting the type of items being shipped.","nullable":true},"fullName":{"type":"integer","description":"The full name of the recipient. This is used to ensure that the delivery is addressed to the correct individual, essential for verification upon delivery.","nullable":true},"phone":{"type":"integer","description":"The contact phone number of the recipient or the recipient’s company representative. Used for delivery notifications and communication with the customer during shipment processing.\n**Format:** The phone number must be provided in **international format** according to the **E.164** standard.\nExample: 380XXXXXXXXX, 491234567890, 371XXXXXXXX\n**Restrictions:**\n- For deliveries to Nova Post branches in Europe, Ukrainian mobile numbers are acceptable.\n- For deliveries to **partner locations** (such as InPost, GLS, Venipak, Cargus, etc.) and **cross-border address deliveries**, the phone number must belong to a mobile operator in the recipient's country. If the phone number is submitted in a local (non-international) format, the system will attempt to **normalize** it to the international format, but the internal algorithm does not cover all possible cases. If your system does not support front-end validation of phone numbers, we recommend informing us about failed phone number cases so we can assess potential improvements to the normalization logic.\n","nullable":true}}},"createdAt":{"type":"string","format":"date-time","description":"The date-time indicating when the record was initially created, formatted in ISO 8601 standard."},"updatedAt":{"type":"string","format":"date-time","description":"The date-time indicating the last update made to the record, formatted in ISO 8601 standard."},"deliveryType":{"type":"string","description":"Unique identifier (UUID) of the delivery tariff type used in the calculation result.\nThis value corresponds to the internal reference of the selected tariff.\n"},"deliveryTypeName":{"type":"string","description":"Code of the delivery tariff type applied to the calculation result.\n\n - `standard`: Standard international delivery tariff.\n - `economy`: Economy international delivery tariff.\n - `express`: Express international delivery tariff.\n"}}}}}}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"404":{"$ref":"#/components/responses/NotFound"},"422":{"$ref":"#/components/responses/Validation"},"503":{"$ref":"#/components/responses/Time-out"}},"summary":"Calculate delivery cost"}}}} ``` --- # Agent Instructions: Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter: ``` GET https://api-portal.novapost.com/metodi-1/methods/shipments/delivery-cost.md?ask= ``` The question should be specific, self-contained, and written in natural language. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.