API reference

Billing

Ledger, invoices, statements, spending and exports. All amounts are USD 6-decimal strings.

22 operationsBase URL https://packetexchange.io/api/v1Postman collection

BrowseBilling

List ledger transactions

GET/api/v1/billing/transactions

Access: API key. Scoped keys need account:read.
Rate limit: 100 requests per second (the default)

Your account ledger, newest first, cursor-paginated. Filter by type and an ISO date range (inclusive from, exclusive to). With format=csv the response is a CSV file of every matching row (up to 10,000) instead of JSON.

Parameters

type
query · string
One of topup, charge, credit, payout, platform_fee, test_credit
from
query · string (date-time)
Inclusive start (ISO-8601)
to
query · string (date-time)
Exclusive end (ISO-8601)
cursor
query · string (uuid)
The nextCursor from the previous page
limit
query · integer
Default 25
format
query · string
csv streams every matching row (up to 10,000) as a spreadsheet fileOne of json, csv

Response 200

FieldDescription

datarequired
object[]
idrequired
string (uuid) · data[].id
userIdrequired
string (uuid) · data[].userId
typerequired
string · data[].type
charge = usage you paid for; credit = seller earnings or a grant; platform_fee = the exchange feeOne of topup, charge, credit, payout, platform_fee, test_credit, chargeback, refund_reversal, refund, transfer
amountrequired
money · data[].amount
Signed: negative for money out (charges, fees, payouts), positive for money in USD as a decimal string with exactly 6 places, e.g. "0.012500".
balanceAfterrequired
money · data[].balanceAfter
USD as a decimal string with exactly 6 places, e.g. "0.012500".
referencerequired
string | null · data[].reference
relatedEntityTyperequired
string | null · data[].relatedEntityType
relatedEntityIdrequired
string (uuid) | null · data[].relatedEntityId
callId
string | null · data[].callId
The call or message this line bills; equals the CDR callUuid
createdAtrequired
string (date-time) · data[].createdAt
ISO-8601 timestamp (UTC)
nextCursorrequired
string | null
Pass as cursor to fetch the next page; null on the last page.
hasMorerequired
boolean
True when another page exists.

Errors

400VALIDATION_ERROR, INVALID_INPUT or BAD_REQUEST. For VALIDATION_ERROR, error.details is an array of { path, message }.
401UNAUTHORIZED: missing, invalid, expired or revoked credential.
403FORBIDDEN: not allowed - a scoped key lacks the scope, or the endpoint is session-only.
429RATE_LIMITED: slow down and retry after the Retry-After seconds.
500INTERNAL_ERROR: unexpected failure. Quote X-Request-Id to support.

Get your spending and earnings summary

GET/api/v1/billing/summary

Access: API key. Scoped keys need account:read.
Rate limit: 100 requests per second (the default)

Dashboard totals: spending (all time and today, UTC), seller earnings (all time, 30 days, today), active purchases and campaigns, and the withdrawable versus held part of your balance.

Response 200

FieldDescription

datarequired
object
totalSpendingrequired
money · data.totalSpending
USD as a decimal string with exactly 6 places, e.g. "0.012500".
totalTransactionsrequired
integer · data.totalTransactions
spendingTodayrequired
money · data.spendingToday
USD as a decimal string with exactly 6 places, e.g. "0.012500".
transactionsTodayrequired
integer · data.transactionsToday
activePurchasesrequired
integer · data.activePurchases
runningCampaignsrequired
integer · data.runningCampaigns
totalCampaignsrequired
integer · data.totalCampaigns
totalEarningsrequired
money · data.totalEarnings
USD as a decimal string with exactly 6 places, e.g. "0.012500".
earnings30drequired
money · data.earnings30d
USD as a decimal string with exactly 6 places, e.g. "0.012500".
earningsTodayrequired
money · data.earningsToday
USD as a decimal string with exactly 6 places, e.g. "0.012500".
availableBalancerequired
money · data.availableBalance
Withdrawable now USD as a decimal string with exactly 6 places, e.g. "0.012500".
heldBalancerequired
money · data.heldBalance
Card top-ups still inside the chargeback hold window USD as a decimal string with exactly 6 places, e.g. "0.012500".

Errors

400VALIDATION_ERROR, INVALID_INPUT or BAD_REQUEST. For VALIDATION_ERROR, error.details is an array of { path, message }.
401UNAUTHORIZED: missing, invalid, expired or revoked credential.
403FORBIDDEN: not allowed - a scoped key lacks the scope, or the endpoint is session-only.
429RATE_LIMITED: slow down and retry after the Retry-After seconds.
500INTERNAL_ERROR: unexpected failure. Quote X-Request-Id to support.

Get seller earnings broken down by route

GET/api/v1/billing/earnings-by-route

