Record a delivery cost receipt

Merchant server only, secret key with retention:view, retention:edit and settings:manage. Imports one provider invoice line for an attempted external delivery. Identify it by deliveryId or providerMessageId; if both are provided they must match. amountMinor is an integer string in currency minor units. Zero requires explicit cost evidence. Replaying an identical receipt is idempotent; changing a recorded amount or reusing its reference returns COST_RECEIPT_CONFLICT (400). Evidence is labelled MERCHANT_PROVIDER_RECEIPT, not an automatically verified provider bill. A delivery acknowledgement does not establish its cost. No currency conversion is performed. Missing costs remain pending and cached results update in the background. Limit120 requests/minute shared per project. The path id identifies the delivery; it need not be repeated in the body.

Authorization

ApiKeyAuth

AuthorizationBearer <token>

API Key authentication. Secret keys (sk_*) are required for all endpoints except /v1/track. Public keys (pk_*) only work with the /v1/track endpoint for client-side event tracking. The project is automatically derived from the key.

In: header

Path Parameters

id*string

Lengthlength <= 100

Request Body

application/json

receiptId*string

Length1 <= length <= 200

currency*string

Match^[A-Z]{3}$

amountMinor*string

Match^(0|[1-9]\d{0,13})$

providerMessageId?string

Length1 <= length <= 500

[key: string]?never

Response Body

`application/json`

curl -X POST "https://bitelio-api.heltia.com/v1/retention/messages/string/cost-receipt" \
  -H "Content-Type: application/json" \
  -d '{
    "receiptId": "invoice-2026-10:line-14",
    "currency": "EUR",
    "amountMinor": "7"
  }'

curl -X POST "https://bitelio-api.heltia.com/v1/retention/messages/string/cost-receipt" \  -H "Content-Type: application/json" \  -d '{    "receiptId": "invoice-2026-10:line-14",    "currency": "EUR",    "amountMinor": "7"  }'

{
  "deliveryId": "string",
  "recorded": true
}

Empty