Invoice

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

List Invoices

GET /invoices/

Parameters

state
Optional string
Only invoices in this state will be returned. Accepted Values are:
  • unpaid
  • awaiting_payment
  • in_progress
  • paid
  • none
reference
Optional string
Only invoices containing this text in their invoice reference are returned.
Example: reference=AA001
invoice_date_from
Optional string of a date in ISO 8061 format YYYY-MM-DD
Only invoices with an invoice_date from this date forward will be returned.
Example: from=2013-09-27
invoice_date_to
Optional string of a date in ISO 8061 format YYYY-MM-DD
Only invoices with an invoice_date on or before this date will be returned.
Example: to=2013-09-27
project_name
Optional string
Only invoices containing this text in their project_name field are returned.
Example: project_name=Invoice
total_amount_from
Optional decimal
Only invoices with a total amount due greater than or equal to this will be returned
total_amount_to
Optional decimal
Only invoices with a total amount due less than or equal to this will be returned
recipient_details
Optional string
Only invoices containing this text in their recipient_details field are returned.
Example: recipient_details=Furniture
project_ids
Optional string
A comma-separated list of project IDs to filter by.
Example: project_ids=4,5,6
company_name
Optional string
Only invoices containing this text in their company_name field are returned.
Example: company_name=Gear
company_details
Optional string
Only invoices containing this text in their company_details field are returned.
Example: company_details=Main
description
Optional string
Only invoices containing this text in their description field are returned
Example: description=Services
footer
Optional string
Only invoices containing this text in their footer field are returned
Example: footer=Payment
has_online_payment_details
Optional boolean
true: Only return invoices that have online payment details.
false: Only return invoices that do not have online payment details.
has_custom_html
Optional boolean
true: Only return invoices that include custom HTML.
false: Only return invoices that do not include custom HTML.
show_hours_worked
Optional boolean
true: Only return invoices that show the hours worked for this invoice.
false: Only return invoices that do not show the hours worked for this invoice.
show_full_report
Optional boolean
true: Only return invoices that show the full report for the invoice.
false: Only return invoices that do not show the full report for the invoice.
show_user_summaries
Optional boolean
true: Only return invoices that show the summary of hours worked for each team member.
false: Only return invoices that do not show the summary of hours worked for each team member.
show_project_summaries
Optional boolean
true: Only return invoices that show the summary of hours worked for each project.
false: Only return invoices that do not show the summary of hours worked for each project.
show_project_name_for_expenses
Optional boolean
true: Only return invoices that show the expense’s project name next to the expense description.
false: Only return invoices that do not show the expense’s project name next to the expense description.
locale
Optional string
Only invoices using this locale are returned.
Accepted values: (Any of the supported locale codes)
Example: locale=en-GB
currency_code
Optional name
Only invoices using this currency are returned
Accepted values: (Any of the supported ISO currency codes)
Example: currency_code=EUR
currency_symbol
Optional string
Only invoices with this text as part of their currency_symbol are returned
Example: currency_symbol=£
rate_calculation
Optional string
How the rate for the hours worked is calculated. The Accepted values are:
  • custom_hourly_rates
  • standard_hourly_rate
  • flat_rate
updated_from
Optional string of a timestamp in ISO 8061 format YYYY-MM-DDTHH:MM:SSZ
Only invoices updated from or after this timestamp will be returned.
Example: updated_from=2012-01-09T08:33:29Z
updated_to
Optional string of a timestamp in ISO 8061 format YYYY-MM-DDTHH:MM:SSZ
Only invoices updated on or before this timestamp will be returned.
Example: updated_to=2012-01-09T08:33:29Z

Response

Status: 200 OK
Link: <https://api.nokotime.com/v2/invoices?page=2>; rel="next",
 <https://api.nokotime.com/v2/invoices?page=5>; rel="last"
