email Contact Us
  1. Harvest API V2 Documentation
  2. Invoices API
  3. Invoice Messages & Payments

Invoice Messages & Payments

Invoice messages

Show invoice messages

GET https://YOURACCOUNT.harvestapp.com/invoices/{INVOICEID}/messages

To show a particular invoice message, use the following request:

GET https://YOURACCOUNT.harvestapp.com/invoices/{INVOICEID}/message/{MESSAGEID}

HTTP Response: 200 OK

<?xml version="1.0" encoding="UTF-8"?>
<invoice-message type="array">
    <invoice-message>
        <id type="integer">12465017</id>
        <invoice-id type="integer">6770075</invoice-id>
        <send-me-a-copy type="boolean">false</send-me-a-copy>
        <body>


---------------------------------------------
Invoice Summary
---------------------------------------------
Invoice ID: 112360
Issue date: 04/22/2015
Client: Your Account
P.O. Number:
Amount: $100.00
Due: 05/02/2015 (NET 10)

The detailed invoice is attached as a PDF.

Thank you!
---------------------------------------------
</body>
        <created-at type="dateTime">2015-04-29T14:28:24Z</created-at>
        <sent-by>Harvest User</sent-by>
        <sent-by-email>[email protected]</sent-by-email>
        <thank-you type="boolean">false</thank-you>
        <subject>Invoice #112360 from Your Harvest Account</subject>
        <include-pay-pal-link type="boolean">false</include-pay-pal-link>
        <updated-at type="dateTime">2015-04-29T14:28:24Z</updated-at>
        <sent-from-email>[email protected]</sent-from-email>
        <sent-from>Harvest User</sent-from>
        <send-reminder-on type="date" nil="true"/>
        <full-recipient-list>"Client Person" &lt;[email protected]&gt;</full-recipient-list>
    </invoice-message>
</invoice-message>
[
    {
        "message": {
            "id": 12465017,
            "invoice_id": 6770075,
            "send_me_a_copy": false,
            "body": "\r\n\r\n\r\n---------------------------------------------\r\nInvoice Summary\r\n---------------------------------------------\r\nInvoice ID: 112360\r\nIssue date: 04/22/2015\r\nClient: Your Account\r\nP.O. Number: \r\nAmount: $100.00\r\nDue: 05/02/2015 (NET 10)\r\n\r\nThe detailed invoice is attached as a PDF.\r\n\r\nThank you!\r\n---------------------------------------------\r\n",
            "created_at": "2015-04-29T14:28:24Z",
            "sent_by": "Harvest User",
            "sent_by_email": "[email protected]",
            "thank_you": false,
            "subject": "Invoice #112360 from Your Harvest Account",
            "include_pay_pal_link": false,
            "updated_at": "2015-04-29T14:28:24Z",
            "sent_from_email": "[email protected]",
            "sent_from": "Harvest User",
            "send_reminder_on": null,
            "full_recipient_list": "\"Client Person\" <[email protected]>"
        }
    }
]

Send an invoice

POST https://YOURACCOUNT.harvestapp.com/invoices/{INVOICEID}/messages

HTTP Response: 201 Created

Make sure to set attach-pdf to true if you’d like to include a PDF copy of your invoice, and use include-pay-pal-link to include a link to the client dashboard, so the client can pay the invoice online with the payment gateway you’ve previously set up.

Example request in Postman 

<message>
  <body>Message body</body>
  <recipients>[email protected], [email protected]</recipients>
  <attach-pdf type="boolean">true</attach-pdf>
  <send-me-a-copy type="boolean">true</send-me-a-copy>
  <include-pay-pal-link type="boolean">true</include-pay-pal-link>
</message>
{
    "message": {
        "body": "Message body",
        "recipients": "[email protected]",
        "attach_pdf": true,
        "send_me_a_copy": true,
        "include_pay_pal_link": true
    }
}

Other message functions

Delete existing message

DELETE https://YOURACCOUNT.harvestapp.com/invoices/{INVOICEID}/messages/{MESSAGEID}

HTTP Response: 200 OK

Mark an invoice as sent

POST https://YOURACCOUNT.harvestapp.com/invoices/{INVOICEID}/messages/mark_as_sent

HTTP Response: 200 OK

Change a sent invoice to draft

POST https://YOURACCOUNT.harvestapp.com/invoices/{INVOICEID}/messages/mark_as_draft

HTTP Response: 200 OK

In the following API calls, you can also include an optional message using the body field.

Write an invoice off

POST https://YOURACCOUNT.harvestapp.com/invoices/{INVOICEID}/messages/mark_as_closed

HTTP Response: 200 OK

Re-open an invoice

POST https://YOURACCOUNT.harvestapp.com/invoices/{INVOICEID}/messages/re_open

HTTP Response: 200 OK

Invoice categories

Here you can change the categories appearing before each line item on your invoice. By default Harvest provides two non-removable categories, for the hours and for the expenses you bill. You can create many more categories and change the name of the default ones.

Show all categories

GET https://YOURACCOUNT.harvestapp.com/invoice_item_categories

HTTP Response: 200 OK

Example request in Postman 

