× Freshbooks App Logo
FreshBooks
Official App
Free - Google Play
Get it

Payments

General Info

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

*Requires Authorization*

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
orderid int id of related orderid
accounting _systemid string unique identifier of business client exists on
updated datetime date staff object was last updated, YYYY-MM-DD
invoiceid int id of related invoice
creditid int id of related credit
amount object subfields: amount and code
amount string amount paid on invoice, to two decimal places
code string three-letter currency code
clientid int id of client who made the payment
vis_state int 0 for active, 1 for deleted
logid int duplicate of id
note string notes on payment, often used for credit card reference number
overpaymentid int id of related overpayment if relevant
gateway string the payment processor used, if any
date string date the payment was made, YYYY-MM-DD format
transactionid int deprecated
from_credit bool whether or not the payment was converted from a Credit on a Client's account
type string "Check", "Credit", "Cash", etc.
id int unique id (across this business) for payment

Get Single Payment

Request: https://api.freshbooks.com/accounting/account/<accountid>/payments/payments/<id>

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

{
  "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/&ltaccountid&gt/payments/payments/&ltid&gt


url = "https://api.freshbooks.com/accounting/account/&ltaccountid&gt/payments/payments/&ltid&gt"
headers = {'Authorization': 'Bearer &ltBearer Token&gt', '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/&ltaccountid&gt/payments/payments


url = "https://api.freshbooks.com/accounting/account/&ltaccountid&gt/payments/payments"
headers = {'Authorization': 'Bearer &ltBearer Token&gt', '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/&ltaccountid&gt/payments/payments/&ltid&gt


url = "https://api.freshbooks.com/accounting/account/&ltaccountid&gt/payments/payments/&ltid&gt"
headers = {'Authorization': 'Bearer &ltBearer Token&gt', '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/&ltaccountid&gt/payments/payments/&ltid&gt


url = "https://api.freshbooks.com/accounting/account/&ltaccountid&gt/payments/payments/&ltid&gt"
headers = {'Authorization': 'Bearer &ltBearer Token&gt', '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/&ltaccountid&gt/payments/payments


url = "https://api.freshbooks.com/accounting/account/&ltaccountid&gt/payments/payments"
headers = {'Authorization': 'Bearer &ltBearer Token&gt', '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
    }
  }
}