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

Payments

Payments are a record of the payments made on your invoices.

Access Requirements

AccessRequires Authorization
Scopesuser:payments:read
user:payments:write

Includes

Include NameDescription
clientinclude client info in payment
invoiceinclude related invoice info in payment
credit_noteinclude credit note info in payment
orderinclude gateway order in payment
gatewayinclude gateway info in payment

Filters

Filter TypeNameFieldDescription
Equalslogidlogidmatches exact logid
Inlogidslogidmatches list of logids, one specified per query arg
Betweendate_mindatedate greater than or equal to parameter, YYYY-MM-DD format
Betweendate_maxdatedate less than parameter, YYYY-MM-DD format
Betweenupdated_minupdatedupdated date greater than or equal to parameter, YYYY-MM-DD format
Betweenupdated_maxupdatedupdated date less than parameter, YYYY-MM-DD format
Betweenamount_minamountamount greater than or equal to parameter
Betweenamount_maxamountamount less than parameter
Equalstypetypematches exact type
Equalscustomeridcustomeridmatches exact customerid
Incustomeridscustomeridmatches list of customerids, one specified per query arg
Equalsclientidclientidmatches exact clientid
Inclientidsclientidmatches list of clientids, one specified per query arg
Equalscurrencycurrency _codematches exact currency code
Equalsinvoiceidinvoiceidmatches exact invoice id
Likenotesnotenote contains parameter
Equalsfrom_creditfrom_credittrue/false filters for payment converted from credit or not
Likeclient_namespecialclient fname, lname, or organization or invoice organization or credit organization contains parameter
Likenumberspecialinvoice or credit number contains parameter
Equalspayment_or _creditspecial‘invoice’ returns payments, ‘credit’ returns credits

Field Descriptions

underlined fields are required on creation

FieldTypeDescription
accounting _systemidstringunique identifier of business client exists on
amountobjectamount paid on invoice
– amountstringstring-decimal amount
-codestringthree-letter currency code
bulk_paymentidint
clientidintid of client who made the payment
creditidintid of related credit
datestringdate the payment was made, YYYY-MM-DD format
from_creditboolwhether or not the payment was converted from a Credit on a Client’s account
gatewaystringthe payment processor used, if any
idintunique id (across this business) for payment
invoiceidintid of related invoice
logidintduplicate of id
notestringnotes on payment, often used for credit card reference number
orderidintid of related orderid
overpaymentidintid of related overpayment if relevant
send_client_notificationboolwhether to send the client a notification of this payment
transactionidintdeprecated
typestring“Check”, “Credit”, “Cash”, etc.
updateddatetimedate payment was last updated, YYYY-MM-DD
vis_stateint0 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
    }
  }
}