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

Name	In	Type	Description
`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

Field	Type	Description
`data`required	object[]	-
`id`requireddata[].id	string (uuid)	-
`userId`requireddata[].userId	string (uuid)	-
`type`requireddata[].type	string	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`
`amount`requireddata[].amount	money	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".
`balanceAfter`requireddata[].balanceAfter	money	USD as a decimal string with exactly 6 places, e.g. "0.012500".
`reference`requireddata[].reference	string \| null	-
`relatedEntityType`requireddata[].relatedEntityType	string \| null	-
`relatedEntityId`requireddata[].relatedEntityId	string (uuid) \| null	-
`callId`data[].callId	string \| null	The call or message this line bills; equals the CDR callUuid
`createdAt`requireddata[].createdAt	string (date-time)	ISO-8601 timestamp (UTC)
`nextCursor`required	string \| null	Pass as `cursor` to fetch the next page; null on the last page.
`hasMore`required	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

Field	Type	Description
`data`required	object	-
`totalSpending`requireddata.totalSpending	money	USD as a decimal string with exactly 6 places, e.g. "0.012500".
`totalTransactions`requireddata.totalTransactions	integer	-
`spendingToday`requireddata.spendingToday	money	USD as a decimal string with exactly 6 places, e.g. "0.012500".
`transactionsToday`requireddata.transactionsToday	integer	-
`activePurchases`requireddata.activePurchases	integer	-
`runningCampaigns`requireddata.runningCampaigns	integer	-
`totalCampaigns`requireddata.totalCampaigns	integer	-
`totalEarnings`requireddata.totalEarnings	money	USD as a decimal string with exactly 6 places, e.g. "0.012500".
`earnings30d`requireddata.earnings30d	money	USD as a decimal string with exactly 6 places, e.g. "0.012500".
`earningsToday`requireddata.earningsToday	money	USD as a decimal string with exactly 6 places, e.g. "0.012500".
`availableBalance`requireddata.availableBalance	money	Withdrawable now USD as a decimal string with exactly 6 places, e.g. "0.012500".
`heldBalance`requireddata.heldBalance	money	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

Name	In	Type	Description
`days`	query	integer	-Default 30

Response 200

Field	Type	Description
`data`required	object[]	-
`routeId`requireddata[].routeId	string (uuid) \| null	-
`destinationName`requireddata[].destinationName	string	-
`credits`requireddata[].credits	money	USD as a decimal string with exactly 6 places, e.g. "0.012500".
`count`requireddata[].count	integer	-
`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

Name	In	Type	Description
`from`	query	string (date-time)	-
`to`	query	string (date-time)	-
`format`	query	string	-One of json, csv

Response 200

Field	Type	Description
`data`required	object[]	-
`country`requireddata[].country	string	-
`countryCode`requireddata[].countryCode	string \| null	-
`attempts`requireddata[].attempts	integer	Deprecated: same as `records` (a row count, not a call count)
`records`requireddata[].records	integer	-
`voiceSessions`requireddata[].voiceSessions	integer	-
`answered`requireddata[].answered	integer	-
`minutes`requireddata[].minutes	number	-
`segments`requireddata[].segments	integer	-
`asr`requireddata[].asr	number \| null	Percent, voice only; null with no voice sessions
`asrBasis`requireddata[].asrBasis	object	Which population and window the ASR counts
`acd`requireddata[].acd	number \| null	Average answered duration in seconds
`cost`requireddata[].cost	money	USD as a decimal string with exactly 6 places, e.g. "0.012500".
`basis`	object	-
`population`requiredbasis.population	string	-One of `customer_sessions`
`window`requiredbasis.window	string	-

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

Name	In	Type	Description
`days`	query	integer	-Default 30

Response 200

Field	Type	Description
`data`required	object	-
`points`requireddata.points	object[]	-
`date`requireddata.points[].date	string	YYYY-MM-DD (UTC)
`balance`requireddata.points[].balance	number	-
`currentBalance`requireddata.currentBalance	number	-
`hasData`requireddata.hasData	boolean	-

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

Name	In	Type	Description
`days`	query	integer	-Default 30

Response 200

Field	Type	Description
`data`required	object	-
`points`requireddata.points	object[]	-
`date`requireddata.points[].date	string	YYYY-MM-DD (UTC)
`voice`requireddata.points[].voice	number	-
`sms`requireddata.points[].sms	number	-
`total`requireddata.points[].total	number	-
`days`requireddata.days	integer	-
`hasData`requireddata.hasData	boolean	-

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

Name	In	Type	Description
`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

