Recurring

Staff have access to the API calls listed below if the Invoices tab is enabled for staff. Staff users can only access recurring profiles that belong to clients they are assigned to.

The Recurring Profile API allows you to create recurring profiles in the FreshBooks application. Recurring profiles can optionally have credit card auto-bill information. Adding credit card auto-billing capabilities to a recurring profile requires the inclusion of an autobill element in the recurring.create or recurring.update request bodies. The autobill element will be included in responses to recurring.get and recurring.list requests, with information about the auto-bill profile if it is enabled.

Note: This method uses pagination.

Note: auto-bill profiles must be in the base currency and are restricted to the credit card types checked on the “Online Payment” settings page. Additionally auto-bill profiles do not accept expired credit cards.

recurring.create

Create a new recurring profile. The method arguments are nearly identical to invoice.create, but include five additional fields:

  • occurrences
    Number of invoices to generate, with zero (0) being infinite
  • frequency
    Rate at which to generate invoices – can be one of ‘weekly’, ’2 weeks’, ’4 weeks’, ‘monthly’, ’2 months’, ’3 months’, ’6 months’, ‘yearly’, ’2 years’
  • stopped
    This profile is no longer generating invoices (1 – stopped, 0 – active)
  • send_email
    Notify client by email each time a new invoice is generated (1 or 0)
  • send_snail_mail
    Send a copy of your invoice by snail mail, each time it’s generated (1 or 0)

  • autobill
    Enable credit card auto-billing for this recurring profile.

Other Notes

  • New profiles that start today will be sent immediately.
  • The method supports two placeholders in return_uri:
    Placeholder Replaced With
    ::invoice id:: The generated invoice ID (used for invoice.get)
    ::invoice number:: The generated invoice number (used in the user interface)
    These placeholders are case-sensitive.
  • More information about the return_uri element is available on the blog.

Request

<?xml version="1.0" encoding="utf-8"?>
<request method="recurring.create">
  <recurring>
    <client_id>40</client_id>	 <!-- Client to generate invoices for -->

	<!-- Contacts are optional -->
	<contacts>
		<contact>
			<contact_id>23</contact_id>
		</contact>
	</contacts>
	
    <date>2007-09-23</date>
            <po_number>2314</po_number>	<!-- Purchase order number (Optional) -->
    <discount>10</discount>	<!-- Percent discount (Optional) -->
    <occurrences>1</occurrences>
    <!-- Number of invoices to generate; 0 infinite (default 0) -->
    <frequency>monthly</frequency>
    <!-- One of 'weekly', '2 weeks', '4 weeks', 'monthly', '2 months', -->
    <!-- '3 months', '6 months', 'yearly', '2 years' -->

    <send_email>1</send_email> <!-- Send email notification(Default 1) -->
    <send_snail_mail>0</send_snail_mail>  <!-- Send copy by snail mail (Default 0) -->

    <currency_code>CAD</currency_code> <!-- Defaults to systems base currency (Optional) -->
    <language>en</language> <!-- Defaults to the client's language  -->

    <notes>Due upon receipt.</notes>       <!-- (Optional) -->
    <terms>Payment due in 30 days.</terms> <!-- (Optional) -->

    <first_name>John</first_name>           <!-- (Optional) -->
    <last_name>Smith</last_name>            <!-- (Optional) -->
    <organization>ABC Corp</organization>   <!-- (Optional) -->
    <p_street1></p_street1>                 <!-- (Optional) -->
    <p_street2></p_street2>                 <!-- (Optional) -->
    <p_city></p_city>                       <!-- (Optional) -->
    <p_state></p_state>                     <!-- (Optional) -->
    <p_country></p_country>                 <!-- (Optional) -->
    <p_code></p_code>                       <!-- (Optional) -->
    <vat_name></vat_name>                   <!-- e.g. 'VAT Number' (Optional) -->
    <vat_number></vat_number>               <!-- If set, shown with vat_name under client address (Optional) -->
    <return_uri></return_uri>               <!-- (Optional) -->
    <autobill>                              <!-- (Optional) -->
      <!-- Case insensitive gateway name from gateway.list (Must be auto-bill capable) -->
      <gateway_name>Authorize.net</gateway_name>
      <card>
        <!-- Can include spaces, hyphens and other punctuation marks -->
        <number>4111 1111 1111 1111</number>
        <name>John Smith</name>
        <expiration>
          <month>3</month>
          <year>2012</year>
        </expiration>
      </card>
    </autobill>
    <lines>
      <line>
        <name>Yard Work</name>
        <description>Mowed the lawn.</description>
        <unit_cost>10</unit_cost>
        <quantity>4</quantity>
        <tax1_name>GST</tax1_name>
        <tax2_name>PST</tax2_name>
        <tax1_percent>8</tax1_percent>
        <tax2_percent>6</tax2_percent>
        <type>Time</type>                            <!-- (Optional) -->
   <!-- One of 'Item' or 'Time'. If omitted, the line's type defaults to 'Item' -->
      </line>
    </lines>
  </recurring>
</request>

Response

<?xml version="1.0" encoding="utf-8"?>
<response xmlns="http://www.freshbooks.com/api/" status="ok">
  <recurring_id>21</recurring_id>