Access: API key. Scoped keys need account:read.
Rate limit: 100 requests per second (the default)

Top 50 routes by earnings over the last days. Attribution comes from call records, so it is partial: records without a route land in an "Unattributed" row, and the total can differ slightly from the credit ledger (attribution: "partial").

Parameters

days
query · integer
Default 30

Response 200

FieldDescription

datarequired
object[]
routeIdrequired
string (uuid) | null · data[].routeId
destinationNamerequired
string · data[].destinationName
creditsrequired
money · data[].credits
USD as a decimal string with exactly 6 places, e.g. "0.012500".
countrequired
integer · data[].count
days
integer
attribution
string
One of partial

Errors

400VALIDATION_ERROR, INVALID_INPUT or BAD_REQUEST. For VALIDATION_ERROR, error.details is an array of { path, message }.
401UNAUTHORIZED: missing, invalid, expired or revoked credential.
403FORBIDDEN: not allowed - a scoped key lacks the scope, or the endpoint is session-only.
429RATE_LIMITED: slow down and retry after the Retry-After seconds.
500INTERNAL_ERROR: unexpected failure. Quote X-Request-Id to support.

Get your outbound usage grouped by destination country

GET/api/v1/billing/usage-by-destination

Access: API key. Scoped keys need account:read.
Rate limit: 100 requests per second (the default)

Records, voice sessions, answered sessions, minutes, SMS segments, ASR, ACD and cost per destination country. ASR is voice-only and counted over customer sessions (a failed-over call counts once). With no dates the window is all time; basis.window states the window used. format=csv returns a CSV file.

Parameters

from
query · string (date-time)
to
query · string (date-time)
format
query · string
One of json, csv

Response 200

FieldDescription

datarequired
object[]
countryrequired
string · data[].country
countryCoderequired
string | null · data[].countryCode
attemptsrequired
integer · data[].attempts
Deprecated: same as records (a row count, not a call count)
recordsrequired
integer · data[].records
voiceSessionsrequired
integer · data[].voiceSessions
answeredrequired
integer · data[].answered
minutesrequired
number · data[].minutes
segmentsrequired
integer · data[].segments
asrrequired
number | null · data[].asr
Percent, voice only; null with no voice sessions
asrBasisrequired
object · data[].asrBasis
Which population and window the ASR counts
acdrequired
number | null · data[].acd
Average answered duration in seconds
costrequired
money · data[].cost
USD as a decimal string with exactly 6 places, e.g. "0.012500".
basis
object
populationrequired
string · basis.population
One of customer_sessions
windowrequired
string · basis.window

Errors

400VALIDATION_ERROR, INVALID_INPUT or BAD_REQUEST. For VALIDATION_ERROR, error.details is an array of { path, message }.
401UNAUTHORIZED: missing, invalid, expired or revoked credential.
403FORBIDDEN: not allowed - a scoped key lacks the scope, or the endpoint is session-only.
429RATE_LIMITED: slow down and retry after the Retry-After seconds.
500INTERNAL_ERROR: unexpected failure. Quote X-Request-Id to support.

Get your end-of-day balance history

GET/api/v1/billing/balance-history

Access: API key. Scoped keys need account:read.
Rate limit: 100 requests per second (the default)

One point per UTC day that had ledger activity. Balances here are plain JSON numbers for charting, not ledger strings.

Parameters

days
query · integer
Default 30

Response 200

FieldDescription

datarequired
object
pointsrequired
object[] · data.points
daterequired
string · data.points[].date
YYYY-MM-DD (UTC)
balancerequired
number · data.points[].balance
currentBalancerequired
number · data.currentBalance
hasDatarequired
boolean · data.hasData

Errors

400VALIDATION_ERROR, INVALID_INPUT or BAD_REQUEST. For VALIDATION_ERROR, error.details is an array of { path, message }.
401UNAUTHORIZED: missing, invalid, expired or revoked credential.
403FORBIDDEN: not allowed - a scoped key lacks the scope, or the endpoint is session-only.
429RATE_LIMITED: slow down and retry after the Retry-After seconds.
500INTERNAL_ERROR: unexpected failure. Quote X-Request-Id to support.

Get daily voice and SMS spend

GET/api/v1/billing/traffic-timeseries

Access: API key. Scoped keys need account:read.
Rate limit: 100 requests per second (the default)

Charges per UTC day split into voice and SMS. Amounts are plain JSON numbers for charting.

Parameters

days
query · integer
Default 30

Response 200

FieldDescription

datarequired
object
pointsrequired
object[] · data.points
daterequired
string · data.points[].date
YYYY-MM-DD (UTC)
voicerequired
number · data.points[].voice
smsrequired
number · data.points[].sms
totalrequired
number · data.points[].total
daysrequired
integer · data.days
hasDatarequired
boolean · data.hasData

Errors

