Admin or project manager permissions required.

The invoice object

Attribute Type Description
id integer Unique ID for the invoice.
client object An object containing invoice’s client id and name.
line_items array Array of invoice line items.
estimate object An object containing the associated estimate’s id.
retainer object An object containing the associated retainer’s id.
creator object An object containing the id and name of the person that created the invoice.
client_key string Used to build a URL to the public web invoice for your client:
https://{ACCOUNT_SUBDOMAIN}.harvestapp.com/client/invoices/abc123456
number string If no value is set, the number will be automatically generated.
purchase_order string The purchase order number.
amount decimal The total amount for the invoice, including any discounts and taxes.
due_amount decimal The total amount due at this time for this invoice.
tax decimal This percentage is applied to the subtotal, including line items and discounts.
tax_amount decimal The first amount of tax included, calculated from tax. If no tax is defined, this value will be null.
tax2 decimal This percentage is applied to the subtotal, including line items and discounts.
tax2_amount decimal The amount calculated from tax2.
discount decimal This percentage is subtracted from the subtotal.
discount_amount decimal The amount calcuated from discount.
subject string The invoice subject.
notes string Any additional notes included on the invoice.
currency string The currency code associated with this invoice.
period_start date Start of the period during which time entries and expenses were added to this invoice.
period_end date End of the period during which time entries and expenses were added to this invoice.
issue_date date Date the invoice was issued.
due_date date Date the invoice is due.
sent_at datetime Date and time the invoice was sent.
paid_at datetime Date and time the invoice was paid.
closed_at datetime Date and time the invoice was closed.
created_at datetime Date and time the invoice was created.
updated_at datetime Date and time the invoice was last updated.

The invoice line item object

Attribute Type Description
id integer Unique ID for the line item.
project object An object containing the associated project’s id, name, and code.
kind string The name of an invoice item category.
description string Text description of the line item.
quantity integer The unit quantity of the item.
unit_price decimal The individual price per unit.
amount decimal The line item subtotal (quantity * unit_price).
taxed boolean Whether the invoice’s tax percentage applies to this line item.
taxed2 boolean Whether the invoice’s tax2 percentage applies to this line item.

List all invoices

Returns a list of your invoices. The invoices are returned sorted by issue date, with the most recently issued invoices appearing first.

The response contains an object with a invoices property that contains an array of up to per_page invoices. Each entry in the array is a separate invoice object. If no more invoices are available, the resulting array will be empty. Several additional pagination properties are included in the response to simplify paginating your invoices.

GET /v2/invoices
Parameter Type Description
client_id integer Only return invoices belonging to the client with the given ID.
project_id integer Only return invoices associated with the project with the given ID.
updated_since datetime Only return invoices that have been updated since the given date and time.
page integer The page number to use in pagination. For instance, if you make a list request and receive 100 records, your subsequent call can include page=2 to retrieve the next page of the list. (Default: 1)
per_page integer The number of records to return per page. Can range between 1 and 100. (Default: 100)

Example Request:

curl "https://api.harvestapp.com/v2/invoices" \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H "Harvest-Account-Id: $ACCOUNT_ID" \
  -H "User-Agent: MyApp (yourname@example.com)"

Example Response:

