Invoicing API

Invoices

15min

An invoice represents a balance owed to you by a Customer. Each invoice has a collection of line items that detail the products or services that are now due. An invoice can be in one of many different states depending on the due date, payments, and whether it was sent to or viewed by the customer.
Invoices can be marked as paid with Payments. Once the sum of all payments for an invoice is greater than or equal to the total then the invoice will be considered paid in full.
Invoice Object
JSON
{
  "id": 46225,
  "object": "invoice",
  "customer": 15444,
  "ship_to": null,
  "name": null,
  "currency": "usd",
  "draft": false,
  "closed": false,
  "paid": false,
  "status": "not_sent",
  "autopay": false,
  "attempt_count": 0,
  "next_payment_attempt": null,
  "subscription": null,
  "number": "INV-0016",
  "date": 1416290400,
  "due_date": 1417500000,
  "payment_terms": "NET 14",
  "purchase_order": null,
  "items": [
    {
      "id": 7,
      "object": "line_item",
      "catalog_item": null,
      "type": "product",
      "name": "Copy Paper, Case",
      "description": null,
      "quantity": 1,
      "unit_cost": 45,
      "amount": 45,
      "discountable": true,
      "discounts": [],
      "taxable": true,
      "taxes": [],
      "metadata": {}
    },
    {
      "id": 8,
      "object": "line_item",
      "catalog_item": "delivery",
      "type": "service",
      "name": "Delivery",
      "description": null,
      "quantity": 1,
      "unit_cost": 10,
      "amount": 10,
      "discountable": true,
      "discounts": [],
      "taxable": true,
      "taxes": [],
      "metadata": {}
    }
  ],
  "notes": null,
  "subtotal": 55,
  "discounts": [],
  "taxes": [
    {
      "id": 20554,
      "object": "tax",
      "amount": 3.85,
      "tax_rate": null
    }
  ],
  "total": 51.15,
  "balance": 51.15,
  "url": "https://dundermifflin.invoiced.com/invoices/IZmXbVOPyvfD3GPBmyd6FwXY",
  "payment_url": "https://dundermifflin.invoiced.com/invoices/IZmXbVOPyvfD3GPBmyd6FwXY/payment",
  "pdf_url": "https://dundermifflin.invoiced.com/invoices/IZmXbVOPyvfD3GPBmyd6FwXY/pdf",
  "updated_at": 1415229884,
  "created_at": 1415229884,
  "metadata": {},
  "payment_plan": null
}
{
  "id": 46225,
  "object": "invoice",
  "customer": 15444,
  "ship_to": null,
  "name": null,
  "currency": "usd",
  "draft": false,
  "closed": false,
  "paid": false,
  "status": "not_sent",
  "autopay": false,
  "attempt_count": 0,
  "next_payment_attempt": null,
  "subscription": null,
  "number": "INV-0016",
  "date": 1416290400,
  "due_date": 1417500000,
  "payment_terms": "NET 14",
  "purchase_order": null,
  "items": [
    {
      "id": 7,
      "object": "line_item",
      "catalog_item": null,
      "type": "product",
      "name": "Copy Paper, Case",
      "description": null,
      "quantity": 1,
      "unit_cost": 45,
      "amount": 45,
      "discountable": true,
      "discounts": [],
      "taxable": true,
      "taxes": [],
      "metadata": {}
    },
    {
      "id": 8,
      "object": "line_item",
      "catalog_item": "delivery",
      "type": "service",
      "name": "Delivery",
      "description": null,
      "quantity": 1,
      "unit_cost": 10,
      "amount": 10,
      "discountable": true,
      "discounts": [],
      "taxable": true,
      "taxes": [],
      "metadata": {}
    }
  ],
  "notes": null,
  "subtotal": 55,
  "discounts": [],
  "taxes": [
    {
      "id": 20554,
      "object": "tax",
      "amount": 3.85,
      "tax_rate": null
    }
  ],
  "total": 51.15,
  "balance": 51.15,
  "url": "https://dundermifflin.invoiced.com/invoices/IZmXbVOPyvfD3GPBmyd6FwXY",
  "payment_url": "https://dundermifflin.invoiced.com/invoices/IZmXbVOPyvfD3GPBmyd6FwXY/payment",
  "pdf_url": "https://dundermifflin.invoiced.com/invoices/IZmXbVOPyvfD3GPBmyd6FwXY/pdf",
  "updated_at": 1415229884,
  "created_at": 1415229884,
  "metadata": {},
  "payment_plan": null
}
﻿
Parameter
Type
Description
id
integer
The invoice's unique ID
object
string
Object type, invoice
customer
integer
Customer ID
name
string
Invoice name for internal use, defaults to "Invoice"
number
string
The reference number assigned to the invoice for use in the dashboard
autopay
boolean
AutoPay enabled?
currency
string
﻿3-letter ISO code﻿
draft
boolean
When false, the invoice is considered outstanding, or when true, the invoice is a draft
closed
boolean
When true, an invoice is closed and considered bad debt. No further payments are allowed.
paid
boolean
Indicates whether an invoice has been paid in full
status
string
Invoice state, one of draft, not_sent, sent, viewed, past_due, pending, paid, voided
attempt_count
integer
# of payment attempts
next_payment_attempt
timestamp
Next scheduled charge attempt, when in automatic collection
subscription
integer
Subscription ID if invoice came from subscription
date
timestamp
Invoice date
due_date
timestamp
Date payment is due by
payment_terms
string
Payment terms for the invoice, i.e. "NET 30"
purchase_order
string
The customer's purchase order number
items
array
Collection of Line Items
notes
string
Additional notes displayed on invoice
subtotal
number
Subtotal
discounts
array
Collection of Discounts
taxes
array
Collection of Taxes
total
number
Total
balance
number
Balance owed
ship_to
object
Shipipng Detail object
payment_plan
integer
Payment plan ID
url
string
URL to view the invoice in the billing portal
payment_url
string
URL for the invoice payment page
pdf_url
string
URL to download the invoice as a PDF
created_at
timestamp
Timestamp when created
updated_at
timestamp
Timestamp when updated
metadata
object
A hash of key/value pairs that can store additional information about this object.
Line Item Object
JSON
{
  "id": 8,
  "object": "line_item",
  "catalog_item": "delivery",
  "type": "service",
  "name": "Delivery",
  "description": null,
  "quantity": 1,
  "unit_cost": 10,
  "amount": 10,
  "discountable": true,
  "discounts": [],
  "taxable": true,
  "taxes": [],
  "metadata": {},
  "updated_at": 1616081811
}
{
  "id": 8,
  "object": "line_item",
  "catalog_item": "delivery",
  "type": "service",
  "name": "Delivery",
  "description": null,
  "quantity": 1,
  "unit_cost": 10,
  "amount": 10,
  "discountable": true,
  "discounts": [],
  "taxable": true,
  "taxes": [],
  "metadata": {},
  "updated_at": 1616081811
}
﻿
Parameter
Type
Description
id
integer
The line item's unique ID
object
string
Object type, line_item
catalog_item
string
Optional Item ID. Fills the line item with the name and pricing of the Item.
type
string
Optional line item type. Used to group line items by type in reporting
name
string
Title
description
string
Optional description
quantity
number
Quantity
unit_cost
number
Unit cost or rate
amount
number
Computed from quantity x unit_cost
discountable
boolean
Excludes amount from invoice discounts when false
discounts
array
Line item Discounts
taxable
boolean
Excludes amount from invoice taxes when false
taxes
array
Line item Taxes
plan
string
Plan ID, only present when type is plan
metadata
object
A hash of key/value pairs that can store additional information about this object.
Discount Object
Represents the application of a discount to an invoice or line item.
JSON
{
  "id": 20553,
  "object": "discount",
  "amount": 5,
  "coupon": null,
  "expires": null
}
{
  "id": 20553,
  "object": "discount",
  "amount": 5,
  "coupon": null,
  "expires": null
}
﻿
Parameter
Type
Description
id
integer
The discount's unique ID
object
string
Object type, discount
amount
number
Discount amount
coupon
object
Coupon the discount was computed from, if any
expires
timestamp
Time until discount expires, if any
Tax Object
Represents the application of tax to an invoice or line item.
Shell
{
  "id": 20554,
  "object": "tax",
  "amount": 3.85,
  "tax_rate": null,
  "updated_at": 1616081811
}
{
  "id": 20554,
  "object": "tax",
  "amount": 3.85,
  "tax_rate": null,
  "updated_at": 1616081811
}
﻿
Parameter
Type
Description
id
integer
The tax's unique ID
object
string
Object type, tax
amount
number
Tax amount
tax_rate
object
Tax Rate the tax was computed from, if any
Shipping Details Object
Represents the shipipng details of an invoice.
JSON
{
  "name": "Myron Williams",
  "attention_to": null,
  "address1": "2548  Bottom Lane",
  "address2": null,
  "city": "Monument Beach",
  "state": "MA",
  "postal_code": "02553",
  "country": "US",
  "updated_at": 1616081811
}
{
  "name": "Myron Williams",
  "attention_to": null,
  "address1": "2548  Bottom Lane",
  "address2": null,
  "city": "Monument Beach",
  "state": "MA",
  "postal_code": "02553",
  "country": "US",
  "updated_at": 1616081811
}
﻿
Parameter
Type
Description
name
string
Ship to name
attention_to
string
Used for ATTN: address line
address1
string
First address line
address2
string
Optional second address line
city
string
City
state
string
State or province
postal_code
string
Zip or postal code
country
string
﻿Two-letter ISO code﻿
Create a new invoice with this endpoint.
POST
Request
﻿
Parameter
Type
Description
customer
integer
Customer ID - required
name
string
Invoice name for internal use, defaults to "Invoice"
number
string
The reference number assigned to the invoice, defaults to next # in auto-numbering sequence
currency
string
﻿3-letter ISO code - defaults to account currency
autopay
boolean
AutoPay enabled? - inherited from customer by default
payment_terms
string
Payment terms for the invoice, i.e. "NET 30" - inherited from customer by default
purchase_order
string
The customer's purchase order number
date
timestamp
Invoice date - defaults to current timestamp
due_date
timestamp
Due date - computed from payment_terms when not supplied
draft
boolean
When false, the invoice is considered outstanding, or when true, the invoice is a draft
closed
boolean
Marks an invoice as closed
items
array
Collection of Line Items
notes
string
Additional notes displayed on invoice
discounts
array
Collection of Discounts
taxes
array
Collection of Taxes
ship_to
object
Shipipng Detail object
metadata
object
A hash of key/value pairs that can store additional information about this object.
attachments
array
A list of File IDs to attach to the invoice.
disabled_payment_methods
array
List of payment methods to disable for this invoice, i.e. ["credit_card", "wire_transfer"].
calculate_taxes
bool
Disables tax calculation, default is true
This endpoint retrieves a specific invoice.
GET
Request
Path Params
id
required
String
Query Parameters
expand
optional
String
Properties to expand
Header Parameters
Accept
optional
String
If you set the Accept header to application/pdf then the invoice PDF will be returned.
﻿
Use this endpoint to update an invoice.
PATCH
Request
Path Params
id
required
String
﻿
Parameter
Type
Description
name
string
Invoice name for internal use, defaults to "Invoice"
number
string
The reference number assigned to the invoice, defaults to next # in auto-numbering sequence
currency
string
﻿3-letter ISO code - defaults to account currency
date
timestamp
Invoice date - defaults to current timestamp
due_date
timestamp
Due date - computed from payment_terms when not supplied
payment_terms
string
Payment terms for the invoice, i.e. "NET 30" - inherited from customer by default
purchase_order
string
The customer's purchase order number
draft
boolean
When false, the invoice is considered outstanding, or when true, the invoice is a draft
sent
boolean
Marks an invoice as sent
closed
boolean
Marks an invoice as closed
items
array
Collection of Line Items
notes
string
Additional notes displayed on invoice
discounts
array
Collection of Discounts
taxes
array
Collection of Taxes
ship_to
object
Shipipng Detail object
metadata
object
A hash of key/value pairs that can store additional information about this object.
attachments
array
A list of File IDs to attach to the invoice. Replaces existing attachments. Not providing this keeps existing attachments.
disabled_payment_methods
array
List of payment methods to disable for this invoice, i.e. ["credit_card", "wire_transfer"].
calculate_taxes
bool
Recalculate taxes, default is false
This endpoint sends an invoice to your customer.
POST
Request
Path Params
id
required
String
﻿
Parameter
Type
Description
to
array
Optional array of recipients like:[{"name": "Client", "email": "[email protected]"}]
bcc
string
Optional comma-separated list of email addresses to be blind carbon copied
template
string
Optional email template ID, otherwise a standard email template is selected
subject
string
Optional subject to override the template
message
string
Optional message body to override the template
This endpoint sends an invoice by SMS to a customer using Twilio. Twilio must be connected to Invoiced for requests to succeed.