400VALIDATION_ERROR, INVALID_INPUT or BAD_REQUEST. For VALIDATION_ERROR, error.details is an array of { path, message }.
401UNAUTHORIZED: missing, invalid, expired or revoked credential.
403FORBIDDEN: not allowed - a scoped key lacks the scope, or the endpoint is session-only.
429RATE_LIMITED: slow down and retry after the Retry-After seconds.
500INTERNAL_ERROR: unexpected failure. Quote X-Request-Id to support.

List your call and message records

GET/api/v1/billing/cdrs

Access: API key. Scoped keys need account:read.
Rate limit: 100 requests per second (the default)

Your call detail records (test probes excluded), newest first, cursor-paginated. With format=csv the response is a CSV file of up to 50,000 rows. For larger exports use POST /billing/exports.

Parameters

from
query · string (date-time)
to
query · string (date-time)
kind
query · string
One of voice, sms
direction
query · string
One of outbound, inbound
cursor
query · string (uuid)
limit
query · integer
Default 50
format
query · string
csv streams up to 50,000 rowsOne of json, csv

Response 200

FieldDescription

datarequired
object[]
idrequired
string (uuid) · data[].id
callUuidrequired
string | null · data[].callUuid
callGroupIdrequired
string (uuid) | null · data[].callGroupId
Groups the legs of one customer call when it failed over
directionrequired
string · data[].direction
One of outbound, inbound
kindrequired
string · data[].kind
One of voice, sms
routeIdrequired
string (uuid) | null · data[].routeId
fromNumberrequired
string | null · data[].fromNumber
toNumberrequired
string | null · data[].toNumber
clirequired
string | null · data[].cli
statusrequired
string | null · data[].status
sipCoderequired
integer | null · data[].sipCode
hangupCauserequired
string | null · data[].hangupCause
durationSecondsrequired
integer | null · data[].durationSeconds
billedSecondsrequired
integer | null · data[].billedSeconds
segmentsrequired
integer | null · data[].segments
SMS segments
pddMsrequired
integer | null · data[].pddMs
buyerCostrequired
money | null · data[].buyerCost
What you were charged for this record USD as a decimal string with exactly 6 places, e.g. "0.012500".
sellerCreditrequired
money | null · data[].sellerCredit
Seller earnings. Null unless you are the seller on this record USD as a decimal string with exactly 6 places, e.g. "0.012500".
ratePerUnitrequired
money | null · data[].ratePerUnit
US dollars as a decimal string with exactly 6 decimal places, e.g. "0.012500". Do money arithmetic with a decimal type, not floating point. USD as a decimal string with exactly 6 places, e.g. "0.012500".
answeredAtrequired
string (date-time) | null · data[].answeredAt
ISO-8601 timestamp (UTC)
endedAtrequired
string (date-time) | null · data[].endedAt
ISO-8601 timestamp (UTC)
createdAtrequired
string (date-time) · data[].createdAt
ISO-8601 timestamp (UTC)
nextCursorrequired
string | null
Pass as cursor to fetch the next page; null on the last page.
hasMorerequired
boolean
True when another page exists.

Errors

400VALIDATION_ERROR, INVALID_INPUT or BAD_REQUEST. For VALIDATION_ERROR, error.details is an array of { path, message }.
401UNAUTHORIZED: missing, invalid, expired or revoked credential.
403FORBIDDEN: not allowed - a scoped key lacks the scope, or the endpoint is session-only.
429RATE_LIMITED: slow down and retry after the Retry-After seconds.
500INTERNAL_ERROR: unexpected failure. Quote X-Request-Id to support.

Stream your call records as CSV

GET/api/v1/billing/cdrs/export

Access: API key. Scoped keys need account:read.
Rate limit: 100 requests per second (the default)

Streams every matching record (up to 1,000,000 rows) as a CSV file in one response.

Parameters

from
query · string (date-time)
to
query · string (date-time)
kind
query · string
One of voice, sms
direction
query · string
One of outbound, inbound

Response 200 (text/csv)

A CSV file of call detail records.

Errors

400VALIDATION_ERROR, INVALID_INPUT or BAD_REQUEST. For VALIDATION_ERROR, error.details is an array of { path, message }.
401UNAUTHORIZED: missing, invalid, expired or revoked credential.
403FORBIDDEN: not allowed - a scoped key lacks the scope, or the endpoint is session-only.
429RATE_LIMITED: slow down and retry after the Retry-After seconds.
500INTERNAL_ERROR: unexpected failure. Quote X-Request-Id to support.

List your call-record exports

GET/api/v1/billing/exports

Access: API key. Scoped keys need account:read.
Rate limit: 100 requests per second (the default)

Your 50 most recent export jobs.

Response 200

FieldDescription