Field	Type	Description
`data`required	object[]	-
`id`requireddata[].id	string (uuid)	-
`callUuid`requireddata[].callUuid	string \| null	-
`callGroupId`requireddata[].callGroupId	string (uuid) \| null	Groups the legs of one customer call when it failed over
`direction`requireddata[].direction	string	-One of `outbound`, `inbound`
`kind`requireddata[].kind	string	-One of `voice`, `sms`
`routeId`requireddata[].routeId	string (uuid) \| null	-
`fromNumber`requireddata[].fromNumber	string \| null	-
`toNumber`requireddata[].toNumber	string \| null	-
`cli`requireddata[].cli	string \| null	-
`status`requireddata[].status	string \| null	-
`sipCode`requireddata[].sipCode	integer \| null	-
`hangupCause`requireddata[].hangupCause	string \| null	-
`durationSeconds`requireddata[].durationSeconds	integer \| null	-
`billedSeconds`requireddata[].billedSeconds	integer \| null	-
`segments`requireddata[].segments	integer \| null	SMS segments
`pddMs`requireddata[].pddMs	integer \| null	-
`buyerCost`requireddata[].buyerCost	money \| null	What you were charged for this record USD as a decimal string with exactly 6 places, e.g. "0.012500".
`sellerCredit`requireddata[].sellerCredit	money \| null	Seller earnings. Null unless you are the seller on this record USD as a decimal string with exactly 6 places, e.g. "0.012500".
`ratePerUnit`requireddata[].ratePerUnit	money \| null	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".
`answeredAt`requireddata[].answeredAt	string (date-time) \| null	ISO-8601 timestamp (UTC)
`endedAt`requireddata[].endedAt	string (date-time) \| null	ISO-8601 timestamp (UTC)
`createdAt`requireddata[].createdAt	string (date-time)	ISO-8601 timestamp (UTC)
`nextCursor`required	string \| null	Pass as `cursor` to fetch the next page; null on the last page.
`hasMore`required	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

