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

Invoice Messages

The invoice message object

Attribute Type Description
id integer Unique ID for the message.
sent_by string Name of the user that created the message.
sent_by_email string Email of the user that created the message.
sent_from string Name of the user that the message was sent from.
sent_from_email string Email of the user that message was sent from.
recipients array Array of invoice message recipients.
subject string The message subject.
body string The message body.
include_link_to_client_invoice boolean Whether to include a link to the client invoice in the message body. Not used when thank_you is true.
attach_pdf boolean Whether to attach the invoice PDF to the message email.
send_me_a_copy boolean Whether to email a copy of the message to the current user.
thank_you boolean Whether this is a thank you message.
event_type string The type of invoice event that occurred with the message: send, close, draft, re-open, or view.
reminder boolean Whether this is a reminder message.
send_reminder_on date The date the reminder email will be sent.
created_at datetime Date and time the message was created.
updated_at datetime Date and time the message was last updated.

The invoice message recipient object

Attribute Type Description
name string Name of the message recipient.
email string Email of the message recipient.

Required permissions

You must be an Administrator or Manager with permission to create and edit invoices in order to interact with the /v2/invoices/{INVOICE_ID}/messages endpoint. Insufficient permissions will result in a 403 Forbidden status code.

List all messages for an invoice

Returns a list of messages associated with a given invoice. The invoice messages are returned sorted by creation date, with the most recently created messages appearing first.

The response contains an object with an invoice_messages property that contains an array of up to per_page messages. Each entry in the array is a separate message object. If no more messages are available, the resulting array will be empty. Several additional pagination properties are included in the response to simplify paginating your messages.

GET /v2/invoices/{INVOICE_ID}/messages
Parameter Type Description
updated_since datetime Only return invoice messages that have been updated since the given date and time.
page integer DEPRECATED 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)
This endpoint supports cursor-based pagination and therefore deprecates the page parameter. For more information, visit the pagination guide.

Example Request:

curl "https://api.harvestapp.com/v2/invoices/13150403/messages" \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H "Harvest-Account-Id: $ACCOUNT_ID" \
  -H "User-Agent: MyApp (yourname@example.com)"

Example Response:

{
  "invoice_messages":[
    {
      "id":27835209,
      "sent_by":"Bob Powell",
      "sent_by_email":"bobpowell@example.com",
      "sent_from":"Bob Powell",
      "sent_from_email":"bobpowell@example.com",
      "include_link_to_client_invoice":false,
      "send_me_a_copy":false,
      "thank_you":false,
      "reminder":false,
      "send_reminder_on":null,
      "created_at":"2017-08-23T22:15:06Z",
      "updated_at":"2017-08-23T22:15:06Z",
      "attach_pdf":true,
      "event_type":null,
      "recipients":[
        {
          "name":"Richard Roe",
          "email":"richardroe@example.com"
        }
      ],
      "subject":"Past due invoice reminder: #1001 from API Examples",
      "body":"Dear Customer,\r\n\r\nThis is a friendly reminder to let you know that Invoice 1001 is 144 days past due. If you have already sent the payment, please disregard this message. If not, we would appreciate your prompt attention to this matter.\r\n\r\nThank you for your business.\r\n\r\nCheers,\r\nAPI Examples"
    },
    {
      "id":27835207,
      "sent_by":"Bob Powell",
      "sent_by_email":"bobpowell@example.com",
      "sent_from":"Bob Powell",
      "sent_from_email":"bobpowell@example.com",
      "include_link_to_client_invoice":false,
      "send_me_a_copy":true,
      "thank_you":false,
      "reminder":false,
      "send_reminder_on":null,
      "created_at":"2017-08-23T22:14:49Z",
      "updated_at":"2017-08-23T22:14:49Z",
      "attach_pdf":true,
      "event_type":null,
      "recipients":[
        {
          "name":"Richard Roe",
          "email":"richardroe@example.com"
        },
        {
          "name":"Bob Powell",
          "email":"bobpowell@example.com"
        }
      ],
      "subject":"Invoice #1001 from API Examples",
      "body":"---------------------------------------------\r\nInvoice Summary\r\n---------------------------------------------\r\nInvoice ID: 1001\r\nIssue Date: 04/01/2017\r\nClient: 123 Industries\r\nP.O. Number: \r\nAmount: €288.90\r\nDue: 04/01/2017 (upon receipt)\r\n\r\nThe detailed invoice is attached as a PDF.\r\n\r\nThank you!\r\n---------------------------------------------"
    }
  ],
  "per_page":2000,
  "total_pages":1,
  "total_entries":2,
  "next_page":null,
  "previous_page":null,
  "page":1,
  "links":{
    "first":"https://api.harvestapp.com/api/v2/invoices/13150403/messages?page=1&per_page=2000",
    "next":null,
    "previous":null,
    "last":"https://api.harvestapp.com/v2/invoices/13150403/messages?page=1&per_page=2000"
  }
}