Text messages can only be sent to customer contacts marked as sms_enabled.
POST
Request
Path Params
id
required
String
Body Parameters
message
required
String
Full text of message
to
required
Array
Array of recipients like: [{"phone": "11234567890", "name": "Bob Loblaw"}]
﻿
This endpoint sends an invoice by mail to a customer using Lob. Lob must be connected to Invoiced for requests to succeed.

There are no request parameters; the letter will automatically be sent to the customer's billing address.
POST
Request
Path Params
id
required
String
﻿
When an invoice is automatically collected we will perform the charge automatically. If a payment attempts fails then another attempt will be scheduled according to your retry settings. Or, you can trigger a charge attempt manually using this endpoint.
POST
Request
Path Params
id
required
String
﻿
This endpoint retrieves a list of files attached to a specific invoice.
GET
Request
Path Params
id
required
String
﻿
Consolidate all of a customer's open invoices to a single invoice with this endpoint.

Requests will fail if there are no invoices to consolidate, or if the customer does not have consolidation enabled.
GET
Request
Path Params
id
required
String
Body Parameters
cutoff_date
optional
Integer
﻿
Use this endpoint to void an invoice.
POST
Request
Path Params
id
required
String
﻿
This endpoint deletes a specific invoice.
DELETE
Request
Path Params
id
required
String
﻿
This endpoint retrieves all invoices.
GET
Request
Query Parameters
sort
optional
String
Column to sort by, i.e. name asc
filter
optional
Object
Filter object
metadata
optional
String
Metadata filter object
start_date
optional
Integer
Restricts the results to invoices on or after the given timestamp
end_date
optional
Integer
Restricts the results to invoices on or before the given timestamp
updated_after
optional
Integer
Only gets records updated after the given timestamp
﻿
﻿