datarequired
object[]
idrequired
string (uuid) · data[].id
typerequired
string · data[].type
One of cdr
paramsrequired
object · data[].params
from
string (date-time) · data[].params.from
ISO-8601 timestamp (UTC)
to
string (date-time) · data[].params.to
ISO-8601 timestamp (UTC)
kind
string · data[].params.kind
One of voice, sms
direction
string · data[].params.direction
One of outbound, inbound
statusrequired
string · data[].status
One of pending, running, done, failed
rowCountrequired
integer | null · data[].rowCount
errorrequired
string | null · data[].error
createdAtrequired
string (date-time) · data[].createdAt
ISO-8601 timestamp (UTC)
completedAtrequired
string (date-time) | null · data[].completedAt
ISO-8601 timestamp (UTC)
downloadablerequired
boolean · data[].downloadable
True once the job is done and its file is on record
downloadUrlrequired
string | null · data[].downloadUrl
The download endpoint for this job once it is done (GET /billing/exports/{id}/download). The only way to the file: no server path is ever returned.

Errors

400VALIDATION_ERROR, INVALID_INPUT or BAD_REQUEST. For VALIDATION_ERROR, error.details is an array of { path, message }.
401UNAUTHORIZED: missing, invalid, expired or revoked credential.
403FORBIDDEN: not allowed - a scoped key lacks the scope, or the endpoint is session-only.
429RATE_LIMITED: slow down and retry after the Retry-After seconds.
500INTERNAL_ERROR: unexpected failure. Quote X-Request-Id to support.

Start a background call-record export

POST/api/v1/billing/exports

Access: API key. Scoped keys need account:read.
Rate limit: 100 requests per second (the default)

Queues a CSV export job. At most 3 exports may be pending or running at once; a fourth gets 429 TOO_MANY_EXPORTS. Poll GET /billing/exports and download when downloadable is true.

Request body (application/json)

FieldDescription

from
string (date-time)
to
string (date-time)
filters
object
Takes precedence over the top-level from/to
from
string (date-time) · filters.from
to
string (date-time) · filters.to
kind
string · filters.kind
One of voice, sms
direction
string · filters.direction
One of outbound, inbound

Response 202

FieldDescription

datarequired
object
Same fields as BillingExportJob, shown earlier on this page.

Errors

400VALIDATION_ERROR, INVALID_INPUT or BAD_REQUEST. For VALIDATION_ERROR, error.details is an array of { path, message }.
401UNAUTHORIZED: missing, invalid, expired or revoked credential.
403FORBIDDEN: not allowed - a scoped key lacks the scope, or the endpoint is session-only.
409CONFLICT (or a code-specific 409): the change clashes with existing state.
429RATE_LIMITED: slow down and retry after the Retry-After seconds.
500INTERNAL_ERROR: unexpected failure. Quote X-Request-Id to support.
AlsoTOO_MANY_EXPORTS

HTTP

curl -X POST "https://packetexchange.io/api/v1/billing/exports" \
  -H "Authorization: Bearer $PACKETEXCHANGE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "from": "2026-10-01T09:00:00Z",
  "to": "2026-10-01T09:00:00Z"
}'

Run it here with a test key.

Download a finished call-record export

GET/api/v1/billing/exports/{id}/download

Access: API key. Scoped keys need account:read.
Rate limit: 100 requests per second (the default)

Returns the CSV file. Only the account that queued the export can download it (another account gets 404). 409 EXPORT_NOT_READY while the job is not finished; 410 EXPORT_EXPIRED once the retention sweep has deleted the file.

Parameters

idrequired
path · string

Response 200 (text/csv)

The export as a CSV file.

Errors

400VALIDATION_ERROR, INVALID_INPUT or BAD_REQUEST. For VALIDATION_ERROR, error.details is an array of { path, message }.
401UNAUTHORIZED: missing, invalid, expired or revoked credential.
403FORBIDDEN: not allowed - a scoped key lacks the scope, or the endpoint is session-only.
404NOT_FOUND: no such resource on your account.
429RATE_LIMITED: slow down and retry after the Retry-After seconds.
500INTERNAL_ERROR: unexpected failure. Quote X-Request-Id to support.
AlsoEXPORT_NOT_READY, EXPORT_EXPIRED

List your receipts and statements

GET/api/v1/billing/invoices

Access: API key. Scoped keys need account:read.
Rate limit: 100 requests per second (the default)

Top-up receipts and statements (up to 200, newest first). For numbered tax invoices see GET /billing/tax-invoices.

Response 200

FieldDescription

