Expenses

Freckle is now Noko! Learn how to migrate your apps here

List Expenses

Get all the expenses, sorted by the most recent date.

GET /v2/expenses

Parameters

Each parameter passed will filter the results, and parameters are chained (meaning that if you search by user_ids and project_ids, it will only return expenses from those users for the specified projects).

user_ids
Optional string: a comma-separated list of user IDs to filter by.
Example: user_ids=1,2,3
description
Optional string
Only expenses containing this text in their description are returned.
Example: description=license
project_ids
Optional string: a comma-separated list of project IDs to filter by.
Example: project_ids=4,5,6
invoice_ids
Optional string: a comma-separated list of invoices to filter by
Example: invoice_ids=4,5,6
from
Optional string of a date in ISO 8061 format YYYY-MM-DD: Only expenses from or after this date will be returned.
to
Optional string of a date in ISO 8061 format: YYYY-MM-DD. Only expenses on or before this date will be returned.
price_from
Optional decimal
Only expenses with a price greater than or equal to this will be returned
price_to
Optional decimal
Only expenses with a price less than or equal to this will be returned
taxable
Optional boolean: true only shows expenses where taxes are applied, false only shows expenses were taxes are not applied.
invoiced
Optional boolean
true: only show invoiced expenses
false: only shows uninvoiced expenses

Response

Status: 200 OK
Link: <https://api.nokotime.com/v2/expenses?page=2>; rel="next",
 <https://api.nokotime.com/v2/expenses?page=5>; rel="last"
[
  {
    "id": 2233,
    "price": 14.55,
    "description": "new software",
    "taxable": true,
    "date": "2010-06-09",
    "project": {
      "id": 37396,
      "name": "Gear GmbH",
      "billing_increment": 10,
      "enabled": true,
      "billable": true,
      "color": "#ff9898",
      "url": "https://api.nokotime.com/v2/projects/37396"
    },
    "invoice": {
      "id": 12345678,
      "reference": "AA001",
      "invoice_date": "2013-07-09",
      "state": "unpaid",
      "total_amount": 189.33,
      "url": "https://api.nokotime.com/v2/invoices/12345678"
    },
    "user": {
      "id": 5538,
      "email": "john.test@test.com",
      "first_name": "John",
      "last_name": "Test",
      "profile_image_url": "https://api.nokotime.com/images/avatars/0000/0001/avatar.jpg",
      "url": "https://api.nokotime.com/v2/users/5538"
    },
    "url": "https://api.nokotime.com/v2/expense/2233",
    "created_at": "2010-06-09T20:44:57Z",
    "updated_at": "2010-06-09T20:44:57Z"
  }
]

Get a single Expense

GET /v2/expenses/:id

Status: 200 OK
{
  "id": 2233,
  "price": 14.55,
  "description": "new software",
  "taxable": true,
  "date": "2010-06-09",
  "project": {
    "id": 37396,
    "name": "Gear GmbH",
    "billing_increment": 10,
    "enabled": true,
    "billable": true,
    "color": "#ff9898",
    "url": "https://api.nokotime.com/v2/projects/37396"
  },
  "invoice": {
    "id": 12345678,
    "reference": "AA001",
    "invoice_date": "2013-07-09",
    "state": "unpaid",
    "total_amount": 189.33,
    "url": "https://api.nokotime.com/v2/invoices/12345678"
  },
  "user": {
    "id": 5538,
    "email": "john.test@test.com",
    "first_name": "John",
    "last_name": "Test",
    "profile_image_url": "https://api.nokotime.com/images/avatars/0000/0001/avatar.jpg",
    "url": "https://api.nokotime.com/v2/users/5538"
  },
  "url": "https://api.nokotime.com/v2/expense/2233",
  "created_at": "2010-06-09T20:44:57Z",
  "updated_at": "2010-06-09T20:44:57Z"
}

Create an Expense

POST /v2/expenses

Input