Parameter	Type	Description
id	integer	The invoice's unique ID
object	string	Object type, invoice
customer	integer	Customer ID
name	string	Invoice name for internal use, defaults to "Invoice"
number	string	The reference number assigned to the invoice for use in the dashboard
autopay	boolean	AutoPay enabled?
currency	string	3-letter ISO code
draft	boolean	When false, the invoice is considered outstanding, or when true, the invoice is a draft
closed	boolean	When true, an invoice is closed and considered bad debt. No further payments are allowed.
paid	boolean	Indicates whether an invoice has been paid in full
status	string	Invoice state, one of draft, not_sent, sent, viewed, past_due, pending, paid, voided
attempt_count	integer	# of payment attempts
next_payment_attempt	timestamp	Next scheduled charge attempt, when in automatic collection
subscription	integer	Subscription ID if invoice came from subscription
date	timestamp	Invoice date
due_date	timestamp	Date payment is due by
payment_terms	string	Payment terms for the invoice, i.e. "NET 30"
purchase_order	string	The customer's purchase order number
items	array	Collection of Line Items
notes	string	Additional notes displayed on invoice
subtotal	number	Subtotal
discounts	array	Collection of Discounts
taxes	array	Collection of Taxes
total	number	Total
balance	number	Balance owed
ship_to	object	Shipipng Detail object
payment_plan	integer	Payment plan ID
url	string	URL to view the invoice in the billing portal
payment_url	string	URL for the invoice payment page
pdf_url	string	URL to download the invoice as a PDF
created_at	timestamp	Timestamp when created
updated_at	timestamp	Timestamp when updated
metadata	object	A hash of key/value pairs that can store additional information about this object.

