bill.php¶

Billing management module for handling customer services, invoices, billing lists, and CSV exports.

API Methods¶

Method	Action	Description
`billing_list`	get billing records list	Retrieves a list of billing records for a specific service with optional filtering and sorting.
`customer_billings_export`	export customer billings to CSV	Generates a CSV export of all billing records for the authenticated customer.
`customer_billings_list`	get customer billings list	Returns a list of billing records for the currently authenticated customer.
`customer_invoice_billings`	get billings for specific invoice	Retrieves all billing records associated with a specific invoice ID.
`customer_prebill_invoice_ids`	get pre-billing invoice IDs	Returns a list of available pre-billing invoice IDs for the authenticated customer.
`customer_services_get`	get billing record by id or ident key	Retrieves detailed information about a specific customer service/billing record.
`customer_services_list`	get customer services list	Returns a paginated list of services for the authenticated user with various filters.
`server_billings_list`	get server billings list	Retrieves a list of billing records associated with a specific server.
`services_list`	get services list	Returns a list of available services from the system options.

bill/billing_list¶

Retrieves a list of billing records for a specific service with optional filtering and sorting.

HTTP method: POST

Parameters:

Parameter	Required	Type	Description
action	✅	string	Method identifier: `billing_list`
token	✅	string	Authentication token.
params[service_id]	✅	integer	The ID of the service to filter billings for.
params[period_start]	❌	string	Start date for filtering. Accepted formats: YYYY-MM-DD HH:MM:SS, YYYY-MM-DD HH:MM, YYYY-MM-DD.
params[period_end]	❌	string	End date for filtering. Accepted formats: YYYY-MM-DD HH:MM:SS, YYYY-MM-DD HH:MM, YYYY-MM-DD.
params[start]	❌	integer	Pagination start offset.
params[items]	❌	integer	Number of items to return per page.
params[sort_order]	❌	string	Sorting order. Allowed values: ASC, DESC.
params[sort_type]	❌	string	Field to sort by. Allowed values: id, period_end, period_start, amount, invoice_id, invoice_paid.

Request example

curl -s "https://invapi.hostkey.com/bill.php" -X POST \
--data "action=billing_list" \
--data "token=HOSTKEY_TOKEN" \
--data "params[service_id]=123"

Success response example

{
"result": "OK",
"action": "billing_list",
"data": {
"items": [
{
"id": 123,
"amount": 49.99,
"currency": "EUR",
"period_start": "2024-01-01 00:00:00",
"period_end": "2024-02-01 00:00:00",
"invoice_id": 5,
"invoice_paid": 1
}
]
}
}

Error examples

{
"code": -1,
"message": "billing/billing_list: invalid param service_id"
}

bill/customer_billings_export¶

Generates a CSV export of all billing records for the authenticated customer.

HTTP method: POST

Parameters:

Parameter	Required	Type	Description
action	✅	string	Method identifier: `customer_billings_export`
token	✅	string	Authentication token.
customer_id	✅	integer	The ID of the customer for whom to export billing records.
skip_filters	✅	string	Параметр `skip_filters`

Request example

curl -s "https://invapi.hostkey.com/bill.php" -X POST \
--data "action=customer_billings_export" \
--data "token=HOSTKEY_TOKEN" \
--data "customer_id=VALUE" \
--data "skip_filters=VALUE"

Success response example

{
"result": "OK",
"action": "customer_billings_export",
"csv": "Date;Period Start;Period End;Service;Service Type;Entity ID;Region;Invoice;Status;Amount;Currency\n2024-01-01;;2024-02-01;VPS;Standard;123;US;#1;Paid;50.00;EUR",
"filename": "billing_export_2024-01-01_12-00-00.csv",
"records": 1,
"currency": "EUR"
}

Error examples

{
"code": -1,
"message": "customer_id is required"
}

bill/customer_billings_list¶

Returns a list of billing records for the currently authenticated customer.

HTTP method: POST

Parameters:

Parameter	Required	Type	Description
action	✅	string	Method identifier: `customer_billings_list`
token	✅	string	Authentication token.
customer_id	✅	integer	The unique identifier of the customer to retrieve billings for.

Request example

curl -s "https://invapi.hostkey.com/bill.php" -X POST \
--data "action=customer_billings_list" \
--data "token=HOSTKEY_TOKEN" \
--data "customer_id=VALUE"

Success response example

{
"result": "OK",
"action": "customer_billings_list",
"data": [
{
"id": 1,
"amount": 25.0,
"currency": "USD",
"accrual_state": "paid"
}
],
"totals": {
"total_amount": 25.0,
"paid_amount": 25.0,
"unpaid_amount": 0.0,
"accrued_amount": 0.0,
"debt_amount": 0.0
},
"currency": "USD"
}

Error examples

{
"code": -1,
"message": "$module/customer_billings_list: customer_id is required"
}

bill/customer_invoice_billings¶

Retrieves all billing records associated with a specific invoice ID.

HTTP method: POST

Parameters:

Parameter	Required	Type	Description
action	✅	string	Method identifier: `customer_invoice_billings`
token	✅	string	Authentication token.
id	❌	integer	Invoice ID (if not provided in params[invoice_id]).
params[invoice_id]	❌	integer	The specific invoice identifier.
invoice_id	✅	integer	Parameter `invoice_id` used to identify the invoice.

Request example

curl -s "https://invapi.hostkey.com/bill.php" -X POST \
--data "action=customer_invoice_billings" \
--data "token=HOSTKEY_TOKEN" \
--data "invoice_id=VALUE"