[
  {
    "id": 26642,
    "state": "paid",
    "reference": "AB 0001",
    "invoice_date": "2013-07-09",
    "project_name": "Knockd, Noko Support",
    "company_name": "John Test",
    "company_details": "1 Main Street\nMainsville, MA 11122",
    "recipient_details": "",
    "description": "",
    "footer": "",
    "show_hours_worked": true,
    "show_full_report": false,
    "show_user_summaries": false,
    "show_project_summaries": false,
    "show_project_name_for_expenses": false,
    "customization": {
      "title": "Invoice",
      "date": "Date",
      "project": "Project",
      "reference": "Invoice reference",
      "total_due": "Total amount due",
      "summary": "Summary",
      "project_summary": "Project summary",
      "user_summary": "People summary",
      "no_project_name": "No project",
      "work_time": "work time",
      "no_tax": "no tax",
      "work_total": "Total worked",
      "total": "TOTAL",
      "report": "Report",
      "locale": "en-US",
      "currency_code": "USD",
      "currency_symbol": "$",
      "taxable_total": "Total taxable",
      "tax_total": "Total tax",
      "taxfree_total": "Total taxfree",
      "total_report": "TOTAL",
      "custom_html": "My Custom Invoice",
      "allow_paypal_invoice": true,
      "paypal_invoice_title": "Paypal Invoice Title",
      "paypal_currency_code": "USD",
      "paypal_address": "payment@test.com",
      "allow_stripe_connect_payment": true,
      "stripe_connect_payment_description": "Stripe Payment Description",
      "stripe_connect_currency_code": "usd",
      "currency_name": "United States dollar",
      "created_at": "2013-04-24T17:39:51Z",
      "updated_at": "2013-04-24T17:39:51Z"
    },
    "rate_calculation": {
      "calculation_method": "custom_hourly_rates",
      "standard_hourly_rate": 30.75,
      "custom_hourly_rates": [
        {
          "user": 5538,
          "hourly_rate": 15.25
        }
      ],
      "flat_rate": 11000.72
    },
    "taxes": [
      {
        "id": 88292,
        "name": "Sales Tax",
        "percentage": 15.0
      }
    ],
    "taxable_amount": 100,
    "taxfree_amount": 0,
    "tax_total_amount": 0,
    "total_amount": 1,
    "taxable_amount_with_currency": "$100.00",
    "taxfree_amount_with_currency": "$0.00",
    "tax_total_amount_with_currency": "$0.00",
    "total_amount_with_currency": "$1.00",
    "payment": {
      "paid_at": "2013-07-09T23:04:06Z",
      "reference": "AP-AAABBBDDDEEEE22222",
      "payment_method": "paypal"
    },
    "payment_transactions": [
      {
        "created_at": "2013-07-09T23:04:06Z",
        "description": "Sent to Paypal",
        "payment_method": "paypal",
        "reference": "AP-AAAAABBBCCCCDDD111",
        "invoice_state": "in_progress"
      }
    ],
    "projects": [
      {
        "id": 37396,
        "name": "Gear GmbH",
        "billing_increment": 10,
        "enabled": true,
        "billable": true,
        "color": "#ff9898",
        "url": "https://api.nokotime.com/v2/projects/37396"
      }
    ],
    "entries": 123,
    "entries_url": "https://api.nokotime.com/v2/invoices/26642/entries",
    "expenses": 324,
    "expenses_url": "https://api.nokotime.com/v2/invoices/26642/expenses",
    "share_url": "https://apitest.nokotime.com/i/bqrnbojlbxqswtq9xla9uc40z",
    "created_at": "2013-07-09T23:04:05Z",
    "updated_at": "2013-07-09T23:04:06Z",
    "url": "https://api.nokotime.com/v2/invoices/26642"
  }
]

Get a single Invoice

GET /invoices/:id

Response

Status: 200 OK
{
  "id": 26642,
  "state": "paid",
  "reference": "AB 0001",
  "invoice_date": "2013-07-09",
  "project_name": "Knockd, Noko Support",
  "company_name": "John Test",
  "company_details": "1 Main Street\nMainsville, MA 11122",
  "recipient_details": "",
  "description": "",
  "footer": "",
  "show_hours_worked": true,
  "show_full_report": false,
  "show_user_summaries": false,
  "show_project_summaries": false,
  "show_project_name_for_expenses": false,
  "customization": {
    "title": "Invoice",
    "date": "Date",
    "project": "Project",
    "reference": "Invoice reference",
    "total_due": "Total amount due",
    "summary": "Summary",
    "project_summary": "Project summary",
    "user_summary": "People summary",
    "no_project_name": "No project",
    "work_time": "work time",
    "no_tax": "no tax",
    "work_total": "Total worked",
    "total": "TOTAL",
    "report": "Report",
    "locale": "en-US",
    "currency_code": "USD",
    "currency_symbol": "$",
    "taxable_total": "Total taxable",
    "tax_total": "Total tax",
    "taxfree_total": "Total taxfree",
    "total_report": "TOTAL",
    "custom_html": "My Custom Invoice",
    "allow_paypal_invoice": true,
    "paypal_invoice_title": "Paypal Invoice Title",
    "paypal_currency_code": "USD",
    "paypal_address": "payment@test.com",
    "allow_stripe_connect_payment": true,
    "stripe_connect_payment_description": "Stripe Payment Description",
    "stripe_connect_currency_code": "usd",
    "currency_name": "United States dollar",
    "created_at": "2013-04-24T17:39:51Z",
    "updated_at": "2013-04-24T17:39:51Z"
  },
  "rate_calculation": {
    "calculation_method": "custom_hourly_rates",
    "standard_hourly_rate": 30.75,
    "custom_hourly_rates": [
      {
        "user": 5538,
        "hourly_rate": 15.25
      }
    ],
    "flat_rate": 11000.72
  },
  "taxes": [
    {
      "id": 88292,
      "name": "Sales Tax",
      "percentage": 15.0
    }
  ],
  "taxable_amount": 100,
  "taxfree_amount": 0,
  "tax_total_amount": 0,
  "total_amount": 1,
  "taxable_amount_with_currency": "$100.00",
  "taxfree_amount_with_currency": "$0.00",
  "tax_total_amount_with_currency": "$0.00",
  "total_amount_with_currency": "$1.00",
  "payment": {
    "paid_at": "2013-07-09T23:04:06Z",
    "reference": "AP-AAABBBDDDEEEE22222",
    "payment_method": "paypal"
  },
  "payment_transactions": [
    {
      "created_at": "2013-07-09T23:04:06Z",
      "description": "Sent to Paypal",
      "payment_method": "paypal",
      "reference": "AP-AAAAABBBCCCCDDD111",
      "invoice_state": "in_progress"
    }
  ],
  "projects": [
    {
      "id": 37396,
      "name": "Gear GmbH",
      "billing_increment": 10,
      "enabled": true,
      "billable": true,
      "color": "#ff9898",
      "url": "https://api.nokotime.com/v2/projects/37396"
    }
  ],
  "entries": 123,
  "entries_url": "https://api.nokotime.com/v2/invoices/26642/entries",
  "expenses": 324,
  "expenses_url": "https://api.nokotime.com/v2/invoices/26642/expenses",
  "share_url": "https://apitest.nokotime.com/i/bqrnbojlbxqswtq9xla9uc40z",
  "created_at": "2013-07-09T23:04:05Z",
  "updated_at": "2013-07-09T23:04:06Z",
  "url": "https://api.nokotime.com/v2/invoices/26642"
}