datarequired
object[]
idrequired
string (uuid) · data[].id
numberrequired
integer · data[].number
Sequential document number; printed as INV-000123
typerequired
string · data[].type
One of topup_receipt, statement
amountrequired
money · data[].amount
USD as a decimal string with exactly 6 places, e.g. "0.012500".
currencyrequired
string · data[].currency
periodStartrequired
string (date-time) | null · data[].periodStart
ISO-8601 timestamp (UTC)
periodEndrequired
string (date-time) | null · data[].periodEnd
ISO-8601 timestamp (UTC)
createdAtrequired
string (date-time) · data[].createdAt
ISO-8601 timestamp (UTC)

Errors

400VALIDATION_ERROR, INVALID_INPUT or BAD_REQUEST. For VALIDATION_ERROR, error.details is an array of { path, message }.
401UNAUTHORIZED: missing, invalid, expired or revoked credential.
403FORBIDDEN: not allowed - a scoped key lacks the scope, or the endpoint is session-only.
429RATE_LIMITED: slow down and retry after the Retry-After seconds.
500INTERNAL_ERROR: unexpected failure. Quote X-Request-Id to support.

Get a receipt or statement

GET/api/v1/billing/invoices/{id}

Access: API key. Scoped keys need account:read.
Rate limit: 100 requests per second (the default)

JSON by default; format=html returns a self-contained printable page.

Parameters

idrequired
path · string
format
query · string
html returns a printable pageOne of json, html

Response 200

FieldDescription

datarequired
object
idrequired
string (uuid) · data.id
numberrequired
integer · data.number
Sequential document number; printed as INV-000123
typerequired
string · data.type
One of topup_receipt, statement
amountrequired
money · data.amount
USD as a decimal string with exactly 6 places, e.g. "0.012500".
currencyrequired
string · data.currency
periodStartrequired
string (date-time) | null · data.periodStart
ISO-8601 timestamp (UTC)
periodEndrequired
string (date-time) | null · data.periodEnd
ISO-8601 timestamp (UTC)
createdAtrequired
string (date-time) · data.createdAt
ISO-8601 timestamp (UTC)
dataJsonrequired
object | null · data.dataJson

Errors

400VALIDATION_ERROR, INVALID_INPUT or BAD_REQUEST. For VALIDATION_ERROR, error.details is an array of { path, message }.
401UNAUTHORIZED: missing, invalid, expired or revoked credential.
403FORBIDDEN: not allowed - a scoped key lacks the scope, or the endpoint is session-only.
404NOT_FOUND: no such resource on your account.
429RATE_LIMITED: slow down and retry after the Retry-After seconds.
500INTERNAL_ERROR: unexpected failure. Quote X-Request-Id to support.

Get your monthly statement

GET/api/v1/billing/statements

Access: API key. Scoped keys need account:read.
Rate limit: 100 requests per second (the default)

Every ledger line in a calendar month (UTC) with totals by type and the tax on platform fees. Totals and net are plain JSON numbers; line-item amounts are ledger strings. format=csv returns a CSV file.

Parameters

monthrequired
query · string
Calendar month, YYYY-MM (UTC)
format
query · string
One of json, csv

Response 200

FieldDescription

datarequired
object
monthrequired
string · data.month
periodStartrequired
string (date-time) · data.periodStart
ISO-8601 timestamp (UTC)
periodEndrequired
string (date-time) · data.periodEnd
ISO-8601 timestamp (UTC)
netrequired
number · data.net
credits + top-ups - charges - payouts
totalsrequired
object · data.totals
chargesrequired
number · data.totals.charges
creditsrequired
number · data.totals.credits
topupsrequired
number · data.totals.topups
payoutsrequired
number · data.totals.payouts
byTyperequired
object · data.totals.byType
lineItemsrequired
object[] · data.lineItems
idrequired
string (uuid) · data.lineItems[].id
typerequired
string · data.lineItems[].type
One of topup, charge, credit, payout, platform_fee, test_credit, chargeback, refund_reversal, refund, transfer
amountrequired
money · data.lineItems[].amount
USD as a decimal string with exactly 6 places, e.g. "0.012500".
referencerequired
string | null · data.lineItems[].reference
createdAtrequired
string (date-time) · data.lineItems[].createdAt
ISO-8601 timestamp (UTC)
taxrequired
object · data.tax
taxableSupplyrequired
string · data.tax.taxableSupply
One of platform_fees
baserequired
number · data.tax.base
ratePctrequired
number · data.tax.ratePct
taxAmountrequired
number · data.tax.taxAmount
totalrequired
number · data.tax.total
treatmentrequired
string · data.tax.treatment
labelrequired
string · data.tax.label
noterequired
string | null · data.tax.note
taxIdrequired
string | null · data.tax.taxId
taxCountryrequired
string | null · data.tax.taxCountry
homeCountryrequired
string · data.tax.homeCountry

Errors

