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 ([email protected])"
Example Response:
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 ([email protected])"
Example Response:
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 ([email protected])" \
-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:
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 ([email protected])" \
-X PATCH \
-H "Content-Type: application/json" \
-d '{"purchase_order":"2345"}'
Example Response:
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 ([email protected])" \
-X PATCH \
-H "Content-Type: application/json" \
-d '{"line_items":[{"kind":"Service","description":"Another Project","unit_price":1000.0}]}'
Example Response:
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 ([email protected])" \
-X PATCH \
-H "Content-Type: application/json" \
-d '{"line_items":[{"id":53339199,"description":"Project Phase 2","unit_price":5000.0}]}'
Example Response:
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 ([email protected])" \
-X PATCH \
-H "Content-Type: application/json" \
-d '{"line_items":[{"id":53339199,"_destroy":true}]}'
Example Response:
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 ([email protected])" \
-X DELETE