Name	In	Type	Description
`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

Field	Type	Description
`data`required	object[]	-
`id`requireddata[].id	string (uuid)	-
`type`requireddata[].type	string	-One of `cdr`
`params`requireddata[].params	object	-
`from`data[].params.from	string (date-time)	ISO-8601 timestamp (UTC)
`to`data[].params.to	string (date-time)	ISO-8601 timestamp (UTC)
`kind`data[].params.kind	string	-One of `voice`, `sms`
`direction`data[].params.direction	string	-One of `outbound`, `inbound`
`status`requireddata[].status	string	-One of `pending`, `running`, `done`, `failed`
`rowCount`requireddata[].rowCount	integer \| null	-
`error`requireddata[].error	string \| null	-
`createdAt`requireddata[].createdAt	string (date-time)	ISO-8601 timestamp (UTC)
`completedAt`requireddata[].completedAt	string (date-time) \| null	ISO-8601 timestamp (UTC)
`downloadable`requireddata[].downloadable	boolean	True once the job is done and its file is on record
`downloadUrl`requireddata[].downloadUrl	string \| null	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)

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

Response 202

Field	Type	Description
`data`required	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

Name	In	Type	Description
`id`required	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

Field	Type	Description
`data`required	object[]	-
`id`requireddata[].id	string (uuid)	-
`number`requireddata[].number	integer	Sequential document number; printed as INV-000123
`type`requireddata[].type	string	-One of `topup_receipt`, `statement`
`amount`requireddata[].amount	money	USD as a decimal string with exactly 6 places, e.g. "0.012500".
`currency`requireddata[].currency	string	-
`periodStart`requireddata[].periodStart	string (date-time) \| null	ISO-8601 timestamp (UTC)
`periodEnd`requireddata[].periodEnd	string (date-time) \| null	ISO-8601 timestamp (UTC)
`createdAt`requireddata[].createdAt	string (date-time)	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

Name	In	Type	Description
`id`required	path	string	-
`format`	query	string	html returns a printable pageOne of json, html

Response 200

Field	Type	Description
`data`required	object	-
`id`requireddata.id	string (uuid)	-
`number`requireddata.number	integer	Sequential document number; printed as INV-000123
`type`requireddata.type	string	-One of `topup_receipt`, `statement`
`amount`requireddata.amount	money	USD as a decimal string with exactly 6 places, e.g. "0.012500".
`currency`requireddata.currency	string	-
`periodStart`requireddata.periodStart	string (date-time) \| null	ISO-8601 timestamp (UTC)
`periodEnd`requireddata.periodEnd	string (date-time) \| null	ISO-8601 timestamp (UTC)
`createdAt`requireddata.createdAt	string (date-time)	ISO-8601 timestamp (UTC)
`dataJson`requireddata.dataJson	object \| null	-

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

Name	In	Type	Description
`month`required	query	string	Calendar month, YYYY-MM (UTC)
`format`	query	string	-One of json, csv

Response 200

Field	Type	Description
`data`required	object	-
`month`requireddata.month	string	-
`periodStart`requireddata.periodStart	string (date-time)	ISO-8601 timestamp (UTC)
`periodEnd`requireddata.periodEnd	string (date-time)	ISO-8601 timestamp (UTC)
`net`requireddata.net	number	credits + top-ups - charges - payouts
`totals`requireddata.totals	object	-
`charges`requireddata.totals.charges	number	-
`credits`requireddata.totals.credits	number	-
`topups`requireddata.totals.topups	number	-
`payouts`requireddata.totals.payouts	number	-
`byType`requireddata.totals.byType	object	-
`lineItems`requireddata.lineItems	object[]	-
`id`requireddata.lineItems[].id	string (uuid)	-
`type`requireddata.lineItems[].type	string	-One of `topup`, `charge`, `credit`, `payout`, `platform_fee`, `test_credit`, `chargeback`, `refund_reversal`, `refund`, `transfer`
`amount`requireddata.lineItems[].amount	money	USD as a decimal string with exactly 6 places, e.g. "0.012500".
`reference`requireddata.lineItems[].reference	string \| null	-
`createdAt`requireddata.lineItems[].createdAt	string (date-time)	ISO-8601 timestamp (UTC)
`tax`requireddata.tax	object	-
`taxableSupply`requireddata.tax.taxableSupply	string	-One of `platform_fees`
`base`requireddata.tax.base	number	-
`ratePct`requireddata.tax.ratePct	number	-
`taxAmount`requireddata.tax.taxAmount	number	-
`total`requireddata.tax.total	number	-
`treatment`requireddata.tax.treatment	string	-
`label`requireddata.tax.label	string	-
`note`requireddata.tax.note	string \| null	-
`taxId`requireddata.tax.taxId	string \| null	-
`taxCountry`requireddata.tax.taxCountry	string \| null	-
`homeCountry`requireddata.tax.homeCountry	string	-

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

Name	In	Type	Description
`customerId`	query	string (uuid)	A sub-account you operate; omit for your own wallet

Response 200

Field	Type	Description
`data`required	object	-
`walletKind`requireddata.walletKind	string	-One of `user`, `sub_account`
`walletId`requireddata.walletId	string (uuid)	-
`label`requireddata.label	string	-
`currency`requireddata.currency	string	-
`postedBalance`requireddata.postedBalance	number	-
`creditLimit`requireddata.creditLimit	number	-
`creditLimitRecorded`requireddata.creditLimitRecorded	boolean	-
`reservedForActiveCalls`requireddata.reservedForActiveCalls	number	-
`settlementHolds`requireddata.settlementHolds	number	-
`pendingPayments`requireddata.pendingPayments	number	-
`promotionalCredit`requireddata.promotionalCredit	number	-
`confirmedFunds`requireddata.confirmedFunds	number	-
`availableToSpend`requireddata.availableToSpend	number	-
`overCommitted`requireddata.overCommitted	boolean	-
`negativeBalance`requireddata.negativeBalance	string	-One of `not_negative`, `within_agreed_credit`, `beyond_agreed_credit`
`beyondCreditBy`requireddata.beyondCreditBy	number	-
`activeCalls`requireddata.activeCalls	integer	-
`reservationEnforced`requireddata.reservationEnforced	boolean	True when reservations actually gate new calls, not just observe them
`creditNote`requireddata.creditNote	string	-
`sources`requireddata.sources	object	-

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

Name	In	Type	Description
`customerId`	query	string (uuid)	A sub-account you operate; omit for your own wallet

Response 200

Field	Type	Description
`data`required	object	-
`calls`requireddata.calls	object[]	-
`callUuid`requireddata.calls[].callUuid	string	-
`amount`requireddata.calls[].amount	number	-
`expiresAt`requireddata.calls[].expiresAt	string (date-time)	ISO-8601 timestamp (UTC)
`total`requireddata.total	number	-
`enforced`requireddata.enforced	boolean	-

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

Name	In	Type	Description
`customerId`	query	string (uuid)	A sub-account you operate; omit for your own wallet

Response 200

Field	Type	Description
`data`required	object	-
`walletKind`requireddata.walletKind	string	-One of `user`, `sub_account`
`walletId`requireddata.walletId	string (uuid)	-
`label`requireddata.label	string	-
`currency`requireddata.currency	string	-
`postedBalance`requireddata.postedBalance	number	-
`openingBalance`requireddata.openingBalance	object	-
`amount`requireddata.openingBalance.amount	number	-
`documented`requireddata.openingBalance.documented	boolean	-
`note`requireddata.openingBalance.note	string	-
`components`requireddata.components	object[]	-
`key`requireddata.components[].key	string	-
`label`requireddata.components[].label	string	-
`amount`requireddata.components[].amount	number	-
`count`requireddata.components[].count	integer	-
`source`requireddata.components[].source	string	-
`explained`requireddata.explained	number	-
`unattributed`requireddata.unattributed	object	-
`amount`requireddata.unattributed.amount	number	-
`count`requireddata.unattributed.count	integer	-
`note`requireddata.unattributed.note	string	-
`unreconciled`requireddata.unreconciled	number	-
`hasUnreconciled`requireddata.hasUnreconciled	boolean	-
`unpostedUsage`requireddata.unpostedUsage	object	-
`amount`requireddata.unpostedUsage.amount	number	-
`calls`requireddata.unpostedUsage.calls	integer	-
`note`requireddata.unpostedUsage.note	string	-
`checkedAt`requireddata.checkedAt	string (date-time)	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

Name	In	Type	Description
`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

