Return to site

FreshBooks-BizMerlin Integration

May 10, 2019 · Integrating BizMerlinHR with 3rd Party Applications,

I. Linking FreshBooks and BizMerlin

  1. Setup FreshBooks in Third Party Integrations
    1. Getting information from FreshBooks:
      1. Separately, in a different tab, sign into your account on Freshbooks.com and navigate to the Setup menu
      2. Get the appid and apptoken for your account (using get/generate buttons)
    2. Linking Freshbooks in your BizMerlin account:
      1. Go to the top right “Setup” menu and scroll down and click on “Third Party Integrations”: Setup-> Third Party Integrations
      2. On the Third Party Integrations page, click on the button “New Integration” and choose “FreshBooks”
      3. In the field “Host” specify your FreshBooks URL
      4. Fill in the fields “appid” and “apptoken” with the corresponding information taken from your FreshBooks account
      5. (User + password are not needed in case of FreshBooks integration)
  2. Configure required custom fields in BizMerlin:
    1. Create a “Contact”  for Accounts:
      1. Go to the top “Allocations” menu and click on “Accounts”
      2. On accounts home page, click on “New Contact” link to create a contact. This contact’s email will be required to create customer in Freshbooks.
        Note: If the contact does not have email linked to it, then account will not get created in Freshbooks.
    2. Create a “freshbooks.client.id” custom field for Accounts:
      1. Go to the top right “Setup” menu and scroll down and click on “Organization Setup”
      2. Now click on “Custom Field” link under Custom Fields Configuration
      3. Click on “Add New” and create a new custom field called: “freshbooks.client.id”
      4. In the “Object Type” menu, select “Account”
    3. (Optional) Create a “freshbooks.client.outstandingBalance” custom field for Accounts (follow instructions for previous steps)
    4. (Optional) Create a “freshbooks.client.overdueBalance” custom field for Accounts (follow instructions for previous steps)
    5. Create a “freshbooks.invoice.id” custom field for Invoice:
      1. Go to the top right “Setup” menu and scroll down and click on “Organization Setup”
      2. Now click on “Custom Field” link under Custom Fields Configuration
      3. Click on “Add New” and create a new custom field called: “freshbooks.invoice.id”
      4. In the “Object Type” menu, select “Invoice”

II. Automatic Client Creation from BizMerlin Account

Note: FreshBooks “clients” are treated as “Accounts” in BizMerlin

This BizMerlin- FreshBooks integration allows to sync the creation of “Clients/Accounts”: when you create an “Account” entity in BizMerlinHR, the system syncs and automatically creates a “Client” entity in FreshBooks.  FreshBooks API is available at https://www.freshbooks.com/api/clients

  1. Option 1: Creating New “Accounts” in BizMerlin and syncing with “Clients” in FreshBooks

    1. In BizMerlin go to the top menu “Account” and click “New Account”
    2. Fill in all the required fields except for “freshbooks.client.id”. When your new account is saved in BizMerlin, the system will automatically create a new client in FreshBooks
    3. The Client ID generated by FreshBooks will automatically be pulled to BizMerlin’s Account field
  2. Option 2: Creating BizMerlin new accounts with existing clients in FreshBooks

    1. If the client already exists in FreshBooks (and therefore already has a client ID) go to the top menu “Account” and click “New Account”
    2. To link the existing client in FreshBooks with the Account in BizMerlin, fill in the “freshbooks.client.id” with the corresponding FreshBooks client ID  and save the Account. 
    3. If for whatever reason, you don’t want to create a client in FreshBooks for a particular Account in BizMerlin, then simply fill in the “freshbooks.client.id” field with “0”.  BM will not create a new client in FreshBooks. BM will leave the value of 0 in that field.

Failure Conditions

  • If you do not supply a contact email, client creation will fail in FreshBooks.
  • If the freshbooks.clientemail is not unique, client creation will fail in FreshBooks.

Success Outcome

  • If client successfully gets created in FreshBooks, then BizMerlin will store the value received from FreshBooks in freshbooks.client.id

III. Automatic Invoice Creation from BizMerlin Project Invoice

Main purpose of this flow is to create an invoice in FreshBooks from the invoice function in BizMerlin.

  1. Create a project invoice in BizMerlin just like you would manually, or through recurring schedule.
  2. When an invoice is created in BizMerlin, BizMerlin will automatically create that invoice in FreshBooks.
  3. BizMerlin stores the FreshBooks invoice id in the invoice as freshbooks.invoice.id field.

IV. Automatic Account Balance and Past Due Update

BizMerlin retrieves the account balances every 24 hours and updates the optional custom fields with that information.

V. Update expense/invoice

This is not currently supported.  If you want to modify an invoice, you need to modify it directly in FreshBooks

VI. Other Items

 In case we want to adjust the amount of invoice we can do this through invoice.update call.

  • Invoice list for customer on site administration page through invoice.list call
  • We will use the client_Id generated by freshbooks at the time of customer creation to fetch the list of invoices for that customer with the status of those invoices. We will give the link of payment along with the above calculated amount from where user will be redirected to freshbooks gateway where he can use his credit card for payments.
  • Redirecting user back to application after payment. [This option is provided in the invoice.create API call]