Invoice Object

The Invoice Object represents a single billing record that tracks all charges, taxes, and payments for a given billing cycle. Each invoice includes detailed line items, tax information, payment records, and references to the associated partner.

Invoice Object Attributes

These fields and values make up the JSON object that gets returned with successful requests.

Attribute	Data Type	Description
amount read only	number	The amount on the invoice. This is not necessarily due at this time.
amount_due read only	number	The amount due. Includes current charges and any previously unpaid balance.
amount_tax read only	number	The taxes charged on the services included in the invoice.
balance_forward read only	number	The balance that will be used as balance_previous for the next invoice.
balance_previous read only	number	The previous balance on the invoice.
date_billing_period_end read only	string	The date and time when the billing period ends.
date_billing_period_start read only	string	The date and time when the billing period begins.
date_charge_expected read only	string	The date and time when the invoice will be charged.
date_charged read only	string	The date and time when the invoice was charged.
date_created read only	string	The date and time when the invoice was created.
date_issued read only	string	The date and time when the invoice was issued.
display_id read only	string	The ID on the rendered invoice.
invoice_items read only	array of objects	The details about each of the invoice items. Refer to the table below for more information.
invoice_sid read only	string	The invoice secure ID.
paid read only	boolean	Shows if the invoice has been paid. Values accepted in this field are: true and false.
partner read only	object	The Partner object associated with the invoice. This field is displayed if with_related is set to true when performing the GET queries.
partner_sid read only	string	The secure ID of the partner associated with the invoice.
pay_items read only	array of objects	The payments made while the invoice was open. Refer to the table below for more information.
status read only	string	The invoice status. Values accepted in this field are: charging for an invoice that is being charged. complete for an invoice that has been charged. created for an invoice that has been created. declined for an invoice that belongs to a partner without a billing method on file, or an invoice with a payment declined. error for a billing module received an error while processing the invoice; invoice may need to be processed manually. open for an open invoice. pending for an invoice that belongs to a partner with a billing method of check on file; this indicates that a check is anticipated. reviewing for an invoice that is awaiting manual approval. uncollectable for an invoice that will not be paid.
tax_items read only	array of objects	The tax items details. Refer to the table below for more information.

Sample Invoice Object

{
    "amount": "0.38",
    "amount_due": "0",
    "amount_tax": "0.32",
    "balance_forward": "-0.45",
    "balance_previous": "-351.91",
    "date_billing_period_end": "2025-01-19T23:59:59.000Z",
    "date_billing_period_start": "2024-12-20T00:00:00.000Z",
    "date_charge_expected": "2025-01-19T23:59:59.000Z",
    "date_charged": null,
    "date_created": "2024-12-19T23:30:01.000Z",
    "date_issued": null,
    "display_id": "004",
    "invoice_items": [
        {
            "amount": "0.37",
            "country_code": "USA",
            "date_billing_period_end": "2025-01-19T23:59:59.000Z",
            "date_billing_period_start": "2024-12-20T00:00:00.000Z",
            "direction": "inbound",
            "type": "toll",
            "usage": 8880
        },
        {
            "amount": "0",
            "country_code": "USA",
            "date_billing_period_end": "2023-07-04T23:59:59.000Z",
            "date_billing_period_start": "2023-06-06T00:00:00.000Z",
            "type": "sms_enablement",
            "usage": 1,
        }  
    ],
    "invoice_sid": "4169705e-4284-482f-8e72-e962a8aaad9d",
    "paid": false,
    "partner_sid": "ed437757-002d-4ecc-aa5a-efdf5e50dba0",
    "pay_items": [],
    "status": "open",
    "tax_items": [
        {
            "amount": "0.32",
            "jurisdiction": "federal",
            "type": "fed_universal_service_fund"
        }
    ]
}

Invoice Item Object

Attribute	Data Type	Description
amount read only	number	The invoice item price total.
country_code read only	string	The ISO 3166-1 alpha-3 code of the service type associated with this invoice item.
date_billing_period_end read only	string	The date and time when this item billing period ended.
date_billing_period_start read only	string	The date and time when this item billing period started.
direction read only	string	The direction of the call or SMS/MMS, either inbound or outbound.
type read only	string	The type of call, SMS/MMS, transcription, or text-to-speech used. Values accepted in this field are: adjustment bridge did did_lookup_carrier did_lookup_cnam did_lookup_lrn mms sms sms_enablement toll toll_free transcription_average transcription_high transcription_low tts
usage read only	integer	The number of times the item was used.

Invoice Pay Item Object

Attribute	Data Type	Description
amount read only	number	The amount of payment.
billing_method read only	object	The billing method that was used for the payment.
check_number read only	string	The check number that was used for the payment.
date_charged read only	string	The date and time when the payment was made.
pay_item_sid read only	string	The pay item secure ID.
status read only	string	The invoice payment status. Values accepted in this field are: complete declined error
type read only	string	The invoice payment type. Values accepted in this field are: balance_refund charge_back check check_refund credit credit_card credit_card_prepay credit_card_refund wire wire_refund

Invoice Tax Item Object

Attribute	Data Type	Description
amount read only	number	The amount of taxes.
jurisdiction read only	string	The invoice tax jurisdiction. Values accepted in this field are: county, county_local, federal, local, other, state, state_county_local, and unincorporated.
type read only	string	The invoice tax type. Values accepted in this field are: business_and_occupation_tax, ca_teleconnect_fund, carrier_gross_receipts, district_tax, district_tax_residential, e911_tax, e911_tax_business, e911_tax_pbx_trunk_line, e911_tax_residential, excise_tax, fed_telecommunications_relay_service, fed_universal_service_fund, fed_usf_a_school, federal_excise_tax, franchise_tax, license_tax, license_tax_business, ny_mctd_184a, ny_mctd_186c, optional_telecommunications_infrastructure_maintenance_fee, puc_fee, sales_tax, sales_tax_business, sales_web_hosting, service_tax, special_tax, state_deaf_and_disabled_fund, state_high_cost_fund, state_poison_control_fund, state_universal_service_fund, statutory_gross_receipts, surcharge, telecom_relay_surcharge, telecommunications_assistance_service_fund, telecommunications_infrastructure_fund, telecommunications_infrastructure_maintenance_fee, transit_tax, trs_business, universal_lifeline_telephone_service_charge, universal_service_fund_access_trunk_line, universal_service_fund_business_line, utility_users_tax, and utility_users_tax_business.