API Reference
Start typing to search…

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 Deprecated in favor of clientId and companyId.

clientId string The ID of the client this invoice is assigned to.

companyId string 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.

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 of the product. This is not relevant for one-off line items.
  • 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",
    "clientId": "d0000000-d7a5-473d-a75b-9821a8f4e180",
    "companyId": "04a818c2-d035-495c-9cc2-06a11a8b91f6",
    "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
        }
    ]
}