<?xml version="1.0" encoding="UTF-8"?>
<invoice-item-categories type="array">
  <invoice-item-category>
    <id type="integer">1</id>
    <name>Service</name>
    <created-at type="dateTime">2016-06-07T10:43:08Z</created-at>
    <updated-at type="dateTime">2016-06-07T10:43:08Z</updated-at>
    <use-as-service type="boolean">true</use-as-service>
    <use-as-expense type="boolean">false</use-as-expense>
  </invoice-item-category>
  <invoice-item-category>
    <id type="integer">2</id>
    <name>Product</name>
    <created-at type="dateTime">2016-06-07T10:43:08Z</created-at>
    <updated-at type="dateTime">2016-06-07T10:43:08Z</updated-at>
    <use-as-service type="boolean">false</use-as-service>
    <use-as-expense type="boolean">true</use-as-expense>
  </invoice-item-category>
</invoice-item-categories>
[
  {
    "invoice_category": {
      "id": 1,
      "name": "Service",
      "created_at": "2016-06-07T10:43:08Z",
      "updated_at": "2016-06-07T10:43:08Z",
      "use_as_service": true,
      "use_as_expense": false
    }
  },
  {
    "invoice_category": {
      "id": 2,
      "name": "Product",
      "created_at": "2016-06-07T10:43:08Z",
      "updated_at": "2016-06-07T10:43:08Z",
      "use_as_service": false,
      "use_as_expense": true
    }
  }
]

Create new category

POST https://YOURACCOUNT.harvestapp.com/invoice_item_categories

HTTP Response: 201 Created

<invoice-item-category>
  <name>Entertainment</name>
</invoice-item-category>
{
        "invoice_item_category": {
            "name": "Entertainment"

        }
    }

Update existing category

PUT https://YOURACCOUNT.harvestapp.com/invoice_item_categories/{CATEGORYID}

HTTP Response: 200 OK

<invoice-item-category>
  <name>Entertainment</name>
</invoice-item-category>
{
        "invoice_item_category": {
            "name": "Entertainment"

        }
    }

Delete a category

DELETE https://YOURACCOUNT.harvestapp.com/invoice_item_categories/{CATEGORYID}

HTTP Response: 200 OK

This request will only work with non-default categories, which can only be edited. If this request is used on a default category, we’ll return HTTP Response: 400 Bad Request

Show payments for an invoice

GET https://YOURACCOUNT.harvestapp.com/invoices/{INVOICEID}/payments

This call will return any payments that have been applied to this particular invoice.

To return a single, specific payment, use:

GET https://YOURACCOUNT.harvestapp.com/invoices/{INVOICEID}/payments/{PAYMENTID}

Depending on how the payment was made, the fields pay-pay-transaction-id, authorization, and payment-gateway-id will reflect information specific to the method used.

HTTP Response: 200 OK

Example request in Postman 

<?xml version="1.0" encoding="UTF-8"?>
<payments type="array">
    <payment>
        <id type="integer">5096287</id>
        <invoice-id type="integer">6770545</invoice-id>
        <amount type="decimal">300.0</amount>
        <paid-at type="dateTime">2015-04-24T00:00:00Z</paid-at>
        <created-at type="dateTime">2015-04-24T14:42:34Z</created-at>
        <notes>Payment notes.</notes>
        <recorded-by>Jane Example</recorded-by>
        <recorded-by-email>[email protected]</recorded-by-email>
        <pay-pal-transaction-id nil="true"/>
        <authorization nil="true"/>
        <payment-gateway-id type="integer" nil="true"/>
        <updated-at type="dateTime">2015-04-24T14:42:34Z</updated-at>
    </payment>
</payments>
[
    {
        "payment": {
            "id": 5096287,
            "invoice_id": 6770545,
            "amount": 300,
            "paid_at": "2015-04-24T00:00:00Z",
            "created_at": "2015-04-24T14:42:34Z",
            "notes": "Payment notes.",
            "recorded_by": "Jane Example",
            "recorded_by_email": "[email protected]",
            "pay_pal_transaction_id": null,
            "authorization": null,
            "payment_gateway_id": null,
            "updated_at": "2015-04-24T14:42:34Z"
        }
    }
]

Create a new payment

POST https://YOURACCOUNT.harvestapp.com/invoices/{INVOICEID}/payments

The fields paid-at and amount are required, and optionally notes can be included.

Payment related invoice attributes like due-amount will be updated. Invoice status will be set to paid if no amount is left due.

HTTP Response: 201 Created

Example request in Postman 

<payment>
  <paid-at type="datetime">2008-02-14T00:00:00Z</paid-at>
  <amount type="decimal">300.0</amount>
  <notes>Some optional notes go here.</notes>
</payment>
    {
        "payment": {
            "amount": 300,
            "paid_at": "2015-04-24T00:00:00Z",
            "notes": "Payment notes."
        }
    }

Delete existing payment

DELETE https://YOURACCOUNT.harvestapp.com/invoices/{INVOICEID}/payments{PAYMENTID}

After a successful request, we’ll return HTTP Response: 200 OK

Payment related invoice attributes like due-amount will be updated. Invoice status will be set to paid if no amount is left due.

Still have questions? We’re happy to help!

Contact Us