date
Required string of a date in ISO 8061 format YYYY-MM-DD: the date of the expense.
project_id
Required integer: The ID of the project this expense is for.
price
Required decimal: The numeric price of this expense. Do not add the currency to this price. Note that the price can be negative
user_id
Optional integer: The ID of the user who created this expense. If no value is provided, the authenticated user will be used.
taxable
Optional boolean: true indicates that the expense is taxable. false indicates that the expense is tax-free. Defaults to true.
description
Optional string: The description of the expense. Note that tags or hashtags will not be parsed.
{
  "date": "2010-06-09",
  "user_id": 5538,
  "price": 14.55,
  "taxable": true,
  "description": "new software",
  "project_id": 37396
}

Reponse

Status: 201 Created
Location: https://api.nokotime.com/v2/expenses/1
{
  "id": 2233,
  "price": 14.55,
  "description": "new software",
  "taxable": true,
  "date": "2010-06-09",
  "project": {
    "id": 37396,
    "name": "Gear GmbH",
    "billing_increment": 10,
    "enabled": true,
    "billable": true,
    "color": "#ff9898",
    "url": "https://api.nokotime.com/v2/projects/37396"
  },
  "invoice": {
    "id": 12345678,
    "reference": "AA001",
    "invoice_date": "2013-07-09",
    "state": "unpaid",
    "total_amount": 189.33,
    "url": "https://api.nokotime.com/v2/invoices/12345678"
  },
  "user": {
    "id": 5538,
    "email": "john.test@test.com",
    "first_name": "John",
    "last_name": "Test",
    "profile_image_url": "https://api.nokotime.com/images/avatars/0000/0001/avatar.jpg",
    "url": "https://api.nokotime.com/v2/users/5538"
  },
  "url": "https://api.nokotime.com/v2/expense/2233",
  "created_at": "2010-06-09T20:44:57Z",
  "updated_at": "2010-06-09T20:44:57Z"
}

Edit an Expense

PUT /v2/expenses/:id

Input

date
Required string of a date in ISO 8061 format YYYY-MM-DD: the date of the expense.
project_id
Required integer: The ID of the project this expense is for.
price
Required decimal: The numeric price of this expense. Do not add the currency to this price. Note that the price can be negative
user_id
Optional integer: The ID of the user who created this expense. If no value is provided, the authenticated user will be used.
taxable
Optional boolean: true indicates that the expense is taxable. false indicates that the expense is tax-free. Defaults to true.
description
Optional string: The description of the expense. Note that tags or hashtags will not be parsed.
{
  "date": "2010-06-09",
  "user_id": 5538,
  "price": 14.55,
  "taxable": true,
  "description": "new software",
  "project_id": 37396
}

Response

Status: 200 OK
{
  "id": 2233,
  "price": 14.55,
  "description": "new software",
  "taxable": true,
  "date": "2010-06-09",
  "project": {
    "id": 37396,
    "name": "Gear GmbH",
    "billing_increment": 10,
    "enabled": true,
    "billable": true,
    "color": "#ff9898",
    "url": "https://api.nokotime.com/v2/projects/37396"
  },
  "invoice": {
    "id": 12345678,
    "reference": "AA001",
    "invoice_date": "2013-07-09",
    "state": "unpaid",
    "total_amount": 189.33,
    "url": "https://api.nokotime.com/v2/invoices/12345678"
  },
  "user": {
    "id": 5538,
    "email": "john.test@test.com",
    "first_name": "John",
    "last_name": "Test",
    "profile_image_url": "https://api.nokotime.com/images/avatars/0000/0001/avatar.jpg",
    "url": "https://api.nokotime.com/v2/users/5538"
  },
  "url": "https://api.nokotime.com/v2/expense/2233",
  "created_at": "2010-06-09T20:44:57Z",
  "updated_at": "2010-06-09T20:44:57Z"
}

Custom Error Codes

The following Custom Error codes can be returned for this action:

Delete an Expense

DELETE /v2/expenses/:id

Response

Status: 204 No Content

Custom Error Codes

The following Custom Error codes can be returned for this action: