`ptkl billing`

Manage billing for the current project — subscriptions, invoices, credit balance/top-ups, usage pricing, and per-project billing-mode overrides.

Overview

ptkl billing maps onto the SDK Transactions client (@ptkl/sdk/beta), reached via platform.billing() (an alias of platform.transactions()) — the transactions/… gateway prefix. This is the billing service (subscriptions, invoices, credits/pricing), not database/distributed transactions.

Subcommands

Subcommand	Description
`subscriptions`	List all subscriptions (including expired) for the current project
`invoices [uuid]`	List invoices, or get a single invoice by uuid
`invoice-pdf <uuid>`	Download an invoice as a PDF
`balance`	Get the current project's credit balance
`topup`	Generate a checkout link to top up the project's credit balance
`credits`	Get the project's credit activity (deductions/top-ups) history
`prices`	Get the usage-based pricing table for a given currency
`billing-modes`	Get, or set, the project's usage-billing-mode overrides

`ptkl billing subscriptions`

List all subscriptions (including expired) for the current project.

ptkl billing subscriptions

`ptkl billing invoices`

List invoices for the current project, or get a single invoice by uuid.

ptkl billing invoices [uuid]

Argument	Description
`[uuid]`	Invoice uuid — omit to list all invoices

# List all invoices
ptkl billing invoices

# Get a single invoice
ptkl billing invoices 3fae1c2e-...

`ptkl billing invoice-pdf`

Download an invoice as a PDF.

ptkl billing invoice-pdf <uuid> -o <file>

Option	Description
`<uuid>`	Invoice uuid (required)
`-o, --out <file>`	File path to write the PDF to (required)

ptkl billing invoice-pdf 3fae1c2e-... --out ./invoice.pdf

`ptkl billing balance`

Get the current project's credit balance.

ptkl billing balance

`ptkl billing topup`

Generate a checkout link to top up the project's credit balance.

ptkl billing topup -a <cents> [-c <currency>]

Option	Description
`-a, --amount-cents <cents>`	Purchase amount in USD cents (e.g. `1000` = $10.00) (required)
`-c, --currency <currency>`	ISO 4217 currency code (defaults to USD server-side)

ptkl billing topup --amount-cents 5000 --currency USD

`ptkl billing credits`

Get the project's credit activity (deductions/top-ups) history.

ptkl billing credits [-l <n>] [--offset <n>] [-t <type>] [-y <year>] [-m <month>]

Option	Description
`-l, --limit <n>`	Max rows to return (server default 50, capped at 200)
`--offset <n>`	Row offset for pagination
`-t, --type <type>`	Filter by entry type (e.g. `deduction` \| `topup`)
`-y, --year <year>`	Filter by year
`-m, --month <month>`	Filter by month

ptkl billing credits --type deduction --year 2026 --month 7 --limit 100

`ptkl billing prices`

Get the usage-based pricing table for a given currency.

ptkl billing prices -c <currency>

Option	Description
`-c, --currency <currency>`	ISO 4217 currency code, e.g. `USD` or `RSD` (required)

ptkl billing prices --currency USD

`ptkl billing billing-modes`

Get the project's usage-billing-mode overrides, or set one with --option-code/--mode.

ptkl billing billing-modes [--option-code <code> --mode <mode>] [-d <json>]

Option	Description
`--option-code <code>`	Usage option code to update (requires `--mode`, or use `-d/--data`)
`--mode <mode>`	Billing mode to set: `credits` \| `hybrid` \| `invoice` (requires `--option-code`)
`-d, --data <json>`	Update payload as a JSON string (`{ option_code, mode }`) — alternative to `--option-code`/`--mode`

# Get current overrides
ptkl billing billing-modes

# Set an override
ptkl billing billing-modes --option-code sandbox-compute --mode hybrid

# Equivalent, via --data
ptkl billing billing-modes --data '{"option_code":"sandbox-compute","mode":"hybrid"}'

Typical Workflow

# 1. Check the current balance and top up if low
ptkl billing balance
ptkl billing topup --amount-cents 5000

# 2. Review usage pricing and credit activity
ptkl billing prices --currency USD
ptkl billing credits --year 2026 --month 7

# 3. Pull an invoice for accounting
ptkl billing invoices
ptkl billing invoice-pdf <invoice-uuid> --out ./invoice.pdf

# 4. Switch a usage option to invoice-based billing
ptkl billing billing-modes --option-code sandbox-compute --mode invoice

ptkl billing

Overview

Subcommands

ptkl billing subscriptions

ptkl billing invoices

ptkl billing invoice-pdf

ptkl billing balance

ptkl billing topup

ptkl billing credits

ptkl billing prices

ptkl billing billing-modes