Invoices

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

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 , 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 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.](http://developers.freshbooks.com/blog/2009/03/26/introducing-return-to-merchant/)

Request


  
    
    13
    
    
        
            14
        
    
    
    FB00004
    
    draft
    
    2007-06-23
    
    2314
    
    10
    
    Due upon receipt.
    
    CAD
    
    en
    
    Payment due in 30 days.
    
    http://example.com/account
    John              
    Smith               
    ABC Corp      
                        
                        
                              
                            
                        
                              
         
     
         
      
        Yard Work                       
        Mowed the lawn.   
        10                    
        4                       
        GST                   
        PST                   
        5               
        8               
        Item                            
     
      
    
  

Response



  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 element, the existing lines will remain unchanged. If you do specify elements the original ones will be replaced by the new ones.

Request



  
    344            
    
  

Response


invoice.get

Return the complete invoice details associated with the given invoice_id.

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

Request



  344

Response



  
    344
    3
    
        
            0
        
    
    FB00004
    
    45.6
    
    0
    paid
    2007-06-23
    
    0
    Due upon receipt.
    Payment due in 30 days.
    CAD
    active
    en
    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 00:00:00  
    15 
    ABC Corp
    John
    Doe
    123 Fake St.
    Unit 555
    New York
    New York
    United States
    553132
    
    
    1
    
      
        1  
        40
        
        Yard work
        Mowed the lawn
        10
        4
        GST
        PST
        5
        8
        Item
      
    
  

invoice.delete

Delete an existing invoice.

Request



  344

Response


invoice.list

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

Note: This method uses pagination.

  • 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



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

Response



  
    
      344
      3
        
            
                0
            
        
      FB00004
      45.6
      CAD
      en
      0
      paid
      2007-06-23
      active
      
      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
      
      
      1
      
        
          1  
          40
          Yard work
          Mowed the lawn
          10
          4
          GST
          PST
          5
          8
          Item
        
      
    
    
      ...
    
    ...
  

invoice.getPDF

Returns the specified invoice in PDF format.

Request



    1679

Response

Raw binary data. Save with a .pdf file extension.

invoice.sendByEmail

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

Request



  344

Response


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



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

Response


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



  344

Response


invoice.lines.add

Adds (a) new line(s) to an existing invoice.

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

Request



  111
  
    
      40
      Yak Shaving
      Shaved the yak
      10
      4
      Item
      ...
    
    
      23
      Telephone Sanitizing
      Sanitized the telephone
      10
      2.30
      Item
      ...
    
  

Response



  111
  
    45
    46
  

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.

invoice.lines.delete

Deletes a single line from an existing invoice.

  • Only a single line can be deleted per request.

Request



  123
  2

Response


invoice.lines.update

Updates (an) existing line(s) on an existing invoice.

  • 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 invoice.lines.add to create new lines.

Request



  99
  
    
      1
      50
      Premium Yak Shaving
      12.50
          ...
      
      
        2
        30
        Advanced Telephone Sanitizing
        3.00
        ...
      
  

Response