Recurring

• recurring.create
• recurring.update
• recurring.get
• recurring.delete
• recurring.list

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: 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"?>

  
    40	 
    
    2007-09-23	
    2314	
    10	
    1	
    
    monthly	
    
    

    1 
    0  

    CAD 

    Due upon receipt.       
    Payment due in 30 days. 

    John           
    Smith            
    ABC Corp   
                     
                     
                           
                         
                     
                           
                   
                                         
      
      Authorize.net  
      
        
        4111 1111 1111 1111  
        John Smith
        
          3
          2012
        
      
    
    
      
        Yard Work
        Mowed the lawn.
        10
        4
        GST
        PST
        8
        6
      
    
  

Response

<?xml version="1.0" encoding="utf-8"?>

  21

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"?>

  
    21

    ...
  

Response

<?xml version="1.0" encoding="utf-8"?>  
  
  

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"?>

  20

Response

<?xml version="1.0" encoding="utf-8"?>

  
    344
    
    2y 
    0
    0
    2
    ABC Corp
    John
    Doe
    123 Fake St.
    Unit 555
    New York
    New York
    United States
    553132
    
    
    109.89
    CAD
    2007-06-23
    
    
    0
    
    0
    1
    
      Authorize.Net
      
        ************1111
        John Smith
        
          03
          2012
        
      
    
    
      
        Product
        Sample product item
        9.99
        10
        99.9
        tax1
        
        10
        0
      
    
  

recurring.delete

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

Request

<?xml version="1.0" encoding="utf-8"?>

  20

Response

<?xml version="1.0" encoding="utf-8"?>  
  
  

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.

Request

<?xml version="1.0" encoding="utf-8"?>

  3 	
  1 

  1	
  10 	

Response

<?xml version="1.0" encoding="utf-8"?>

  
    
      00000000001
	  m
	  0
	  1
	  2
	  XYZ Widgets Ltd
	  Joe
	  Smith
	  2770 Dufferin St.
	  Suite 201
	  Toronto
	  Ontario
	  Canada
	  M6B 3R7
	  
	  
	  200
      CAD
	  2009-06-08
	  
	  Payment due in 30 days.
	  0
	  
	  0
	  1
      
        Authorize.Net
        
          ************1111
          John Smith
          
            03
            2012
          
        
      
	  
	    
	      Service
	      Monthly Subscription
	      200
	      1
	      200
	      
	      
	      0
	      0
	    
	  
	
    ...