APPENDIX A. Variables that can be used in an external invoice template

env.i_env

ID

env.name

Environment name

env.companyname

The conventional form for your company’s name

env.addr1

Company’s street address

env.addr2

…

env.addr3

…

env.addr4

…

env.contact_city

City where company is located

env.contact_email

Company contact person’s email address

env.contact_subdivision

Province/state where the company is located

env.contact_zip

Postal code for company’s location

env.country

Country name

env.description

Short description

env.email

Primary email contact

env.faxnum

Primary fax number

env.laddr1

Address where company name is legally registered

env.laddr2

…

env.lcountry

Country where company is legally registered

env.lcity

City where company is legally registered

env.lname

Legally recognized form of company’s name

env.lzip

Postal code for company’s registered location

env.iso_3166_2

Country subdivision code

env.iso_3166_1_a2

Country code

env.iso_4217

The internal currency

env.phone

Company’s primary telephone number

env.subdivision

Country subdivision name

env.tax_id

Locally designated tax number

env.tz

Time zone company operates in

env.web

Company’s web address

customer.i_customer

Customer’s unique numeric number

customer.i_customer_class

Numeric ID for customer Class assigned to customer

customer.i_customer_type

1 (Retail), 2 (Reseller), 3 (Distributor)

customer.i_lang

Localization language, 2 characters ISO639-1 code (examples: en, es)

customer.iso_4217

Customer’s currency

customer.address

Full address line

customer.address_line_2

The 2nd line of the customer’s address that contains the values from baddr2, baddr3, baddr4 and baddr5 fields. The values are separated by the ‘\n’ delimiter.

customer.balance

Customer’s balance at time of PDF generation

customer.billing_period

Defines customer’s invoicing frequency

customer.bp_charge_cc

Y or N defines if customer’s credit card is charged when invoice is generated

customer.companyname

The conventional form of company’s name

customer.cont1

Primary contact

customer.cont2

Alternative contact

customer.city

City name

customer.country

Country name

customer.creation_date

Date when customer was added to PortaBilling system

customer.credit_limit

Customer’s current credit limit

customer.custom_fields

Stores information about custom fields.

customer.custom_fields.my_custom_field

Value for a specific custom field name. For example, if a custom field name is “Country code,” this variable will be customer.custom_fields.${‘Country Code’}

customer.custom_fields.custom_field1, customer.custom_fields.custom_field2, customer.custom_fields.custom_fieldN

Value for the Nth customer field. The order number of the custom fields corresponds to the position of a custom field enabled for the customer class in PortaBilling.

For example, the custom field “Country Code” goes first in the Custom fields list, so the corresponding variable will be customer.custom_field1. Note that the number after “custom_field” should be added without spaces.

customer.discount_rate

Amount of discount applied to all of customer’s subscriptions by default

customer.email

Primary email contact

customer.faxnum

Primary fax number

customer.firstname

First name

customer.midinit

Middle name

customer.lastname

Last name

customer.lname

Either company name or first name + last name

customer.login

Customer self-care login

customer.name

Customer ID, defines customer name as it appears in the PortaBilling system

customer.notepad

Text entered in Notepad field on the web

customer.opening_balance

Customer’s starting balance

customer.out_date_format

customer.out_date_format

customer.out_date_time_format

Preferable date-time format

customer.out_time_format

Preferable time format

customer.phone1

Primary telephone number

customer.phone2

Alternative telephone number

customer.salutation

Something like ‘Mr.,’ ‘Ms.’

customer.state

Province/state name

customer.zip

Postal code

customer.tax_id

Locally-designated tax number

customer.TZ

Time zone

invoice.i_env

Environment ID

invoice.i_customer

Reference to customer’s ID number

invoice.i_invoice

ID number

invoice.invoice_number

Visible invoice number

invoice.i_invoice_status

Invoice status, refer to value from Invoice_Status_Attribs table

invoice.i_invoice_type

Indicates the type of invoice: 1 – regular, 2 – out of turn, 3 – midterm

invoice.additional_invoices

Sum of out-of-turn invoices for a period

invoice.adjustments

Adjusted amount customer must pay for this period

invoice.amount_due

The current amount due of the invoice

invoice.amount_net

Invoice period’s total amount

invoice.amount_paid

Amount customer already paid

invoice.calls

Sum of charges for all other services

invoice.cust_name

Name of the customer for whom the invoice was issued