Create an Invoice

POST /invoices/

Input

invoice_date
Required string in ISO 8061 format YYYY-MM-DD
The date the invoice was issued.
reference
Optional string
The invoice’s reference identifier. If no value is provided, a value will be generated based on previous invoices.
project_name
Optional string
The name of the projects involved in this invoice.
company_name
Optional string
The name of the company issuing the invoice.
company_details
Optional string
The mailing address and other information for the company issuing the invoice.
recipient_details
Optional string
The mailing address and other information for the invoice’s recipient.
description
Optional string that supports a limited version of Markdown
A description of the invoice.
footer
Optional string that supports a limited version of Markdown
The footer for each page of the invoice.
show_hours_worked
Optional boolean
true (Default): The hours worked will be shown when viewing the invoice
false: The hours worked will not be shown when viewing the invoice.
show_full_report
Optional boolean
true: The full report will be shown when viewing the invoice.
false (Default): The full report will not be shown when viewing the invoice.
show_user_summaries
Optional boolean
true: A summary of how many minutes each team member worked will be shown when viewing the invoice.
false (Default): A summary of how many minutes each team member worked will not be shown when viewing the invoice.
show_project_summaries
Optional boolean
true: A summary of how many minutes were worked for each project will be shown when viewing the invoice.
false (Default): A summary of how many minutes were worked for each project will not be shown when viewing the invoice.
show_project_name_for_expenses
Optional boolean
true: The expense’s project name will be shown next to its description when viewing the invoice.
false (Default): The expense’s project name will not be shown next to its description when viewing the invoice
rate_calculation
Optional object
How to calculate the total amount for hours worked. The fields are:
calculation_method
Required string
What method will be used to calculate the total amount for hours worked. Accepted values are:
  • standard_hourly_rate: a single hourly rate is used across the entire invoice.
  • custom_hourly_rates: custom hourly rates can be defined for individual users in the custom_hourly_rates array. If no custom_hourly_rate is defined for an individual user, the standard_hourly_rate is used for that user.
  • flat_rate: a flat rate is used for the the total cost of the hours in the invoice.