</response>

recurring.update

Update an existing recurring profile. For all elements but autobill, if they are supplied, they will be changed. The autobill element is optional. If it is not passed as part of the request then the recurring.update method will not modify any auto-bill information. The recurring.update method can convert a non auto-bill enabled recurring profile into an auto-bill enabled recurring profile with the inclusion of the autobill element. When updating auto-bill information, all child elements are required. An empty autobill element will turn off auto-billing on a recurring profile and delete all related information.

Request

<?xml version="1.0" encoding="utf-8"?>
<request method="recurring.update">
  <recurring>
    <recurring_id>21</recurring_id>
    <!-- Remaining arguments same as recurring.create -->
    ...
  </recurring>
</request>

Response

<?xml version="1.0" encoding="utf-8"?>
<response xmlns="http://www.freshbooks.com/api/" status="ok">
</response>

recurring.get

Return the details of an existing recurring profile, including auto-bill information if this recurring profile has auto-billing enabled.

Request

<?xml version="1.0" encoding="utf-8"?>
<request method="recurring.get">
  <recurring_id>20</recurring_id>
</request>

Response

<?xml version="1.0" encoding="utf-8"?>
<response xmlns="http://www.freshbooks.com/api/" status="ok">
  <recurring>
    <recurring_id>344</recurring_id>
    <!-- One of '2y', 'y', '6m', '3m', '2m', 'm', '4w', '2w', 'w' -->
    <frequency>2y</frequency>
    <occurrences>0</occurrences>
    <stopped>0</stopped>
    <client_id>2</client_id>
	<contacts>
		<contact>
			<contact_id>10</contact_id>
		</contact>
	</contacts>
    <staff_id>1</staff_id>
    <organization>ABC Corp</organization>
    <first_name>John</first_name>
    <last_name>Doe</last_name>
    <p_street1>123 Fake St.</p_street1>
    <p_street2>Unit 555</p_street2>
    <p_city>New York</p_city>
    <p_state>New York</p_state>
    <p_country>United States</p_country>
    <p_code>553132</p_code>
    <vat_name></vat_name>
    <vat_number></vat_number>
    <po_number></po_number>
    <status></status>
    <amount>109.89</amount>
    <currency_code>CAD</currency_code>
    <language>en</language>
    <date>2007-06-23</date>
    <notes></notes>
    <terms></terms>
    <discount>0</discount>
    <return_uri></return_uri>
    <send_snail_mail>0</send_snail_mail>
    <send_email>1</send_email>
    <folder>active</folder>
    <autobill>
      <gateway_name>Authorize.Net</gateway_name>
      <card>
        <number>************1111</number>
        <name>John Smith</name>
        <expiration>
          <month>03</month>
          <year>2012</year>
        </expiration>
      </card>
    </autobill>
    <lines>
      <line>
        <line_id>1</line_id>  <!-- (Read Only) line id -->
        <name>Product</name>
        <description>Sample product item</description>
        <unit_cost>9.99</unit_cost>
        <quantity>10</quantity>
        <amount>99.9</amount>
        <tax1_name>tax1</tax1_name>
        <tax2_name></tax2_name>
        <tax1_percent>10</tax1_percent>
        <tax2_percent>0</tax2_percent>
        <type>Item</type>
      </line>
    </lines>
  </recurring>
</response>

recurring.delete

Delete a recurring profile. Once deleted, it will no longer generate invoices.

Request

<?xml version="1.0" encoding="utf-8"?>
<request method="recurring.delete">
  <recurring_id>20</recurring_id>
</request>

Response

<?xml version="1.0" encoding="utf-8"?>
<response xmlns="http://www.freshbooks.com/api/" status="ok">
</response>

recurring.list

Returns a list of recurring profile summaries. Results are ordered by descending recurring_id.

Note: A list request that returns no results (i.e. page 999), will return an empty result set, not an error.

Note: The response will include an empty autobill tag if the recurring profile does not have auto-billing enabled, otherwise the response will include an autobill element with the gateway name and card element.

Note: This method uses pagination.

Request

<?xml version="1.0" encoding="utf-8"?>
<request method="recurring.list">
   <!-- Filter by client (Optional) -->
   <client_id>3</client_id>
   <!-- Return auto-bills dated after this arg (Optional) -->
   <date_from>2007-01-01</date_from>
   <!-- Return auto-bills dated before this arg (Optional) -->
   <date_to>2007-04-01</date_to>
   <!-- Return invoices modified after this arg (Optional) -->
   <updated_from>2007-01-01 00:00:00</updated_from>
   <!-- Return invoices modified before this arg (Optional) -->
   <updated_to>2007-01-02 00:00:00</updated_to>
   <!-- Filter auto-bill profiles (Optional) -->
   <autobill>1</autobill>
   <!-- Page number to return, default is 1 (Optional) -->
   <page>1</page>
   <!-- Number of results per page, default is 25 (Optional) -->
   <per_page>10</per_page>
   <!--One of 'active', 'archived', 'deleted' (Optional) -->
   <folder>active</folder>
</request>

Response