400VALIDATION_ERROR, INVALID_INPUT or BAD_REQUEST. For VALIDATION_ERROR, error.details is an array of { path, message }.
401UNAUTHORIZED: missing, invalid, expired or revoked credential.
403FORBIDDEN: not allowed - a scoped key lacks the scope, or the endpoint is session-only.
429RATE_LIMITED: slow down and retry after the Retry-After seconds.
500INTERNAL_ERROR: unexpected failure. Quote X-Request-Id to support.

Get the financial position of your wallet or a sub-account

GET/api/v1/billing/financial-activity/position

Access: API key. Scoped keys need account:read.
Rate limit: 100 requests per second (the default)

Posted balance, credit limit, reserved for live calls, settlement holds, pending payments, and what that leaves to spend, with the source of each figure. Figures are plain JSON numbers (USD). Pass customerId for a sub-account you operate.

Parameters

customerId
query · string (uuid)
A sub-account you operate; omit for your own wallet

Response 200

FieldDescription

datarequired
object
walletKindrequired
string · data.walletKind
One of user, sub_account
walletIdrequired
string (uuid) · data.walletId
labelrequired
string · data.label
currencyrequired
string · data.currency
postedBalancerequired
number · data.postedBalance
creditLimitrequired
number · data.creditLimit
creditLimitRecordedrequired
boolean · data.creditLimitRecorded
reservedForActiveCallsrequired
number · data.reservedForActiveCalls
settlementHoldsrequired
number · data.settlementHolds
pendingPaymentsrequired
number · data.pendingPayments
promotionalCreditrequired
number · data.promotionalCredit
confirmedFundsrequired
number · data.confirmedFunds
availableToSpendrequired
number · data.availableToSpend
overCommittedrequired
boolean · data.overCommitted
negativeBalancerequired
string · data.negativeBalance
One of not_negative, within_agreed_credit, beyond_agreed_credit
beyondCreditByrequired
number · data.beyondCreditBy
activeCallsrequired
integer · data.activeCalls
reservationEnforcedrequired
boolean · data.reservationEnforced
True when reservations actually gate new calls, not just observe them
creditNoterequired
string · data.creditNote
sourcesrequired
object · data.sources

Errors

400VALIDATION_ERROR, INVALID_INPUT or BAD_REQUEST. For VALIDATION_ERROR, error.details is an array of { path, message }.
401UNAUTHORIZED: missing, invalid, expired or revoked credential.
403FORBIDDEN: not allowed - a scoped key lacks the scope, or the endpoint is session-only.
429RATE_LIMITED: slow down and retry after the Retry-After seconds.
500INTERNAL_ERROR: unexpected failure. Quote X-Request-Id to support.

List live call authorisations on a wallet

GET/api/v1/billing/financial-activity/authorisations

Access: API key. Scoped keys need account:read.
Rate limit: 100 requests per second (the default)

Funds currently reserved for calls in progress. Amounts are plain JSON numbers (USD).

Parameters

customerId
query · string (uuid)
A sub-account you operate; omit for your own wallet

Response 200

FieldDescription

datarequired
object
callsrequired
object[] · data.calls
callUuidrequired
string · data.calls[].callUuid
amountrequired
number · data.calls[].amount
expiresAtrequired
string (date-time) · data.calls[].expiresAt
ISO-8601 timestamp (UTC)
totalrequired
number · data.total
enforcedrequired
boolean · data.enforced

Errors

400VALIDATION_ERROR, INVALID_INPUT or BAD_REQUEST. For VALIDATION_ERROR, error.details is an array of { path, message }.
401UNAUTHORIZED: missing, invalid, expired or revoked credential.
403FORBIDDEN: not allowed - a scoped key lacks the scope, or the endpoint is session-only.
429RATE_LIMITED: slow down and retry after the Retry-After seconds.
500INTERNAL_ERROR: unexpected failure. Quote X-Request-Id to support.

Reconcile a wallet balance against its ledger

GET/api/v1/billing/financial-activity/reconciliation

Access: API key. Scoped keys need account:read.
Rate limit: 100 requests per second (the default)

Explains the posted balance by ledger component and reports anything it cannot explain as unreconciled, rather than as confirmed money. Amounts are plain JSON numbers (USD).

Parameters

customerId
query · string (uuid)
A sub-account you operate; omit for your own wallet

Response 200

FieldDescription