flat_rate
Required if payment_type equals flat_rate decimal
The flat rate used as the total amount for hours worked.
standard_hourly_rate
Required if calculation_method equals standard_hourly_rate or custom_hourly_rate decimal
The standard hourly rate used to calculate the total amount for hours worked.
custom_hourly_rates
Required if calculation_method equals custom_hourly_rate (ignored otherwise) array of objects
The custom hourly rates for users, which are used to calculate the total amount for the hours they worked in this invoice. The fields are:
user_id
Required integer
the ID of the user
hourly_rate
Required decimal
the hourly rate for this specific user.
entry_ids
Optional array of integers
The IDs of the entries to be included in this invoice.
expense_ids
Optional array of integers
The IDs of the expenses to be included in this invoice.
taxes
Optional array of objects
The taxes to apply to this invoice. The fields are:
percentage
Required decimal in percentage format (00.00)
the numeric percentage of the tax
name
Optional string
the name of the tax
customization
Optional object
These fields define the labels and localization settings used when viewing an invoice, and the details for making an invoice payable via Paypal. The fields are:
title
Optional string
The title of the Invoice.
Defaults to the value used in a previous invoice for these projects, or “Invoice” if none is found.
date
Optional string
The label for the Invoice Date.
Defaults to the value used in a previous invoice for these projects, or “Date” if none is found.
project
Optional string
The label for the name of the projects involved in this invoice.
Defaults to the value used in a previous invoice for these projects, or “Projects” if none is found.
reference
Optional string
The label for the invoice’s reference identifier (Invoice Number).
Defaults to the value used in a previous invoice for these projects, or “Invoice reference” if none is found.
total_due
Optional string
The label for the total amount due for the Invoice.
Defaults to the value used in a previous invoice for these projects, or “Total amount due” if none is found.
summary
Optional string
The label for the section of the invoice summarizing the time worked by each employee, subtotals, expenses, and tax calculations for the invoice.
Defaults to the value used in a previous invoice for these projects, or “Summary” if none is found.
project_summary
Optional string
The label for the project summary section of the invoice.
Defaults to the value used in a previous invoice for these projects, or “Project summary” if none is found.
user_summary
Optional string
The label for the user summary section of the invoice.
Defaults to the value used in a previous invoice for these projects, or “People summary” if none is found.
no_project_name
Optional string
the label used to summarize entries without any project in the project summary section.
Defaults to the value used in a previous invoice for these projects, or “No project” if none is found.
work_time
Optional string
The label for the section of the summary that details the time worked by each employee.
Defaults to the value used in a previous invoice for these projects, or “work time” if none is found.
no_tax
Optional string
The label for the section of the summary that outlines the amounts in the invoice which do not have tax applied.
Defaults to the value used in a previous invoice for these projects, or “no tax” if none is found.
work_total
Optional string
The label used for the summary of the total amount of time worked in the invoice.
Defaults to the value used in a previous invoice for these projects, or “Total worked” if none is found.
total
Optional string
The label for the total amount for the invoice.
Defaults to the value used in a previous invoice for these projects, or “TOTAL” if none is found.
report
Optional string
The label for the report of total time worked for this invoice.
Defaults to the value used in a previous invoice for these projects, or “Report” if none is found.
locale
Optional string of a locale code (Supported locale codes)
The locale of the invoice, which is used to localize dates and other non-currency values.
Defaults to the value used in a previous invoice for these projects, or “en-US” if none is found.
currency_code
Optional string of a ISO 4217 currency code (Supported Currency Codes)
The ISO 4217 code of the currency used in this invoice, which is used to correctly represent the currency value in the correct format.
Defaults to the value used in a previous invoice for these projects.
If no previous invoice is found, the currency code will be automatically selected based on the locale.
currency_symbol
Optional string
The custom currency symbol used in this invoice.
Defaults to the value used in a previous invoice for these projects.
If no previous invoice is found, the currency symbol will automatically be selected based on the locale.
taxable_total
Optional string
The label for the total taxable amount in the invoice.
Defaults to the value used in a previous invoice for these projects, or “Total taxable” if none is found.
tax_total
Optional string
The label for the total amount of taxes applied to the invoice.
Defaults to the value used in a previous invoice for these projects, or “Total tax” if none is found.
taxfree_total
Optional string
The label for the total amount of the invoice which is tax-free.
Defaults to the value used in a previous invoice for these projects, or “Total taxfree” if none is found.
total_report
Optional string
The label for the total number of minutes worked, which is shown in the full report for this invoice.
Defaults to the value used in a previous invoice for these projects, or “TOTAL” if none is found.
custom_html
Optional string
Any custom HTML used in the invoice.
Defaults to the value used in a previous invoice for these projects.
If no previous invoice is found, the field will be blank.
paypal_invoice
Optional object
This object is used to setup the invoice so that it can be paid via paypal. The fields are:
paypal_address
Optional string
The email address that will be receive the money for this invoice. This should be your Paypal email address.
Defaults to the value used in a previous invoice for these projects.
If no previous invoice is found, the field will be blank.
paypal_invoice_title
Optional string
The title for the paypal invoice. If no value is provided, then the invoice_number will be used.
paypal_currency_code
Optional string of a Paypal currency code
The paypal currency code used for this invoice.
Defaults to the value used in a previous invoice for these projects, or “USD” if none is found.
stripe_connect_payment
Optional object
This object is used to setup the invoice so that it can be paid via Stripe Connect. The fields are:
payment_description
Optional string
The description for the payment in Stripe. If no value is provided, then the invoice_number will be used.
currency_code
Optional string of a Stripe currency code
The ISO currency code used for this invoice.
Defaults to the value used in a previous invoice for these projects, or “usd” if none is found.
{
  "invoice_date": "2013-07-09",
  "reference": "AB 0001",
  "project_name": "Knockd, Noko Support",
  "company_name": "John Test",
  "company_details": "1 Main Street\nMainsville, MA 11122",
  "recipient_details": "",
  "description": "",
  "footer": "",
  "show_hours_worked": true,
  "show_full_report": false,
  "show_user_summaries": false,
  "show_project_summaries": false,
  "rate_calculation": {
    "calculation_method": "custom_hourly_rates",
    "standard_hourly_rate": 30.75,
    "custom_hourly_rates": [
      {
        "user": 5538,
        "hourly_rate": 15.25
      }
    ],
    "flat_rate": 11000.72
  },
  "entry_ids": [
    1
  ],
  "expense_ids": [
    2233
  ],
  "taxes": [
    {
      "name": "Sales Tax",
      "percentage": 15.0
    }
  ]
}

Response

