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

Bill Vendors (beta)

A Vendor will work with your business to provide goods or services with a Bill to be paid at a later date. If you’ve already paid for an item or service in full, this would be an Expense instead. The Vendors API can be used to create, edit or delete Vendors in your FreshBooks account. As you track your Bills (part of Accounts Payable), you can add, manage and delete your Vendors as your business’ relationships with other Vendors grow directly using the Vendor API.

Access Requirements

AccessRequires Authorization
Scopesuser:bill_vendors:read
user:bill_vendors:write

Field Descriptions

underlined fields are required on creation

FieldTypeDescription
account_numberstringaccount number of the vendor
citystringcity of vendor
countrystringcountry of vendor
created_atdatetimeRead-only. time the vendor was created, YYYY-MM-DD HH:MM:SS format
currency_codestringdefault three-letter currency code for vendor
is_1099boolean set true if vendor is a 1099 contractor
languagestringtwo-letter language code, e.g. “en”
notestring 
outstanding_balanceobjectRead-only. subfields: amount and code
– amountstringthe outstanding amount to be paid to the Vendor
– codestringthree-letter currency code
overdue_balanceobjectRead-only. subfields: amount and code
– amountstringoverdue amount to be paid to the Vendor
– codestringthree-letter currency code
phonestringphone number
postal_codestringpostal code
primary_contact_emailstringvendor primary email
primary_contact_first_namestringvendor primary first name
primary_contact_last_namestringvendor primary last name
provincestringprovince
streetstringstreet address
street2stringstreet address 2nd part
tax_defaultsobjectarray of “bill_vendor_tax_defaults” object, see below
updated_atdatetimeRead-only. time of last modification to resource
vendor_namestringvendor name
vendoridintegerunique identifier for vendor
vis_statestringvisibility state, possible values are 0, 1, 2
websitestringvendor website address

Tax Defaults

vendoridintegerUnique identifier for vendor
taxidintegerUnique identifier for vendor tax default
system_taxidintegerTax id in your FreshBooks business, you can get the tax id using the get taxes api
enabledbooleanIf the tax is enabled for the vendor or not.
namestringRead-only. Populated from related system tax
amountstringRead-only. Populated from related system tax
tax_authorityidstringCustom identifier for tax tax authority.
created_atdatetimeRead-only. Time the resource was created, YYYY-MM-DD HH:MM:SS format
updated_atdatetimeRead-only. Time the resource was updated, YYYY-MM-DD HH:MM:SS format

Get Vendors

curl -L -X GET 'https://api.freshbooks.com/accounting/account/<accountId>/bill_vendors/bill_vendors' \
-H 'Authorization: Bearer <insert-bearer-token>'#Response:
{
    "response": {
        "result": {
            "bill_vendors": [
                {
                    "account_number": "45454545",
                    "city": "San Francisco",
                    "country": "United States",
                    "created_at": "2021-06-17 12:08:25",
                    "currency_code": "USD",
                    "is_1099": false,
                    "language": "en",
                    "note": null,
                    "outstanding_balance": [],
                    "overdue_balance": [],
                    "phone": "4158859378",
                    "postal_code": null,
                    "primary_contact_email": "someone@ikea.com",
                    "primary_contact_first_name": "Jimmy",
                    "primary_contact_last_name": "McNamara",
                    "province": "California",
                    "street": "332 Carlton Ave.",
                    "street2": null,
                    "tax_defaults": [],
                    "updated_at": "2021-06-17 12:08:25",
                    "vendor_name": "IKEA",
                    "vendorid": 1563,
                    "vis_state": 0,
                    "website": "ikea.com"
                },
                {
                    "account_number": "",
                    "city": null,
                    "country": null,
                    "created_at": "2021-06-16 09:49:46",
                    "currency_code": "USD",
                    "is_1099": false,
                    "language": "en",
                    "note": null,
                    "outstanding_balance": [
                        {
                            "amount": {
                                "amount": "53885.00",
                                "code": "USD"
                            }
                        }
                    ],
                    "overdue_balance": [],
                    "phone": null,
                    "postal_code": null,
                    "primary_contact_email": "someone@freshbooks.com",
                    "primary_contact_first_name": "Rahul",
                    "primary_contact_last_name": "Varma",
                    "province": null,
                    "street": null,
                    "street2": null,
                    "tax_defaults": [
                        {
                            "amount": "6",
                            "created_at": "2021-06-16 09:49:46",
                            "enabled": true,
                            "name": "GST1",
                            "system_taxid": 5307,
                            "tax_authorityid": null,
                            "taxid": 95,
                            "updated_at": "2021-06-16 09:49:46",
                            "vendorid": 1562
                        },
                        {
                            "amount": "7",
                            "created_at": "2021-06-16 09:49:46",
                            "enabled": true,
                            "name": "PST",
                            "system_taxid": 6047,
                            "tax_authorityid": null,
                            "taxid": 96,
                            "updated_at": "2021-06-16 09:49:46",
                            "vendorid": 1562
                        }
                    ],
                    "updated_at": "2021-06-16 09:49:46",
                    "vendor_name": "Bread Supplier",
                    "vendorid": 1562,
                    "vis_state": 0,
                    "website": ""
                },
                {
                    "account_number": "",
                    "city": "",
                    "country": null,
                    "created_at": "2021-01-18 13:28:30",
                    "currency_code": "EUR",
                    "is_1099": false,
                    "language": "en",
                    "note": null,
                    "outstanding_balance": [
                        {
                            "amount": {
                                "amount": "50113.00",
                                "code": "EUR"
                            }
                        }
                    ],
                    "overdue_balance": [
                        {
                            "amount": {
                                "amount": "50113.00",
                                "code": "EUR"
                            }
                        }
                    ],
                    "phone": "+",
                    "postal_code": "",
                    "primary_contact_email": "apiteam@gmail.com",
                    "primary_contact_first_name": "teak",
                    "primary_contact_last_name": "Wood",
                    "province": "",
                    "street": "",
                    "street2": null,
                    "tax_defaults": [],
                    "updated_at": "2021-01-18 13:35:39",
                    "vendor_name": "Teak Provider",
                    "vendorid": 817,
                    "vis_state": 0,
                    "website": null
                }
            ],
            "page": 1,
            "pages": 1,
            "per_page": 15,
            "total": 3
        }
    }
}