{
"invoices":[
{
"id":13150403,
"client_key":"21312da13d457947a217da6775477afee8c2eba8",
"number":"1001",
"purchase_order":"",
"amount":288.9,
"due_amount":288.9,
"tax":5,
"tax_amount":13.5,
"tax2":2,
"tax2_amount":5.4,
"discount":10,
"discount_amount":30,
"subject":"Online Store - Phase 1",
"notes":"Some notes about the invoice.",
"period_start":"2017-03-01",
"period_end":"2017-03-01",
"issue_date":"2017-04-01",
"due_date":"2017-04-01",
"sent_at":"2017-08-23T22:25:59Z",
"paid_at":null,
"closed_at":null,
"created_at":"2017-06-27T16:27:16Z",
"updated_at":"2017-08-23T22:25:59Z",
"currency":"EUR",
"client":{
"id":5735776,
"name":"123 Industries"
},
"estimate":null,
"retainer":null,
"creator":{
"id":1782884,
"name":"Bob Powell"
},
"line_items":[
{
"id":53341602,
"kind":"Service",
"description":"03/01/2017 - Project Management: [9:00am - 11:00am] Planning meetings",
"quantity":2,
"unit_price":100,
"amount":200,
"taxed":true,
"taxed2":true,
"project":{
"id":14308069,
"name":"Online Store - Phase 1",
"code":"OS1"
}
},
{
"id":53341603,
"kind":"Service",
"description":"03/01/2017 - Programming: [1:00pm - 2:00pm] Importing products",
"quantity":1,
"unit_price":100,
"amount":100,
"taxed":true,
"taxed2":true,
"project":{
"id":14308069,
"name":"Online Store - Phase 1",
"code":"OS1"
}
}
]
},
{
"id":13150378,
"client_key":"9e97f4a65c5b83b1fc02f54e5a41c9dc7d458542",
"number":"1000",
"purchase_order":"1234",
"amount":10700.0,
"due_amount":0.0,
"tax":5.0,
"tax_amount":500.0,
"tax2":2.0,
"tax2_amount":200.0,
"discount":null,
"discount_amount":0.0,
"subject":"Online Store - Phase 1",
"notes":"Some notes about the invoice.",
"period_start":null,
"period_end":null,
"issue_date":"2017-02-01",
"due_date":"2017-03-03",
"sent_at":"2017-02-01T07:00:00Z",
"paid_at":"2017-02-21T00:00:00Z",
"closed_at":null,
"created_at":"2017-06-27T16:24:30Z",
"updated_at":"2017-06-27T16:24:57Z",
"currency":"USD",
"client":{
"id":5735776,
"name":"123 Industries"
},
"estimate":{
"id":1439814
},
"retainer":null,
"creator":{
"id":1782884,
"name":"Bob Powell"
},
"line_items":[
{
"id":53341450,
"kind":"Service",
"description":"50% of Phase 1 of the Online Store",
"quantity":100.0,
"unit_price":100.0,
"amount":10000.0,
"taxed":true,
"taxed2":true,
"project":{
"id":14308069,
"name":"Online Store - Phase 1",
"code":"OS1"
}
}
]
}
],
"per_page":100,
"total_pages":1,
"total_entries":2,
"next_page":null,
"previous_page":null,
"page":1,
"links":{
"first":"https://api.harvestapp.com/v2/invoices?page=1&per_page=100",
"next":null,
"previous":null,
"last":"https://api.harvestapp.com/v2/invoices?page=1&per_page=100"
}
}

Retrieve an invoice

Retrieves the invoice with the given ID. Returns an invoice object and a 200 OK response code if a valid identifier was provided.

GET /v2/invoices/{INVOICE_ID}

Example Request:

curl "https://api.harvestapp.com/v2/invoices/13150378" \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H "Harvest-Account-Id: $ACCOUNT_ID" \
  -H "User-Agent: MyApp (yourname@example.com)"

Example Response:

{
"id":13150378,
"client_key":"9e97f4a65c5b83b1fc02f54e5a41c9dc7d458542",
"number":"1000",
"purchase_order":"1234",
"amount":10700.0,
"due_amount":0.0,
"tax":5.0,
"tax_amount":500.0,
"tax2":2.0,
"tax2_amount":200.0,
"discount":null,
"discount_amount":0.0,
"subject":"Online Store - Phase 1",
"notes":"Some notes about the invoice.",
"period_start":null,
"period_end":null,
"issue_date":"2017-02-01",
"due_date":"2017-03-03",
"sent_at":"2017-02-01T07:00:00Z",
"paid_at":"2017-02-21T00:00:00Z",
"closed_at":null,
"created_at":"2017-06-27T16:24:30Z",
"updated_at":"2017-06-27T16:24:57Z",
"currency":"USD",
"client":{
"id":5735776,
"name":"123 Industries"
},
"estimate":{
"id":1439814
},
"retainer":null,
"creator":{
"id":1782884,
"name":"Bob Powell"
},
"line_items":[
{
"id":53341450,
"kind":"Service",
"description":"50% of Phase 1 of the Online Store",
"quantity":100.0,
"unit_price":100.0,
"amount":10000.0,
"taxed":true,
"taxed2":true,
"project":{
"id":14308069,
"name":"Online Store - Phase 1",
"code":"OS1"
}
}
]
}