Status: 201 Created
Location: https://api.nokotime.com/v2/invoices/1
{
  "id": 26642,
  "state": "paid",
  "reference": "AB 0001",
  "invoice_date": "2013-07-09",
  "project_name": "Knockd, Noko Support",
  "company_name": "John Test",
  "company_details": "1 Main Street\nMainsville, MA 11122",
  "recipient_details": "",
  "description": "",
  "footer": "",
  "show_hours_worked": true,
  "show_full_report": false,
  "show_user_summaries": false,
  "show_project_summaries": false,
  "show_project_name_for_expenses": false,
  "customization": {
    "title": "Invoice",
    "date": "Date",
    "project": "Project",
    "reference": "Invoice reference",
    "total_due": "Total amount due",
    "summary": "Summary",
    "project_summary": "Project summary",
    "user_summary": "People summary",
    "no_project_name": "No project",
    "work_time": "work time",
    "no_tax": "no tax",
    "work_total": "Total worked",
    "total": "TOTAL",
    "report": "Report",
    "locale": "en-US",
    "currency_code": "USD",
    "currency_symbol": "$",
    "taxable_total": "Total taxable",
    "tax_total": "Total tax",
    "taxfree_total": "Total taxfree",
    "total_report": "TOTAL",
    "custom_html": "My Custom Invoice",
    "allow_paypal_invoice": true,
    "paypal_invoice_title": "Paypal Invoice Title",
    "paypal_currency_code": "USD",
    "paypal_address": "payment@test.com",
    "allow_stripe_connect_payment": true,
    "stripe_connect_payment_description": "Stripe Payment Description",
    "stripe_connect_currency_code": "usd",
    "currency_name": "United States dollar",
    "created_at": "2013-04-24T17:39:51Z",
    "updated_at": "2013-04-24T17:39:51Z"
  },
  "rate_calculation": {
    "calculation_method": "custom_hourly_rates",
    "standard_hourly_rate": 30.75,
    "custom_hourly_rates": [
      {
        "user": 5538,
        "hourly_rate": 15.25
      }
    ],
    "flat_rate": 11000.72
  },
  "taxes": [
    {
      "id": 88292,
      "name": "Sales Tax",
      "percentage": 15.0
    }
  ],
  "taxable_amount": 100,
  "taxfree_amount": 0,
  "tax_total_amount": 0,
  "total_amount": 1,
  "taxable_amount_with_currency": "$100.00",
  "taxfree_amount_with_currency": "$0.00",
  "tax_total_amount_with_currency": "$0.00",
  "total_amount_with_currency": "$1.00",
  "payment": {
    "paid_at": "2013-07-09T23:04:06Z",
    "reference": "AP-AAABBBDDDEEEE22222",
    "payment_method": "paypal"
  },
  "payment_transactions": [
    {
      "created_at": "2013-07-09T23:04:06Z",
      "description": "Sent to Paypal",
      "payment_method": "paypal",
      "reference": "AP-AAAAABBBCCCCDDD111",
      "invoice_state": "in_progress"
    }
  ],
  "projects": [
    {
      "id": 37396,
      "name": "Gear GmbH",
      "billing_increment": 10,
      "enabled": true,
      "billable": true,
      "color": "#ff9898",
      "url": "https://api.nokotime.com/v2/projects/37396"
    }
  ],
  "entries": 123,
  "entries_url": "https://api.nokotime.com/v2/invoices/26642/entries",
  "expenses": 324,
  "expenses_url": "https://api.nokotime.com/v2/invoices/26642/expenses",
  "share_url": "https://apitest.nokotime.com/i/bqrnbojlbxqswtq9xla9uc40z",
  "created_at": "2013-07-09T23:04:05Z",
  "updated_at": "2013-07-09T23:04:06Z",
  "url": "https://api.nokotime.com/v2/invoices/26642"
}

A note about entries or expenses that cannot be added

If entries or expenses cannot be added to an invoice, the invoice will not be created and an itemized errors array will be returned.

Status: 400 Bad Request
{
  "message": "Entries or Expenses could not be added",
  "errors": [
    {
      "resource": "Entry",
      "field": "entry_ids[1]",
      "code": "archived_project"
    },
    {
      "resource": "Expense",
      "field": "expense_ids[4]",
      "code": "missing"
    }
  ]
}

Custom Error Codes

Edit an Invoice

PUT /invoices/:id

Inputs

invoice_date
Optional string in ISO 8061 format YYYY-MM-DD
The date the invoice was issued.
reference
Optional string
The invoice’s reference identifier. If no value is provided, a value will be generated based on previous invoices.
project_name
Optional string
The name of the projects involved in this invoice.
company_name
Optional string
The name of the company issuing the invoice.
company_details
Optional string
The mailing address and other information for the company issuing the invoice.
recipient_details
Optional string
The mailing address and other information for the invoice’s recipient.
description
Optional string that supports a limited version of Markdown
A description of the invoice.
footer
Optional string that supports a limited version of Markdown
The footer for each page of the invoice.
show_hours_worked
Optional boolean
true (Default): The hours worked will be shown when viewing the invoice
false: The hours worked will not be shown when viewing the invoice.
show_full_report
Optional boolean
true: The full report will be shown when viewing the invoice.
false (Default): The full report will not be shown when viewing the invoice.
show_user_summaries
Optional boolean
true: A summary of how many minutes each team member worked will be shown when viewing the invoice.
false (Default): A summary of how many minutes each team member worked will not be shown when viewing the invoice.
show_project_summaries
Optional boolean
true: A summary of how many minutes were worked for each project will be shown when viewing the invoice.
false (Default): A summary of how many minutes were worked for each project will not be shown when viewing the invoice.
show_project_name_for_expenses
Optional boolean
true: The expense’s project name will be shown next to its description when viewing the invoice.
false (Default): The expense’s project name will not be shown next to its description when viewing the invoice
rate_calculation
Optional object
How to calculate the total amount for hours worked. The fields are:
calculation_method
Required string
What method will be used to calculate the total amount for hours worked. Accepted values are:
  • standard_hourly_rate: a single hourly rate is used across the entire invoice.
  • custom_hourly_rates: custom hourly rates can be defined for individual users in the custom_hourly_rates array. If no custom_hourly_rate is defined for an individual user, the standard_hourly_rate is used for that user.
  • flat_rate: a flat rate is used for the the total cost of the hours in the invoice.