Field	Type	Description
`data`required	object	-
`rows`requireddata.rows	object[]	-
`id`requireddata.rows[].id	string	-
`state`requireddata.rows[].state	string	-One of `posted`, `pending`, `usage`
`at`requireddata.rows[].at	string (date-time)	ISO-8601 timestamp (UTC)
`kind`requireddata.rows[].kind	string	-
`label`requireddata.rows[].label	string	-
`amount`requireddata.rows[].amount	number	-
`balanceAfter`requireddata.rows[].balanceAfter	number \| null	-
`reference`requireddata.rows[].reference	string \| null	-
`callId`requireddata.rows[].callId	string \| null	-
`traceTo`requireddata.rows[].traceTo	string	-
`truncated`requireddata.truncated	boolean	-

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

Field	Type	Description
`data`required	object[]	-
`id`requireddata[].id	string (uuid)	-
`label`requireddata[].label	string	-
`currency`requireddata[].currency	string	-
`status`requireddata[].status	string	-
`postedBalance`requireddata[].postedBalance	number	-
`creditLimit`requireddata[].creditLimit	number	-
`confirmedFunds`requireddata[].confirmedFunds	number	-
`reservedForActiveCalls`requireddata[].reservedForActiveCalls	number	-
`activeCalls`requireddata[].activeCalls	integer	-
`availableToSpend`requireddata[].availableToSpend	number	-
`negativeWithinAgreedCredit`requireddata[].negativeWithinAgreedCredit	boolean	-
`beyondAgreedCredit`requireddata[].beyondAgreedCredit	boolean	-

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