Create an invoice

Creates a new invoice object. Returns an invoice object and a 201 Created response code if the call succeeded.

Note: We currently only support creating free-form invoices. Support for other types will be added in the future!

POST /v2/invoices
Parameter Type Required Description
client_id integer required The ID of the client this invoice belongs to.
retainer_id integer optional The ID of the retainer associated with this invoice.
estimate_id integer optional The ID of the estimate associated with this invoice.
number string optional If no value is set, the number will be automatically generated.
purchase_order string optional The purchase order number.
tax decimal optional This percentage is applied to the subtotal, including line items and discounts. Example: use 10.0 for 10.0%.
tax2 decimal optional This percentage is applied to the subtotal, including line items and discounts. Example: use 10.0 for 10.0%.
discount decimal optional This percentage is subtracted from the subtotal. Example: use 10.0 for 10.0%.
subject string optional The invoice subject.
notes string optional Any additional notes to include on the invoice.
currency string optional The currency used by the invoice. If not provided, the client’s currency will be used. See a list of supported currencies
issue_date date optional Date the invoice was issued. Defaults to today’s date.
due_date date optional Date the invoice is due. Defaults to the issue_date.
line_items array optional Array of line item parameters
Line Item Parameter Type Required Description
project_id integer optional The ID of the project associated with this line item.
kind string required The name of an invoice item category.
description string optional Text description of the line item.
quantity integer optional The unit quantity of the item. Defaults to 1.
unit_price decimal required The individual price per unit.
taxed boolean optional Whether the invoice’s tax percentage applies to this line item. Defaults to false.
taxed2 boolean optional Whether the invoice’s tax2 percentage applies to this line item. Defaults to false.

Example Request:

curl "https://api.harvestapp.com/v2/invoices" \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H "Harvest-Account-Id: $ACCOUNT_ID" \
  -H "User-Agent: MyApp (yourname@example.com)" \
  -X POST \
  -H "Content-Type: application/json" \
  -d '{"client_id":"5735774","subject":"ABC Project Quote","due_date":"2017-07-27","line_items":[{"kind":"Service","description":"ABC Project","unit_price":"5000.0"}]}'

Example Response:

{
"id":13150453,
"client_key":"8b86437630b6c260c1bfa289f0154960f83b606d",
"number":"1002",
"purchase_order":null,
"amount":0.0,
"due_amount":0.0,
"tax":null,
"tax_amount":0.0,
"tax2":null,
"tax2_amount":0.0,
"discount":null,
"discount_amount":0.0,
"subject":"ABC Project Quote",
"notes":null,
"period_start":null,
"period_end":null,
"issue_date":"2017-06-27",
"due_date":"2017-07-27",
"sent_at":null,
"paid_at":null,
"closed_at":null,
"created_at":"2017-06-27T16:34:24Z",
"updated_at":"2017-06-27T16:34:24Z",
"currency":"USD",
"client":{
"id":5735774,
"name":"ABC Corp"
},
"estimate":null,
"retainer":null,
"creator":{
"id":1782884,
"name":"Bob Powell"
},
"line_items":[
{
"id":53341928,
"kind":"Service",
"description":"ABC Project",
"quantity":1.0,
"unit_price":5000.0,
"amount":5000.0,
"taxed":false,
"taxed2":false,
"project":null
}
]
}

Update an invoice

Updates the specific invoice by setting the values of the parameters passed. Any parameters not provided will be left unchanged. Returns an invoice object and a 200 OK response code if the call succeeded.