<?xml version="1.0" encoding="utf-8"?>
<response xmlns="http://www.freshbooks.com/api/" status="ok">
  <recurrings page="1" per_page="10" pages="5" total="48">
    <recurring>
      <recurring_id>00000000001</recurring_id>
	  <!-- One of '2y', 'y', '6m', '3m', '2m', 'm', '4w', '2w', 'w' -->
	  <frequency>m</frequency> 
	  <occurrences>0</occurrences>
	  <stopped>1</stopped>
	  <client_id>2</client_id>
		<contacts>
			<contact>
				<contact_id>30</contact_id>
			</contact>
		</contacts>
      <staff_id>1</staff_id>
	  <organization>XYZ Widgets Ltd</organization>
	  <first_name>Joe</first_name>
	  <last_name>Smith</last_name>
	  <p_street1>2770 Dufferin St.</p_street1>
	  <p_street2>Suite 201</p_street2>
	  <p_city>Toronto</p_city>
	  <p_state>Ontario</p_state>
	  <p_country>Canada</p_country>
	  <p_code>M6B 3R7</p_code>
          <vat_name></vat_name>
          <vat_number></vat_number>
	  <po_number></po_number>
	  <status></status>
	  <amount>200</amount>
          <currency_code>CAD</currency_code>
          <language>en</language>
	  <date>2009-06-08</date>
	  <notes></notes>
	  <terms>Payment due in 30 days.</terms>
	  <discount>0</discount>
	  <return_uri></return_uri>
	  <send_snail_mail>0</send_snail_mail>
	  <send_email>1</send_email>
          <folder>active</folder>
      <autobill>
        <gateway_name>Authorize.Net</gateway_name>
        <card>
          <number>************1111</number>
          <name>John Smith</name>
          <expiration>
            <month>03</month>
            <year>2012</year>
          </expiration>
        </card>
      </autobill>
	  <lines>
	    <line>
              <line_id>1</line_id>  <!-- (Read Only) line id -->
	      <name>Service</name>
	      <description>Monthly Subscription</description>
	      <unit_cost>200</unit_cost>
	      <quantity>1</quantity>
	      <amount>200</amount>
	      <tax1_name></tax1_name>
	      <tax2_name></tax2_name>
	      <tax1_percent>0</tax1_percent>
	      <tax2_percent>0</tax2_percent>
          <type>Item</type>
	    </line>
	  </lines>
	</recurring>
    ...
  </recurrings>
</response>

recurring.lines.add

Adds (a) new line(s) to an existing recurring profile.

  • One or more lines may be added.
  • Do not specify line_id for any lines. (Ids will be assigned automatically). Use recurring.lines.update to change existing lines.

Request

<?xml version="1.0" encoding="utf-8"?>
<request method="recurring.lines.add">
  <recurring_id>111</recurring_id>
  <lines>
    <line>
      <amount>80</amount>
      <name>Bacon</name>
      <description>Bacon ration (1lb)</description>
      <unit_cost>2</unit_cost>
      <quantity>40</quantity>
      <type>Item</type>
            ...
    </line>
    <line>
      <amount>22.30</amount>
      <name>Sphygmomanometer</name>
      <description>Blood pressure cuff</description>
      <unit_cost>1</unit_cost>
      <quantity>22.30</quantity>
      <type>Item</type>
      ...
    </line>
  </lines>
</request>

Note: In most cases, the returned line_ids will correspond to the new lines in the order that they were sent, however, this behavior is not guaranteed and should not be relied on. If you absolutely require the ability to match the created line_ids with the data you sent, you should create each line in its own request, or use some unique value for each line to eliminate any ambiguity.

Response

<?xml version="1.0" encoding="utf-8"?>
<response xmlns="http://www.freshbooks.com/api/" status="ok">
  <recurring_id>111</invoice_id>
  <lines>
    <line_id>45</line_id>
    <line_id>46</line_id>
  </lines>
</response>

recurring.lines.delete

Deletes a single line from an existing recurring profile.

  • Only a single line can be deleted per request.

Request

<?xml version="1.0" encoding="utf-8"?>
<request method="recurring.lines.delete">
  <recurring_id>123</recurring_id>
  <line_id>2</line_id>
</request>

Response

<?xml version="1.0" encoding="utf-8"?>
<response xmlns="http://www.freshbooks.com/api/" status="ok"/>

recurring.lines.update

Updates (an) existing line(s) on an existing recurring profile.

  • One or more lines may be updated.
  • Only the provided fields will be updated. All others will be left unchanged.
  • line_id is mandatory for each line to be updated. Use recurring.lines.add to create new lines.

Request

<?xml version="1.0" encoding="utf-8"?>
<request method="recurring.lines.update">
  <recurring_id>99</recurring_id>
  <lines>
    <line>
      <line_id>1</line_id>
      <amount>100</amount>
      <quantity>50.00</quantity>
      <name>Bacon Ration (1lb)</name>
      <unit_cost>2</unit_cost>
      ...
    </line>
  </lines>
</request>

Response

<?xml version="1.0" encoding="utf-8"?>
<response xmlns="http://www.freshbooks.com/api/" status="ok"/>

Search