invoice.do_not_pay

This indicates that the invoice amount is too low to charge the customer, therefore the invoice amount is added to the next invoice.

invoice.due_date

Due date of the invoice in the format defined by the customer

invoice_due_date_orig

The invoice due date defined in the ISO format (YYYY-MM-DD)

invoice.closed

Indicates whether the invoice is closed (sent to the customer) or not.

invoice.issue_date

Date when an invoice was created, displayed in a format defined by the customer

invoice.issue_date_orig

Date when an invoice was created, displayed in ISO format (YYYY-MM-DD)

invoice.invoice_status_desc

Invoice status description

invoice.is_void

N for normal invoices; Y for voided ones

invoice.iso_4217

Currency

invoice.last_invoice

The amount due from the previous regular invoice

invoice.last_closing_date

Indicates the date the customer was closed after the invocie became overdue

invoice.last_notific_date

Indicates the date the invoice was first sent to the customer

invoice.last_recollect_date

Indicates the date the collection attempt was made (attempt to charge the customer’s credit card on file for the amount due).

invoice.last_resend_date

Indicates the date the invoice was resent to the customer

invoice.last_suspension_date

Indicates the date the customer was suspended after an invoice became overdue

invoice.last_warning_date

Indicates the date the notification email was sent to the customer informing about the service suspension

invoice.manual_charges

Sum of manual charges from invoice period

invoice.measured_services

Sum of charges for measured services

invoice.new_style

Defines whether the invoice includes the previous balance or not

invoice.override_control

1 indicates that this is an invoice to charge for recurring fees separately

invoice.period_from

Invoice period’s start date

invoice.period_from_orig

Invoice period’s start date, displayed in ISO format (YYYY-MM-DD HH:MI:SS) and the UTC time zone

invoice.period_to_orig

Invoice period’s end date, displayed in ISO format (YYYY-MM-DD HH:MI:SS) and the UTC time zone

invoice.period_to

Invoice period’s end date

invoice.payments

Sum of payments made during invoice period

invoice.previous_balance

The amount due from the previous regular and out-of-turn invoices

invoice.prior_balance

Amount charged to customer before the first invoice issued. It might be that invoicing for this customer was initially disabled.

invoice.prior_balance_paid

Amount customer paid before the first invoice was issued.

invoice.subscriptions

Sum of subscription charges generated during invoice period

invoice.subtotal

Equal to amount_net. Available only if taxation plug-in used

invoice.subtotal_without_taxes

Equal to (amount_net – taxes). Available only if taxation plug-in used

invoice.taxes

Sum of taxes, non-zero only if taxation plugin used

services

Array indexed by i_service number

i_service

Unique ID number for service

name

Service name

i_service_type

Unique ID number for service type

rating_base

An attribute used for billing. Depends on the service type selected while creating the service. Possible values: session-time, quantity, unit, upload, download, upload+download.

period_totals

• period_totals.records

Total number of records for a specific service.

The period_totals.records is the total number of records for a specific service that are contained in all invoices for the billing period, e.g., the regular and the out-of-turn invoices. To get the total number of records contained in this invoice only, use invoice_totals.records.

• period_totals.quantity

Total volume of a consumed service.

The period_totals.quantity is the total volume of a consumed service contained in all invoices for the billing period, e.g., the regular and the out-of-turn invoices. To get the total volume of a consumed service contained in this invoice only, use invoice_totals.quantity.

• period_totals.amount

Total charges for a specific service.

The period_totals.amount is the total charges for a specific service contained in all invoices for the billing period, e.g., the regular and the out-of-turn invoices. To get the total of the charged amount contained in this invoice only, use invoice_totals.amount.

• period_totals.tax_amount

Total sum of taxes for a specific service.

The period_totals.tax_amount is the total tax amount for a specific service contained in all invoices for the billing period, e.g., the regular and the out-of-turn invoices.

• period_totals.total_amount

Total sum of charges and taxes for a specific service.

The period_totals.total_amount is the total amount of charges and taxes for a specific service contained in all invoices for the billing period, e.g., the regular and the out-of-turn invoices.

invoice_totals

• invoice_totals.records

Total number of records for a specific service contained in this specific invoice.

• invoice_totals.quantity

Total volume of consumed service contained in this specific invoice.

• invoice_totals.amount

Total charges for a specific service contained in this specific invoice.

next_row

Iterator, which returns next xDRs’ row for this service, or undefined if there are no more records