PATCH /v2/invoices/{INVOICE_ID}
Parameter Type Description
client_id integer The ID of the client this invoice belongs to.
retainer_id integer The ID of the retainer associated with this invoice.
estimate_id integer The ID of the estimate associated with this invoice.
number string If no value is set, the number will be automatically generated.
purchase_order string The purchase order number.
tax decimal This percentage is applied to the subtotal, including line items and discounts. Example: use 10.0 for 10.0%.
tax2 decimal This percentage is applied to the subtotal, including line items and discounts. Example: use 10.0 for 10.0%.
discount decimal This percentage is subtracted from the subtotal. Example: use 10.0 for 10.0%.
subject string The invoice subject.
notes string Any additional notes to include on the invoice.
currency string The currency used by the invoice. If not provided, the client’s currency will be used. See a list of supported currencies
issue_date date Date the invoice was issued.
due_date date Date the invoice is due.
line_items array Array of line item parameters
Line Item Parameter Type Description
id integer Unique ID for the line item.
project_id integer The ID of the project associated with this line item.
kind string The name of an invoice item category.
description string Text description of the line item.
quantity integer The unit quantity of the item. Defaults to 1.
unit_price decimal The individual price per unit.
taxed boolean Whether the invoice’s tax percentage applies to this line item. Defaults to false.
taxed2 boolean Whether the invoice’s tax2 percentage applies to this line item. Defaults to false.

Example Request:

curl "https://api.harvestapp.com/v2/invoices/13150453" \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H "Harvest-Account-Id: $ACCOUNT_ID" \
  -H "User-Agent: MyApp (yourname@example.com)" \
  -X PATCH \
  -H "Content-Type: application/json" \
  -d '{"purchase_order":"2345"}'

Example Response:

{
"id":13150453,
"client_key":"8b86437630b6c260c1bfa289f0154960f83b606d",
"number":"1002",
"purchase_order":"2345",
"amount":0.0,
"due_amount":0.0,
"tax":null,
"tax_amount":0.0,
"tax2":null,
"tax2_amount":0.0,
"discount":null,
"discount_amount":0.0,
"subject":"ABC Project Quote",
"notes":null,
"period_start":null,
"period_end":null,
"issue_date":"2017-06-27",
"due_date":"2017-07-27",
"sent_at":null,
"paid_at":null,
"closed_at":null,
"created_at":"2017-06-27T16:34:24Z",
"updated_at":"2017-06-27T16:36:33Z",
"currency":"USD",
"client":{
"id":5735774,
"name":"ABC Corp"
},
"estimate":null,
"retainer":null,
"creator":{
"id":1782884,
"name":"Bob Powell"
},
"line_items":[
{
"id":53341928,
"kind":"Service",
"description":"ABC Project",
"quantity":1.0,
"unit_price":5000.0,
"amount":5000.0,
"taxed":false,
"taxed2":false,
"project":null
}
]
}

Create an invoice line item

Create a new line item on an invoice. Returns a 200 OK response code if the call succeeded.

Example Request:

curl "https://api.harvestapp.com/api/v2/invoices/13150403" \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H "Harvest-Account-ID: $ACCOUNT_ID" \
  -H "User-Agent: MyApp (yourname@example.com)" \
  -X PATCH \
  -H "Content-Type: application/json" \
  -d '{"line_items":[{"kind":"Service","description":"DEF Project","unit_price":"1000.0"}]}'

Example Response:

{
"id":13150453,
"client_key":"8b86437630b6c260c1bfa289f0154960f83b606d",
"number":"1002",
"purchase_order":"2345",
"amount":0.0,
"due_amount":0.0,
"tax":null,
"tax_amount":0.0,
"tax2":null,
"tax2_amount":0.0,
"discount":null,
"discount_amount":0.0,
"subject":"ABC Project Quote",
"notes":null,
"period_start":null,
"period_end":null,
"issue_date":"2017-06-27",
"due_date":"2017-07-27",
"sent_at":null,
"paid_at":null,
"closed_at":null,
"created_at":"2017-06-27T16:34:24Z",
"updated_at":"2017-06-27T16:36:33Z",
"currency":"USD",
"client":{
"id":5735774,
"name":"ABC Corp"
},
"estimate":null,
"retainer":null,
"creator":{
"id":1782884,
"name":"Bob Powell"
},
"line_items":[
{
"id":53341928,
"kind":"Service",
"description":"ABC Project",
"quantity":1.0,
"unit_price":5000.0,
"amount":0.0,
"taxed":false,
"taxed2":false,
"project":null
},
{
"id":53341929,
"kind":"Service",
"description":"DEF Project",
"quantity":1.0,
"unit_price":1000.0,
"amount":1000.0,
"taxed":false,
"taxed2":false,
"project":null
}
]
}