datarequired
object
walletKindrequired
string · data.walletKind
One of user, sub_account
walletIdrequired
string (uuid) · data.walletId
labelrequired
string · data.label
currencyrequired
string · data.currency
postedBalancerequired
number · data.postedBalance
openingBalancerequired
object · data.openingBalance
amountrequired
number · data.openingBalance.amount
documentedrequired
boolean · data.openingBalance.documented
noterequired
string · data.openingBalance.note
componentsrequired
object[] · data.components
keyrequired
string · data.components[].key
labelrequired
string · data.components[].label
amountrequired
number · data.components[].amount
countrequired
integer · data.components[].count
sourcerequired
string · data.components[].source
explainedrequired
number · data.explained
unattributedrequired
object · data.unattributed
amountrequired
number · data.unattributed.amount
countrequired
integer · data.unattributed.count
noterequired
string · data.unattributed.note
unreconciledrequired
number · data.unreconciled
hasUnreconciledrequired
boolean · data.hasUnreconciled
unpostedUsagerequired
object · data.unpostedUsage
amountrequired
number · data.unpostedUsage.amount
callsrequired
integer · data.unpostedUsage.calls
noterequired
string · data.unpostedUsage.note
checkedAtrequired
string (date-time) · data.checkedAt
ISO-8601 timestamp (UTC)

Errors

400VALIDATION_ERROR, INVALID_INPUT or BAD_REQUEST. For VALIDATION_ERROR, error.details is an array of { path, message }.
401UNAUTHORIZED: missing, invalid, expired or revoked credential.
403FORBIDDEN: not allowed - a scoped key lacks the scope, or the endpoint is session-only.
429RATE_LIMITED: slow down and retry after the Retry-After seconds.
500INTERNAL_ERROR: unexpected failure. Quote X-Request-Id to support.

List posted, pending and unposted money movements

GET/api/v1/billing/financial-activity/activity

Access: API key. Scoped keys need account:read.
Rate limit: 100 requests per second (the default)

One timeline of posted ledger lines, pending payments and usage not yet posted. truncated is true when more rows matched than limit. Amounts are plain JSON numbers (USD).

Parameters

customerId
query · string (uuid)
A sub-account you operate; omit for your own wallet
limit
query · integer
Default 100
from
query · string (date-time)
to
query · string (date-time)
state
query · string
One of all, posted, pending, usage

Response 200

FieldDescription

datarequired
object
rowsrequired
object[] · data.rows
idrequired
string · data.rows[].id
staterequired
string · data.rows[].state
One of posted, pending, usage
atrequired
string (date-time) · data.rows[].at
ISO-8601 timestamp (UTC)
kindrequired
string · data.rows[].kind
labelrequired
string · data.rows[].label
amountrequired
number · data.rows[].amount
balanceAfterrequired
number | null · data.rows[].balanceAfter
referencerequired
string | null · data.rows[].reference
callIdrequired
string | null · data.rows[].callId
traceTorequired
string · data.rows[].traceTo
truncatedrequired
boolean · data.truncated

Errors

400VALIDATION_ERROR, INVALID_INPUT or BAD_REQUEST. For VALIDATION_ERROR, error.details is an array of { path, message }.
401UNAUTHORIZED: missing, invalid, expired or revoked credential.
403FORBIDDEN: not allowed - a scoped key lacks the scope, or the endpoint is session-only.
429RATE_LIMITED: slow down and retry after the Retry-After seconds.
500INTERNAL_ERROR: unexpected failure. Quote X-Request-Id to support.

List sub-account wallets you operate with their positions

GET/api/v1/billing/financial-activity/customers

Access: API key. Scoped keys need account:read.
Rate limit: 100 requests per second (the default)

Every non-closed sub-account with its balance, credit and what it can spend now. Amounts are plain JSON numbers.

Response 200

FieldDescription

datarequired
object[]
idrequired
string (uuid) · data[].id
labelrequired
string · data[].label
currencyrequired
string · data[].currency
statusrequired
string · data[].status
postedBalancerequired
number · data[].postedBalance
creditLimitrequired
number · data[].creditLimit
confirmedFundsrequired
number · data[].confirmedFunds
reservedForActiveCallsrequired
number · data[].reservedForActiveCalls
activeCallsrequired
integer · data[].activeCalls
availableToSpendrequired
number · data[].availableToSpend
negativeWithinAgreedCreditrequired
boolean · data[].negativeWithinAgreedCredit
beyondAgreedCreditrequired
boolean · data[].beyondAgreedCredit

Errors

400VALIDATION_ERROR, INVALID_INPUT or BAD_REQUEST. For VALIDATION_ERROR, error.details is an array of { path, message }.
401UNAUTHORIZED: missing, invalid, expired or revoked credential.
403FORBIDDEN: not allowed - a scoped key lacks the scope, or the endpoint is session-only.
429RATE_LIMITED: slow down and retry after the Retry-After seconds.
500INTERNAL_ERROR: unexpected failure. Quote X-Request-Id to support.

List your tax invoices

GET/api/v1/billing/tax-invoices

Access: API key. Scoped keys need account:read.
Rate limit: 100 requests per second (the default)

Numbered tax invoices (gap-free per account), newest first, up to 500.

Response 200

FieldDescription

