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

Invoice Payments

The invoice payment object

Attribute Type Description
id integer Unique ID for the payment.
amount decimal The amount of the payment.
paid_at datetime Date and time the payment was made.
paid_date date Date the payment was made.
recorded_by string The name of the person who recorded the payment.
recorded_by_email string The email of the person who recorded the payment.
notes string Any notes associated with the payment.
transaction_id string Either the card authorization or PayPal transaction ID.
payment_gateway object The payment gateway id and name used to process the payment.
created_at datetime Date and time the payment was recorded.
updated_at datetime Date and time the payment was last updated.

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}/payments endpoint. Insufficient permissions will result in a 403 Forbidden status code.

List all payments for an invoice

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

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

GET /v2/invoices/{INVOICE_ID}/payments
Parameter Type Description
updated_since datetime Only return invoice payments 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/13150378/payments" \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H "Harvest-Account-Id: $ACCOUNT_ID" \
  -H "User-Agent: MyApp ([email protected])"

Example Response:

{
    "invoice_payments": [
        {
            "id": 10112854,
            "amount": 10700,
            "paid_at": "2017-02-21T00:00:00Z",
            "paid_date": "2017-02-21",
            "recorded_by": "Alice Doe",
            "recorded_by_email": "[email protected]",
            "notes": "Paid via check #4321",
            "transaction_id": null,
            "created_at": "2017-06-27T16:24:57Z",
            "updated_at": "2017-06-27T16:24:57Z",
            "payment_gateway": {
                "id": 1234,
                "name": "Linkpoint International"
            }
        }
    ],
    "per_page": 2000,
    "total_pages": 1,
    "total_entries": 1,
    "next_page": null,
    "previous_page": null,
    "page": 1,
    "links": {
        "first": "https://api.harvestapp.com/v2/invoices/13150378/payments?page=1&per_page=2000",
        "next": null,
        "previous": null,
        "last": "https://api.harvestapp.com/v2/invoices/13150378/payments?page=1&per_page=2000"
    }
}

Create an invoice payment

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

POST /v2/invoices/{INVOICE_ID}/payments
Parameter Type Required Description
amount decimal required The amount of the payment.
paid_at datetime optional Date and time the payment was made. Pass either paid_at or paid_date, but not both.
paid_date date optional Date the payment was made. Pass either paid_at or paid_date, but not both.
notes string optional Any notes to be associated with the payment.
send_thank_you boolean optional Whether or not to send a thank you email (if enabled for your account in Invoices > Configure > Messages). Only sends an email if the invoice will be fully paid after creating this payment. Defaults to true.

Example Request:

curl "https://api.harvestapp.com/v2/invoices/13150378/payments" \
  -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 '{"amount":1575.86,"paid_at":"2017-07-24T13:32:18Z","notes":"Paid by phone"}'

Example Response:

{
    "id": 10336386,
    "amount": 1575.86,
    "paid_at": "2017-07-24T13:32:18Z",
    "paid_date": "2017-07-24",
    "recorded_by": "Jane Bar",
    "recorded_by_email": "[email protected]",
    "notes": "Paid by phone",
    "transaction_id": null,
    "created_at": "2017-07-28T14:42:44Z",
    "updated_at": "2017-07-28T14:42:44Z",
    "payment_gateway": {
        "id": null,
        "name": null
    }
}

Delete an invoice payment

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

DELETE /v2/invoices/{INVOICE_ID}/payments/{PAYMENT_ID}

Example Request:

curl "https://api.harvestapp.com/v2/invoices/13150378/payments/10336386" \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H "Harvest-Account-Id: $ACCOUNT_ID" \
  -H "User-Agent: MyApp ([email protected])" \
  -X DELETE

Still have questions? We’re happy to help!

Contact Us