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

idstring

The unique identifier for this item.

createdAtstring

The date this item was created in RFC3339 format.

updatedAtstring

The date this item was updated in RFC3339 format.

objectstring

The object type of this resource.

collectionMethodstring

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.

currencystring

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

dueDatestring

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

memostring

The memo added to the invoice.

numberstring

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

recipientIdstring

Deprecated in favor of clientId and companyId.

clientIdstring

The ID of the client this invoice is assigned to.

companyIdstring

The ID of the company this invoice is assigned to. When the invoice is assigned to an individual this represents which of the client’s companies this invoice is associated with.

addressobject | null

Optional billing address associated with the invoice.

The two-letter country code for the address.

The state, province, or region for the address.

The postal or ZIP code for the address.

The first line of the street address.

The city for the address.

The formatted mailing address, including line breaks.

sentDatestring

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

paymentSuccessDatestring

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.

statusstring

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

Status Description
draft When 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.
open This invoice is ready for payment. Open invoices can not be edited.
paid This invoice has been paid. A successful payment was received or the invoice was marked as manually paid.
void This invoice has been voided. Only open invoices can be voided.

taxPercentagenumber

The percentage of tax set on this invoice.

taxAmountnumber

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

totalnumber

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

lineItemsarray(lineItems)

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

The description of the product. This is not relevant for one-off line items.

How many units of this item are being invoiced

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.

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.

paymentMethodPreferencesArray(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:

Payment method type. Values are creditCard or bankAccount

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

Example Invoice Object

{
    "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",
    "clientId": "d0000000-d7a5-473d-a75b-9821a8f4e180",
    "companyId": "04a818c2-d035-495c-9cc2-06a11a8b91f6",
    "address": {
        "country": "US",
        "region": "Oregon",
        "postalCode": "97818",
        "addressLine1": "312 Boardman Avenue Northeast",
        "city": "Boardman",
        "fullAddress": "312 Boardman Avenue Northeast\nBoardman, Oregon, 97818\nUnited States"
    },
    "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
        }
    ],
    "updatedAt": "2024-06-06T18:08:05.618445Z"
}