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

Credits

General Info

Credits are notes issued to Clients for when you need to owe a service to be provided at a future date to your Clients. These include Credit Notes, Prepayment and Overpayment Credits which can then be applied to future Invoices.

Access Requirements

AccessRequires Authorization
Scopesuser:credit_notes:write
user:credit_notes:read

Credit Notes 

Credit Notes are used for when you want to offer Items or Services to Clients at a future date without receiving any form of payment from your Clients. Credit Notes are often issued as gifts, loyalty rewards, or free offers to entice new customers to try out your Items or Services, as well as in lieu of refunding payments. Create

Credit Note or Prepayment

FieldTypeDescription
credit_numberstringname of the credit note
currency_codestringabbreviated currency code identified type of currency
create_datedatedate the credit was created
notesstringnotes associated with the creation of the credit note.
credit_typeenumdefines type of credit (i.e. “goodwill” or “prepayment”
termsstringterms of the credit note
languageenumlanguage the credit is received in. ie. “en”
linesarrayline item of a credit. Each lines array that is created provides an additional line item on the credit. 
clientidstringidentifier for client the note is associated with. For information on how to find the clientid, check the “Client” section. 

Credit Lines 

FieldTypeDescription
namestringname of the credit note
descriptionstringabbreviated currency code identified type of currency
taxName1stringname of the first tax on the credit line.
taxAmount1stringfirst tax amount in percentage, up to 3 decimal places (i.e. “13.175”)
taxName2stringname of the second tax on the credit line. 
taxAmount2stringsecond tax amount in percentage, up to 3 decimal places (i.e. “6.175”)
compounded_taxbooleanThe second tax will take the first tax into its calculation.
unit_costobjectthe cost of one item, before taxes. sub-fields: amount (string, i.e. “150”) and code (enum, i.e. “USD”, “CAD”)
credit_notestringadditional information related to the description of the credit. 

List all Credits

Request: GET "https://api.freshbooks.com/accounting/account/<accountid>/credit_notes/credit_notes"

Response:

{
   "response": {
      "result": {
         "credit_notes": [
             {
                 "accounting_systemid": "K7viiN"
                 "amount": {
                     "amount": "25.00",
                     "code": "USD"
                },
                 "city": "",
                 "clientid": "H3Llo"                 "code": "",
                 "country": "Canada",
                 "create_date": "2020-9-22",
                 "credit_number": "00002134",
                 "credit_type": "goodwill",
                 "creditid": 31131,
                 "current_organization": "Zoom PBS",
                 "description": "",
                 "display_status": "created",
                 "dispute_status": null,
                 "ext_archive": 0,
                 "fname": "Wayne",
                 "id": 31131,
                 "language": "en",
                 "last_order_status": null,
                 "lname": "Bruce",
                 "notes": "",
                 "organization": "Wayne Industries",
                 "paid": {
                     "amount": "15.00",
                     "code": "CAD"
                 },
                 "payment_status": "paid",
                 "province": "",
                 "sentid": 1,
                 "status": "created",
                 "street": "",
                 "street2": "",
                 "template": "clean-grouped",
                 "terms": null,
                 "vat_name":  null,
                 "vat_number": "",
                 "vis_state": 0,
             }]
         }
      }
   }
},{...}

Get Single Client

Request: POST "https://api.freshbooks.com/accounting/account/<accountid>/credit_notes/credit_notes/<creditid>"

{
   "response": {
      "result": {
         "credit_notes": [
             {
                 "accounting_systemid": "K7viiN"
                 "amount": {
                     "amount": "25.00",
                     "code": "USD"
                },
                 "city": "",
                 "clientid": "H3Llo"                 "code": "",
                 "country": "Canada",
                 "create_date": "2020-9-22",
                 "credit_number": "00002134",
                 "credit_type": "goodwill",
                 "creditid": 31131,
                 "current_organization": "Zoom PBS",
                 "description": "",
                 "display_status": "created",
                 "dispute_status": null,
                 "ext_archive": 0,
                 "fname": "Wayne",
                 "id": 31131,
                 "language": "en",
                 "last_order_status": null,
                 "lname": "Bruce",
                 "notes": "",
                 "organization": "Wayne Industries",
                 "paid": {
                     "amount": "15.00",
                     "code": "CAD"
                 },
                 "payment_status": "paid",
                 "province": "",
                 "sentid": 1,
                 "status": "created",
                 "street": "",
                 "street2": "",
                 "template": "clean-grouped",
                 "terms": null,
                 "vat_name":  null,
                 "vat_number": "",
                 "vis_state": 0,
             }]
         }
      }
   }
}

Create Credit Note