Parameter	Type	Description
id	integer	The line item's unique ID
object	string	Object type, line_item
catalog_item	string	Optional Item ID. Fills the line item with the name and pricing of the Item.
type	string	Optional line item type. Used to group line items by type in reporting
name	string	Title
description	string	Optional description
quantity	number	Quantity
unit_cost	number	Unit cost or rate
amount	number	Computed from quantity x unit_cost
discountable	boolean	Excludes amount from invoice discounts when false
discounts	array	Line item Discounts
taxable	boolean	Excludes amount from invoice taxes when false
taxes	array	Line item Taxes
plan	string	Plan ID, only present when type is plan
metadata	object	A hash of key/value pairs that can store additional information about this object.

Parameter	Type	Description
id	integer	The discount's unique ID
object	string	Object type, discount
amount	number	Discount amount
coupon	object	Coupon the discount was computed from, if any
expires	timestamp	Time until discount expires, if any

Parameter	Type	Description
id	integer	The tax's unique ID
object	string	Object type, tax
amount	number	Tax amount
tax_rate	object	Tax Rate the tax was computed from, if any

Parameter	Type	Description
name	string	Ship to name
attention_to	string	Used for ATTN: address line
address1	string	First address line
address2	string	Optional second address line
city	string	City
state	string	State or province
postal_code	string	Zip or postal code
country	string	Two-letter ISO code

