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/balance

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.Balance
  • 401Missing, invalid or expired API key. Codes: API_KEY_MISSING, API_KEY_INVALID, API_KEY_EXPIRED.Error
  • 403Authenticated 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.Error
  • 410Version retired. Code VERSION_RETIRED.Error
  • 429Daily or burst limit exceeded. Code DAILY_LIMIT_EXCEEDED or RATE_LIMIT_EXCEEDED. Wait Retry-After seconds.Error
  • 500Unexpected error. Code SERVER_ERROR; details.correlation_id repeats the correlation id.Error
  • 502The carrier or an internal dependency failed. Code UPSTREAM_ERROR. Safe to retry reads; retry writes with the same Idempotency-Key.Error

Request

GET
/balance
Loading...

Response 200

{
  "balance": {
    "amount": "245.90",
    "currency": "EUR"
  }
}
GET/customers/{customer_id}/balance

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.CustomerBalance
  • 401Missing, invalid or expired API key. Codes: API_KEY_MISSING, API_KEY_INVALID, API_KEY_EXPIRED.Error
  • 403Authenticated 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.Error
  • 404The resource does not exist or is not visible to the caller. Codes: NOT_FOUND and resource-specific ones (SHIPMENT_NOT_FOUND, QUOTATION_NOT_FOUND, CUSTOMER_NOT_FOUND, ...). Resources of other customers are reported as not found.Error
  • 410Version retired. Code VERSION_RETIRED.Error
  • 429Daily or burst limit exceeded. Code DAILY_LIMIT_EXCEEDED or RATE_LIMIT_EXCEEDED. Wait Retry-After seconds.Error
  • 500Unexpected error. Code SERVER_ERROR; details.correlation_id repeats the correlation id.Error
  • 502The carrier or an internal dependency failed. Code UPSTREAM_ERROR. Safe to retry reads; retry writes with the same Idempotency-Key.Error

Request

GET
/customers/{customer_id}/balance
Loading...

Response 200

{
  "customer_id": "3723",
  "balance": {
    "amount": "23.75",
    "currency": "EUR"
  }
}
POST/credit-transfers

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 422 IDEMPOTENCY_KEY_REUSED; while the first call is running, 409 IDEMPOTENCY_KEY_IN_USE. Keys expire after 24 hours. Missing: 400 IDEMPOTENCY_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.CreditTransfer
  • 400Malformed or invalid request. Codes: VALIDATION_ERROR (with details.errors), INVALID_JSON, IDEMPOTENCY_KEY_REQUIRED, UNSUPPORTED_VERSION.Error
  • 401Missing, invalid or expired API key. Codes: API_KEY_MISSING, API_KEY_INVALID, API_KEY_EXPIRED.Error
  • 403Authenticated 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.Error
  • 404The resource does not exist or is not visible to the caller. Codes: NOT_FOUND and resource-specific ones (SHIPMENT_NOT_FOUND, QUOTATION_NOT_FOUND, CUSTOMER_NOT_FOUND, ...). Resources of other customers are reported as not found.Error
  • 410Version retired. Code VERSION_RETIRED.Error
  • 422The request is well formed but a business rule refuses it. Codes: INSUFFICIENT_CREDIT, SERVICE_NOT_AVAILABLE, CARRIER_NOT_AVAILABLE, IDEMPOTENCY_KEY_REUSED, ...Error
  • 429Daily or burst limit exceeded. Code DAILY_LIMIT_EXCEEDED or RATE_LIMIT_EXCEEDED. Wait Retry-After seconds.Error
  • 500Unexpected error. Code SERVER_ERROR; details.correlation_id repeats the correlation id.Error
  • 502The carrier or an internal dependency failed. Code UPSTREAM_ERROR. Safe to retry reads; retry writes with the same Idempotency-Key.Error

Request

POST
/credit-transfers
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.

BadRequest

Unprocessable

Was this page helpful?