Success response example

{
"result": "OK",
"action": "customer_invoice_billings",
"data": [
{
"id": 10,
"amount": 15.0,
"currency": "EUR"
}
]
}

Error examples

{
"code": -1,
"message": "$module/$action: invoice_id is required"
}

bill/customer_prebill_invoice_ids¶

Returns a list of available pre-billing invoice IDs for the authenticated customer.

HTTP method: POST

Parameters:

Parameter	Required	Type	Description
action	✅	string	Method identifier: `customer_prebill_invoice_ids`
token	✅	string	Authentication token.

Request example

curl -s "https://invapi.hostkey.com/bill.php" -X POST \
--data "action=customer_prebill_invoice_ids" \
--data "token=HOSTKEY_TOKEN"

Success response example

{
"result": "OK",
"action": "customer_prebill_invoice_ids",
"invoice_ids": [
101,
102,
103
]
}

Error examples

{
"code": -1,
"message": "$module/$action: customer_id is required"
}

bill/customer_services_get¶

Retrieves detailed information about a specific customer service/billing record.

HTTP method: POST

Parameters:

Parameter	Required	Type	Description
action	✅	string	Method identifier: `customer_services_get`
token	✅	string	Authentication token.
params[id]	❌	integer	The internal ID of the service.
params[customer_id]	❌	integer	Customer identifier (automatically set for customers).
params[service_ident]	❌	string	The 10-character hex billing key.
customer_id	✅	int	Параметр `customer_id`
email	✅	string	Параметр `email`

Request example

curl -s "https://invapi.hostkey.com/bill.php" -X POST \
--data "action=customer_services_get" \
--data "token=HOSTKEY_TOKEN" \
--data "customer_id=VALUE" \
--data "email=VALUE"

Success response example

{
"result": "OK",
"action": "customer_services_get",
"service": {
"id": 5,
"entity_id": 12,
"customer_id": 45,
"server_data": {
"id": 12,
"name": "Server Name"
}
},
"customer": {
"id": 45,
"email": "[email protected]",
"name": "John Doe"
}
}

Error examples

{
"code": -1,
"message": "billing record not found"
}

bill/customer_services_list¶

Returns a paginated list of services for the authenticated user with various filters.

HTTP method: POST

Parameters:

Parameter	Required	Type	Description
action	✅	string	Method identifier: customer_services_list
token	✅	string	Authentication token.
params[id]	❌	integer	Filter by service ID.
params[email]	❌	string	Filter by customer email.
params[service_list_id]	❌	integer	Filter by service list ID.
params[period_end]	❌	string	End date filter (YYYY-MM-DD).
params[period_start]	❌	string	Start date filter (YYYY-MM-DD).
params[service_ident]	❌	string	Filter by service identifier.
params[start]	❌	integer	Pagination start offset.
params[items]	❌	integer	Number of items to return.
params[sort_order]	❌	string	Field to sort by. Allowed values: id, customer_id, period_end, period_start, service_ident, service_list_id.
params[sort_type]	❌	string	Sorting order. Allowed values: ASC, DESC.
params[key]	❌	string	Filter by 10-character billing key.
params[date_from]	❌	string	Start date filter (YYYY-MM-DD).
params[date_to]	❌	string	End date filter (YYYY-MM-DD).

Request example

curl -s "https://invapi.hostkey.com/bill.php" -X POST \
--data "action=customer_services_list" \
--data "token=HOSTKEY_TOKEN"

Success response example

{
"result": "OK",
"action": "customer_services_list",
"items": [
{
"id": 10,
"service_ident": "a1b2c3d4e5",
"status": "active"
}
]
}

Error examples

{
"code": -1,
"message": "invalid email"
}

bill/services_list¶

Returns a list of available services from the system options.

HTTP method: POST

Parameters:

Parameter	Required	Type	Description
action	✅	string	The name of the action to perform.

Request example

curl -s "https://invapi.hostkey.com/bill.php" -X POST \
--data "action=services_list"

Success response example

{
"result": "OK",
"action": "services_list",
"data": [
{
"id": 1,
"name": "VPS KVM Instance",
"price": {
"EUR": 5.0,
"USD": 5.5
}
},
{
"id": 2,
"name": "Dedicated Server Node",
"price": {
"EUR": 120.0,
"USD": 130.0
}
}
]
}

Error examples

{
"code": -2,
"message": "bill: action required"
}

bill/server_billings_list¶

Retrieves a list of billing records associated with a specific server.

HTTP method: POST

Parameters:

Parameter	Required	Type	Description
action	✅	string	Method identifier: `server_billings_list`
token	✅	string	Authentication token.
id	❌	integer	Server entity ID. If provided, it takes precedence over entity_id in params.
params[entity_id]	❌	integer	The ID of the server entity to retrieve billings for.
entity_id	✅	integer	The ID of the server entity for which billing records are retrieved.
scope_customer_id	✅	int	Параметр `scope_customer_id`

Request example

curl -s "https://invapi.hostkey.com/bill.php" -X POST \
--data "action=server_billings_list" \
--data "token=HOSTKEY_TOKEN" \
--data "entity_id=VALUE" \
--data "scope_customer_id=VALUE"

Success response example

{
"result": "OK",
"action": "server_billings_list",
"data": [
{
"id": 105,
"amount": 25.0,
"currency": "EUR",
"status": "paid",
"period_start": "2024-01-01 00:00:00",
"period_end": "2024-02-01 00:00:00"
}
]
}

Error examples

{
"code": -1,
"message": "bill/server_billings_list: entity_id is required"
}