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: 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) |
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 | 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 | 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
}