Create an invoice message

Creates a new invoice message object. Returns an invoice message object and a 201 Created response code if the call succeeded.

POST /v2/invoices/{INVOICE_ID}/messages
Parameter Type Required Description
recipients array required Array of recipient parameters. See below for details.
subject string optional The message subject.
body string optional The message body.
include_link_to_client_invoice boolean optional If set to true, a link to the client invoice URL will be included in the message email. Defaults to false. Ignored when thank_you is set to true.
attach_pdf boolean optional If set to true, a PDF of the invoice will be attached to the message email. Defaults to false.
send_me_a_copy boolean optional If set to true, a copy of the message email will be sent to the current user. Defaults to false.
thank_you boolean optional If set to true, a thank you message email will be sent. Defaults to false.
event_type string optional If provided, runs an event against the invoice. Options: close, draft, re-open, or send.
Recipient Parameter Type Required Description
name string optional Name of the message recipient.
email string required Email of the message recipient.

Example Request:

curl "https://api.harvestapp.com/v2/invoices/13150403/messages" \
  -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 '{"subject":"Invoice #1001","body":"The invoice is attached below.","attach_pdf":true,"send_me_a_copy":true,"recipients":[{"name":"Richard Roe","email":"richardroe@example.com"}]}'

Example Response:

{
  "id":27835324,
  "sent_by":"Bob Powell",
  "sent_by_email":"bobpowell@example.com",
  "sent_from":"Bob Powell",
  "sent_from_email":"bobpowell@example.com",
  "include_link_to_client_invoice":false,
  "send_me_a_copy":true,
  "thank_you":false,
  "reminder":false,
  "send_reminder_on":null,
  "created_at":"2017-08-23T22:25:59Z",
  "updated_at":"2017-08-23T22:25:59Z",
  "attach_pdf":true,
  "event_type":null,
  "recipients":[
    {
      "name":"Richard Roe",
      "email":"richardroe@example.com"
    },
    {
      "name":"Bob Powell",
      "email":"bobpowell@example.com"
    }
  ],
  "subject":"Invoice #1001",
  "body":"The invoice is attached below."
}

Retrieve invoice message subject and body for specific invoice

Returns the subject and body text as configured in Harvest of an invoice message for a specific invoice and a 200 OK response code if the call succeeded. Does not create the invoice message. If no parameters are passed, will return the subject and body of a general invoice message for the specific invoice.

GET /v2/invoices/{INVOICE_ID}/messages/new
Parameter Type Required Description
thank_you boolean optional Set to true to return the subject and body of a thank-you invoice message for the specific invoice.
reminder boolean optional Set to true to return the subject and body of a reminder invoice message for the specific invoice.

Example Request:

curl "https://api.harvestapp.com/v2/invoices/13150403/messages/new?reminder=true" \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H "Harvest-Account-Id: $ACCOUNT_ID" \
  -H "User-Agent: MyApp (yourname@example.com)"

Example Response:

{
  "invoice_id": 13150403,
  "subject": "Past due invoice reminder: #1002 from API Examples",
  "body": "Dear Customer,\n\nThis is a friendly reminder to let you know that Invoice 1002 is 20 days past due. If you have already sent the payment, please disregard this message. If not, we would appreciate your prompt attention to this matter.\n\nThank you for your business.\n\nCheers,\nAPI Examples\n",
  "reminder": false,
  "thank_you": false
}

Delete an invoice message

Delete an invoice message. Returns a 200 OK response code if the call succeeded.

DELETE /v2/invoices/{INVOICE_ID}/messages/{message_ID}

Example Request:

curl "https://api.harvestapp.com/v2/invoices/13150403/messages/27835324" \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H "Harvest-Account-Id: $ACCOUNT_ID" \
  -H "User-Agent: MyApp (yourname@example.com)" \
  -X DELETE

