Invoices & Billing¶

16 endpoints. Authentication, errors, paging and rate limits are described once, in the API overview.

Action	Method	Description
`addbillableitem`	POST	Add a billable item for a client
`addinvoicepayment`	POST	Record a manual payment for an invoice
`addpaymethod`	POST	Add a stored payment method (not available)
`addtransaction`	POST	Add a manual transaction record
`capturepayment`	POST	Charge a stored payment method (not available)
`createinvoice`	POST	Create a new invoice
`deletepaymethod`	POST	Remove a stored payment method
`geninvoices`	POST	Generate the invoices that are due
`getcurrencies`	GET	List all configured currencies
`getinvoice`	GET	Get a single invoice with line items
`getinvoices`	GET	List invoices with optional filtering
`getpaymethods`	GET	List a client's stored payment methods
`gettransactions`	GET	List payment transactions with optional filtering
`updateinvoice`	POST	Update an existing invoice
`updatepaymethod`	POST	Rename a stored payment method or make it the default
`updatetransaction`	POST	Update a transaction

addbillableitem¶

Add a billable item for a client.

POST /api/v1/addbillableitem

Permission: create_invoices

Parameters

Name	Type	Required	Description
`clientid`	integer	yes	The client.
`description`	string	yes	Up to 255 characters.
`amount`	number	yes	The amount.
`duedate`	date	no	When to bill it.

Response

Field	Description
`result`	`success`
`billableitemid`	integer

Example

curl -X POST https://example.com/api/v1/addbillableitem \
  -H "X-API-Key: $PNLCS_IDENTIFIER" \
  -H "X-API-Secret: $PNLCS_SECRET" \
  --data-urlencode "clientid=1" \
  --data-urlencode "description=example" \
  --data-urlencode "amount=10.00"

addinvoicepayment¶

Record a manual payment for an invoice.

POST /api/v1/addinvoicepayment

Permission: create_invoices

Parameters

Name	Type	Required	Description
`invoiceid`	integer	yes	The invoice.
`transid`	string	yes	The payment reference. The same reference is never recorded twice.
`amount`	number	yes	At least 0.01.
`gateway`	string	no	The gateway it came through. Default banktransfer.

Response

Field	Description
`result`	`success`
`transactionid`	integer
`status`	string: the invoice status afterwards
`balance`	number: what is still owed
`duplicate`	boolean: true when transid had already been recorded

Errors

Status	When
404	No such invoice.
422	The payment could not be recorded.

Note

A part payment leaves the invoice partly paid; an overpayment becomes credit. When the invoice is paid, whatever waits on it (provisioning, unsuspension, an upgrade) runs.

Example

curl -X POST https://example.com/api/v1/addinvoicepayment \
  -H "X-API-Key: $PNLCS_IDENTIFIER" \
  -H "X-API-Secret: $PNLCS_SECRET" \
  --data-urlencode "invoiceid=1" \
  --data-urlencode "transid=example" \
  --data-urlencode "amount=10.00"

addpaymethod¶

Add a stored payment method (not available).

POST /api/v1/addpaymethod

Permission: create_invoices

Not available

Always answers 501: a card is stored through the gateway's own form, with the customer there for 3-D Secure. Card numbers never pass through PNLCS. The customer adds it in the client area.

addtransaction¶

Add a manual transaction record.

POST /api/v1/addtransaction

Permission: create_invoices

Parameters

Name	Type	Required	Description
`userid`	integer	yes	The client.
`description`	string	yes	What the transaction is.
`amountin`	number	no	Money received.
`amountout`	number	no	Money paid out.
`invoiceid`	integer	no	An invoice of this client.
`transid`	string	no	The reference.
`gateway`	string	no	The gateway.

Response

Field	Description
`result`	`success`
`transactionid`	integer

Note

A ledger line only. To pay an invoice, use addinvoicepayment.

Example

curl -X POST https://example.com/api/v1/addtransaction \
  -H "X-API-Key: $PNLCS_IDENTIFIER" \
  -H "X-API-Secret: $PNLCS_SECRET" \
  --data-urlencode "userid=1" \
  --data-urlencode "description=example"

capturepayment¶

Charge a stored payment method (not available).

POST /api/v1/capturepayment

Permission: manage_invoices

Not available

Always answers 501: charging a stored card from the API is not implemented. The payment is taken in the client area or by the automatic payment run.

createinvoice¶

