Create An Invoice
Invoice parameters
Important: this assumes that the invoice feature is enabled for your account via Settings > Choose Modules”.
User-editable parameters
Parameter | Description |
---|---|
due-at-human-format |
Invoice due date. Acceptable formats are NET N where N is the number of days until the invoice is due. |
client-id |
A valid client-id |
currency |
A valid currency format (Example: United States Dollar - USD ). Optional, and will default to the client currency if no value is passed. Click here for a list of supported currencies |
discount |
Optional value to discount invoice total. |
issued-at |
Invoice creation date. (Example: 2015-04-22 ) |
subject |
Optional invoice subject. |
notes |
Optional invoice notes. |
number |
Optional invoice number. If no value is set, the number will be automatically generated. |
kind |
Invoice type. Options: free-form , project , task , people , detailed . (See Invoice Types) |
projects-to-invoice |
Comma separated project IDs to gather data from, unused for free-form invoices. |
import-hours |
Hours to import into invoices. Options: all (import all hours), yes (import hours using period-start , period-end ), no (do not import hours). |
import-expenses |
Expenses to import into invoices. Options: all (import all expenses), yes (import expenses using expense-period-start , expense-period-end ), no (do not import expenses). |
expense-summary-type |
Summary type for expenses in an invoice. Options: project , people , category , detailed . |
period-start |
Date for included project hours. (Example: 2015-04-22) |
period-end |
End date for included project hours. (Example: 2015-05-22) |
expense-period-start |
Date for included project expenses. (Example: 2015-04-22) |
expense-period-end |
End date for included project expenses. (Example: 2015-05-22) |
csv-line-items |
Used to create line items in free-form invoices. Entries should have their entries enclosed in quotes when they contain extra commas. This is especially important if you are using a number format which uses commas as the decimal separator. |
tax |
First tax rate for created invoice. Optional. Account default used otherwise. |
tax2 |
Second tax rate for created invoice. Optional. Account default used otherwise. |
purchase-order |
Optional purchase order number. |
Invoice types
Type | Description |
---|---|
free-form |
Creates free form invoice. Line items added with csv-line-items |
project |
Gathers hours & expenses from Harvest grouped by projects. |
task |
Gathers hours & expenses from Harvest grouped by task. |
people |
Gathers hours & expenses from Harvest grouped by person. |
detailed |
Uses a line item for each hour & expense entry, including detailed notes. |
Parameters generated by Harvest
Parameters | Description |
---|---|
client-key |
Value to generate URL to client dashboard. (Example: https://YOURACCOUNT.harvestapp.com/clients/invoices/{CLIENTKEY} ) |
estimate-id |
This value will exist if an estimate was converted into an invoice. |
retainer-id |
This value will exist if the invoice was created from a retainer. |
recurring-invoice-id |
This value will exist if the invoice is recurring, and automatically generated. |
created-by-id |
User ID of the invoice creator. |
updated-at |
Date invoice was last updated. (Example: 2015-04-09T12:07:56Z) |
created-at |
Date invoice was created. (Example: 2015-04-09T12:07:56Z) |
state |
Updated when invoice is created, sent, paid, late, or written off. Options: draft , paid , late , sent , written-off . |
Create an invoice
POST https://YOURACCOUNT.harvestapp.com/invoices
HTTP Response: 201 Created
Invoice based on hours & expenses
<invoice>
<due-at-human-format>NET 10</due-at-human-format>
<client-id type="integer">1929151</client-id>
<currency>United States Dollar - USD</currency>
<issued-at type="date">2008-02-06</issued-at>
<subject>Your invoice subject goes here</subject>
<notes>Some notes go here</notes>
<number>82208</number>
<kind>project</kind>
<projects-to-invoice>12345</projects-to-invoice>
<import-hours>yes</import-hours>
<import-expenses>yes</import-expenses>
<period-start type="date">2015-03-01</period-start>
<period-end type="date">2015-03-31</period-end>
<expense-period-start type="date">2015-03-01</expense-period-start>
<expense-period-end type="date">2015-03-31</expense-period-end>
</invoice>
{
"invoice": {
"due_at_human_format": "NET 10",
"client_id": 1929151,
"currency" : "United States Dollar - USD",
"issued_at": "2015-04-22",
"subject": "Your invoice subject goes here",
"notes": "Some notes go here",
"number": "82208",
"kind": "project",
"projects_to_invoice": "12345",
"import_hours": "yes",
"import_expenses": "yes",
"period_start": "2015-03-01",
"period_end": "2015-03-31",
"expense_period_start": "2015-03-31",
"expense_period_end": "2015-03-31"
}
}
Free form invoice
Sample free form invoice request, using
csv-line-items
:
<invoice>
<due-at-human-format>due upon receipt</due-at-human-format>
<client-id type="integer">1929151</client-id>
<currency>United States Dollar - USD</currency>
<issued-at type="date">2015-04-06</issued-at>
<subject>Your invoice subject goes here</subject>
<notes>Some notes go here</notes>
<number>82208</number>
<kind>free_form</kind>
<tax type="decimal">3</tax>
<tax2 type="decimal">5</tax2>
<csv-line-items>kind,description,quantity,unit_price,amount,taxed,taxed2,project_id
Service,A service,1.00,100.00,100.0,true,true,
Product,A product,2,100.00,200.0,false,false,
</csv-line-items>
</invoice>
{
"invoice": {
"due_at_human_format": "due upon receipt",
"client_id": 1929151,
"currency" : "United States Dollar - USD",
"issued_at": "2015-04-06",
"subject": "Your invoice subject goes here",
"notes": "Some notes go here",
"number": "82208",
"kind": "free-form",
"tax": "3",
"tax2": "5",
"csv_line_items":
"kind,description,quantity,unit_price,amount,taxed,taxed2,project_id
Service,A service,1.00,100.00,100.0,true,true,
Product,A product,2,100.00,200.0,false,false,"
}
}