Add Vendor

curl -L -X POST 'https://api.freshbooks.com/accounting/account/<accountId>/bill_vendors/bill_vendors' \
-H 'Authorization: Bearer <insert-bearer-token>' \
-H 'Content-Type: application/json' \
--data-raw '{
    "bill_vendor": {
        "vendor_name": "IKEA",
        "primary_contact_first_name": "Jimmy",
        "primary_contact_last_name": "McNamara",
        "primary_contact_email": "someone@ikea.com",
        "primary_contact": null,
        "street": "332 Carlton Ave.",
        "street2": null,
        "city": "San Francisco",
        "province": "California",
        "postal_code": null,
        "country": "United States",
        "account_number": "45454545",
        "phone": "4158859378",
        "website": "ikea.com",
        "currency_code": "USD",
        "language": "en",
        "is_1099": false,
        "tax_defaults": []
    }
}'#Response:
{
    "response": {
        "result": {
            "bill_vendor": {
                "account_number": "45454545",
                "city": "San Francisco",
                "country": "United States",
                "created_at": "2021-06-17 12:08:25",
                "currency_code": "USD",
                "is_1099": false,
                "language": "en",
                "note": null,
                "outstanding_balance": [],
                "overdue_balance": [],
                "phone": "4158859378",
                "postal_code": null,
                "primary_contact_email": "someone@ikea.com",
                "primary_contact_first_name": "Jimmy",
                "primary_contact_last_name": "McNamara",
                "province": "California",
                "street": "332 Carlton Ave.",
                "street2": null,
                "tax_defaults": [],
                "updated_at": "2021-06-17 12:08:25",
                "vendor_name": "IKEA",
                "vendorid": 1563,
                "vis_state": 0,
                "website": "ikea.com"
            }
        }
    }
}

Edit Vendor Details

curl -L -X PUT 'https://api.freshbooks.com/accounting/account/<accountId>/bill_vendors/bill_vendors/<vendorId>' \
-H 'Authorization: Bearer <insert-bearer-token>' \
-H 'Content-Type: application/json' \
--data-raw '{
    "bill_vendor": {
        "vendor_name": "IKEA",
        "primary_contact_first_name": "Jimmy",
        "primary_contact_last_name": "McNamara",
        "primary_contact_email": "someone2@ikea.com",
        "primary_contact": null,
        "street": "332 Carlton Ave.",
        "street2": null,
        "city": "San Francisco",
        "province": "California",
        "postal_code": null,
        "country": "United States",
        "account_number": "45454545",
        "phone": "4158859378",
        "website": "ikea.com",
        "currency_code": "USD",
        "language": "en",
        "is_1099": false,
        "tax_defaults": []
    }
}'#Response:
{
    "response": {
        "result": {
            "bill_vendor": {
                "account_number": "45454545",
                "city": "San Francisco",
                "country": "United States",
                "created_at": "2021-06-17 12:08:25",
                "currency_code": "USD",
                "is_1099": false,
                "language": "en",
                "note": null,
                "outstanding_balance": [],
                "overdue_balance": [],
                "phone": "4158859378",
                "postal_code": null,
                "primary_contact_email": "someone2@ikea.com",
                "primary_contact_first_name": "Jimmy",
                "primary_contact_last_name": "McNamara",
                "province": "California",
                "street": "332 Carlton Ave.",
                "street2": null,
                "tax_defaults": [],
                "updated_at": "2021-06-17 12:18:16",
                "vendor_name": "IKEA",
                "vendorid": 1563,
                "vis_state": 0,
                "website": "ikea.com"
            }
        }
    }
}