Create a new invoice.

POST /api/v1/createinvoice

Permission: create_invoices

Parameters

Name	Type	Required	Description
`userid`	integer	yes	The client.
`items`	array	no	The lines: items[0][description], items[0][amount], items[0][taxed] (default true). Or send itemdescription1, itemamount1, itemtaxed1, itemdescription2, ... (up to 50). At least one line is required.
`date`	date	no	Invoice date. Default today.
`duedate`	date	no	Due date.
`paymentmethod`	string	no	A gateway module name.
`status`	string	no	draft, unpaid or paid.
`notes`	string	no	Notes printed on the invoice.

Response

Field	Description
`result`	`success`
`invoiceid`	integer
`total`	number

Errors

Status	When
422	No line was sent, or a line has no amount.

Note

Totals, tax and the client group discount are worked out as for any other invoice.

Example

curl -X POST https://example.com/api/v1/createinvoice \
  -H "X-API-Key: $PNLCS_IDENTIFIER" \
  -H "X-API-Secret: $PNLCS_SECRET" \
  --data-urlencode "userid=7" \
  --data-urlencode "items[0][description]=Hosting - October" \
  --data-urlencode "items[0][amount]=9.99" \
  --data-urlencode "duedate=2026-10-15"

deletepaymethod¶

Remove a stored payment method.

POST /api/v1/deletepaymethod

Permission: manage_invoices

Parameters

Name	Type	Required	Description
`clientid`	integer	yes	The client.
`paymethodid`	integer	yes	One of that client's stored methods.

Response

Field	Description
`result`	`success`
`paymethodid`	integer

Errors

Status	When
404	The client has no such payment method.

Note

PNLCS stops using it at once; the gateway is asked to forget it on the next run, as when the customer removes it.

Example

curl -X POST https://example.com/api/v1/deletepaymethod \
  -H "X-API-Key: $PNLCS_IDENTIFIER" \
  -H "X-API-Secret: $PNLCS_SECRET" \
  --data-urlencode "clientid=1" \
  --data-urlencode "paymethodid=1"

geninvoices¶

Generate the invoices that are due.

POST /api/v1/geninvoices

Permission: manage_invoices

Parameters

None.

Response

Field	Description
`result`	`success`
`generated`	integer
`skipped`	integer
`errors`	integer
`invoice_ids`	array of integers

Errors

Status	When
422	A filter (clientid, serviceids, domainids, addonids) was sent.

Note

Runs the invoice generation for every service that is due, like the daily cron. It cannot be limited to one client; to bill one client, use createinvoice.

Example

curl -X POST https://example.com/api/v1/geninvoices \
  -H "X-API-Key: $PNLCS_IDENTIFIER" \
  -H "X-API-Secret: $PNLCS_SECRET"

getcurrencies¶

List all configured currencies.

GET /api/v1/getcurrencies

Permission: list_invoices

Parameters

None.

Response

Field	Description
`result`	`success`
`currencies`	array of every currency

Example

curl -G https://example.com/api/v1/getcurrencies \
  -H "X-API-Key: $PNLCS_IDENTIFIER" \
  -H "X-API-Secret: $PNLCS_SECRET"

getinvoice¶

Get a single invoice with line items.

GET /api/v1/getinvoice

Permission: list_invoices

Parameters

Name	Type	Required	Description
`invoiceid`	integer	yes	The invoice.

Response

Field	Description
`result`	`success`
`invoice`	object: the invoice with its client and line items

Errors

Status	When
404	No such invoice.

Example

curl -G https://example.com/api/v1/getinvoice \
  -H "X-API-Key: $PNLCS_IDENTIFIER" \
  -H "X-API-Secret: $PNLCS_SECRET" \
  --data-urlencode "invoiceid=1"

getinvoices¶

List invoices with optional filtering.

GET /api/v1/getinvoices

Permission: list_invoices

Parameters

Name	Type	Required	Description
`userid`	integer	no	Only this client's invoices.
`status`	string	no	draft, unpaid, paid, partially_paid, overdue, cancelled, refunded, collections or payment_pending.
`limitstart`	integer	no	Where the page starts. Default 0.
`limitnum`	integer	no	Page size, 1 to 250. Default 25.

Response

Field	Description
`result`	`success`
`totalresults`	integer: rows matching the filters
`startnumber`	integer: where this page starts
`numreturned`	integer: rows on this page
`data`	array: the rows

