email Contact Us
  1. Harvest API V2 Documentation
  2. Estimates API
  3. Estimates

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

Still have questions? We’re happy to help!

Contact Us