datarequired
object[]
idrequired
string (uuid) · data[].id
seqrequired
integer · data[].seq
Gap-free per-account sequence
numberrequired
string · data[].number
periodrequired
string · data[].period
YYYY-MM
periodStartrequired
string (date-time) · data[].periodStart
ISO-8601 timestamp (UTC)
periodEndrequired
string (date-time) · data[].periodEnd
ISO-8601 timestamp (UTC)
currencyrequired
string · data[].currency
subtotalrequired
string · data[].subtotal
Decimal string
taxAmountrequired
string · data[].taxAmount
Decimal string
totalrequired
string · data[].total
Decimal string
createdAtrequired
string (date-time) · data[].createdAt
ISO-8601 timestamp (UTC)

Errors

400VALIDATION_ERROR, INVALID_INPUT or BAD_REQUEST. For VALIDATION_ERROR, error.details is an array of { path, message }.
401UNAUTHORIZED: missing, invalid, expired or revoked credential.
403FORBIDDEN: not allowed - a scoped key lacks the scope, or the endpoint is session-only.
429RATE_LIMITED: slow down and retry after the Retry-After seconds.
500INTERNAL_ERROR: unexpected failure. Quote X-Request-Id to support.

Generate the tax invoice for a month

POST/api/v1/billing/tax-invoices/generate

Access: API key. Scoped keys need account:write.
Rate limit: 100 requests per second (the default)

Idempotent per period: if the month already has an invoice it is returned with alreadyExisted: true and status 200; a new one returns 201. 503 when the invoice register is not available on this node.

Request body (application/json)

FieldDescription

periodrequired
string

Response 201

FieldDescription

datarequired
object
idrequired
string (uuid) · data.id
seqrequired
integer · data.seq
Gap-free per-account sequence
numberrequired
string · data.number
periodrequired
string · data.period
YYYY-MM
periodStartrequired
string (date-time) · data.periodStart
ISO-8601 timestamp (UTC)
periodEndrequired
string (date-time) · data.periodEnd
ISO-8601 timestamp (UTC)
currencyrequired
string · data.currency
subtotalrequired
string · data.subtotal
Decimal string
taxAmountrequired
string · data.taxAmount
Decimal string
totalrequired
string · data.total
Decimal string
createdAtrequired
string (date-time) · data.createdAt
ISO-8601 timestamp (UTC)
dataJsonrequired
object | null · data.dataJson
Frozen line items and the tax section as issued
alreadyExistedrequired
boolean · data.alreadyExisted

Errors

400VALIDATION_ERROR, INVALID_INPUT or BAD_REQUEST. For VALIDATION_ERROR, error.details is an array of { path, message }.
401UNAUTHORIZED: missing, invalid, expired or revoked credential.
403FORBIDDEN: not allowed - a scoped key lacks the scope, or the endpoint is session-only.
409CONFLICT (or a code-specific 409): the change clashes with existing state.
429RATE_LIMITED: slow down and retry after the Retry-After seconds.
500INTERNAL_ERROR: unexpected failure. Quote X-Request-Id to support.

HTTP

curl -X POST "https://packetexchange.io/api/v1/billing/tax-invoices/generate" \
  -H "Authorization: Bearer $PACKETEXCHANGE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "period": "<period>"
}'

Run it here with a test key.

Get a tax invoice

GET/api/v1/billing/tax-invoices/{id}

Access: API key. Scoped keys need account:read.
Rate limit: 100 requests per second (the default)

JSON by default; format=html returns a printable invoice page.

Parameters

idrequired
path · string
format
query · string
html returns a printable pageOne of json, html

Response 200

FieldDescription

datarequired
object
idrequired
string (uuid) · data.id
seqrequired
integer · data.seq
Gap-free per-account sequence
numberrequired
string · data.number
periodrequired
string · data.period
YYYY-MM
periodStartrequired
string (date-time) · data.periodStart
ISO-8601 timestamp (UTC)
periodEndrequired
string (date-time) · data.periodEnd
ISO-8601 timestamp (UTC)
currencyrequired
string · data.currency
subtotalrequired
string · data.subtotal
Decimal string
taxAmountrequired
string · data.taxAmount
Decimal string
totalrequired
string · data.total
Decimal string
createdAtrequired
string (date-time) · data.createdAt
ISO-8601 timestamp (UTC)
dataJsonrequired
object | null · data.dataJson
Frozen line items and the tax section as issued

Errors

400VALIDATION_ERROR, INVALID_INPUT or BAD_REQUEST. For VALIDATION_ERROR, error.details is an array of { path, message }.
401UNAUTHORIZED: missing, invalid, expired or revoked credential.
403FORBIDDEN: not allowed - a scoped key lacks the scope, or the endpoint is session-only.
404NOT_FOUND: no such resource on your account.
429RATE_LIMITED: slow down and retry after the Retry-After seconds.
500INTERNAL_ERROR: unexpected failure. Quote X-Request-Id to support.