Invoices

This resource represents an invoice. An invoice can be created one-off or as part of a recurring subscription.

An invoice consists of line items which can be connected to Products & Prices or be one-off items.

All amounts are in the minor unit of the currency. For example, 1000 represents $10.00 for USD, £10.00 for GBP, or ¥1000 for JPY.

Properties

id string
The unique identifier for this item.

createdAt string
The date this item was created in RFC3339 format.

object string
The object type of this resource.

collectionMethod string
How the payment for this invoice is collected. It will be sendInvoice when an invoice is sent to a recipient for payment. It will be chargeAutomatically if the invoice is charged at the time of creation.

currency string
The 3 letter currency code representing the settlement currency for this invoice.

dueDate string
The date when this invoice is due in RFC3339 format. This only applies when the collectionMethod is sendInvoice.

memo string
The memo added to the invoice.

number string
A unique number generated for this invoice. Invoice numbers are commonly used for accounting purposes.

recipientId string
The ID of the recipient of the invoice. This can either be a Client or a Company.

sentDate string
The date this invoice was sent to a client in RFC3339 format.

paymentSuccessDate string
The date this invoice was paid in RFC3339 format. This property is only set when there is a successful payment associated with an invoice. When an invoice is marked as manually paid, there is no associated payment so this property is ignored.

status string
The status of the invoice. One of draft, open, paid, void.

StatusDescription
draftWhen an invoice is duplicated it will initially be in a draft state. In this state the invoice is not yet visible to the recipient. This gives you the opportunity to modify the invoice before sending it.
openThis invoice is ready for payment. Open invoices can not be edited.
paidThis invoice has been paid. A successful payment was received or the invoice was marked as manually paid.
voidThis invoice has been voided. Only open invoices can be voided.

taxPercentage number
The percentage of tax set on this invoice.

taxAmount number
The amount of tax on this invoice based on the percentage amount and lineItems.

total number
The total amount of this invoice to be paid. This is the total of the lineItems and taxAmount.

lineItems array(lineItems)

  • amount number 
    The amount for a single unit of this line item. The total amount due for this line item is the product of this amount and quantity
  • description string
    The description given to this line item
  • quantity number
    How many units of this item are being invoiced
  • priceId string
    The ID of the price that this line item is based off. The amount property is set based on the amount of specified on the Price. This is not relevant for one-off line items.
  • productId string
    The ID of the product that this line item is based off. The description property is set based on the description of set on the product. This is not relevant for one-off line items.

paymentMethodPreferences Array(object)
Array of payment method configurations that specify which payment methods are allowed and how transaction fees are handled for each method.

Each object in the array contains:

  • type string
    Payment method type. Values are creditCard or bankAccount
  • feePaidByClient boolean
    When true, the transaction fee is paid by the client. When false, the fee is absorbed by the business.

fileUrl: string
Link to download invoice PDF

receiptNumber: string
Invoice receipt number if invoice is paid.

receiptUrl: string
Link to download invoice receipt PDF, if invoice is paid.

billingReason: string | null
Indicates the reason why the invoice was created.

Values can be

  • manual
  • subscriptionCreate
  • subscriptionCycle
  • subscriptionUpdate
    • For subscription invoices, this field will have non-empty value for invoices created after Jan. 29th 2025.

{
    "collectionMethod": "sendInvoice",
    "createdAt": "2024-06-06T18:08:05.618445Z",
    "currency": "usd",
    "dueDate": "2024-06-14T18:08:01.292Z",
    "id": "in_1POkjGFdviIHOKAncZ4XrBe0",
    "lineItems": [
        {
            "amount": 10000,
            "description": "Product A",
            "priceId": "F0tsrfYSg",
            "productId": "aae1c02f-c524-4601-bbcb-34d6379e76e3",
            "quantity": 1
        }
    ],
    "memo": "Invoice amount",
    "number": "",
    "object": "invoice",
    "recipientId": "fe818b15-431f-4e8b-82b6-85574ef35820",
    "sentDate": "2024-06-06T14:08:05.618421-04:00",
    "status": "draft",
    "taxAmount": 0,
    "taxPercentage": 0,
    "total": 10000,
    "receiptNumber": "",
    "receiptUrl": "",
    "fileUrl": "<url to download file>",
    "billingReason": "manual",
    "paymentMethodPreferences": [
        {
            "type": "creditCard",
            "feePaidByClient": false
        },
        {
            "type": "bankAccount",
            "feesPaidByClient": true
        }
    ]
}