Estimates
The estimate object
Attribute | Type | Description |
---|---|---|
id |
integer | Unique ID for the estimate. |
client |
object | An object containing estimate’s client id and name. |
line_items |
array | Array of estimate line items. |
creator |
object | An object containing the id and name of the person that created the estimate. |
client_key |
string | Used to build a URL to the public web invoice for your client:https://{ACCOUNT_SUBDOMAIN}.harvestapp.com/client/estimates/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 estimate, including any discounts and taxes. |
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 calculated from discount . |
subject |
string | The estimate subject. |
notes |
string | Any additional notes included on the estimate. |
currency |
string | The currency code associated with this estimate. |
state |
string | The current state of the estimate: draft , sent , accepted , or declined . |
issue_date |
date | Date the estimate was issued. |
sent_at |
datetime | Date and time the estimate was sent. |
accepted_at |
datetime | Date and time the estimate was accepted. |
declined_at |
datetime | Date and time the estimate was declined. |
created_at |
datetime | Date and time the estimate was created. |
updated_at |
datetime | Date and time the estimate was last updated. |
The estimate line item object
Attribute | Type | Description |
---|---|---|
id |
integer | Unique ID for the line item. |
kind |
string | The name of an estimate 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 estimate’s tax percentage applies to this line item. |
taxed2 |
boolean | Whether the estimate’s tax2 percentage applies to this line item. |
Required permissions
You must be an Administrator or Manager with permission to create and edit estimates in order to interact with the /v2/estimates
endpoint. Insufficient permissions will result in a 403 Forbidden
status code.
List all estimates
Returns a list of your estimates. The estimates are returned sorted by issue date, with the most recently issued estimates appearing first.
The response contains an object with a estimates
property that contains an array of up to per_page
estimates. Each entry in the array is a separate estimate object. If no more estimates are available, the resulting array will be empty. Several additional pagination properties are included in the response to simplify paginating your estimates.
GET /v2/estimates
Parameter | Type | Description |
---|---|---|
client_id |
integer | Only return estimates belonging to the client with the given ID. |
updated_since |
datetime | Only return estimates that have been updated since the given date and time. |
from |
date | Only return estimates with an issue_date on or after the given date. |
to |
date | Only return estimates with an issue_date on or before the given date. |
state |
string | Only return estimates with a state matching the value provided. Options: draft , sent , accepted , or declined . |
page |
integer | The page number to use in pagination. For instance, if you make a list request and receive 2000 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 2000. (Default: 2000) |
Example Request:
curl "https://api.harvestapp.com/v2/estimates" \
-H "Authorization: Bearer $ACCESS_TOKEN" \
-H "Harvest-Account-Id: $ACCOUNT_ID" \
-H "User-Agent: MyApp (yourname@example.com)"
Example Response:
{
"estimates":[
{
"id":1439818,
"client_key":"13dc088aa7d51ec687f186b146730c3c75dc7423",
"number":"1001",
"purchase_order":"5678",
"amount":9630.0,
"tax":5.0,
"tax_amount":450.0,
"tax2":2.0,
"tax2_amount":180.0,
"discount":10.0,
"discount_amount":1000.0,
"subject":"Online Store - Phase 2",
"notes":"Some notes about the estimate",
"state":"sent",
"issue_date":"2017-06-01",
"sent_at":"2017-06-27T16:11:33Z",
"created_at":"2017-06-27T16:11:24Z",
"updated_at":"2017-06-27T16:13:56Z",
"accepted_at":null,
"declined_at":null,
"currency":"USD",
"client":{
"id":5735776,
"name":"123 Industries"
},
"creator":{
"id":1782884,
"name":"Bob Powell"
},
"line_items":[
{
"id":53334195,
"kind":"Service",
"description":"Phase 2 of the Online Store",
"quantity":100,
"unit_price":100,
"amount":10000,
"taxed":true,
"taxed2":true
}
]
},
{
"id":1439814,
"client_key":"a5ffaeb30c55776270fcd3992b70332d769f97e7",
"number":"1000",
"purchase_order":"1234",
"amount":21000.0,
"tax":5.0,
"tax_amount":1000.0,
"tax2":null,
"tax2_amount":0.0,
"discount":null,
"discount_amount":0.0,
"subject":"Online Store - Phase 1",
"notes":"Some notes about the estimate",
"state":"accepted",
"issue_date":"2017-01-01",
"sent_at":"2017-06-27T16:10:30Z",
"created_at":"2017-06-27T16:09:33Z",
"updated_at":"2017-06-27T16:12:00Z",
"accepted_at":"2017-06-27T16:10:32Z",
"declined_at":null,
"currency":"USD",
"client":{
"id":5735776,
"name":"123 Industries"
},
"creator":{
"id":1782884,
"name":"Bob Powell"
},
"line_items":[
{
"id":57531966,
"kind":"Service",
"description":"Phase 1 of the Online Store",
"quantity":1,
"unit_price":20000,
"amount":20000,
"taxed":true,
"taxed2":false
}
]
}
],
"per_page":2000,
"total_pages":1,
"total_entries":2,
"next_page":null,
"previous_page":null,
"page":1,
"links":{
"first":"https://api.harvestapp.com/v2/estimates?page=1&per_page=2000",
"next":null,
"previous":null,
"last":"https://api.harvestapp.com/v2/estimates?page=1&per_page=2000"
}
}
Retrieve an estimate
Retrieves the estimate with the given ID. Returns an estimate object and a 200 OK
response code if a valid identifier was provided.
GET /v2/estimates/{ESTIMATE_ID}
Example Request:
curl "https://api.harvestapp.com/v2/estimates/1439818" \
-H "Authorization: Bearer $ACCESS_TOKEN" \
-H "Harvest-Account-Id: $ACCOUNT_ID" \
-H "User-Agent: MyApp (yourname@example.com)"
Example Response:
{
"id":1439818,
"client_key":"13dc088aa7d51ec687f186b146730c3c75dc7423",
"number":"1001",
"purchase_order":"5678",
"amount":9630.0,
"tax":5.0,
"tax_amount":450.0,
"tax2":2.0,
"tax2_amount":180.0,
"discount":10.0,
"discount_amount":1000.0,
"subject":"Online Store - Phase 2",
"notes":"Some notes about the estimate",
"state":"sent",
"issue_date":"2017-06-01",
"sent_at":"2017-06-27T16:11:33Z",
"created_at":"2017-06-27T16:11:24Z",
"updated_at":"2017-06-27T16:13:56Z",
"accepted_at":null,
"declined_at":null,
"currency":"USD",
"client":{
"id":5735776,
"name":"123 Industries"
},
"creator":{
"id":1782884,
"name":"Bob Powell"
},
"line_items":[
{
"id":53334195,
"kind":"Service",
"description":"Phase 2 of the Online Store",
"quantity":100.0,
"unit_price":100.0,
"amount":10000.0,
"taxed":true,
"taxed2":true
}
]
}
Create an estimate
Creates a new estimate object. Returns an estimate object and a 201 Created
response code if the call succeeded.
POST /v2/estimates
Parameter | Type | Required | Description |
---|---|---|---|
client_id |
integer | required | The ID of the client this estimate belongs to. |
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 estimate subject. |
notes |
string | optional | Any additional notes to include on the estimate. |
currency |
string | optional | The currency used by the estimate. If not provided, the client’s currency will be used. See a list of supported currencies |
issue_date |
date | optional | Date the estimate was issued. Defaults to today’s date. |
line_items |
array | optional | Array of line item parameters |
Line Item Parameter | Type | Required | Description |
---|---|---|---|
kind |
string | required | The name of an estimate 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 estimate’s tax percentage applies to this line item. Defaults to false . |
taxed2 |
boolean | optional | Whether the estimate’s tax2 percentage applies to this line item. Defaults to false . |
Example Request:
curl "https://api.harvestapp.com/v2/estimates" \
-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","line_items":[{"kind":"Service","description":"ABC Project Quote","unit_price":5000.0}]}'
Example Response:
{
"id":1439827,
"client_key":"ddd4504a68fb7339138d0c2ea89ba05a3cf12aa8",
"number":"1002",
"purchase_order":null,
"amount":5000.0,
"tax":null,
"tax_amount":0.0,
"tax2":null,
"tax2_amount":0.0,
"discount":null,
"discount_amount":0.0,
"subject":"Project Quote",
"notes":null,
"state":"draft",
"issue_date":null,
"sent_at":null,
"created_at":"2017-06-27T16:16:24Z",
"updated_at":"2017-06-27T16:16:24Z",
"accepted_at":null,
"declined_at":null,
"currency":"USD",
"client":{
"id":5735774,
"name":"ABC Corp"
},
"creator":{
"id":1782884,
"name":"Bob Powell"
},
"line_items":[
{
"id":53339199,
"kind":"Service",
"description":"Project Description",
"quantity":1.0,
"unit_price":5000.0,
"amount":5000.0,
"taxed":false,
"taxed2":false
}
]
}
Update an estimate
Updates the specific estimate by setting the values of the parameters passed. Any parameters not provided will be left unchanged. Returns an estimate object and a 200 OK
response code if the call succeeded.
PATCH /v2/estimates/{ESTIMATE_ID}
Parameter | Type | Description |
---|---|---|
client_id |
integer | The ID of the client this estimate belongs to. |
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 estimate subject. |
notes |
string | Any additional notes to include on the estimate. |
currency |
string | The currency used by the estimate. If not provided, the client’s currency will be used. See a list of supported currencies |
issue_date |
date | Date the estimate was issued. |
line_items |
array | Array of line item parameters |
Line Item Parameter | Type | Description |
---|---|---|
id |
integer | Unique ID for the line item. |
kind |
string | The name of an estimate 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 estimate’s tax percentage applies to this line item. Defaults to false . |
taxed2 |
boolean | Whether the estimate’s tax2 percentage applies to this line item. Defaults to false . |
Example Request:
curl "https://api.harvestapp.com/v2/estimates/1439827" \
-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":1439827,
"client_key":"ddd4504a68fb7339138d0c2ea89ba05a3cf12aa8",
"number":"1002",
"purchase_order":"2345",
"amount":5000.0,
"tax":null,
"tax_amount":0.0,
"tax2":null,
"tax2_amount":0.0,
"discount":null,
"discount_amount":0.0,
"subject":"Project Quote",
"notes":null,
"state":"draft",
"issue_date":null,
"sent_at":null,
"created_at":"2017-06-27T16:16:24Z",
"updated_at":"2017-06-27T16:17:06Z",
"accepted_at":null,
"declined_at":null,
"currency":"USD",
"client":{
"id":5735774,
"name":"ABC Corp"
},
"creator":{
"id":1782884,
"name":"Bob Powell"
},
"line_items":[
{
"id":53339199,
"kind":"Service",
"description":"Project Description",
"quantity":1.0,
"unit_price":5000.0,
"amount":5000.0,
"taxed":false,
"taxed2":false
}
]
}
Create an estimate line item
Create a new line item on an estimate. Returns a 200 OK
response code if the call succeeded.
Example Request:
curl "https://api.harvestapp.com/api/v2/estimates/1439827" \
-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":"Another Project","unit_price":1000.0}]}'
Example Response:
{
"id":1439827,
"client_key":"ddd4504a68fb7339138d0c2ea89ba05a3cf12aa8",
"number":"1002",
"purchase_order":"2345",
"amount":6000.0,
"tax":null,
"tax_amount":0.0,
"tax2":null,
"tax2_amount":0.0,
"discount":null,
"discount_amount":0.0,
"subject":"Project Quote",
"notes":null,
"state":"draft",
"issue_date":null,
"sent_at":null,
"created_at":"2017-06-27T16:16:24Z",
"updated_at":"2017-06-27T16:17:06Z",
"accepted_at":null,
"declined_at":null,
"currency":"USD",
"client":{
"id":5735774,
"name":"ABC Corp"
},
"creator":{
"id":1782884,
"name":"Bob Powell"
},
"line_items":[
{
"id":53339199,
"kind":"Service",
"description":"Project Description",
"quantity":1.0,
"unit_price":5000.0,
"amount":5000.0,
"taxed":false,
"taxed2":false
},
{
"id":53339200,
"kind":"Service",
"description":"Another Project",
"quantity":1.0,
"unit_price":1000.0,
"amount":1000.0,
"taxed":false,
"taxed2":false
}
]
}
Update an estimate line item
Update an existing line item on an estimate. Returns a 200 OK
response code if the call succeeded.
Example Request:
curl "https://api.harvestapp.com/api/v2/estimates/1439827" \
-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":53339199,"description":"Project Phase 2","unit_price":5000.0}]}'
Example Response:
{
"id":1439827,
"client_key":"ddd4504a68fb7339138d0c2ea89ba05a3cf12aa8",
"number":"1002",
"purchase_order":"2345",
"amount":6000.0,
"tax":null,
"tax_amount":0.0,
"tax2":null,
"tax2_amount":0.0,
"discount":null,
"discount_amount":0.0,
"subject":"Project Quote",
"notes":null,
"state":"draft",
"issue_date":null,
"sent_at":null,
"created_at":"2017-06-27T16:16:24Z",
"updated_at":"2017-06-27T16:17:06Z",
"accepted_at":null,
"declined_at":null,
"currency":"USD",
"client":{
"id":5735774,
"name":"ABC Corp"
},
"creator":{
"id":1782884,
"name":"Bob Powell"
},
"line_items":[
{
"id":53339199,
"kind":"Service",
"description":"Project Phase 2",
"quantity":1.0,
"unit_price":5000.0,
"amount":5000.0,
"taxed":false,
"taxed2":false
},
{
"id":53339200,
"kind":"Service",
"description":"Another Project",
"quantity":1.0,
"unit_price":1000.0,
"amount":1000.0,
"taxed":false,
"taxed2":false
}
]
}
Delete an estimate line item
Delete a line item from an estimate. Returns a 200 OK
response code if the call succeeded.
Example Request:
curl "https://api.harvestapp.com/api/v2/estimates/1439827" \
-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":53339199,"_destroy":true}]}'
Example Response:
{
"id":1439827,
"client_key":"ddd4504a68fb7339138d0c2ea89ba05a3cf12aa8",
"number":"1002",
"purchase_order":"2345",
"amount":1000.0,
"tax":null,
"tax_amount":0.0,
"tax2":null,
"tax2_amount":0.0,
"discount":null,
"discount_amount":0.0,
"subject":"Project Quote",
"notes":null,
"state":"draft",
"issue_date":null,
"sent_at":null,
"created_at":"2017-06-27T16:16:24Z",
"updated_at":"2017-06-27T16:17:06Z",
"accepted_at":null,
"declined_at":null,
"currency":"USD",
"client":{
"id":5735774,
"name":"ABC Corp"
},
"creator":{
"id":1782884,
"name":"Bob Powell"
},
"line_items":[
{
"id":53339200,
"kind":"Service",
"description":"Another Project",
"quantity":1.0,
"unit_price":1000.0,
"amount":1000.0,
"taxed":false,
"taxed2":false
}
]
}
Delete an estimate
Delete an estimate. Returns a 200 OK
response code if the call succeeded.
DELETE /v2/estimates/{ESTIMATE_ID}
Example Request:
curl "https://api.harvestapp.com/v2/estimates/1439827" \
-H "Authorization: Bearer $ACCESS_TOKEN" \
-H "Harvest-Account-Id: $ACCOUNT_ID" \
-H "User-Agent: MyApp (yourname@example.com)" \
-X DELETE