Mavenlink

Invoices

This documentation describes how to use the API to list Invoices.

Fetching invoices

Invoices allow users in a Mavenlink Project to track invoices. You can access all of your own invoices from all workspaces you are in through the API as follows:

curl "https://api.mavenlink.com/api/v1/invoices.json"

The resulting JSON will be an array of objects. The entries will be sorted by the date field. Each object will have the following fields:

  • id - the internal invoice id
  • created_at - the date the invoice was recorded in Mavenlink, format: YY-MM-DD[T]HH:MM:SS-TIMEZONE
  • updated_at - the date the invoice was last updated, format: YY-MM-DD[T]HH:MM:SS-TIMEZONE
  • invoice_date - the date the invoice was incurred, format: YYYY-MM-DD
  • due_date - the date the invoice is due, format: YYYY-MM-DD
  • message - any notes added to the invoice
  • title - A string of the format "(Draft )Invoice #<user-invoice-number>"
  • draft - whether the invoice is a draft or not
  • status - the current status of the invoice
  • balance_in_cents - the balance of invoice in cents
  • user_invoice_number - the user-specified invoice number
  • user_invoice_title - a user-specified invoice title
  • tax_rate - the invoice tax rate
  • purchase_order - the user-specified invoice purchase order
  • project_code - the user-specified invoice project code
  • currency - the currency of this invoice
  • currency_symbol the symbol that represents the currency of the invoice
  • currency_base_unit the number of the units in the balance_in_cents attribute that are required to make up a single unit of the currency
  • payment_schedule - the payment schedule (i.e. 30) in days of this invoice
  • workspace_ids - the internal ids of the project workspaces this invoice is associated with
  • user_id - the internal id of the user who created this invoice
  • recipient_id - the internal id of the user who received this invoice; this will be the client lead at the time that the invoice was created, or null if no lead client existed at that time.

As with all API index actions, you can provide per_page and page to paginate your response. The default page size for invoices is 200

You can also retrieve a specific invoice as follows:

curl "https://api.mavenlink.com/api/v1/invoices/1.json"

The resulting JSON will be a single invoice having the keys above.

Filtering Invoices

The Mavenlink API allows you to pass in filter conditions to allow the retrieval of only certain invoices.

Supported filters are workspace_id, pending, paid, without_drafts, and within_dates.

  • workspace_id - provide one or more workspace ids, separated by commas. If present, only invoices in those workspaces will be returned.
  • pending - provide true or false, default false. When true is passed, only non-accepted, non-draft Invoices will be returned.
  • paid - provide true or false, default false. When true is passed, only paid Invoices will be returned.
  • without_drafts - provide true or false, default false. When true is passed, no draft Invoices will be returned.
  • within_dates - provide a date range of the format 2000-01-01:2000-12-31. When provided, only Invoices created within this range will be returned.

For example, you can retrieve invoices filtered by workspace as follows:

curl "https://api.mavenlink.com/api/v1/invoices.json?workspace_id=1,6"

Associated Objects

You can include invoices' associations with the include param. For example, to include time_entries, expenses, and additional_items for Invoice#5 you would do the following:

curl "https://api.mavenlink.com/api/v1/invoices/5.json?include=time_entries,additional_items,expenses"

In this example, our API will ensure that the returned JSON contains top-level keys called time_entries, expenses, and additional_items, where you can find associated data by inspecting workspaces' time_entry_ids, expense_ids, and additional_item_ids fields. See Object Associations to learn more. The following associations can be requested through the API:

  • time_entries - when included, the time_entry_ids array will reference all of the time entries included in the Invoice
  • expenses - when included, the expense_ids array will reference all of the expenses included in the Invoice
  • additional_items - when included, the additional_item_ids array will reference all of the additional items (additional invoice line items) included in the Invoice (see below for schema).
  • fixed_fee_items - when included, the fixed_fee_items array will reference all of the fixed fee items included in the Invoice (see below for schema).
  • workspaces - when included, the workspace_ids array will reference the workspaces that this Invoice covers
  • user - user_id will reference the User who created this Invoice
  • recipient - recipient_id will reference the User who received this Invoice. This will be the client lead at the time that the invoice was created, or null if no lead client existed at that time.

Additional Item Fields

