Invoices

• invoice.create
• invoice.update
• invoice.get
• invoice.delete
• invoice.list
• invoice.sendByEmail
• invoice.sendBySnailMail

invoice.create

Create a new invoice complete with line items. If successful, returns the invoice_id of the newly created invoice.

• If you don't specify an invoice <number>, it will increment from the last one.
• You may optionally specify a different address on the invoice; otherwise the address will be pulled from your client's details.
• You may optionally specify a <return_uri> element. If provided, users will be presented with a link to the URI when they pay the invoice. More details of the return_uri element are available on the blog.

Request

  
    
    13	
    
    FB00004	
    
    draft	
    
    2007-06-23	
    
    2314	
    
    10	
    
    Due upon receipt.	
    
    Payment due in 30 days.
    
    http://example.com/account

    John			
    Smith			
    ABC Corp	
    					
    					
    						
    						
    					
    						

    	
      
        Yard Work						
        Mowed the lawn.	
        10					
        4						
        GST					
        PST					
        5				
        8				
      
    
  

Response

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

  344

invoice.update

Update an existing invoice with the given invoice_id. Any invoice fields left out of the request will remain unchanged.

• If you do not specify a <lines> element, the existing lines will remain unchanged.

Request

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

  
    344            
    
  

Response

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

invoice.get

Return the complete invoice details associated with the given invoice_id.

• You can use the <url> value to provide your customers with a direct link to their invoice.
• You can use the <links> element to provide your customers with direct links to the invoice for editing, viewing by the client and viewing by an administrator.

Request

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

  344

Response

<?xml version="1.0"?>

  
    344
    3

    FB00004
    
    45.6 
    
    0 
    paid
    2007-06-23
    
    0
    Due upon receipt.
    Payment due in 30 days.

    https://2ndsite.freshbooks.com/view/St2gThi6rA2t7RQ 
    https://2ndsite.freshbooks.com/invoices/344 
    
      https://2ndsite.freshbooks.com/view/St2gThi6rA2t7RQ 
      https://2ndsite.freshbooks.com/invoices/344 
      https://2ndsite.freshbooks.com/invoices/344/edit 
    

    http://www.example.com/callback 
    2009-08-12 09:00:00  

    15 

    ABC Corp
    John
    Doe
    123 Fake St.
    Unit 555
    New York
    New York
    United States
    553132

    
      
        40 
        
        Yard work
        Mowed the lawn
        10
        4
        GST
        PST
        5
        8
      
    
  

invoice.delete

Delete an existing invoice.

Request

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

  344

Response

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

invoice.list

Returns a list of invoice summaries. Results are ordered by descending invoice_id.

• The value used for 'status' can be 'disputed', 'draft', 'sent', 'viewed', 'paid', 'auto-paid', 'retry', 'failed' or the special status 'unpaid' which will retrieve all invoices with a status of 'disputed', 'sent', 'viewed', 'retry' or 'failed'.

Request

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

  
  3       
       
  10     
  
  draft              
  
  2007-01-01   
  
  2007-04-01
  
  2007-01-01 00:00:00
  
  2007-01-02 00:00:00
  
  1                    
    
  10             

Response

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

  
    
      344
      3
      FB00004
      45.6 
      0 
      paid
      2007-06-23
      
      0
      Due upon receipt.
      Payment due in 30 days.
      https://2ndsite.freshbooks.com/view/St2gThi6rA2t7RQ 
      https://2ndsite.freshbooks.com/invoices/344 
      
        https://2ndsite.freshbooks.com/view/St2gThi6rA2t7RQ 
        https://2ndsite.freshbooks.com/invoices/344 
        https://2ndsite.freshbooks.com/invoices/344/edit
      
      http://www.example.com/callback
      2009-08-12 09:00:00
      15 
      ABC Corp
      John
      Doe
      123 Fake St.
      Unit 555
      New York
      New York
      United States
      553132
      
        
          40 
          Yard work
          Mowed the lawn
          10
          4
          GST
          PST
          5
          8
        
      
    
    
      ...
    
    ...
  

invoice.sendByEmail

Send an existing invoice to your client via e-mail. The invoice status will be changed to sent.

Request

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

  344

Response

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

Custom Emails

If you would like to send a custom email, include a message and subject element. Note that both of these elements are required (one or the other will not work).

Request

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

  344
  This is a custom subject!
  You have a new invoice. Get it here: ::invoice link::

Response

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

invoice.sendBySnailMail

Send an existing invoice to your client via snail mail. If you do not have enough stamps, the request will fail. If successful, the invoice status will be changed to sent.

Be careful with this method. This operation cannot be undone.

Request

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

  344

Response

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