× FreshBooks App Logo
FreshBooks
Official App
Free - Google Play
Get it
You're currently on our US site. Select your regional site here:

Bill Payments (beta)

Bill Payments are a record of the payments made on a Bill.

Access Requirements

AccessRequires Authorization
Scopesuser:bill_payments:read
user:bill_payments:write

Field Descriptions

underlined fields are required on creation

Field New Descriptions

FieldTypeDescription
idintegeruniquely identifies the payment associated with the business.
amountobjectsubfields: amount and code
– amountstringamount paid to the bill
– codestringthree-letter currency code
billidintegerid of the bill to create the payment for
matched_with_expensebooleaninternal use. If the Bill has been reconciled with a bank-imported expense.
paid_datedatedate the payment was made, YYYY-MM-DD format
payment_typestring“Check”, “Credit”, “Cash”, etc.
notestringnotes on payment
vis_stateinteger0 for active, 1 for deleted, 2 for archived

Add Payment to Bill

curl -L -X POST 'https://api.freshbooks.com/accounting/account/<accountId>/bill_payments/bill_payments' \
-H 'Authorization: Bearer <insert-bearer-token>' \
-H 'Content-Type: application/json' \
--data-raw '{
    "bill_payment": {
        "billid": "1626",
        "amount": {
            "amount": "4000.00",
            "code": "USD"
        },
        "payment_type": "Check",
        "paid_date": "2021-06-16",
        "note": "Test Payment via API"
    }
}'

#Response:
 {
    "response": {
        "result": {
            "bill_payment": {
                "amount": {
                    "amount": "4000.00",
                    "code": "USD"
                },
                "billid": 1626,
                "id": 1490,
                "matched_with_expense": false,
                "note": "Test Payment via API",
                "paid_date": "2021-06-16",
                "payment_type": "Check",
                "vis_state": 0
            }
        }
    }
}

Edit Payment to Bill

curl -L -X PUT 'https://api.freshbooks.com/accounting/account/<accountId>/bill_payments/bill_payments/<billPaymentId>' \
-H 'Authorization: Bearer <insert-bearer-token>' \
-H 'Content-Type: application/json' \
--data-raw '{
    "bill_payment": {
        "billid": "1626",
        "amount": {
            "amount": "23000",
            "code": "USD"
        },
        "payment_type": "Cash",
        "paid_date": "2020-10-09",
        "note": ""
    }
}'

#Response:
 {
    "response": {
        "result": {
            "bill_payment": {
                "amount": {
                    "amount": "23000.00",
                    "code": "USD"
                },
                "billid": 1626,
                "id": 1490,
                "matched_with_expense": false,
                "note": "",
                "paid_date": "2021-06-16",
                "payment_type": "Cash",
                "vis_state": 0
            }
        }
    }
}

List Bill Payments

curl -L -X GET 'https://api.freshbooks.com/accounting/account/<accountId>/bill_payments/bill_payments' \
-H 'Authorization: Bearer <insert-bearer-token>'

#Response:
{
  "response": {
    "result": {
      "bill_payments": [
        {
          "amount": {
            "amount": "23000.00",
            "code": "USD"
          },
          "billid": 1626,
          "id": 1490,
          "matched_with_expense": false,
          "note": "",
          "paid_date": "2021-06-16",
          "payment_type": "Cash",
          "vis_state": 0
        }
      ]
    }
  }
}

Get A Bill Payment

curl -L -X GET 'https://api.freshbooks.com/accounting/account/<accountId>/bill_payments/bill_payments/<billPaymentId>' \
-H 'Authorization: Bearer <insert-bearer-token>'
 #Response:
{
  "response": {
    "result": {
      "bill_payment": {
        "amount": {
          "amount": "23000.00",
          "code": "USD"
        },
        "billid": 1626,
        "id": 1490,
        "matched_with_expense": false,
        "note": "",
        "paid_date": "2021-06-16",
        "payment_type": "Cash",
        "vis_state": 0
      }
    }
  }
}

Delete A Bill Payment

curl -L -X PUT 'https://api.freshbooks.com/accounting/account/<accountId>/bill_payments/bill_payments/<billPaymentId>' \ -H 'Authorization: Bearer <insert-bearer-token>' \ -H 'Content-Type: application/json' \ --data-raw '{ "bill_payment": { "vis_state": 1 } }'

Add Payment to Bill

Request: POST

https://api.freshbooks.com/accounting/account/<accountid>/bill_payments/bill_payments/<billid>


url = "https://api.freshbooks.com/accounting/account/<accountid>/bill_payments/bill_payments/<billid>"
headers = {'Authorization': 'Bearer <bearer token>', 'Api-Version': 'alpha', 'Content-Type': 'application/json'}
payload = {
  "bill_payment":{
    "billid":1141,
    "amount":{
      "amount":"100",
      "code":"EUR"
    },
    "payment_type":"Check",
    "paid_date":"2021-01-30",
    "note":""
  }
}
res = requests.post(url, data=json.dumps(payload), headers=headers)


Response:

{
  "response":{
    "result":{
      "bill_payment":{
        "amount":{
          "amount":"100.00",
          "code":"EUR"
        },
        "billid":1141,
        "id":901,
        "matched_with_expense":false,
        "note":"",
        "paid_date":"2021-01-30",
        "payment_type":"Check",
        "vis_state":0
      }
    }
  }
}

Edit Payment to Bill

Request: PUT

https://api.freshbooks.com/accounting/account/<accountid>/bill_payments/bill_payments/<billpaymentid>


url = "https://api.freshbooks.com/accounting/account/<accountid>/expenses/expenses/<id>"
headers = {'Authorization': 'Bearer <bearer token>', 'Api-Version': 'alpha', 'Content-Type': 'application/json'}
payload = {
  "bill_payment":{
    "billid":1141,
    "amount":{
      "amount":"0",
      "code":"EUR"
    },
    "payment_type":"Check",
    "paid_date":"2021-01-30",
    "note":"",
  }
res = requests.put(url, data=json.dumps(payload), headers=headers)


Response:

{
  "response":{
    "result":{
      "bill_payment":{
        "amount":{
          "amount":"0.00",
          "code":"EUR"
        },
        "billid":1141,
        "id":907,
        "matched_with_expense":false,
        "note":"",
        "paid_date":"2021-01-30",
        "payment_type":"Check",
        "vis_state":0
      }
    }
  }
}