Update an invoice line item

Update an exisitng line item on an invoice. Returns a 200 OK response code if the call succeeded.

Example Request:

curl "https://api.harvestapp.com/api/v2/invoices/13150403" \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H "Harvest-Account-ID: $ACCOUNT_ID" \
  -H "User-Agent: MyApp (yourname@example.com)" \
  -X PATCH \
  -H "Content-Type: application/json" \
  -d '{"line_items":{[{"id":"53341928","description":"ABC Project Phase 2","unit_price":5000.0}]}'

Example Response:

{
"id":13150453,
"client_key":"8b86437630b6c260c1bfa289f0154960f83b606d",
"number":"1002",
"purchase_order":"2345",
"amount":0.0,
"due_amount":0.0,
"tax":null,
"tax_amount":0.0,
"tax2":null,
"tax2_amount":0.0,
"discount":null,
"discount_amount":0.0,
"subject":"ABC Project Quote",
"notes":null,
"period_start":null,
"period_end":null,
"issue_date":"2017-06-27",
"due_date":"2017-07-27",
"sent_at":null,
"paid_at":null,
"closed_at":null,
"created_at":"2017-06-27T16:34:24Z",
"updated_at":"2017-06-27T16:36:33Z",
"currency":"USD",
"client":{
"id":5735774,
"name":"ABC Corp"
},
"estimate":null,
"retainer":null,
"creator":{
"id":1782884,
"name":"Bob Powell"
},
"line_items":[
{
"id":53341928,
"kind":"Service",
"description":"ABC Project Phase 2",
"quantity":1.0,
"unit_price":5000.0,
"amount":0.0,
"taxed":false,
"taxed2":false,
"project":null
},
{
"id":53341929,
"kind":"Service",
"description":"DEF Project",
"quantity":1.0,
"unit_price":1000.0,
"amount":1000.0,
"taxed":false,
"taxed2":false,
"project":null
}
]
}

Delete an invoice line item

Delete a line item from an invoice. Returns a 200 OK response code if the call succeeded.

Example Request:

curl "https://api.harvestapp.com/api/v2/invoices/13150403" \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H "Harvest-Account-ID: $ACCOUNT_ID" \
  -H "User-Agent: MyApp (yourname@example.com)" \
  -X PATCH \
  -H "Content-Type: application/json" \
  -d '{"line_items":[{"id":"53341928","_destroy":"true"}]}'

Example Response:

{
"id":13150453,
"client_key":"8b86437630b6c260c1bfa289f0154960f83b606d",
"number":"1002",
"purchase_order":"2345",
"amount":0.0,
"due_amount":0.0,
"tax":null,
"tax_amount":0.0,
"tax2":null,
"tax2_amount":0.0,
"discount":null,
"discount_amount":0.0,
"subject":"ABC Project Quote",
"notes":null,
"period_start":null,
"period_end":null,
"issue_date":"2017-06-27",
"due_date":"2017-07-27",
"sent_at":null,
"paid_at":null,
"closed_at":null,
"created_at":"2017-06-27T16:34:24Z",
"updated_at":"2017-06-27T16:36:33Z",
"currency":"USD",
"client":{
"id":5735774,
"name":"ABC Corp"
},
"estimate":null,
"retainer":null,
"creator":{
"id":1782884,
"name":"Bob Powell"
},
"line_items":[
{
"id":53341929,
"kind":"Service",
"description":"DEF Project",
"quantity":1.0,
"unit_price":1000.0,
"amount":1000.0,
"taxed":false,
"taxed2":false,
"project":null
}
]
}

Delete an invoice

Delete an invoice. Returns a 200 OK response code if the call succeeded.

DELETE /v2/invoices/{INVOICE_ID}

Example Request:

curl "https://api.harvestapp.com/v2/invoices/13150453" \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H "Harvest-Account-Id: $ACCOUNT_ID" \
  -H "User-Agent: MyApp (yourname@example.com)" \
  -X DELETE