Note

Newest first. Each invoice carries its client.

Example

curl -G https://example.com/api/v1/getinvoices \
  -H "X-API-Key: $PNLCS_IDENTIFIER" \
  -H "X-API-Secret: $PNLCS_SECRET"

getpaymethods¶

List a client's stored payment methods.

GET /api/v1/getpaymethods

Permission: list_invoices

Parameters

Name	Type	Required	Description
`clientid`	integer	yes	The client.

Response

Field	Description
`result`	`success`
`clientid`	integer
`paymethods`	array of {id, type, description, gateway_name, card_type, card_last_four, expiry_date, is_default, status}. Tokens and gateway customer ids are never returned.

Errors

Status	When
404	No such client.

Example

curl -G https://example.com/api/v1/getpaymethods \
  -H "X-API-Key: $PNLCS_IDENTIFIER" \
  -H "X-API-Secret: $PNLCS_SECRET" \
  --data-urlencode "clientid=1"

gettransactions¶

List payment transactions with optional filtering.

GET /api/v1/gettransactions

Permission: list_invoices

Parameters

Name	Type	Required	Description
`clientid`	integer	no	Only this client's transactions. userid is accepted too.
`invoiceid`	integer	no	Only this invoice's transactions.
`limitstart`	integer	no	Where the page starts. Default 0.
`limitnum`	integer	no	Page size, 1 to 250. Default 25.

Response

Field	Description
`result`	`success`
`totalresults`	integer: rows matching the filters
`startnumber`	integer: where this page starts
`numreturned`	integer: rows on this page
`data`	array: the rows

Example

curl -G https://example.com/api/v1/gettransactions \
  -H "X-API-Key: $PNLCS_IDENTIFIER" \
  -H "X-API-Secret: $PNLCS_SECRET"

updateinvoice¶

Update an existing invoice.

POST /api/v1/updateinvoice

Permission: manage_invoices

Parameters

Name	Type	Required	Description
`invoiceid`	integer	yes	The invoice.
`status`	string	no	draft, unpaid, paid, partially_paid, overdue, cancelled, refunded, collections or payment_pending.
`date`	date	no	Invoice date.
`duedate`	date	no	Due date.
`paymentmethod`	string	no	A gateway installed here.
`notes`	string	no	Notes.
`transid`	string	no	With status=paid: the payment reference.
`gateway`	string	no	With status=paid: the gateway it was paid through. Default manual.

Response

Field	Description
`result`	`success`
`invoiceid`	integer

Errors

Status	When
404	No such invoice.

Note

status=paid records the payment the way the admin area does (transaction, paid event, provisioning). status=cancelled hands back any credit applied. Other statuses only change the label.

Example

curl -X POST https://example.com/api/v1/updateinvoice \
  -H "X-API-Key: $PNLCS_IDENTIFIER" \
  -H "X-API-Secret: $PNLCS_SECRET" \
  --data-urlencode "invoiceid=1"

updatepaymethod¶

Rename a stored payment method or make it the default.

POST /api/v1/updatepaymethod

Permission: manage_invoices

Parameters

Name	Type	Required	Description
`clientid`	integer	yes	The client.
`paymethodid`	integer	yes	One of that client's stored methods.
`set_as_default`	boolean	no	Make it the default.
`description`	string	no	Rename it.

Response

Field	Description
`result`	`success`
`paymethodid`	integer
`is_default`	boolean

Errors

Status	When
404	The client has no such payment method.

Example

curl -X POST https://example.com/api/v1/updatepaymethod \
  -H "X-API-Key: $PNLCS_IDENTIFIER" \
  -H "X-API-Secret: $PNLCS_SECRET" \
  --data-urlencode "clientid=1" \
  --data-urlencode "paymethodid=1"

updatetransaction¶

Update a transaction.

POST /api/v1/updatetransaction

Permission: manage_invoices

Parameters

Name	Type	Required	Description
`transactionid`	integer	yes	The transaction.
`description`	string	no	What the transaction is.
`amount`	number	no	The amount received.

Response

Field	Description
`result`	`success`
`transactionid`	integer

Errors

Status	When
404	No such transaction.

Example

curl -X POST https://example.com/api/v1/updatetransaction \
  -H "X-API-Key: $PNLCS_IDENTIFIER" \
  -H "X-API-Secret: $PNLCS_SECRET" \
  --data-urlencode "transactionid=1"