Delete Vendor

curl -L -X PUT 'https://api.freshbooks.com/accounting/account/<accountId>/bill_vendors/bill_vendors/<vendorId>' \
-H 'Authorization: Bearer <insert-bearer-token>' \
-H 'Content-Type: application/json' \
--data-raw '{
    "bill_vendor": {
        "vis_state": 1
    }
}'#Response:
{
    "response": {
        "result": {
            "bill_vendor": {
                "account_number": "45454545",
                "city": "San Francisco",
                "country": "United States",
                "created_at": "2021-06-17 12:08:25",
                "currency_code": "USD",
                "is_1099": false,
                "language": "en",
                "note": null,
                "outstanding_balance": [],
                "overdue_balance": [],
                "phone": "4158859378",
                "postal_code": null,
                "primary_contact_email": "someone2@ikea.com",
                "primary_contact_first_name": "Jimmy",
                "primary_contact_last_name": "McNamara",
                "province": "California",
                "street": "332 Carlton Ave.",
                "street2": null,
                "tax_defaults": [],
                "updated_at": "2021-06-17 12:31:24",
                "vendor_name": "IKEA",
                "vendorid": 1563,
                "vis_state": 1,
                "website": "ikea.com"
            }
        }
    }
}

Get Vendors

import http.client

conn = http.client.HTTPSConnection("api.freshbooks.com")
payload = ''
headers = {
  'Authorization': 'Bearer <insert-bearer-token>'
}
conn.request("GET", "/accounting/account/<accountId>/bill_vendors/bill_vendors", payload, headers)
res = conn.getresponse()
data = res.read()
print(data.decode("utf-8"))
 

 
#Response:
{
    "response": {
        "result": {
            "bill_vendors": [
                {
                    "account_number": "45454545",
                    "city": "San Francisco",
                    "country": "United States",
                    "created_at": "2021-06-17 12:08:25",
                    "currency_code": "USD",
                    "is_1099": false,
                    "language": "en",
                    "note": null,
                    "outstanding_balance": [],
                    "overdue_balance": [],
                    "phone": "4158859378",
                    "postal_code": null,
                    "primary_contact_email": "someone@ikea.com",
                    "primary_contact_first_name": "Jimmy",
                    "primary_contact_last_name": "McNamara",
                    "province": "California",
                    "street": "332 Carlton Ave.",
                    "street2": null,
                    "tax_defaults": [],
                    "updated_at": "2021-06-17 12:08:25",
                    "vendor_name": "IKEA",
                    "vendorid": 1563,
                    "vis_state": 0,
                    "website": "ikea.com"
                },
                {
                    "account_number": "",
                    "city": null,
                    "country": null,
                    "created_at": "2021-06-16 09:49:46",
                    "currency_code": "USD",
                    "is_1099": false,
                    "language": "en",
                    "note": null,
                    "outstanding_balance": [
                        {
                            "amount": {
                                "amount": "53885.00",
                                "code": "USD"
                            }
                        }
                    ],
                    "overdue_balance": [],
                    "phone": null,
                    "postal_code": null,
                    "primary_contact_email": "someone@freshbooks.com",
                    "primary_contact_first_name": "Rahul",
                    "primary_contact_last_name": "Varma",
                    "province": null,
                    "street": null,
                    "street2": null,
                    "tax_defaults": [
                        {
                            "amount": "6",
                            "created_at": "2021-06-16 09:49:46",
                            "enabled": true,
                            "name": "GST1",
                            "system_taxid": 5307,
                            "tax_authorityid": null,
                            "taxid": 95,
                            "updated_at": "2021-06-16 09:49:46",
                            "vendorid": 1562
                        },
                        {
                            "amount": "7",
                            "created_at": "2021-06-16 09:49:46",
                            "enabled": true,
                            "name": "PST",
                            "system_taxid": 6047,
                            "tax_authorityid": null,
                            "taxid": 96,
                            "updated_at": "2021-06-16 09:49:46",
                            "vendorid": 1562
                        }
                    ],
                    "updated_at": "2021-06-16 09:49:46",
                    "vendor_name": "Bread Supplier",
                    "vendorid": 1562,
                    "vis_state": 0,
                    "website": ""
                },
                {
                    "account_number": "",
                    "city": "",
                    "country": null,
                    "created_at": "2021-01-18 13:28:30",
                    "currency_code": "EUR",
                    "is_1099": false,
                    "language": "en",
                    "note": null,
                    "outstanding_balance": [
                        {
                            "amount": {
                                "amount": "50113.00",
                                "code": "EUR"
                            }
                        }
                    ],
                    "overdue_balance": [
                        {
                            "amount": {
                                "amount": "50113.00",
                                "code": "EUR"
                            }
                        }
                    ],
                    "phone": "+",
                    "postal_code": "",
                    "primary_contact_email": "apiteam@gmail.com",
                    "primary_contact_first_name": "teak",
                    "primary_contact_last_name": "Wood",
                    "province": "",
                    "street": "",
                    "street2": null,
                    "tax_defaults": [],
                    "updated_at": "2021-01-18 13:35:39",
                    "vendor_name": "Teak Provider",
                    "vendorid": 817,
                    "vis_state": 0,
                    "website": null
                }
            ],
            "page": 1,
            "pages": 1,
            "per_page": 15,
            "total": 3
        }
    }
}

