Expenses

Expenses in Mavenlink allow users to track non-timed items of work or expense. Once created, they can be included in invoices generated subsequently.

Expense objects have seventeen readable attributes. They are:

• id the unique identifier for this expense object
• created_at the date the expense was recorded in Mavenlink
• updated_at the date the expense was last updated
• date the date the expense was incurred
• notes any notes added to the expense
• category the category of the expense, which can be any string. Built-in categories are: "Travel", "Mileage", "Lodging", "Food", "Entertainment", "Other"
• amount_in_cents the amount of the expense, in cents
• currency the currency of the expense
• currency_symbol the symbol that represents the currency of the expense
• currency_base_unit the number of the units in the amount_as_cents attribute that are required to make up a single unit of the currency
• user_can_edit can the viewing user edit this expense?
• is_invoiced has this expense been included on an invoice?
• is_billable is this a billable expense?
• taxable was this expense marked as taxable when invoiced?
• workspace_id the id of the project Workspace this expense is associated with
• user_id the id of the user who created this expense
• receipt_id the id of an attached Receipt Attachment
• story_id the id of the story Story (Task) this expense is associated with

Fetching Expenses

The expenses endpoint provides a list of every expense that the user making the request is allowed to see, across all workspaces that the user belongs to.

The response will contain an array of expense objects, sorted by the date attribute in descending order, available under the key named expenses.

As with all API listing actions, you can provide per_page and page to paginate your response. You may also limit the response to one or more specific expenses using the only parameter.

To list all a user's expenses using curl, run:

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

Associated Objects

You can include expenses' associations with the include param. For example, to include returned expenses' workspaces and stories, you would do the following:

curl "https://api.mavenlink.com/api/v1/expenses.json?include=workspace,story"

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

• workspace - the workspace (project) that owns this expense, returned in the workspaces top-level key
• user - the user object of the expense creator, returned in the users top-level key
• story - linked story (task), returned in the stories top-level key
• receipt - information about any receipt associated with this expense, returned in the attachments top-level key
• expense_category - the expense category that this expense is associated with

Filtering Expenses

The expenses list provides filters to allow you to limit the expenses that will be returned.

• workspace_id limits the returned expenses to only the expenses that belong to the workspace whose ID was given
• from_archived_workspaces (default: false) can be set to true to request that expenses from archived workspaces be included in the response
• date_expensed_between - Requires a colon separated pair of dates in YYYY-MM-DD format. If a date is not passed in, it is interpreted as negative or positive infinity
• created_before - include expenses created before the given timestamp (in ISO 8601 format)
• created_after - include expenses created after the given timestamp (in ISO 8601 format)
• updated_before - include expenses updated before the given timestamp (in ISO 8601 format)
• updated_after - include expenses updated after the given timestamp (in ISO 8601 format)

For example, to retrieve expenses filtered by workspace:

curl "https://api.mavenlink.com/api/v1/expenses.json?workspace_id=1"

To request expenses including those from archived workspaces:

curl "https://api.mavenlink.com/api/v1/expenses.json?from_archived_workspaces=true"

Ordering Expenses

Valid orders are:

• date

Getting a Single Expense

As with all resources, you can request either GET /api/v1/expenses.json?only=5 or GET /api/v1/expenses/5.json. In both cases, default filters will be applied. Therefore, you won't receive Expenses from archived workspaces (and will receive a 404 status on the "show" route) unless you provide the from_archived_workspaces:true filter.

Creating a Single New Expense

The expense parameter has four required attributes:

• workspace_id the ID of the Workspace in which the expense will be created
• date the date of the expense in ISO8601 format
• category the category of the expense as a string
• amount_in_cents the amount of the expense, expressed in cents

There are four optional attributes:

• notes freeform text related to the expense
• billable is a boolean that indicates whether or not this expense is billable
• receipt_id is the optional id of a Receipt Attachment for this expense
• story_id is the optional id of a Story in the Workspace to link to this new Expense
• user_id - the internal ID of the user the expense is associated with. This parameter is ignored unless the authorizing user has financial access in the workspace and is on the consultants team (or if the authorizing user is an account administrator and has proxy permissions via an account member with those permissions).

For example, to create a new expense using curl in the "Food" category, incurred on February 19th, 2013, at 5:13:23 PM PST, for an amount of $30, run:

curl -H "Content-Type: application/json" --data-binary '{"expense": {"workspace_id": 1, "date": "2013-02-19T17:13:23-08:00", "category": "Food", "amount_in_cents": 3000}}' "https://api.mavenlink.com/api/v1/expenses.json"

Creating Multiple New Expenses

You can create multiple expenses in a single request if you send a expenses array. An example would be to send a request with the following parameters encoded as application/json:

{"expenses": [{"workspace_id": 1, "date": "2013-02-19T17:13:23-08:00", "category": "Food", "amount_in_cents": 5000},{"workspace_id": 1, "date": "2015-02-19T17:13:23-08:00", "category": "Travel", "amount_in_cents": 10000} ]}

Using curl, that request could be sent as:

curl -H "Content-Type: application/json" -d '{"expenses": [{"workspace_id": 1, "date": "2013-02-19T17:13:23-08:00", "category": "Food", "amount_in_cents": 5000},{"workspace_id": 1, "date": "2015-02-19T17:13:23-08:00", "category": "Travel", "amount_in_cents": 10000} ]}' "https://api.mavenlink.com/api/v1/expenses.json"

Updating an existing Expense

An expense that has already been created can be updated with an HTTP PUT request. Any required or optional attribute, with the exception of workspace_id, can be changed in an update.

For example, to update the expense with ID 5 to a cost of $100 using curl, run:

curl -X PUT -H "Content-Type: application/json" --data-binary '{"expense": {"amount_in_cents": 10000}}' "https://api.mavenlink.com/api/v1/expenses/5.json"

The response will contain the JSON representation of the updated expense or an error message indicating which arguments are missing or erroneous.

Destroying an existing Expense

An expense that has already been created can be deleted with an HTTP DELETE request.

For example, to delete the expense with ID 5 run:

curl -X DELETE "https://api.mavenlink.com/api/v1/expenses/5.json"

The response will have no content and HTTP 204 status code if the expense has been successfully deleted, or a JSON error message indicating why the expense could not be deleted.