flat_rate
Required if payment_type equals flat_rate decimal
The flat rate used as the total amount for hours worked.
standard_hourly_rate
Required if calculation_method equals standard_hourly_rate or custom_hourly_rate decimal
The standard hourly rate used to calculate the total amount for hours worked.
custom_hourly_rates
Required if calculation_method equals custom_hourly_rate (ignored otherwise) array of objects
The custom hourly rates for users, which are used to calculate the total amount for the hours they worked in this invoice. The fields are:
user_id
Required integer
the ID of the user
hourly_rate
Required decimal
the hourly rate for this specific user.
customization
Optional object
These fields define the labels and localization settings used when viewing an invoice, and the details for making an invoice payable via Paypal. The fields are:
title
Optional string
The title of the Invoice.
Defaults to the value used in a previous invoice for these projects, or “Invoice” if none is found.
date
Optional string
The label for the Invoice Date.
Defaults to the value used in a previous invoice for these projects, or “Date” if none is found.
project
Optional string
The label for the name of the projects involved in this invoice.
Defaults to the value used in a previous invoice for these projects, or “Projects” if none is found.
reference
Optional string
The label for the invoice’s reference identifier (Invoice Number).
Defaults to the value used in a previous invoice for these projects, or “Invoice reference” if none is found.
total_due
Optional string
The label for the total amount due for the Invoice.
Defaults to the value used in a previous invoice for these projects, or “Total amount due” if none is found.
summary
Optional string
The label for the section of the invoice summarizing the time worked by each employee, subtotals, expenses, and tax calculations for the invoice.
Defaults to the value used in a previous invoice for these projects, or “Summary” if none is found.
project_summary
Optional string
The label for the project summary section of the invoice.
Defaults to the value used in a previous invoice for these projects, or “Project summary” if none is found.
user_summary
Optional string
The label for the user summary section of the invoice.
Defaults to the value used in a previous invoice for these projects, or “People summary” if none is found.
no_project_name
Optional string
the label used to summarize entries without any project in the project summary section.
Defaults to the value used in a previous invoice for these projects, or “No project” if none is found.
work_time
Optional string
The label for the section of the summary that details the time worked by each employee.
Defaults to the value used in a previous invoice for these projects, or “work time” if none is found.
no_tax
Optional string
The label for the section of the summary that outlines the amounts in the invoice which do not have tax applied.
Defaults to the value used in a previous invoice for these projects, or “no tax” if none is found.
work_total
Optional string
The label used for the summary of the total amount of time worked in the invoice.
Defaults to the value used in a previous invoice for these projects, or “Total worked” if none is found.
total
Optional string
The label for the total amount for the invoice.
Defaults to the value used in a previous invoice for these projects, or “TOTAL” if none is found.
report
Optional string
The label for the report of total time worked for this invoice.
Defaults to the value used in a previous invoice for these projects, or “Report” if none is found.
locale
Optional string of a locale code (Supported locale codes)
The locale of the invoice, which is used to localize dates and other non-currency values.
Defaults to the value used in a previous invoice for these projects, or “en-US” if none is found.
currency_code
Optional string of a ISO 4217 currency code (Supported Currency Codes)
The ISO 4217 code of the currency used in this invoice, which is used to correctly represent the currency value in the correct format.
Defaults to the value used in a previous invoice for these projects.
If no previous invoice is found, the currency code will be automatically selected based on the locale.
currency_symbol
Optional string
The custom currency symbol used in this invoice.
Defaults to the value used in a previous invoice for these projects.
If no previous invoice is found, the currency symbol will automatically be selected based on the locale.
taxable_total
Optional string
The label for the total taxable amount in the invoice.
Defaults to the value used in a previous invoice for these projects, or “Total taxable” if none is found.
tax_total
Optional string
The label for the total amount of taxes applied to the invoice.
Defaults to the value used in a previous invoice for these projects, or “Total tax” if none is found.
taxfree_total
Optional string
The label for the total amount of the invoice which is tax-free.
Defaults to the value used in a previous invoice for these projects, or “Total taxfree” if none is found.
total_report
Optional string
The label for the total number of minutes worked, which is shown in the full report for this invoice.
Defaults to the value used in a previous invoice for these projects, or “TOTAL” if none is found.
custom_html
Optional string
Any custom HTML used in the invoice.
Defaults to the value used in a previous invoice for these projects.
If no previous invoice is found, the field will be blank.
paypal_invoice
Optional object
This object is used to setup the invoice so that it can be paid via paypal. The fields are:
paypal_address
Optional string
The email address that will be receive the money for this invoice. This should be your Paypal email address.
Defaults to the value used in a previous invoice for these projects.
If no previous invoice is found, the field will be blank.
paypal_invoice_title
Optional string
The title for the paypal invoice. If no value is provided, then the invoice_number will be used.
paypal_currency_code
Optional string of a Paypal currency code
The paypal currency code used for this invoice.
Defaults to the value used in a previous invoice for these projects, or “USD” if none is found.
stripe_connect_payment
Optional object
This object is used to setup the invoice so that it can be paid via Stripe Connect. The fields are:
payment_description
Optional string
The description for the payment in Stripe. If no value is provided, then the invoice_number will be used.
currency_code
Optional string of a Stripe currency code
The ISO currency code used for this invoice.
Defaults to the value used in a previous invoice for these projects, or “usd” if none is found.
{
  "invoice_date": "2013-07-09",
  "reference": "AB 0001",
  "project_name": "Knockd, Noko Support",
  "company_name": "John Test",
  "company_details": "1 Main Street\nMainsville, MA 11122",
  "recipient_details": "",
  "description": "",
  "footer": "",
  "show_hours_worked": true,
  "show_full_report": false,
  "show_user_summaries": false,
  "show_project_summaries": false,
  "rate_calculation": {
    "calculation_method": "custom_hourly_rates",
    "standard_hourly_rate": 30.75,
    "custom_hourly_rates": [
      {
        "user": 5538,
        "hourly_rate": 15.25
      }
    ],
    "flat_rate": 11000.72
  }
}

Response

Status: 200 OK
{
  "id": 26642,
  "state": "paid",
  "reference": "AB 0001",
  "invoice_date": "2013-07-09",
  "project_name": "Knockd, Noko Support",
  "company_name": "John Test",
  "company_details": "1 Main Street\nMainsville, MA 11122",
  "recipient_details": "",
  "description": "",
  "footer": "",
  "show_hours_worked": true,
  "show_full_report": false,
  "show_user_summaries": false,
  "show_project_summaries": false,
  "show_project_name_for_expenses": false,
  "customization": {
    "title": "Invoice",
    "date": "Date",
    "project": "Project",
    "reference": "Invoice reference",
    "total_due": "Total amount due",
    "summary": "Summary",
    "project_summary": "Project summary",
    "user_summary": "People summary",
    "no_project_name": "No project",
    "work_time": "work time",
    "no_tax": "no tax",
    "work_total": "Total worked",
    "total": "TOTAL",
    "report": "Report",
    "locale": "en-US",
    "currency_code": "USD",
    "currency_symbol": "$",
    "taxable_total": "Total taxable",
    "tax_total": "Total tax",
    "taxfree_total": "Total taxfree",
    "total_report": "TOTAL",
    "custom_html": "My Custom Invoice",
    "allow_paypal_invoice": true,
    "paypal_invoice_title": "Paypal Invoice Title",
    "paypal_currency_code": "USD",
    "paypal_address": "payment@test.com",
    "allow_stripe_connect_payment": true,
    "stripe_connect_payment_description": "Stripe Payment Description",
    "stripe_connect_currency_code": "usd",
    "currency_name": "United States dollar",
    "created_at": "2013-04-24T17:39:51Z",
    "updated_at": "2013-04-24T17:39:51Z"
  },
  "rate_calculation": {
    "calculation_method": "custom_hourly_rates",
    "standard_hourly_rate": 30.75,
    "custom_hourly_rates": [
      {
        "user": 5538,
        "hourly_rate": 15.25
      }
    ],
    "flat_rate": 11000.72
  },
  "taxes": [
    {
      "id": 88292,
      "name": "Sales Tax",
      "percentage": 15.0
    }
  ],
  "taxable_amount": 100,
  "taxfree_amount": 0,
  "tax_total_amount": 0,
  "total_amount": 1,
  "taxable_amount_with_currency": "$100.00",
  "taxfree_amount_with_currency": "$0.00",
  "tax_total_amount_with_currency": "$0.00",
  "total_amount_with_currency": "$1.00",
  "payment": {
    "paid_at": "2013-07-09T23:04:06Z",
    "reference": "AP-AAABBBDDDEEEE22222",
    "payment_method": "paypal"
  },
  "payment_transactions": [
    {
      "created_at": "2013-07-09T23:04:06Z",
      "description": "Sent to Paypal",
      "payment_method": "paypal",
      "reference": "AP-AAAAABBBCCCCDDD111",
      "invoice_state": "in_progress"
    }
  ],
  "projects": [
    {
      "id": 37396,
      "name": "Gear GmbH",
      "billing_increment": 10,
      "enabled": true,
      "billable": true,
      "color": "#ff9898",
      "url": "https://api.nokotime.com/v2/projects/37396"
    }
  ],
  "entries": 123,
  "entries_url": "https://api.nokotime.com/v2/invoices/26642/entries",
  "expenses": 324,
  "expenses_url": "https://api.nokotime.com/v2/invoices/26642/expenses",
  "share_url": "https://apitest.nokotime.com/i/bqrnbojlbxqswtq9xla9uc40z",
  "created_at": "2013-07-09T23:04:05Z",
  "updated_at": "2013-07-09T23:04:06Z",
  "url": "https://api.nokotime.com/v2/invoices/26642"
}

Custom Error Codes

Mark an Invoice as paid

PUT /invoices/:id/paid

Response

Status: 204 No Content

Mark an Invoice as unpaid

PUT /invoices/:id/unpaid

Response

Status: 204 No Content

Get the invoice’s entries

GET /invoices/:id/entries

Parameters

