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	DEPRECATED This will be `true` when `payment_options` are assigned to the invoice and `false` when there are no `payment_options`.
`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: close, draft, re-open, or send (marked the invoice as sent). If `event_type` was omitted in the request, a `null` value is returned, meaning the invoice was sent.
`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 ([email protected])"

Example Response:

{
  "invoice_messages":[
    {
      "id":27835209,
      "sent_by":"Bob Powell",
      "sent_by_email":"[email protected]",
      "sent_from":"Bob Powell",
      "sent_from_email":"[email protected]",
      "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":"[email protected]"
        }
      ],
      "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":"[email protected]",
      "sent_from":"Bob Powell",
      "sent_from_email":"[email protected]",
      "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":"[email protected]"
        },
        {
          "name":"Bob Powell",
          "email":"[email protected]"
        }
      ],
      "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 and send an invoice message

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

A note about the optional event_type parameter: If event_type is omitted in a request, its default value of null means the message will be sent. In such a request, if the recipients array is omitted or empty and send_me_a_copy is also omitted or set to false, the request will fail because the message has no recipients. When omitting event_type to create and send a message, be sure to include a recipients array as a parameter or ensure the send_me_a_copy parameter is included and set to true.

POST /v2/invoices/{INVOICE_ID}/messages

Parameter	Type	Required	Description
`recipients`	array	optional	Array of recipient parameters. See below for more details.
`subject`	string	optional	The message subject.
`body`	string	optional	The message body.
`include_link_to_client_invoice`	boolean	optional	DEPRECATED A link to the client invoice URL will be automatically included in the message email if `payment_options` have been assigned to the invoice. Setting to `true` will be ignored. Setting to `false` will clear all `payment_options` on the invoice.
`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	Omit when intending to create and send a message. If omitted, the default value is `null` and the message will be sent. See other sections below for including this parameter with the following options: close, draft, re-open, or send (which marks a draft invoice as sent, it does not send the message).

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 ([email protected])" \
  -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":"[email protected]"}]}'

Example Response:

{
  "id":27835324,
  "sent_by":"Bob Powell",
  "sent_by_email":"[email protected]",
  "sent_from":"Bob Powell",
  "sent_from_email":"[email protected]",
  "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":"[email protected]"
    },
    {
      "name":"Bob Powell",
      "email":"[email protected]"
    }
  ],
  "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 ([email protected])"

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 ([email protected])" \
  -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 ([email protected])" \
  -X POST \
  -H "Content-Type: application/json" \
  -d '{"event_type":"send"}'

Example Response:

{
  "id":27835325,
  "sent_by":"Bob Powell",
  "sent_by_email":"[email protected]",
  "sent_from":"Bob Powell",
  "sent_from_email":"[email protected]",
  "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 (written off). 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 ([email protected])" \
  -X POST \
  -H "Content-Type: application/json" \
  -d '{"event_type":"close"}'

Example Response:

{
  "id":27835326,
  "sent_by":"Bob Powell",
  "sent_by_email":"[email protected]",
  "sent_from":"Bob Powell",
  "sent_from_email":"[email protected]",
  "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 written-off (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 ([email protected])" \
  -X POST \
  -H "Content-Type: application/json" \
  -d '{"event_type":"re-open"}'

Example Response:

{
  "id":27835327,
  "sent_by":"Bob Powell",
  "sent_by_email":"[email protected]",
  "sent_from":"Bob Powell",
  "sent_from_email":"[email protected]",
  "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 ([email protected])" \
  -X POST \
  -H "Content-Type: application/json" \
  -d '{"event_type":"draft"}'

Example Response:

{
  "id":27835328,
  "sent_by":"Bob Powell",
  "sent_by_email":"[email protected]",
  "sent_from":"Bob Powell",
  "sent_from_email":"[email protected]",
  "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
}

Welcome to the Harvest API v2 Help Center

The invoice message object

The invoice message recipient object

Required permissions

List all messages for an invoice

Create and send an invoice message

Retrieve invoice message subject and body for specific invoice

Delete an invoice message

Mark a draft invoice as sent

Mark an open invoice as closed

Re-open a closed invoice

Mark an open invoice as a draft

Still have questions? We’re happy to help!