Add Vendor

import http.client
import json

conn = http.client.HTTPSConnection("api.freshbooks.com")
payload = json.dumps({
  "bill_vendor": {
    "vendor_name": "IKEA2",
    "primary_contact_first_name": "Jimmy",
    "primary_contact_last_name": "McNamara",
    "primary_contact_email": "jmcnamarae@ikea.com",
    "primary_contact": None,
    "street": "332 Carlton Ave.",
    "street2": None,
    "city": "San Francisco",
    "province": "California",
    "postal_code": None,
    "country": "United States",
    "account_number": "45454545",
    "phone": "4158859378",
    "website": "ikea.com",
    "currency_code": "USD",
    "language": "en",
    "is_1099": False,
    "tax_defaults": []
  }
})
headers = {
  'Authorization': 'Bearer <insert-bearer-token>',
  'Content-Type': 'application/json'
}
conn.request("POST", "/accounting/account/<accountId>/bill_vendors/bill_vendors", payload, headers)
res = conn.getresponse()
data = res.read()
print(data.decode("utf-8"))
 

#Response:
{
    "response": {
        "result": {
            "bill_vendor": {
                "account_number": "45454545",
                "city": "San Francisco",
                "country": "United States",
                "created_at": "2021-06-17 12:08:25",
                "currency_code": "USD",
                "is_1099": false,
                "language": "en",
                "note": null,
                "outstanding_balance": [],
                "overdue_balance": [],
                "phone": "4158859378",
                "postal_code": null,
                "primary_contact_email": "someone@ikea.com",
                "primary_contact_first_name": "Jimmy",
                "primary_contact_last_name": "McNamara",
                "province": "California",
                "street": "332 Carlton Ave.",
                "street2": null,
                "tax_defaults": [],
                "updated_at": "2021-06-17 12:08:25",
                "vendor_name": "IKEA",
                "vendorid": 1563,
                "vis_state": 0,
                "website": "ikea.com"
            }
        }
    }
}

Edit Vendor Details

import http.client
import json

conn = http.client.HTTPSConnection("api.freshbooks.com")
payload = json.dumps({
    "bill_vendor": {
        "vendor_name": "IKEA",
        "primary_contact_first_name": "Jimmy",
        "primary_contact_last_name": "McNamara",
        "primary_contact_email": "someone2@ikea.com",
        "primary_contact": None,
        "street": "332 Carlton Ave.",
        "street2": None,
        "city": "San Francisco",
        "province": "California",
        "postal_code": None,
        "country": "United States",
        "account_number": "45454545",
        "phone": "4158859378",
        "website": "ikea.com",
        "currency_code": "USD",
        "language": "en",
        "is_1099": False,
        "tax_defaults": []
    }
})
headers = {
  'Authorization': 'Bearer <insert-bearer-token>',
  'Content-Type': 'application/json'
}
conn.request("PUT", "/accounting/account/<accountId>/bill_vendors/bill_vendors/<vendorId>", payload, headers)
res = conn.getresponse()
data = res.read()
print(data.decode("utf-8"))

#Response:
{
    "response": {
        "result": {
            "bill_vendor": {
                "account_number": "45454545",
                "city": "San Francisco",
                "country": "United States",
                "created_at": "2021-06-17 12:08:25",
                "currency_code": "USD",
                "is_1099": false,
                "language": "en",
                "note": null,
                "outstanding_balance": [],
                "overdue_balance": [],
                "phone": "4158859378",
                "postal_code": null,
                "primary_contact_email": "someone2@ikea.com",
                "primary_contact_first_name": "Jimmy",
                "primary_contact_last_name": "McNamara",
                "province": "California",
                "street": "332 Carlton Ave.",
                "street2": null,
                "tax_defaults": [],
                "updated_at": "2021-06-17 12:18:16",
                "vendor_name": "IKEA",
                "vendorid": 1563,
                "vis_state": 0,
                "website": "ikea.com"
            }
        }
    }
}