Mark a draft invoice as sent

Creates a new invoice message object and marks the invoice as sent. Returns an invoice message object and a 201 Created response code if the call succeeded.

POST /v2/invoices/{INVOICE_ID}/messages
Parameter Type Required Description
event_type string required Pass “send” to mark the invoice as sent.

Example Request:

curl "https://api.harvestapp.com/v2/invoices/13150403/messages" \
  -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 '{"event_type":"send"}'

Example Response:

{
  "id":27835325,
  "sent_by":"Bob Powell",
  "sent_by_email":"bobpowell@example.com",
  "sent_from":"Bob Powell",
  "sent_from_email":"bobpowell@example.com",
  "include_link_to_client_invoice":false,
  "send_me_a_copy":false,
  "thank_you":false,
  "reminder":false,
  "send_reminder_on":null,
  "created_at":"2017-08-23T22:25:59Z",
  "updated_at":"2017-08-23T22:25:59Z",
  "attach_pdf":false,
  "event_type":"send",
  "recipients":[],
  "subject":null,
  "body":null
}

Mark an open invoice as closed

Creates a new invoice message object and marks the invoice as closed. Returns an invoice message object and a 201 Created response code if the call succeeded.

POST /v2/invoices/{INVOICE_ID}/messages
Parameter Type Required Description
event_type string required Pass “close” to mark the invoice as closed.

Example Request:

curl "https://api.harvestapp.com/v2/invoices/13150403/messages" \
  -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 '{"event_type":"close"}'

Example Response:

{
  "id":27835326,
  "sent_by":"Bob Powell",
  "sent_by_email":"bobpowell@example.com",
  "sent_from":"Bob Powell",
  "sent_from_email":"bobpowell@example.com",
  "include_link_to_client_invoice":false,
  "send_me_a_copy":false,
  "thank_you":false,
  "reminder":false,
  "send_reminder_on":null,
  "created_at":"2017-08-23T22:25:59Z",
  "updated_at":"2017-08-23T22:25:59Z",
  "attach_pdf":false,
  "event_type":"close",
  "recipients":[],
  "subject":null,
  "body":null
}

Re-open a closed invoice

Creates a new invoice message object and re-opens a closed invoice. Returns an invoice message object and a 201 Created response code if the call succeeded.

POST /v2/invoices/{INVOICE_ID}/messages
Parameter Type Required Description
event_type string required Pass “re-open” to re-open the invoice.

Example Request:

curl "https://api.harvestapp.com/v2/invoices/13150403/messages" \
  -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 '{"event_type":"re-open"}'

Example Response:

{
  "id":27835327,
  "sent_by":"Bob Powell",
  "sent_by_email":"bobpowell@example.com",
  "sent_from":"Bob Powell",
  "sent_from_email":"bobpowell@example.com",
  "include_link_to_client_invoice":false,
  "send_me_a_copy":false,
  "thank_you":false,
  "reminder":false,
  "send_reminder_on":null,
  "created_at":"2017-08-23T22:25:59Z",
  "updated_at":"2017-08-23T22:25:59Z",
  "attach_pdf":false,
  "event_type":"re-open",
  "recipients":[],
  "subject":null,
  "body":null
}

Mark an open invoice as a draft

Creates a new invoice message object and marks an open invoice as a draft. Returns an invoice message object and a 201 Created response code if the call succeeded.

POST /v2/invoices/{INVOICE_ID}/messages
Parameter Type Required Description
event_type string required Pass “draft” to mark the invoice as a draft.

Example Request:

curl "https://api.harvestapp.com/v2/invoices/13150403/messages" \
  -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 '{"event_type":"draft"}'

Example Response:

{
  "id":27835328,
  "sent_by":"Bob Powell",
  "sent_by_email":"bobpowell@example.com",
  "sent_from":"Bob Powell",
  "sent_from_email":"bobpowell@example.com",
  "include_link_to_client_invoice":false,
  "send_me_a_copy":false,
  "thank_you":false,
  "reminder":false,
  "send_reminder_on":null,
  "created_at":"2017-08-23T22:25:59Z",
  "updated_at":"2017-08-23T22:25:59Z",
  "attach_pdf":false,
  "event_type":"draft",
  "recipients":[],
  "subject":null,
  "body":null
}

Still have questions? We’re happy to help!

Contact Us