Billing
Read your balance and your customers' balances, and move credit to a customer of your network. Your account must be enabled for the customer network; other accounts get 403 FEATURE_NOT_ENABLED.
Get your prepaid balance
Coming soon The contract is published ahead of the implementation. This operation is not available yet and its shape may still change.
Only for accounts enabled for the customer network. Other accounts get 403 FEATURE_NOT_ENABLED.
Remaining prepaid credit of your (master) account.
Needs the customer-network feature; without it the answer is 403 FEATURE_NOT_ENABLED. The page is public.
Authentication: your API key in the X-API-Key header.
Responses
200Balance.Balance401Missing, invalid or expired API key. Codes:API_KEY_MISSING,API_KEY_INVALID,API_KEY_EXPIRED.Error403Authenticated 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.Error410Version retired. CodeVERSION_RETIRED.Error429Daily or burst limit exceeded. CodeDAILY_LIMIT_EXCEEDEDorRATE_LIMIT_EXCEEDED. WaitRetry-Afterseconds.Error500Unexpected error. CodeSERVER_ERROR;details.correlation_idrepeats the correlation id.Error502The carrier or an internal dependency failed. CodeUPSTREAM_ERROR. Safe to retry reads; retry writes with the sameIdempotency-Key.Error
Request
Loading...
Response 200
{
"balance": {
"amount": "245.90",
"currency": "EUR"
}
}Get the balance of a customer
Coming soon The contract is published ahead of the implementation. This operation is not available yet and its shape may still change.
Only for accounts enabled for the customer network. Other accounts get 403 FEATURE_NOT_ENABLED.
Remaining prepaid credit of a customer of your network. 404 CUSTOMER_NOT_FOUND when the customer does not exist or is not in your network.
Needs the customer-network feature; without it the answer is 403 FEATURE_NOT_ENABLED. The page is public.
Authentication: your API key in the X-API-Key header.
Parameters
- Name
customer_id- Type
- string
- required
- Description
Customer id.
Responses
200Balance.CustomerBalance401Missing, invalid or expired API key. Codes:API_KEY_MISSING,API_KEY_INVALID,API_KEY_EXPIRED.Error403Authenticated 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.Error404The resource does not exist or is not visible to the caller. Codes:NOT_FOUNDand resource-specific ones (SHIPMENT_NOT_FOUND,QUOTATION_NOT_FOUND,CUSTOMER_NOT_FOUND, ...). Resources of other customers are reported as not found.Error410Version retired. CodeVERSION_RETIRED.Error429Daily or burst limit exceeded. CodeDAILY_LIMIT_EXCEEDEDorRATE_LIMIT_EXCEEDED. WaitRetry-Afterseconds.Error500Unexpected error. CodeSERVER_ERROR;details.correlation_idrepeats the correlation id.Error502The carrier or an internal dependency failed. CodeUPSTREAM_ERROR. Safe to retry reads; retry writes with the sameIdempotency-Key.Error
Request
Loading...
Response 200
{
"customer_id": "3723",
"balance": {
"amount": "23.75",
"currency": "EUR"
}
}Move credit to a customer
Coming soon The contract is published ahead of the implementation. This operation is not available yet and its shape may still change.
Only for accounts enabled for the customer network. Other accounts get 403 FEATURE_NOT_ENABLED.
Transfers prepaid credit from your master account to a customer of your network. The master credit must cover the amount, otherwise 422 INSUFFICIENT_CREDIT. Only for accounts with the network function. Your own top-up by card is a dashboard feature, not part of this API.
Needs the customer-network feature; without it the answer is 403 FEATURE_NOT_ENABLED. The page is public.
Authentication: your API key in the X-API-Key header.
Parameters
- Name
Idempotency-Key- Type
- string
- required
- Description
Unique key (UUID recommended, max 255 characters) that makes the write safe to retry. A retry with the same key and body returns the first response with
Idempotent-Replayed: true; same key with a different body is 422IDEMPOTENCY_KEY_REUSED; while the first call is running, 409IDEMPOTENCY_KEY_IN_USE. Keys expire after 24 hours. Missing: 400IDEMPOTENCY_KEY_REQUIRED.length ≥ 1, length ≤ 255.
Request body CreditTransferCreate
- Name
customer_id- Type
- string
- required
- Italian alias:
idcustomer - Description
Customer to credit; must belong to your network.
- Name
amount- Type
- MoneyAmount
- required
- Italian alias:
amount - Description
Amount to move from your master account. Must not exceed your master credit.
Responses
201Transfer done.CreditTransfer400Malformed or invalid request. Codes:VALIDATION_ERROR(withdetails.errors),INVALID_JSON,IDEMPOTENCY_KEY_REQUIRED,UNSUPPORTED_VERSION.Error401Missing, invalid or expired API key. Codes:API_KEY_MISSING,API_KEY_INVALID,API_KEY_EXPIRED.Error403Authenticated 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.Error404The resource does not exist or is not visible to the caller. Codes:NOT_FOUNDand resource-specific ones (SHIPMENT_NOT_FOUND,QUOTATION_NOT_FOUND,CUSTOMER_NOT_FOUND, ...). Resources of other customers are reported as not found.Error410Version retired. CodeVERSION_RETIRED.Error422The request is well formed but a business rule refuses it. Codes:INSUFFICIENT_CREDIT,SERVICE_NOT_AVAILABLE,CARRIER_NOT_AVAILABLE,IDEMPOTENCY_KEY_REUSED, ...Error429Daily or burst limit exceeded. CodeDAILY_LIMIT_EXCEEDEDorRATE_LIMIT_EXCEEDED. WaitRetry-Afterseconds.Error500Unexpected error. CodeSERVER_ERROR;details.correlation_idrepeats the correlation id.Error502The carrier or an internal dependency failed. CodeUPSTREAM_ERROR. Safe to retry reads; retry writes with the sameIdempotency-Key.Error
Request
Loading...
Response 201
{
"id": "ct_01JD2X",
"customer_id": "3723",
"amount": {
"amount": "100.00",
"currency": "EUR"
},
"master_balance": {
"amount": "145.90",
"currency": "EUR"
},
"created_at": "2026-12-09T09:31:59+00:00"
}Models
Objects used by the requests and responses on this page.
ParceLabsVersion
CorrelationId
KeyLocale
Balance
- Name
balance- Type
- Money
- required
- Italian alias:
saldo - Description
Remaining prepaid credit.
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.
Unauthorized
Forbidden
Gone
TooManyRequests
ServerError
BadGateway
CustomerBalance
- Name
customer_id- Type
- string
- required
- Italian alias:
idcustomer - Description
Customer id.
- Name
balance- Type
- Money
- required
- Italian alias:
balance_customer - Description
Remaining prepaid credit of the customer.
NotFound
CreditTransferCreate
- Name
customer_id- Type
- string
- required
- Italian alias:
idcustomer - Description
Customer to credit; must belong to your network.
- Name
amount- Type
- MoneyAmount
- required
- Italian alias:
amount - Description
Amount to move from your master account. Must not exceed your master credit.
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.
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.
IdempotentReplayed
CreditTransfer
- Name
id- Type
- string
- Italian alias:
id - Description
Transfer id. QUESTION FOR CLAUDIO: legacy returns none; needed for idempotent replays and audit.
- Name
customer_id- Type
- string
- required
- Italian alias:
idcustomer - Description
Credited customer.
- Name
amount- Type
- Money
- required
- Italian alias:
amount - Description
Amount moved.
- Name
master_balance- Type
- Money
- Italian alias:
saldo_principale - Description
Master balance after the transfer.
- Name
created_at- Type
- string (date-time)
- required
- Italian alias:
timestamp - Description
When.