Parameter	Type	Description
customer	integer	Customer ID - required
name	string	Invoice name for internal use, defaults to "Invoice"
number	string	The reference number assigned to the invoice, defaults to next # in auto-numbering sequence
currency	string	3-letter ISO code - defaults to account currency
autopay	boolean	AutoPay enabled? - inherited from customer by default
payment_terms	string	Payment terms for the invoice, i.e. "NET 30" - inherited from customer by default
purchase_order	string	The customer's purchase order number
date	timestamp	Invoice date - defaults to current timestamp
due_date	timestamp	Due date - computed from payment_terms when not supplied
draft	boolean	When false, the invoice is considered outstanding, or when true, the invoice is a draft
closed	boolean	Marks an invoice as closed
items	array	Collection of Line Items
notes	string	Additional notes displayed on invoice
discounts	array	Collection of Discounts
taxes	array	Collection of Taxes
ship_to	object	Shipipng Detail object
metadata	object	A hash of key/value pairs that can store additional information about this object.
attachments	array	A list of File IDs to attach to the invoice.
disabled_payment_methods	array	List of payment methods to disable for this invoice, i.e. ["credit_card", "wire_transfer"].
calculate_taxes	bool	Disables tax calculation, default is true

Parameter	Type	Description
name	string	Invoice name for internal use, defaults to "Invoice"
number	string	The reference number assigned to the invoice, defaults to next # in auto-numbering sequence
currency	string	3-letter ISO code - defaults to account currency
date	timestamp	Invoice date - defaults to current timestamp
due_date	timestamp	Due date - computed from payment_terms when not supplied
payment_terms	string	Payment terms for the invoice, i.e. "NET 30" - inherited from customer by default
purchase_order	string	The customer's purchase order number
draft	boolean	When false, the invoice is considered outstanding, or when true, the invoice is a draft
sent	boolean	Marks an invoice as sent
closed	boolean	Marks an invoice as closed
items	array	Collection of Line Items
notes	string	Additional notes displayed on invoice
discounts	array	Collection of Discounts
taxes	array	Collection of Taxes
ship_to	object	Shipipng Detail object
metadata	object	A hash of key/value pairs that can store additional information about this object.
attachments	array	A list of File IDs to attach to the invoice. Replaces existing attachments. Not providing this keeps existing attachments.
disabled_payment_methods	array	List of payment methods to disable for this invoice, i.e. ["credit_card", "wire_transfer"].
calculate_taxes	bool	Recalculate taxes, default is false

Parameter	Type	Description
to	array	Optional array of recipients like:[{"name": "Client", "email": "[email protected]"}]
bcc	string	Optional comma-separated list of email addresses to be blind carbon copied
template	string	Optional email template ID, otherwise a standard email template is selected
subject	string	Optional subject to override the template
message	string	Optional message body to override the template

Did this page help you?

Introduction

Files