Skip to main content
The cost calculation endpoint lets you simulate the delivery cost for a paper notification before committing to a send request. You supply the postal product, the destination geokey (CAP or foreign country code), and the document dimensions; Paper Channel looks up the applicable rate from the active tender and returns the cost in eurocents.
Base path: /paper-channel-private/v2Note that this endpoint is on v2, not v1. The path is /paper-channel-private/v2/tenders/{tenderId}/cost/calculate.This is an internal API. It is not exposed publicly and requires network-level access to the private Paper Channel service.

​
Calculate shipment cost

POST /paper-channel-private/v2/tenders/{tenderId}/cost/calculate Submit a cost simulation request. Paper Channel validates the input parameters, looks up the rate applicable to the given tenderId, product, and geokey, applies the page-weight model, and returns the calculated cost in eurocents.

​
Path parameters

​
tenderId
string
required
Identifier of the tender (contratto postale) whose rates to use for the calculation.
  • Minimum length: 5
  • Maximum length: 100

​
Request body

​
product
string
required
Postal product type.Allowed values:
  • AR — Raccomandata nazionale Andata e Ritorno
  • RS — Raccomandata nazionale Semplice
  • 890 — Recapito a norma della legge 890/1982
  • RIR — Raccomandata internazionale Andata e Ritorno
  • RIS — Raccomandata internazionale Semplice
Example: AR
​
geokey
string
required
Destination postal code (CAP) for domestic deliveries, or foreign country identifier for international deliveries.Example: 00184 (Rome, domestic), DE (Germany, international)
​
numSides
integer
required
Number of sides (faces) that make up the document. Used together with isReversePrinter to calculate the number of physical sheets and the resulting envelope weight.Example: 5
​
isReversePrinter
boolean
required
Set to true if the document is printed double-sided (fronte-retro). When true, every two sides produce one printed sheet, halving the sheet count compared to single-sided printing.
​
pageWeight
integer
Weight of a single sheet in grams. Used to calculate the total envelope weight when a precise weight model is required.Example: 15

​
Responses

StatusMeaning
200Calculation succeeded. Returns the cost in eurocents.
400Syntactic validation error in the request body.
404No tender found for the given tenderId.

​
200 response — ShipmentCalculateResponse

​
cost
integer
Calculated shipment cost in eurocents.Example: 350 (= €3.50)

​
How the cost is calculated

Paper Channel applies the following logic:
  1. Resolves the rate table for the given tenderId.
  2. Selects the rate row matching product and geokey.
  3. Calculates the number of printed sheets from numSides and isReversePrinter.
  4. Applies the pageWeight (or a default if omitted) to compute the envelope weight bracket.
  5. Looks up the cost for that weight bracket in the rate table.
The cost returned is a simulation based on the current tender configuration. The actual cost charged during a send request may differ if the tender rates change between simulation and send.
curl --request POST \
  --url https://api.paperchannel.pagopa.local/paper-channel-private/v2/tenders/TENDER-2024-001/cost/calculate \
  --header 'Content-Type: application/json' \
  --data '{
    "product": "AR",
    "geokey": "00184",
    "numSides": 6,
    "isReversePrinter": true,
    "pageWeight": 15
  }'

{
  "cost": 350
}

Build docs developers (and LLMs) love

Get started for freeTalk to us