Payments
Payments are a record of the payments made on your invoices.
Access Requirements
| Access | Requires Authorization |
| Scopes | user:payments:readuser:payments:write |
Includes
| Include Name | Description |
|---|---|
| client | include client info in payment |
| invoice | include related invoice info in payment |
| credit_note | include credit note info in payment |
| order | include gateway order in payment |
| gateway | include gateway info in payment |
Filters
| Filter Type | Name | Field | Description |
|---|---|---|---|
| Equals | logid | logid | matches exact logid |
| In | logids | logid | matches list of logids, one specified per query arg |
| Between | date_min | date | date greater than or equal to parameter, YYYY-MM-DD format |
| Between | date_max | date | date less than parameter, YYYY-MM-DD format |
| Between | updated_min | updated | updated date greater than or equal to parameter, YYYY-MM-DD format |
| Between | updated_max | updated | updated date less than parameter, YYYY-MM-DD format |
| Between | amount_min | amount | amount greater than or equal to parameter |
| Between | amount_max | amount | amount less than parameter |
| Equals | type | type | matches exact type |
| Equals | customerid | customerid | matches exact customerid |
| In | customerids | customerid | matches list of customerids, one specified per query arg |
| Equals | clientid | clientid | matches exact clientid |
| In | clientids | clientid | matches list of clientids, one specified per query arg |
| Equals | currency | currency _code | matches exact currency code |
| Equals | invoiceid | invoiceid | matches exact invoice id |
| Like | notes | note | note contains parameter |
| Equals | from_credit | from_credit | true/false filters for payment converted from credit or not |
| Like | client_name | special | client fname, lname, or organization or invoice organization or credit organization contains parameter |
| Like | number | special | invoice or credit number contains parameter |
| Equals | payment_or _credit | special | ‘invoice’ returns payments, ‘credit’ returns credits |
Field Descriptions
underlined fields are required on creation
| Field | Type | Description |
|---|---|---|
| accounting _systemid | string | unique identifier of business client exists on |
| amount | object | amount paid on invoice |
| – amount | string | string-decimal amount |
| -code | string | three-letter currency code |
| bulk_paymentid | int | |
| clientid | int | id of client who made the payment |
| creditid | int | id of related credit |
| date | string | date the payment was made, YYYY-MM-DD format |
| from_credit | bool | whether or not the payment was converted from a Credit on a Client’s account |
| gateway | string | the payment processor used, if any |
| id | int | unique id (across this business) for payment |
| invoiceid | int | id of related invoice |
| logid | int | duplicate of id |
| note | string | notes on payment, often used for credit card reference number |
| orderid | int | id of related orderid |
| overpaymentid | int | id of related overpayment if relevant |
| send_client_notification | bool | whether to send the client a notification of this payment |
| transactionid | int | deprecated |
| type | string | “Check”, “Credit”, “Cash”, etc. |
| updated | datetime | date payment was last updated, YYYY-MM-DD |
| vis_state | int | 0 for active, 1 for deleted |
Get Single Payment
Request: https://api.freshbooks.com/accounting/account/<accountid>/payments/payments/<id>
Response:
{
"response": {
"result": {
"payment": {
"accounting_systemid": "zDmNq",
"amount": {
"amount": "10.00",
"code": "USD"
},
"bulk_paymentid": null,
"creditid": null,
"clientid": 1758507,
"date": "2013-12-10",
"from_credit": false,
"gateway": null,
"id": 10865326
"invoiceid": 2010190,
"logid": 10865326,
"note": "",
"orderid": null,
"overpaymentid": null,
"send_client_notification": null,
"transactionid": null,
"type": "Check",
"updated": "2016-09-28 21:00:46",
"vis_state": 1,
}
}
}
}Create Single Payment
Request: POST https://api.freshbooks.com/accounting/account/<accountid>/payments/payments
{
"payment":{
"invoiceid": 2214249,
"amount": {
"amount": "10.00"
},
"date": "2013-12-10",
"type": "Check"
}
}Response:
{
"response": {
"result": {
"payment": {
"orderid": null,
"accounting_systemid": "zDmNq",
"updated": "2016-09-29 19:09:17",
"invoiceid": 2214249,
"creditid": null,
"amount": {
"amount": "0.00",
"code": "USD"
},
"clientid": 1831231,
"vis_state": 0,
"logid": 10865341,
"note": "",
"overpaymentid": 10865342,
"gateway": null,
"date": "2013-12-10",
"transactionid": null,
"from_credit": false,
"type": "Check",
"id": 10865341
}
}
}
}Update Single Payment
Request: PUT https://api.freshbooks.com/accounting/account/<accountid>/payments/payments/<id>
{
"payment": {
"invoiceid": 2219739
}
}Response:
{
"response": {
"result": {
"payment": {
"orderid": null,
"accounting_systemid": "KAG77",
"updated": "2016-09-28 18:46:36",
"invoiceid": 2219739,
"creditid": null,
"amount": {
"amount": "10.00",
"code": "USD"
},
"clientid": 2185379,
"vis_state": 0,
"logid": 10865291,
"note": "",
"overpaymentid": null,
"gateway": null,
"date": "2013-12-10",
"transactionid": null,
"from_credit": false,
"type": "Check",
"id": 10865291
}
}
}
}Delete Single Payment
Request: PUT https://api.freshbooks.com/accounting/account/<accountid>/payments/payments/<id>
{
"payment": {
"vis_state": 1
}
}Response:
{
"response": {
"result": {
"payment": {
"orderid": null,
"accounting_systemid": "zDmNq",
"updated": "2016-09-28 21:00:46",
"invoiceid": 2010190,
"creditid": null,
"amount": {
"amount": "10.00",
"code": "USD"
},
"clientid": 1758507,
"vis_state": 1,
"logid": 10865326,
"note": "",
"overpaymentid": null,
"gateway": null,
"date": "2013-12-10",
"transactionid": null,
"from_credit": false,
"type": "Check",
"id": 10865326
}
}
}
}List Payments
Request: GET https://api.freshbooks.com/accounting/account/<accountid>/payments/payments
Response:
{
"response": {
"result": {
"per_page": 15,
"pages": 1,
"total": 3,
"payments": [
{
// same format as single payment
},
{
// same format as single payment
},
{
// same format as single payment
}
],
"page": 1
}
}
}Get Single Payment
Request: GET
https://api.freshbooks.com/accounting/account/<accountid>/payments/payments/<id>
url = "https://api.freshbooks.com/accounting/account/<accountid>/payments/payments/<id>"
headers = {'Authorization': 'Bearer <Bearer Token>', 'Api-Version': 'alpha', 'Content-Type': 'application/json'}
res = requests.get(url, data=None, headers=headers)
Response:
{
"response": {
"result": {
"payment": {
"orderid": null,
"accounting_systemid": "zDmNq",
"updated": "2016-09-28 21:00:46",
"invoiceid": 2010190,
"creditid": null,
"amount": {
"amount": "10.00",
"code": "USD"
},
"clientid": 1758507,
"vis_state": 1,
"logid": 10865326,
"note": "",
"overpaymentid": null,
"gateway": null,
"date": "2013-12-10",
"transactionid": null,
"from_credit": false,
"type": "Check",
"id": 10865326
}
}
}
}
Create Single Payment
Request: POST
https://api.freshbooks.com/accounting/account/<accountid>/payments/payments
url = "https://api.freshbooks.com/accounting/account/<accountid>/payments/payments"
headers = {'Authorization': 'Bearer <Bearer Token>', 'Api-Version': 'alpha', 'Content-Type': 'application/json'}
payload = { 'payment': {
'invoiceid': 2214249,
'amount': {
'amount': "10.00"
},
'date': "2013-12-10",
'type': "credit"
}
}
res = requests.post(url, data=json.dumps(payload), headers=headers)
Response:
{
"response": {
"result": {
"payment": {
"orderid": null,
"accounting_systemid": "zDmNq",
"updated": "2016-09-29 19:09:17",
"invoiceid": 2214249,
"creditid": null,
"amount": {
"amount": "0.00",
"code": "USD"
},
"clientid": 1831231,
"vis_state": 0,
"logid": 10865341,
"note": "",
"overpaymentid": 10865342,
"gateway": null,
"date": "2013-12-10",
"transactionid": null,
"from_credit": false,
"type": "Check",
"id": 10865341
}
}
}
}
Update Single Payment
Request: PUT
https://api.freshbooks.com/accounting/account/<accountid>/payments/payments/<id>
url = "https://api.freshbooks.com/accounting/account/<accountid>/payments/payments/<id>"
headers = {'Authorization': 'Bearer <Bearer Token>', 'Api-Version': 'alpha', 'Content-Type': 'application/json'}
payload = { 'payment': {
'invoiceid': 2219739
}
}
res = requests.put(url, data=json.dumps(payload), headers=headers)
Response:
{
"response": {
"result": {
"payment": {
"orderid": null,
"accounting_systemid": "KAG77",
"updated": "2016-09-28 18:46:36",
"invoiceid": 2219739,
"creditid": null,
"amount": {
"amount": "10.00",
"code": "USD"
},
"clientid": 2185379,
"vis_state": 0,
"logid": 10865291,
"note": "",
"overpaymentid": null,
"gateway": null,
"date": "2013-12-10",
"transactionid": null,
"from_credit": false,
"type": "Check",
"id": 10865291
}
}
}
}
Delete Single Payment
Request: PUT
https://api.freshbooks.com/accounting/account/<accountid>/payments/payments/<id>
url = "https://api.freshbooks.com/accounting/account/<accountid>/payments/payments/<id>"
headers = {'Authorization': 'Bearer <Bearer Token>', 'Api-Version': 'alpha', 'Content-Type': 'application/json'}
payload = { 'payment': {
'vis_state': 1
}
}
res = requests.put(url, data=json.dumps(payload), headers=headers)
Response:
{
"response": {
"result": {
"payment": {
"orderid": null,
"accounting_systemid": "zDmNq",
"updated": "2016-09-28 21:00:46",
"invoiceid": 2010190,
"creditid": null,
"amount": {
"amount": "10.00",
"code": "USD"
},
"clientid": 1758507,
"vis_state": 1,
"logid": 10865326,
"note": "",
"overpaymentid": null,
"gateway": null,
"date": "2013-12-10",
"transactionid": null,
"from_credit": false,
"type": "Check",
"id": 10865326
}
}
}
}
List Payments
Request: GET
https://api.freshbooks.com/accounting/account/<accountid>/payments/payments
url = "https://api.freshbooks.com/accounting/account/<accountid>/payments/payments"
headers = {'Authorization': 'Bearer <Bearer Token>', 'Api-Version': 'alpha', 'Content-Type': 'application/json'}
res = requests.get(url, data=None, headers=headers)
Response:
{
"response": {
"result": {
"per_page": 15,
"pages": 1,
"total": 3,
"payments": [
{
// same format as single payment
},
{
// same format as single payment
},
{
// same format as single payment
}
],
"page": 1
}
}
}