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

Example request in Postman

<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,"
    }
}

Still have questions? We’re happy to help!

Contact Us