If you include additional_items, you will receive any additional Invoice line items in a top-level object called additional_items. Values of this object will have the following fields:

  • id - the internal Additional Item id
  • notes - any notes on the Additional Item
  • amount_in_cents - the value of the Additional Item, in the currency's base unit
  • currency - the currency of the Additional Item, will always be the same as the Invoice's currency
  • taxable - whether or not this Additional Item was marked as taxable

Fixed Fee Item Fields

If you include fixed_fee_items, you will receive any visible fixed-fee items associated with this Invoice in a top-level object called fixed_fee_items. Values of this object will have the following fields:

  • id - the internal Additional Item id
  • notes - any notes on the Fixed Fee Item
  • amount_in_cents - the value of the Fixed Fee Item, in the currency's base unit
  • currency - the currency of the Fixed Fee Item, will always be the same as the Invoice's currency
  • taxable - whether or not this Fixed Fee Item was marked as taxable
  • story_id - the Story associated with this Fixed Fee Item
  • workspace_id - the Workspace associated with this Fixed Fee Item, which will always contain the Story

Requesting a Single Invoice

As with all resources, you can request either GET /api/v1/invoices.json?only=5 or GET /api/v1/invoices/5.json.

Creating New Invoices in a Workspace

You can create an invoice with the following parameters:

  • time_entry_ids (optional - see note below) An array of Time Entry IDs
  • expense_ids (optional - see note below) An array of Expense IDs
  • workspace_id (required) The ID of the workspace to create the invoice in
  • payment_schedule (required) The payment schedule in days
  • invoice_date (optional) Defaults to today's date if none is specified
  • user_invoice_number (optional) A user defined invoice number
  • draft (optional) A boolean determinining whether an invoice should be created as a draft
  • message (optional) The invoice's message
  • user_invoice_title (optional) A user defined invoice title
  • purchase_order (optional) A user defined purchase order
  • project_code (optional) A user defined project code
  • fixed_fee_items (optional - see note below) Fixed fee items to create
  • additional_items (optional - see note below) Additional items to create

Note:

In order to create an invoice you must include at least one of the following: a time entry id, an expense id, a fixed fee item, or an additional item.

You can create an invoice through the API as follows:

curl -H "Content-Type: application/json" -d '{"time_entry_ids": [1], "expense_ids": [2], "workspace_id": 3, "payment_schedule": 20}' "https://api.mavenlink.com/api/v1/invoices.json"

The response will contain a JSON representation of the newly created invoice or an error message indicating which arguments are missing or erroneous.

Creating fixed fee items during invoice creation

Fixed fees are created with the following parameters:

  • story_id
  • notes
  • amount
  • taxable

An invoice creation request that creates a fixed fee item would be as follows:

curl -H "Content-Type: application/json" -d '{"workspace_id": 3, "payment_schedule": 20, "fixed_fee_items": [{"story_id": 1, "notes": "This is a fixed fee item", "amount": 10, "taxable": true}]}' "https://api.mavenlink.com/api/v1/invoices.json"

Creating additional items

Additional items are created with the following parameters:

  • notes
  • amount
  • taxable

An invoice creation request that creates an additional item would be as follows:

curl -H "Content-Type: application/json" -d '{"workspace_id": 3, "payment_schedule": 20, "additional_items": [{"notes": "This is an additional item", "amount": 10, "taxable": true}]}' "https://api.mavenlink.com/api/v1/invoices.json"

Updating Invoices

You can edit Invoices as follows:

curl -X PUT -d "invoice[message]='new message'" -d "invoice[time_entry_ids]=[1,2,3]" "https://api.mavenlink.com/api/v1/invoices/1.json"

The following parameters are currently supported for updating invoices:

  • expense_ids
  • time_entry_ids
  • payment_schedule
  • user_invoice_number
  • draft
  • message
  • user_invoice_title
  • purchase_order
  • project_code

Notes

Active invoices cannot be changed back to drafts.

expense_ids and time_entry_ids should be sent as an array of ids that you want associated with the invoice. If you wish to remove all time entries or expenses from the invoice, send an empty array. If you do not include those parameters the corresponding expenses or time entries will not be modified.

Destroying Invoices

You can destroy an Invoice as follows:

curl -X DELETE "https://api.mavenlink.com/api/v1/invoices/1.json"

You can only destroy draft invoices. Active invoices must be cancelled instead.

Cancelling Invoices

An active Invoice can be cancelled as follows:

curl -x PUT "https://api.mavenlink.com/api/v1/invoices/1/cancel.json"