Cashboard API

« Back to Overview

Invoices

Operations on this resource are restricted to admins only.

List
GET /invoices

Parameters

  • client_id / client_type
    client_id is an id of either a Client Company or Client Contact.
    client_type must be set to either 'Company' (Client Company) or 'Person' (Client Contact) if client_id is set.
  • has_been_paid
    true returns all PAID invoices, false returns all UNPAID
  • has_been_sent
    true returns all SENT invoices, false returns all UNPAID
  • start_date_invoice
    Returns all invoices with an invoice_date AFTER the date given
    Expects a CGI encoded date in the form of YYYY-MM-DD
  • end_date_invoice
    Returns all invoices with a invoice_date BEFORE the date given
    Expects a CGI encoded date in the form of YYYY-MM-DD
  • start_date_due
    Returns all invoices with a due_date AFTER the date given
    Expects a CGI encoded date in the form of YYYY-MM-DD
  • end_date_due
    Returns all invoices with a due_date BEFORE the date given
    Expects a CGI encoded date in the form of YYYY-MM-DD
  • updated_since
    Returns all invoices last modified after the given date/time.
    Expects a CGI encoded datetime in the form of YYYY-MM-DD HH:MM:SS

New
GET /invoices/new

Returns a data template that you can fill in to use the CREATE action.

Create
POST /invoices

Creates a new invoice. Use the template provided by the NEW action.

Actions

Show
GET [invoice link 'self']

Returns a single invoice.

Can return invoice in a variety of formats,
including HTML and PDF as you'd see in the Cashboard web UI.

Supported Content Types

  • application/xml
  • application/pdf
  • text/html

Update
PUT [invoice link 'self']

Updates a invoice.

Import Uninvoiced Items
PUT [invoice link 'import_uninvoiced_items']

Imports expenses, time entries, and flat-fee tasks from projects.
Returns all line items for invoice.

Optional parameters

All uninvoiced items for this invoice's client will be imported if all of these parameters are omitted.

  <?xml version="1.0" encoding="UTF-8"?>
  <projects>
    <id>{project id}</id>
    <id>{project id}</id>
    etc...
  </projects>
  <start_date>{start date of import}</start_date>
  <end_date>{end date of import}</end_date>
  

Delete
DELETE [invoice link 'self']

Deletes an invoice and all comments associated with it.

List Line Items
GET [invoice link 'line_items']

Returns all invoice line items associated with this invoice.

Data Reference

<?xml version="1.0" encoding="UTF-8"?>
<invoice>
  <address></address>
  <assigned_id></assigned_id>
  <balance rel="financial" read_only="true">0.0</balance>
  <client_id></client_id>
  <client_type></client_type>
  <comments_count read_only="true">0</comments_count>
  <created_on></created_on>
  <discount rel="financial" read_only="true">0.0</discount>
  <discount_percentage rel="financial"></discount_percentage>
  <document_template_id></document_template_id>
  <due_date>2017-01-19</due_date>
  <early_period_in_days></early_period_in_days>
  <has_been_paid read_only="true">false</has_been_paid>
  <has_been_sent>false</has_been_sent>
  <include_expenses>false</include_expenses>
  <include_pdf>false</include_pdf>
  <include_time_entries>false</include_time_entries>
  <invoice_date>2017-01-19</invoice_date>
  <item_actual rel="financial" read_only="true">0.0</item_actual>
  <item_cost rel="financial" read_only="true">0.0</item_cost>
  <item_profit rel="financial" read_only="true">0.0</item_profit>
  <item_taxable rel="financial" read_only="true">0.0</item_taxable>
  <late_fee rel="financial" read_only="true">0.0</late_fee>
  <late_percentage></late_percentage>
  <late_period_in_days></late_period_in_days>
  <notes></notes>
  <payment_total rel="financial" read_only="true">0.0</payment_total>
  <po_number></po_number>
  <post_reminder_in_days></post_reminder_in_days>
  <pre_reminder_in_days></pre_reminder_in_days>
  <sales_tax rel="financial"></sales_tax>
  <sales_tax_2 rel="financial"></sales_tax_2>
  <sales_tax_2_cumulative rel="financial">false</sales_tax_2_cumulative>
  <total rel="financial" read_only="true">0.0</total>
  <total_quantity rel="financial" read_only="true">0.0</total_quantity>
  <updated_at read_only="true"></updated_at>
</invoice>

Property Reference

assigned_id The display "number" of an invoice.
client_id ID of a Client Contact or Client Company.
client_type (Person, Company)
created_on Creation date of this invoice.
discount Dollar amount of discount applied.
discount_percentage Can be used alone, or in combination with early_period_in_days to provide an early payment discount. When used as an early discount, the percentage is multiplied by early_period_in_days - so you can define a discount of "1% every 5 days paid early", etc.
Floating point value. Specified as a percentage.
document_template_id ID of the document_template used to display this invoice.
due_date Date this invoice is due for payment.
early_period_in_days Defines the number of days before due_date that discount_percentage is applied, if you wish to use an "early payment" discount.
has_been_paid True if invoice is paid, false if not.
has_been_sent Will be set to true if it has been emailed via the system.
May also be set manually if customer post-mails their invoices.
include_expenses Controls the visibility of associated expenses when rendering to HTML or PDF.
include_pdf Determines if a PDF file should be included when sending reminder notifications
include_time_entries Controls the visibility of associated time entries when rendering to HTML or PDF.
invoice_date The date this invoice was issued to the client.
item_actual Dollar amount of all line_items, including markup_percentage.
item_cost Dollar amount of all line_items, before markup_percentage.
item_profit Dollar amount made via markup_percentage on all line items.
item_taxable Dollar amount of items that are marked taxable.
late_fee Dollar amount assessed for late payments.
late_percentage Similar to discount_percentage, but applies a late payment fee instead.
Used in combination with late_period_in_days.
late_percentage will be applied every late_period_in_days after due_date.
Floating point value. Specified as a percentage.
late_period_in_days Defines the number of days after due_date that late_percentage is applied, if you wish to use late payment fees.
notes Custom notes field that is shown on the invoice to your clients.
payment_total Dollar amount of payments that have been made against this invoice.
post_reminder_in_days Every X days after due_date the invoice is unpaid an email notification will be sent to your client.
pre_reminder_in_days Every X days before due_date the invoice is unpaid an email notification will be sent to your client.
sales_tax Floating point value. Specified as a percentage.
sales_tax_2 Floating point value. Specified as a percentage.
sales_tax_cumulative Boolean. Determines if sales_tax_2 is a compound tax, including sales_tax
total Dollar amount of the entire invoice, including discounts and fees.
total_quantity Sum of quantity field on all line items on invoice.