Request: POST

"https://api.freshbooks.com/accounting/account/<accountid>/credit_notes/credit_notes"

{
   "credit_note": {
      "clientid": 12345,
      "credit_number": "0923403",
      "currency_code": "CAD",
      "create_date": "2020-09-22",
      "notes": "Free $150 voucher",
      "credit_type": "goodwill",
      "terms": "Squarespace site"
   }
}


Response:

{
   "response": {
      "result": {
         "credit_notes": [
             {
                 "accounting_systemid": "K7viiN"
                 "amount": {
                     "amount": "25.00",
                     "code": "USD"
                },
                 "city": "",
                 "clientid": "H3Llo"                 "code": "",
                 "country": "Canada",
                 "create_date": "2020-9-22",
                 "credit_number": "00002134",
                 "credit_type": "goodwill",
                 "creditid": 31131,
                 "current_organization": "Zoom PBS",
                 "description": "",
                 "display_status": "created",
                 "dispute_status": null,
                 "ext_archive": 0,
                 "fname": "Wayne",
                 "id": 31131,
                 "language": "en",
                 "last_order_status": null,
                 "lname": "Bruce",
                 "notes": "",
                 "organization": "Wayne Industries",
                 "paid": {
                     "amount": "15.00",
                     "code": "CAD"
                 },
                 "payment_status": "paid",
                 "province": "",
                 "sentid": 1,
                 "status": "created",
                 "street": "",
                 "street2": "",
                 "template": "clean-grouped",
                 "terms": null,
                 "vat_name":  null,
                 "vat_number": "",
                 "vis_state": 0,
             }]
         }
      }
   }
}

Delete Credit

Request:  PUT "https://api.freshbooks.com/accounting/account/<accountid>/credit_notes/credit_notes/<creditid>"

{
   "credit_note": {
      "vis_state": 1
   }
}


Response:

{
   "response": {
      "result": {
         "credit_notes": [
             {
                 "accounting_systemid": "K7viiN"
                 "amount": {
                     "amount": "25.00",
                     "code": "USD"
                },
                 "city": "",
                 "clientid": "H3Llo"                 "code": "",
                 "country": "Canada",
                 "create_date": "2020-9-22",
                 "credit_number": "00002134",
                 "credit_type": "goodwill",
                 "creditid": 31131,
                 "current_organization": "Zoom PBS",
                 "description": "",
                 "display_status": "created",
                 "dispute_status": null,
                 "ext_archive": 0,
                 "fname": "Wayne",
                 "id": 31131,
                 "language": "en",
                 "last_order_status": null,
                 "lname": "Bruce",
                 "notes": "",
                 "organization": "Wayne Industries",
                 "paid": {
                     "amount": "15.00",
                     "code": "CAD"
                 },
                 "payment_status": "paid",
                 "province": "",
                 "sentid": 1,
                 "status": "created",
                 "street": "",
                 "street2": "",
                 "template": "clean-grouped",
                 "terms": null,
                 "vat_name":  null,
                 "vat_number": "",
                 "vis_state": 1,
             }]
         }
      }

Update Credit

Request: POST "https://api.freshbooks.com/accounting/account/<accountid>/credit_notes/credit_notes"

Request: PUT

"https://api.freshbooks.com/accounting/account/<accountid>/credit_notes/credit_notes/<creditid>"

{
   "credit_note": {
      "notes": "Pay me my money!"
   }
}


Response:

{
   "response": {
      "result": {
         "credit_notes": [
             {
                 "accounting_systemid": "K7viiN"
                 "amount": {
                     "amount": "25.00",
                     "code": "USD"
                },
                 "city": "",
                 "clientid": "H3Llo"                 "code": "",
                 "country": "Canada",
                 "create_date": "2020-9-22",
                 "credit_number": "00002134",
                 "credit_type": "goodwill",
                 "creditid": 31131,
                 "current_organization": "Zoom PBS",
                 "description": "",
                 "display_status": "created",
                 "dispute_status": null,
                 "ext_archive": 0,
                 "fname": "Wayne",
                 "id": 31131,
                 "language": "en",
                 "last_order_status": null,
                 "lname": "Bruce",
                 "notes": "Pay me my money!",
                 "organization": "Wayne Industries",
                 "paid": {
                     "amount": "15.00",
                     "code": "CAD"
                 },
                 "payment_status": "paid",
                 "province": "",
                 "sentid": 1,
                 "status": "created",
                 "street": "",
                 "street2": "",
                 "template": "clean-grouped",
                 "terms": null,
                 "vat_name":  null,
                 "vat_number": "",
                 "vis_state": 0,
             }]
         }
      }
   }
}