next_row_simple

Iterator, which returns next xDRs’ row for this service, or undefined if there are no more records. The iterator returns simplified xDR information:

• xDRs’ time is in UTC and ISO format.
• There is no information about auxiliary xDR fields (for example, xdr_xcld, xdr_media_duration, xdr_merge_origin.)

rating_base_unit

Name of the smallest unit for measuring service usage. This is also the smallest unit you can use in rating configuration (e.g., one second)

rate_unit

Name of the unit for calculating service usage charges (e.g., one minute)

taxation_codes

Taxation codes defined for this service

account_id

Master account ID

account_batch

Account batch name

account_i_account

Account’s unique ID

account_name

Account owner’s name specified in the Contact field in PortaBilling (Account > Personal info > General info > Contact)

country_iso_3166_1_a2

Country code

country_name

Country corresponding to destination

country_subdivision_name

Country subdivision corresponding to destination

destination_destination

Destination used

destination_description

Destination description

destination_group_name

Destination group name

destination_i_dest

Destination’s unique ID

rate_i_rate

Rate ID used

rate_effective_from

Date when rate becomes effective

rate_is_off_peak

‘Y’ for off-peak period rate, ‘N’ otherwise

rate_interval_1

Rates.interval_1 (Rates.op_interval_1 for off-peak)

rate_interval_n

Rates.interval_n (Rates.op_interval_n for off-peak)

rate_price_1

Rates.price_1 (Rates.op_price_1 for off-peak)

rate_price_n

Rates.price_n (Rates.op_price_n for off-peak)

rate_off_peak_period

0, 1, 2 for ‘normal,’ off-peak and second off-peak periods

tariff_i_tariff

Tariff ID used

tariff_name

Tariff name used

xdr_account_id

Account ID in xDR, may be account alias

xdr_accumulated_correction

Difference between initial and re-rated xDRs’ amounts

xdr_bill_time

Date-time of session billing, displayed in customer’s format

xdr_bill_time_orig

Date-time of session billing, displayed in ISO format

xdr_bit_flags

Bit flags provide additional information about how the service was used by the type of xDR. The xdr_bit_flags value is a number that represents some peculiarities of the xDR (e.g., 68 – outgoing recorded call, 1 – debit overdraft). See more details on bit flag usage in the PortaBilling API guide

xdr_call_id

Call-id

xdr_charged_amount

Charged amount

xdr_charged_quantity

Service quantity charged

xdr_cli

CLI

xdr_cld

CLD

xdr_connect_time

Connection date-time defined in customer format

xdr_connect_time_orig

Connection date-time defined in ISO format (YYYY-MM-DD HH:MM:SS)

xdr_disconnect_time

Date-time when session is disconnected, displayed in customer’s format

xdr_disconnect_time_orig

Date-time when session is disconnected, displayed in ISO format (YYYY-MM-DD HH:MM:SS)

xdr_h323_conf_id

H323-conf-id

xdr_h323_incoming_conf_id

Incoming H323-conf-id

xdr_history

Additional information about xDR

xdr_id

ID of xDR

xdr_peak_level

Peak level applied

xdr_setup_time

Time (in mins.) between initial provisional response and connect_time.

xdr_split_order

Sequential number if xDR is part of a group of xDRs resulting from the same session

xdr_subscriber_ip

Subscriber IP

xdr_table

Table name: cdr_accounts or cdr_customers

xdr_used_quantity

Service quantity used

xdr_acli

Information about actual caller identity within PBX environment where call originated from. This identity may differ from the one delivered by the cloud PBX (e.g., the cloud PBX main account or caller’s phone if forwarded calls occurred) and displayed on the called party’s device

xdr_xcld

Information about the extension ID dialed

xdr_xcli

Information about the extension ID initiating the call

xdr_via_hg

Information about the huntgroup dispatching the call

xdr_via_ext

Information about the last extension ID the call was either forwarded or transferred from

xdr_media_duration

Information about an actual time during which the owner of the billed account spoke

xdr_prerated_charge

Information about original charges imported to PortaBilling associated with xDR

xdr_e212_roaming_network

Information about caller/callee roaming ID in E.212 format

image_path

Path to the template images used to make a full link to the included image

xrate_list

Enables the retrieval of exchange rate for the currency and calculates the price there. This variable requires the key that equals the iso_4217 code of the required currency (e.g., xrate_list.EUR)