API Reference

Invoice object

Invoices are the record of payments made or due by a client, these can be generated by a subscription or uniquely.

Invoice object atributes


id

string
Unique object's identifier.


customer

string
The ID of the customer who will be billed. In read resources this field is expandable, returns the customer object.


number

number
A unique, identifying number that appears on invoice header sent to the customer of this invoice. It's automatically assigned.


document

string
The ID of the document type for this invoice. Learn more about


test_mode

boolean
Has the value true if the object exists in production mode or the value false if the object exists in test mode.


date

date
Closing date of the invoice. Typically this is the date on which invoice is generated.


due_date

date
Due date of the invoice.


lines

list
The list of line items for this invoice.


payments

list
The list of transactions for this invoice.


amount

decimal
Taxable subtotal of this invoice.


exempt

decimal
Non taxable subtotal of this invoice.


tax

decimal
Tax amount of this invoice.


tax_percent

decimal
Tax rate for this invoice.


subtotal

decimal
Sum of amount and exempt of this invoice.


total

decimal
Sum of subtotal and taxes of this invoice.


discount

decimal
Discount amount applicable to subtotal of this invoice.


discount_scheme

string
Scheme of the discount, one of $ or %.


period_start

date
The time when the service period for the billing starts.


period_end

date
The time when the service period for the billing ends.


collection_method

string
Method to collect payments of this invoice, one of automatically, deferred or deferred_dues.


local_file

url
URL to local format when document type of this invoice belong to a tax agency.


note

string
A note for the customer of this invoice.


fiscal_settings

object
An object with key pairs for tax agency.


subscription

string
The id of subscription if this invoice was created by a subscription.


status

string
Status of this invoice, one of draft, finalized or paid. Learn more about


metadata

object
An object with key pairs for store custom information about this invoice.


user

string
Email of the user that created this invoice.


created

datetime
Date and time of the creation of this invoice.


Invoice object example

{
  "id": "inv_XsTY9J7C12iAD9Zc1J",
  "customer": {
    "id": "cus_APxT9s7X12ilP9Zx9O",
    "name": "Acme Nation LLC",
    "address": "17st, National Sub",
    "state": "IL",
    "country": "US",
    "phone": null,
    "email": "[email protected]",
    "website": "https://www.stark.com"
    "tax_settings": {},
    "metadata": {},
    "created": "2020-05-12 15:42:09",
    "updated": "2020-05-12 21:16:12"
  },
  "document": {
    "id": "US1",
    "name": "Invoice",
    "country": "US",
    "currency": "USD"
  },
  "number": 10923,
  "test_mode": false,
  "date": "2020-06-17",
  "due_date": "2020-07-12",
  "lines": [
    {
      "id": "lin_APxT9s7X12ilP9Zx9O",
      "name": "Acme App",
      "description": "Software services",
      "quantity": 4.0,
      "discount": 10.0
      "discount_scheme": "%"
    },
    ...
  ],
  "collection_method": "deferred_dues",
  "payments": [
    {
      "id": "pay_APxT9s7X12ilP9Zx9O",
      "amount": 50.5,
      "currency": "USD",
      "date": "2020-06-30",
      "description": "Invoice Nº 10923"
      "source": null,
      "payment_date": null,
      "customer": "cus_APxT9s7X12ilP9Zx9O",
      "invoice": "inv_XsTY9J7C12iAD9Zc1J",
      "status": "requires_payment_method",
      "metadata": {},
      "created": "2020-06-17 14:21:32",
      "updated": "2020-06-17 14:21:32"
    },
    ...
  ],
  "amount": 100.50,
  "exempt": 0,
  "tax": 0,
  "tax_percent": 0,
  "subtotal": 100.50,
  "discount": 10.0,
  "discount_scheme": "$",
  "total": 90.50,
  "period_start": null,
  "period_end": null,
  "local_file": null,
  "note": "Hint: Chargeable to 2020-07-12",
  "fiscal_settings": {},
  "status": "finalized",
  "metadata": {},
  "user": "[email protected]",
  "created": "2020-06-17 14:21:32",
  "updated": "2020-06-17 14:21:32"
}