Field	Type	Description
`data`required	object[]	-
`id`requireddata[].id	string (uuid)	-
`seq`requireddata[].seq	integer	Gap-free per-account sequence
`number`requireddata[].number	string	-
`period`requireddata[].period	string	YYYY-MM
`periodStart`requireddata[].periodStart	string (date-time)	ISO-8601 timestamp (UTC)
`periodEnd`requireddata[].periodEnd	string (date-time)	ISO-8601 timestamp (UTC)
`currency`requireddata[].currency	string	-
`subtotal`requireddata[].subtotal	string	Decimal string
`taxAmount`requireddata[].taxAmount	string	Decimal string
`total`requireddata[].total	string	Decimal string
`createdAt`requireddata[].createdAt	string (date-time)	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)

Field	Type	Description
`period`required	string	-

Response 201

Field	Type	Description
`data`required	object	-
`id`requireddata.id	string (uuid)	-
`seq`requireddata.seq	integer	Gap-free per-account sequence
`number`requireddata.number	string	-
`period`requireddata.period	string	YYYY-MM
`periodStart`requireddata.periodStart	string (date-time)	ISO-8601 timestamp (UTC)
`periodEnd`requireddata.periodEnd	string (date-time)	ISO-8601 timestamp (UTC)
`currency`requireddata.currency	string	-
`subtotal`requireddata.subtotal	string	Decimal string
`taxAmount`requireddata.taxAmount	string	Decimal string
`total`requireddata.total	string	Decimal string
`createdAt`requireddata.createdAt	string (date-time)	ISO-8601 timestamp (UTC)
`dataJson`requireddata.dataJson	object \| null	Frozen line items and the tax section as issued
`alreadyExisted`requireddata.alreadyExisted	boolean	-

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

Name	In	Type	Description
`id`required	path	string	-
`format`	query	string	html returns a printable pageOne of json, html

Response 200

Field	Type	Description
`data`required	object	-
`id`requireddata.id	string (uuid)	-
`seq`requireddata.seq	integer	Gap-free per-account sequence
`number`requireddata.number	string	-
`period`requireddata.period	string	YYYY-MM
`periodStart`requireddata.periodStart	string (date-time)	ISO-8601 timestamp (UTC)
`periodEnd`requireddata.periodEnd	string (date-time)	ISO-8601 timestamp (UTC)
`currency`requireddata.currency	string	-
`subtotal`requireddata.subtotal	string	Decimal string
`taxAmount`requireddata.taxAmount	string	Decimal string
`total`requireddata.total	string	Decimal string
`createdAt`requireddata.createdAt	string (date-time)	ISO-8601 timestamp (UTC)
`dataJson`requireddata.dataJson	object \| null	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.