Noko Invoices

The NokoClient offers multiple methods to interact with invoices in Noko. On methods where keyword arguments are supported, parameter validation happens through Pydantic, allowing Python types other than what’s supported by the Noko API to be used when making requests, and providing a validation layer before the request is even made to the API.

class noko_client.client.NokoClient(access_token: str)

Simple Client for the Noko API.

Provide a friendlier interface to interact with the Noko API. Where Noko expects parameters to be passed in a specific way (for example, a list of strings for IDs, provide support for multiple types and handle formatting and validation.

This client does not currently support oAuth.

access_token

The Noko access token to authenticate the requests.

Type:

str

add_entries_to_invoice(invoice_id: int | str, entry_ids: list[int | str]) → None

Add time entries to an invoice.

Parameters:

  • invoice_id (int | str) – The ID of the invoice to add entries to.

  • entry_ids (list[int | str]) – A list of the IDs of the entries to add to the invoice.

Returns:

Doesn’t return anything, if unsuccessful, raises an exception.

Return type:

(None)

add_expenses_to_invoice(invoice_id: int | str, expense_ids: list[int | str]) → None

Add expenses to an invoice.

Parameters:

  • invoice_id (int | str) – The ID of the invoice to add expenses to.

  • expense_ids (list[int | str]) – A list of the IDs of the expenses to add to the invoice.

Returns:

Doesn’t return anything, if unsuccessful, raises an exception.

Return type:

(None)

add_taxes_to_invoice(invoice_id: int | str, taxes: list[dict]) → None

Add taxes to an invoice.

Parameters:

  • invoice_id (int | str) – The ID of the invoice to add taxes to.

  • taxes (list[dict]) – A list of taxes to add to the invoice. Each tax should be represented as a dictionary with, at least, a percentage key and, optionally, a name key.

Returns:

Doesn’t return anything, if unsuccessful, raises an exception.

Return type:

(None)

create_invoice(**kwargs) → list[dict]

Create a new invoice in Noko.

For additional information on options available for rate_calculation, taxes and customisation, refer to the Noko API documentation: https://developer.nokotime.com/v2/invoices/#create-an-invoice

Keyword Arguments:

  • invoice_date (str | datetime) – The date the invoice was issued. If provided as a string, must be provided in ISO 8601 format (YYYY-MM-DD).

  • reference (str | None) – The invoice’s reference identifier. If no value is provided, a value will be generated based on previous invoices as a default.

  • project_name (str | None) – The name of the project involved in this invoice. Defaults to None.

  • company_name (str | None) – The name of the company issuing the invoice. Defaults to None.

  • company_details (str | None) – The mailing address and any additional relevant information for the company issuing the invoice. Defaults to None.

  • recipient_details (str | None) – The mailing address and any additional relevant information for the recipient of the invoice. Defaults to None.

  • description (str | None) – A description of the invoice. Supports a limited version of Markdown. Noko documentation: https://help.nokotime.com/article/84-customizing-invoice-labels-and-formatting

  • footer (str | None) – The footer for each page of the invoice. Supports a limited version of Markdown. Noko documentation: https://help.nokotime.com/article/84-customizing-invoice-labels-and-formatting

  • show_hours_worked (bool | str) – Whether to show the hours worked when viewing the invoice. Defaults to True.

  • show_full_report (bool | str) – Whether to show the full report when viewing the invoice. Defaults to False.

  • show_user_summaries (bool | str) – Whether to show the total time in minutes worked by each team member. Defaults to False.

  • show_project_summaries (bool | str) – Whether to show the total time in minutes worked on each project. Defaults to False.

  • show_project_name_for_expenses (bool | str) – Whether to show the expense’s project name next to its description on the invoice. Defaults to False.

  • rate_calculation (dict | None) – How to calculate the total amount of hours worked to generate the invoice. Dictionary keys are: calculation_method (required), flat_rate (required if calculation_method is flat_rate), standard_hourly_rate (required if calculation_method is standard_hourly_rate or custom_hourly_rate), custom_hourly_rates (required if calculation_method is custom_hourly_rate). Defaults to None.

  • entry_ids (list | None) – List of entries to include in the invoice. Can be a list of strings or integers. Defaults to None.

  • expense_ids (list | None) – List of expenses to include in the invoice. Can be a list of strings or integers. Defaults to None.

  • taxes (list[dict] | None) – The taxes to apply to this invoice, as a list of dictionaries. Dictionary fields: percentage (required), name (optional)

  • customization (dict | None) – Dictionary of customization options that define the labels and localization settings for the invoice. Reference: https://developer.nokotime.com/v2/invoices/#create-an-invoice

Returns:

The created invoice as a dictionary.

Return type:

(list[dict])

delete_invoice(invoice_id: int | str) → None

Delete an invoice from Noko.

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

Parameters:

invoice_id (int | str) – The ID of the invoice to delete.

Returns:

Doesn’t return anything, if unsuccessful, raises an exception.

Return type:

(None)

edit_invoice(invoice_id: str | int, **kwargs) → list[dict]

Edit a Noko invoice.

Parameters:

invoice_id (str | int) – The ID of the invoice to edit.

Keyword Arguments:

  • invoice_date (str | datetime) – The date the invoice was issued. If provided as a string, must be provided in ISO 8601 format (YYYY-MM-DD).

  • reference (str | None) – The invoice’s reference identifier. If no value is provided, a value will be generated based on previous invoices as a default.

  • project_name (str | None) – The name of the project involved in this invoice. Defaults to None.

  • company_name (str | None) – The name of the company issuing the invoice. Defaults to None.

  • company_details (str | None) – The mailing address and any additional relevant information for the company issuing the invoice. Defaults to None.

  • recipient_details (str | None) – The mailing address and any additional relevant information for the recipient of the invoice. Defaults to None.

  • description (str | None) – A description of the invoice. Supports a limited version of Markdown. Noko documentation: https://help.nokotime.com/article/84-customizing-invoice-labels-and-formatting

  • footer (str | None) – The footer for each page of the invoice. Supports a limited version of Markdown. Noko documentation: https://help.nokotime.com/article/84-customizing-invoice-labels-and-formatting

  • show_hours_worked (bool | str) – Whether to show the hours worked when viewing the invoice. Defaults to True.

  • show_full_report (bool | str) – Whether to show the full report when viewing the invoice. Defaults to False.

  • show_user_summaries (bool | str) – Whether to show the total time in minutes worked by each team member. Defaults to False.

  • show_project_summaries (bool | str) – Whether to show the total time in minutes worked on each project. Defaults to False.

  • show_project_name_for_expenses (bool | str) – Whether to show the expense’s project name next to its description on the invoice. Defaults to False.

  • rate_calculation (dict | None) – How to calculate the total amount of hours worked to generate the invoice. Dictionary keys are: calculation_method (required), flat_rate (required if calculation_method is flat_rate), standard_hourly_rate (required if calculation_method is standard_hourly_rate or custom_hourly_rate), custom_hourly_rates (required if calculation_method is custom_hourly_rate). Defaults to None.

  • entry_ids (list | None) – List of entries to include in the invoice. Can be a list of strings or integers. Defaults to None.

  • expense_ids (list | None) – List of expenses to include in the invoice. Can be a list of strings or integers. Defaults to None.

  • taxes (list[dict] | None) – The taxes to apply to this invoice, as a list of dictionaries. Dictionary fields: percentage (required), name (optional)

  • customization (dict | None) – Dictionary of customization options that define the labels and localization settings for the invoice. Reference: https://developer.nokotime.com/v2/invoices/#create-an-invoice

Returns:

The edited invoice as a dictionary.

Return type:

(list[dict])

get_invoice_entries(invoice_id: str | int, **kwargs) → list[dict]

Retrieve all time entries associated with an invoice.

Results can be filtered using the same keyword arguments as the ones used for the list entries endpoint. All keyword arguments are optional.

Parameters:

invoice_id (str | int) – The ID of the invoice to retrieve entries for.

Keyword Arguments:

  • user_ids (str | list | None) – IDs of users to filter. If provided as a string, must be comma separated. If provided as a list, can be provided as a list of integers or strings. Defaults to None.

  • description (str | None) – Only descriptions containing the provided text will be returned. Defaults to None.

  • project_ids (str | list | None) – IDs of projects to filter for. If provided as a string, must be comma separated. If provided as a list, can be provided as a list of integers or strings. Defaults to None.

  • tag_ids (str | list | None) – IDs of users to filter for. If provided as a string, must be comma separated. If provided as a list, can be provided as a list of integers or strings. Defaults to None.

  • tag_filter_type (str | None) – The type of filter to apply if filtering for tag_ids. Defaults to None.

  • from (str | datetime | None) – The date from which to search. Only entries logged on this day onwards will be returned. If provided as string, must be in ISO 8601 format (YYYY-MM-DD).

  • to (str | datetime | None) – The date up to which to search. Only entries logged up to this day will be returned. If provided as string, must be in ISO 8601 format (YYYY-MM-DD).

  • invoiced (bool | str | None) – Whether to filter for invoiced or uninvoiced entries. If provided as string, must be lower case. Defaults to None.

  • updated_from (str | datetime | None) – Only entries with updates from this timestamp onwards are returned. If provided as string, must be in ISO 8601 format (YYYY-MM-DDTHH:MM:SSZ). Defaults to None.

  • updated_to (str | datetime | None) – Only entries with updates up to this timestamp are returned. If provided as string, must be in ISO 8601 format (YYYY-MM-DDTHH:MM:SSZ). Defaults to None.

  • billable (bool | str | None) – Whether to filter for billable or unbillable entries. If provided as string, must be lower case. Defaults to None.

  • approved_at_from (str | datetime | None) – Only entries with approvals from this date on will be returned. If provided as string, must be in ISO 8601 format (YYYY-MM-DD). Defaults to None.

  • approved_at_to (str | datetime | None) – Only entries with approvals up to this date will be returned. If provided as string, must be in ISO 8601 format (YYYY-MM-DD). Defaults to None.

Returns:

A list of all retrieved entries meeting the specified criteria.

Return type:

(list[dict])

get_invoice_expenses(invoice_id: str | int, **kwargs) → list[dict]

Retrieve all expenses associated with an invoice.

Results can be filtered using the same keyword arguments as the ones used for the list expenses endpoint. All keyword arguments are optional.

Parameters:

invoice_id (str | int) – The ID of the invoice to retrieve expenses for.

Keyword Arguments:

  • user_ids (str | list | None) – The IDs of the users to filter expenses by. If provided as string, must be a comma separated string. Defaults to None.

  • description (str | None) – Only expenses containing this text in their description are returned.

  • project_ids (str | list | None) – The IDs of the projects to filter expenses by. If provided as string, must be a comma separated string. Defaults to None.

  • invoice_ids (str | list | None) – The IDs of the invoices to filter expenses by. If provided as string, must be a comma separated string. Defaults to None.

  • from (str | datetime | None) – Only expenses from or after this date will be returned. If provided as string, must be in ISO 8601 format (YYY-MM-DD). Defaults to None.

  • to (str | datetime | None) – Only expenses on or before this date will be returned. If provided as string, must be in ISO 8601 format (YYY-MM-DD). Defaults to None.

  • price_from (int | float | None) – Only expenses with a price grater than or equal to this will be returned. Defaults to None.

  • price_to (int | float | None) – Only expenses with a price less than or equal to this will be returned. Defaults to None.

  • taxable (bool | str | None) – Return only expenses where taxes are applied or not applied. Defaults to both.

  • invoiced (bool | str | None) – Return only invoiced or uninvoiced expenses. Defaults to both.

Returns:

A list of all retrieved expenses meeting the specified criteria.

Return type:

(list[dict])

get_single_invoice(invoice_id: str | int) → list[dict]

Retrieve a single invoice from Noko.

Parameters:

invoice_id (str | int) – The ID of the invoice to retrieve.

Returns:

The invoice retrieved as a dictionary.

Return type:

(list[dict])

list_invoices(**kwargs) → list[dict]

List Noko invoices.

Keyword Arguments:

  • state (str | None) – Only invoices in this state will be returned. Defaults to None. Accepted Values are: unpaid, awaiting_payment, in_progress, paid, none

  • reference (str | None) – Only invoices with this text in their invoice reference will be returned. Defaults to None.

  • invoice_date_from (str | datetime | None) – Only invoices dated from this day forward will be returned. If provided as string, must be in ISO 8061 format (YYYY-MM-DD). Defaults to None.

  • invoice_date_to (str | datetime | None) – Only invoices dated up to this day will be returned. If provided as string, must be in ISO 8061 format (YYYY-MM-DD). Defaults to None.

  • project_name (str | None) – Only invoices containing this text in their project_name field will be returned. Defaults to None.

  • total_amount_from (int | float | None) – Only invoices with a total amount due greater than or equal to this will be returned. Defaults to None.

  • total_amount_to (int | float | None) – Only invoices with a total amount due less than or equal to this will be returned. Defaults to None.

  • recipient_details (str | None) – Only invoices containing this text in their recipient_details field will be returned. Defaults to None.

  • project_ids (str | list[int | str] | None) – Only invoices containing these projects will be returned. If provided as a string, must be a comma separated string. Defaults to None.

  • company_name (str | None) – Only invoices containing this text in their company_name field are returned. Defaults to None.

  • company_details (str | None) – Only invoices containing this text in their company_details field are returned. Defaults to None.

  • description (str | None) – Only invoices containing this text in their description field are returned. Defaults to None.

  • footer (str | None) – Only invoices containing this text in their footer field are returned. Defaults to None.

  • has_online_payment_details (str | bool | None) – Whether to only return invoices that have or don’t have online payment details. Defaults to None.

  • has_custom_html (str | bool | None) – Whether to only return invoices that include or don’t include custom HTML. Defaults to None.

  • show_hours_worked (str | bool | None) – Whether to only return invoices that show or don’t show hours worked. Defaults to None.

  • show_full_report (str | bool | None) – Whether to only return invoices that show or don’t show the full report for the invoice. Defaults to None.

  • show_user_summaries (str | bool | None) – Whether to only return invoices that show or don’t show the summary of hours worked for each team member. Defaults to None.

  • show_project_summaries (str | bool | None) – Whether to only return invoices that show or don’t show the summary of hours worked for each project. Defaults to None.

  • show_project_name_for_expenses (str | bool | None) – Whether to only return invoices that show or don’t show the expense’s project name next to the expense description. Defaults to None.

  • locale (str | None) – Only invoices using the specified locally are returned. Accepted values are any of the locale codes supported by Noko. Defaults to None.

  • currency_code (str | None) – Only invoices using this currency are returned. Accepted values are any of the ISO currency codes support by Noko. Defaults to None.

  • currency_symbol (str | None) – Only invoices with this text as part of their currency_symbol are returned. Defaults to None.

  • rate_calculation (str | None) – Only invoices with the rate for the hours calculated in this manner are returned. Defaults to None. Accepted values: custom_hourly_rates, standard_hourly_rate, flat_rate

  • updated_from (str | datetime | None) – Only invoices updated from or after this timestamp will be returned. Defaults to None.

  • updated_to (str | datetime | None) – Only invoices updated on or before this timestamp will be returned. Defaults to None.

Noko Invoice Locales: https://developer.nokotime.com/invoice_locales/#locales

Returns:

All invoices matching the criteria as a list of dictionaries.

Return type:

(list[dict])

mark_invoice_as_paid(invoice_id: str | int) → None

Mark an invoice as paid.

Parameters:

invoice_id (str | int) – The ID of the invoice to mark as paid.

Returns:

Doesn’t return anything, if unsuccessful, raises an exception.

Return type:

(None)

mark_invoice_as_unpaid(invoice_id: str | int) → None

Mark an invoice as unpaid.

Parameters:

invoice_id (str | int) – The ID of the invoice to mark as unpaid.

Returns:

Doesn’t return anything, if unsuccessful, raises an exception.

Return type:

(None)

remove_all_entries_from_invoice(invoice_id: int | str) → None

Remove all time entries from an invoice.

Parameters:

invoice_id (int | str) – The ID of the invoice to remove all entries from.

Returns:

Doesn’t return anything, if unsuccessful, raises an exception.

Return type:

(None)

remove_all_expenses_from_invoice(invoice_id: int | str) → None

Remove all expenses from an invoice.

Parameters:

invoice_id (int | str) – The ID of the invoice to remove all expenses from.

Returns:

Doesn’t return anything, if unsuccessful, raises an exception.

Return type:

(None)

remove_all_taxes_from_invoice(invoice_id: int | str) → None

Remove all taxes from an invoice.

Parameters:

invoice_id (int | str) – The ID of the invoice to remove all taxes from.

Returns:

Doesn’t return anything, if unsuccessful, raises an exception.

Return type:

(None)

remove_entries_from_invoice(invoice_id: int | str, entry_ids: list[int | str]) → None

Remove time entries from an invoice.

Parameters:

  • invoice_id (int | str) – The ID of the invoice to remove entries from.

  • entry_ids (list[int | str]) – A list of the IDs of the entries to remove from the invoice. Any entries not associated with the invoice will be ignored and will not affect the response.

Returns:

Doesn’t return anything, if unsuccessful, raises an exception.

Return type:

(None)

remove_expenses_from_invoice(invoice_id: int | str, expense_ids: list[int | str]) → None

Remove expenses from an invoice.

Parameters:

  • invoice_id (int | str) – The ID of the invoice to remove expenses from.

  • expense_ids (list[int | str]) – A list of the IDs of the expenses to remove from the invoice. Any expenses not associated with the invoice will be ignored and will not affect the response.

Returns:

Doesn’t return anything, if unsuccessful, raises an exception.

Return type:

(None)

remove_taxes_from_invoice(invoice_id: int | str, tax_ids: list[str | int]) → None

Remove taxes from an invoice.

Parameters:

  • invoice_id (int | str) – The ID of the invoice to remove taxes from.

  • tax_ids (list[str | int]) – The IDs of the taxes to remove from the invoice. Any taxes that are not associated with the invoice will be ignored and will not affect the response.

Returns:

Doesn’t return anything, if unsuccessful, raises an exception.

Return type:

(None)