You can use the parameters specified in the Entry API’s List Action to further limit the results

Response

Status: 200 OK
Link: <https://api.nokotime.com/v2/invoices/:id/entries?page=2>; rel="next",
 <https://api.nokotime.com/v2/invoices/:id/entries?page=5>; rel="last"
{
  "id": 1,
  "date": "2012-01-09",
  "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"
  },
  "billable": true,
  "minutes": 60,
  "description": "noko",
  "project": {
    "id": 37396,
    "name": "Gear GmbH",
    "billing_increment": 10,
    "enabled": true,
    "billable": true,
    "color": "#ff9898",
    "url": "https://api.nokotime.com/v2/projects/37396"
  },
  "tags": [
    {
      "id": 249397,
      "name": "noko",
      "billable": true,
      "formatted_name": "#noko",
      "url": "https://api.nokotime.com/v2/tags/249397"
    }
  ],
  "source_url": "http://someapp.com/special/url/",
  "invoiced_at": "2012-01-10T08:33:29Z",
  "invoice": {
    "id": 12345678,
    "reference": "AA001",
    "invoice_date": "2013-07-09",
    "state": "unpaid",
    "total_amount": 189.33,
    "url": "https://api.nokotime.com/v2/invoices/12345678"
  },
  "import": {
    "id": 8910,
    "url": "https://api.nokotime.com/v2/imports/8910"
  },
  "approved_at": "2012-01-10T08:33:29Z",
  "approved_by": {
    "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/entries/1711626",
  "invoiced_outside_of_noko_url": "https://api.nokotime.com/v2/entries/1711626/marked_as_invoiced",
  "approved_url": "https://api.nokotime.com/v2/entries/1711626/approved",
  "unapproved_url": "https://api.nokotime.com/v2/entries/1711626/unapproved",
  "created_at": "2012-01-09T08:33:29Z",
  "updated_at": "2012-01-09T08:33:29Z"
}

Get the invoice’s expenses

GET /invoices/:id/expenses

Parameters

You can use the parameters specified in the Expense API’s List Action to further limit the results.

Response

Status: 200 OK
Link: <https://api.nokotime.com/v2/invoices/:id/expenses?page=2>; rel="next",
 <https://api.nokotime.com/v2/invoices/:id/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"
}

Add Entries to an Invoice

PUT /invoices/:id/add_entries

Inputs

entry_ids
Required array of integers
the IDs of the entries to add to this invoice.

Response

Status: 204 No Content

A note about entries that cannot be added

If entries cannot be added to an invoice, the invoice will not be created and an itemized errors array will be returned.

Status: 400 Bad Request
{
  "message": "Entries could not be added",
  "errors": [
    {
      "resource": "Entry",
      "field": "entry_ids[1]",
      "code": "archived_project"
    }
  ]
}

Custom Error Codes

Remove Entries from an Invoice

PUT /invoices/:id/remove_entries

Inputs

entry_ids
Required array of integers
the IDs of the entries to remove from this invoice. Any entries that are not associated with the invoice will be ignored and will not affect the Response.

Response

Status: 204 No Content

Custom Error Codes

Remove all Entries from an Invoice

PUT /invoices/:id/remove_all_entries

Response

Status: 204 No Content

Custom Error Codes

Add Expenses to an Invoice

PUT /invoices/:id/add_expenses

Inputs

expense_ids
Required array of integers
the IDs of the expenses to add to this invoice.

Response

Status: 204 No Content

A note about entries that cannot be added

If entries cannot be added to an invoice, the invoice will not be created and an itemized errors array will be returned.

Status: 400 Bad Request
{
  "message": "Entries could not be added",
  "errors": [
    {
      "resource": "Entry",
      "field": "entry_ids[1]",
      "code": "archived_project"
    }
  ]
}

Custom Error Codes

Remove Expenses from an Invoice

PUT /invoices/:id/remove_expenses

Inputs

expense_ids
Required array of integers
the IDs of the expenses to remove from this invoice. Any expenses that are not associated with this invoice will be ignored and will not affect the Response.

Response

Status: 204 No Content

Custom Error Codes

Remove all Expenses from an Invoice

PUT /invoices/:id/remove_all_expenses

Response

Status: 204 No Content

Custom Error Codes

Add Taxes to an Invoice

PUT /invoices/:id/add_taxes

Inputs

taxes
Required array of objects
the taxes to add to this invoice. The fields are:
percentage
Required decimal in percentage format (00.00)
the numeric percentage of the tax
name
Optional string
the name of the tax

Response

Status: 204 No Content

Custom Error Codes

Remove Taxes from an Invoice

PUT /invoices/:id/remove_taxes

Inputs

tax_ids
Required array of integers
the IDs of taxes to remove from this invoice. Any taxes that are not associated with this invoice will be ignored.

Response

Status: 204 No Content

Custom Error Codes

Remove all Taxes from an Invoice

PUT /invoices/:id/remove_all_taxes

Response

Status: 204 No Content

Custom Error Codes

Delete an Invoice

DELETE /invoices/:id

Response

Status: 204 No Content

A note about invoice deletion

When an invoice is deleted, the entries and expenses associated with that tag are marked as uninvoiced. An invoice cannot be deleted if it has been paid or is locked for payment.

Custom Error Codes