Kantata Kantata OX Knowledge Base
Release Notes
Kantata OX Release Notes API Breaking Changes
Status Page
Kantata OX API Documentation

Invoices

Users can create Invoices in a Kantata OX project. An Invoice must have at least one line item (a time entry, expense, fixed fee item, or additional item). By default, the recipient of an invoice is the primary client in the project. Manual formatting options are available to define the format and information that should be displayed on an invoice.

Invoices can only be created and viewed by participants with financial permission in a project.

Fetching a list of Invoices

This endpoint returns structured Invoice objects. As with all Kantata OX API endpoints, the returned data will be referenced in sorted order in the results array and will be indexed by ID in the invoices top-level JSON key. Please see our Response Format section for more information.

Request
query Parameters
created_after
string <date-time>

Filter for records created after a specified datetime. The datetime must be in ISO 8601 format.

created_before
string <date-time>

Filter for records created before a specified datetime. The datetime must be in ISO 8601 format.

external_reference_external_message
string

Filter the objects based on the external message of their associated external references. This is an exact match.

external_reference_external_status
string

Filter by the status of the external object in the external system.

external_reference_service_model
string

Filter by the type of the external object this external reference belongs to.

external_reference_service_model_ref
integer <int32>

Filter by the id of the external object this external reference belongs to.

external_reference_service_model_refs
string

Filter for objects that correlate to the specified external object IDs. Provide a comma-separated list of up to 200 external IDs.

external_reference_service_name
string

Filter by the name of the provider for integration.

external_reference_status
string

Filter by the status of the integration, this can be successful or fail.

has_external_references
boolean

Filter by whether or not the object has external references.

include
string

Any of the below associations can be included in your request by providing the include param, e.g. include=association1,association2.

  • additional_items (AdditionalItem) - When included, the additional_item_ids array will reference all additional items included in the invoice.
  • expenses (Expense) - When included, the expense_ids array will reference all expenses included in the invoice.
  • external_references (ExternalReference) - Includes references to external integrations for this object.
  • fixed_fee_items (FixedFeeItem) - When included, the fixed_fee_items array will reference all fixed fee items included in the invoice.
  • recipient (User) - The User who received the invoice. Namely, the client lead at the time that the invoice was created (or null, if no lead client existed at the time).
  • time_entries (TimeEntry) - When included, the time_entry_ids array will reference all time entries included in the invoice.
  • user (User) - The user who created the invoice.
  • workspaces (Workspace) - When included, the workspace_ids array will reference all projects covered by the invoice.
only
string

Allows you to request one or more resources directly by ID. Multiple IDs can be supplied in a comma separated list, like GET /api/v1/workspaces.json?only=5,6,7.

order
string
Default: "created_at:desc"

Supply order with the name of a valid sort field for the endpoint and a direction.

Valid values: created_at:asc, created_at:desc, id:asc, id:desc, invoice_date:asc, invoice_date:desc, updated_at:asc, and updated_at:desc.

page
integer <int32>
Default: 1
paid
boolean
Default: false

When true is passed, only paid invoices are returned.

pending
boolean
Default: false

When true is passed, only non-accepted, non-draft invoices are returned.

per_page
integer <int32> <= 200
Default: 20
updated_after
string <date-time>

Filter for records updated after a specified datetime. The datetime must be in ISO 8601 format.

updated_before
string <date-time>

Filter for records updated before a specified datetime. The datetime must be in ISO 8601 format.

user_invoice_number
string

Provide one or more user invoice numbers, separated by commas. When provided, only invoices with the specified user invoice numbers will be returned.

within_dates
string

Provide a date range in 2000-01-01:2000-12-31 format. When provided, only invoices created within the specified range will be returned.

without_drafts
boolean
Default: false

When true is passed, draft invoices will not be returned.

without_external_reference_service_name
string

Exclude by the existence of an external reference with the specified service name.

workspace_id
string

Provide one or more workspace IDs, separated by commas. If present, only invoices in the provided projects will be returned.

Responses
200

A list of Invoices have been retrieved.

Response Schema: application/json
count
integer <int32>
object
Array of objects
object
object
object
object
object
object
object
object
400

Bad Request

401

Unauthorized request

403

Forbidden request

404

Page Not Found

422

Unprocessable Entity

503

Service is unavailable

get/invoices
Request samples 
Response samples 
application/json
{
  • "count": 0,
  • "meta": {
    },
  • "results": [
    ],
  • "invoices": {
    },
  • "external_references": {
    },
  • "users": {
    },
  • "workspaces": {
    },
  • "additional_items": {
    },
  • "time_entries": {
    },
  • "expenses": {
    },
  • "fixed_fee_items": {
    }
}
Creating a new Invoice
This endpoint returns structured Invoice objects.
As with all Kantata OX API endpoints, the returned data will be referenced in sorted order in the results array
and will be indexed by ID in the invoices top-level JSON key.
Please see our Response Format section for more information.


Request 
query Parameters
include
string
Any of the below associations can be included in your request by providing the include param, e.g. include=association1,association2.


    

  • additional_items (AdditionalItem) - When included, the additional_item_ids array will reference all additional items included in the invoice.
    • 

  • expenses (Expense) - When included, the expense_ids array will reference all expenses included in the invoice.
    • 

  • external_references (ExternalReference) - Includes references to external integrations for this object.
    • 

  • fixed_fee_items (FixedFeeItem) - When included, the fixed_fee_items array will reference all fixed fee items included in the invoice.
    • 

  • recipient (User) - The User who received the invoice. Namely, the client lead at the time that the invoice
was created (or null, if no lead client existed at the time).
    • 

  • time_entries (TimeEntry) - When included, the time_entry_ids array will reference all time entries included in the invoice.
    • 

  • user (User) - The user who created the invoice.
    • 

  • workspaces (Workspace) - When included, the workspace_ids array will reference all projects covered by the invoice.
    • 



 
Request Body schema: application/json
required
object
 
time_entry_ids
required
Array of integers <int32> 
Time Entry IDs. (At least one of the following is required: time_entry_ids, expense_ids, additional_items, or fixed_fee_items).


 
expense_ids
required
Array of integers <int32> 
Expense IDs. (At least one of the following is required: time_entry_ids, expense_ids, additional_items, or fixed_fee_items).


 
required
Array of objects
Fixed fee item objects to create (At least one of the following is required: time_entry_ids, expense_ids, additional_items, or fixed_fee_items).


 
required
Array of objects
Additional item objects to create (At least one of the following is required: time_entry_ids, expense_ids, additional_items, or fixed_fee_items).


 
workspace_id
required
integer <int32> 
The ID of the Workspace in which to create the invoice.


 
workspace_ids
Array of integers <int32> 
The IDs of the Workspaces in which to create the (multi-project) invoice.


 
payment_schedule
required
integer <int32> 
The number of days within which the total amount of the invoice is expected to be paid. For example, use 30 for a Net 30 payment schedule. See https://en.wikipedia.org/wiki/Net_D.


 
invoice_date
string <date> 
The invoice date. The date must be in ISO 8601 format.


 
user_invoice_number
integer <int32> 
The invoice number (defined by the user).


 
draft
boolean
Whether the invoice is a draft.


 
message
string
Notes to be displayed on the invoice.


 
user_invoice_title
string
The invoice title (defined by the user).


 
purchase_order
string
The invoice purchase order (defined by the user).


 
project_code
string
The invoice project code (defined by the user).


 
suppress_emails
boolean
Setting suppress_emails to true will prevent creation emails from being sent.


 
object
Typically populated programmatically by a third party system via an integration, this is an optional
object that holds data from an external system. It connects objects in an external system with objects in
Kantata OX (for example, to connect a Jira issue to a Kantata OX Project).


 
Responses 
200
Invoice has been created.


Response Schema: application/json
count
integer <int32> 
 
object
 
Array of objects
 
object
 
object
 
object
 
object
 
object
 
object
 
object
 
object
 
400
Bad Request


401
Unauthorized request


403
Forbidden request


404
Page Not Found


422
Unprocessable Entity


503
Service is unavailable


post/invoices
Request samples 
application/json
{
  • "invoice": {
    }
}
Response samples 
application/json
{
  • "count": 0,
  • "meta": {
    },
  • "results": [
    ],
  • "invoices": {
    },
  • "external_references": {
    },
  • "users": {
    },
  • "workspaces": {
    },
  • "additional_items": {
    },
  • "time_entries": {
    },
  • "expenses": {
    },
  • "fixed_fee_items": {
    }
}
Retrieve the next available invoice number.
Responses 
200
A list of objects have been retrieved.


Response Schema: application/json
next_invoice_number
string
The next invoice number.


 
400
Bad Request


401
Unauthorized request


403
Forbidden request


404
Page Not Found


422
Unprocessable Entity


503
Service is unavailable


get/invoices/next_invoice_number
Request samples 
Response samples 
application/json
{
  • "next_invoice_number": "string"
}
Fetching a single Invoice
This endpoint returns structured Invoice objects.
As with all Kantata OX API endpoints, the returned data will be referenced in sorted order in the results array
and will be indexed by ID in the invoices top-level JSON key.
Please see our Response Format section for more information.


Request 
path Parameters
id
required
integer
The ID of the Model.


 
query Parameters
include
string
Any of the below associations can be included in your request by providing the include param, e.g. include=association1,association2.


    

  • additional_items (AdditionalItem) - When included, the additional_item_ids array will reference all additional items included in the invoice.
    • 

  • expenses (Expense) - When included, the expense_ids array will reference all expenses included in the invoice.
    • 

  • external_references (ExternalReference) - Includes references to external integrations for this object.
    • 

  • fixed_fee_items (FixedFeeItem) - When included, the fixed_fee_items array will reference all fixed fee items included in the invoice.
    • 

  • recipient (User) - The User who received the invoice. Namely, the client lead at the time that the invoice
was created (or null, if no lead client existed at the time).
    • 

  • time_entries (TimeEntry) - When included, the time_entry_ids array will reference all time entries included in the invoice.
    • 

  • user (User) - The user who created the invoice.
    • 

  • workspaces (Workspace) - When included, the workspace_ids array will reference all projects covered by the invoice.
    • 



 
Responses 
200
The Invoice has been retrieved.


Response Schema: application/json
count
integer <int32> 
 
object
 
Array of objects
 
object
 
object
 
object
 
object
 
object
 
object
 
object
 
object
 
400
Bad Request


401
Unauthorized request


403
Forbidden request


404
Page Not Found


422
Unprocessable Entity


503
Service is unavailable


get/invoices/{id}
Request samples 
Response samples 
application/json
{
  • "count": 0,
  • "meta": {
    },
  • "results": [
    ],
  • "invoices": {
    },
  • "external_references": {
    },
  • "users": {
    },
  • "workspaces": {
    },
  • "additional_items": {
    },
  • "time_entries": {
    },
  • "expenses": {
    },
  • "fixed_fee_items": {
    }
}
Updating an existing Invoice
This endpoint returns structured Invoice objects.
As with all Kantata OX API endpoints, the returned data will be referenced in sorted order in the results array
and will be indexed by ID in the invoices top-level JSON key.
Please see our Response Format section for more information.


Request 
path Parameters
id
required
integer
The ID of the Model.


 
query Parameters
include
string
Any of the below associations can be included in your request by providing the include param, e.g. include=association1,association2.


    

  • additional_items (AdditionalItem) - When included, the additional_item_ids array will reference all additional items included in the invoice.
    • 

  • expenses (Expense) - When included, the expense_ids array will reference all expenses included in the invoice.
    • 

  • external_references (ExternalReference) - Includes references to external integrations for this object.
    • 

  • fixed_fee_items (FixedFeeItem) - When included, the fixed_fee_items array will reference all fixed fee items included in the invoice.
    • 

  • recipient (User) - The User who received the invoice. Namely, the client lead at the time that the invoice
was created (or null, if no lead client existed at the time).
    • 

  • time_entries (TimeEntry) - When included, the time_entry_ids array will reference all time entries included in the invoice.
    • 

  • user (User) - The user who created the invoice.
    • 

  • workspaces (Workspace) - When included, the workspace_ids array will reference all projects covered by the invoice.
    • 



 
Request Body schema: application/json
required
object
 
time_entry_ids
Array of integers <int32> 
An array of Time Entry IDs. Setting this field updates the invoice's complete list of time entries; it behaves as an overwrite. Any time entries not included in your request will be removed from the invoice. Additionally, sending an empty array will remove all time entries from the invoice. At least one time entry, expense, fixed fee item, or additional item must be on the invoice.


 
expense_ids
Array of integers <int32> 
An array of Expense IDs. Setting this field updates the invoice's complete list of expenses; it behaves as an overwrite. Any expenses not included in your request will be removed from the invoice. Additionally, sending an empty array will remove all expenses from the invoice. At least one time entry, expense, fixed fee item, or additional item must be on the invoice.


 
payment_schedule
integer <int32> 
The number of days within which the total amount of the invoice is expected to be paid. For example, use 30 for a Net 30 payment schedule. See https://en.wikipedia.org/wiki/Net_D.


 
invoice_date
string <date> 
The invoice date.  Determines the date from which the payment schedule will start. The date must be in ISO 8601 format.


 
user_invoice_number
integer <int32> 
The invoice number (defined by the user).


 
draft
boolean
Whether the invoice is a draft.


 
message
string
Notes to be displayed on the invoice.


 
user_invoice_title
string
The invoice title (defined by the user).


 
purchase_order
string
The invoice purchase order (defined by the user).


 
project_code
string
The invoice project code (defined by the user).


 
object
Typically populated programmatically by a third party system via an integration, this is an optional
object that holds data from an external system. It connects objects in an external system with objects in
Kantata OX (for example, to connect a Jira issue to a Kantata OX Project).


 
Responses 
200
Invoice has been updated.


Response Schema: application/json
count
integer <int32> 
 
object
 
Array of objects
 
object
 
object
 
object
 
object
 
object
 
object
 
object
 
object
 
400
Bad Request


401
Unauthorized request


403
Forbidden request


404
Page Not Found


422
Unprocessable Entity


503
Service is unavailable


put/invoices/{id}
Request samples 
application/json
{
  • "invoice": {
    }
}
Response samples 
application/json
{
  • "count": 0,
  • "meta": {
    },
  • "results": [
    ],
  • "invoices": {
    },
  • "external_references": {
    },
  • "users": {
    },
  • "workspaces": {
    },
  • "additional_items": {
    },
  • "time_entries": {
    },
  • "expenses": {
    },
  • "fixed_fee_items": {
    }
}
Deleting an existing Invoice
You can delete draft invoices with this endpoint. Active invoices cannot be
deleted. They must be cancelled instead.


The response will contain no content and an HTTP 204 status code if the request was
successful, or a standard Kantata OX error message explaining why the object could not be deleted.


Request 
path Parameters
id
required
integer
The ID of the Model.


 
Responses 
204
Invoice has been deleted.


400
Bad Request


401
Unauthorized request


403
Forbidden request


404
Page Not Found


422
Unprocessable Entity


503
Service is unavailable


delete/invoices/{id}
Request samples 
Response samples 
application/json
{
  • "errors": [
    ]
}
Cancel an existing invoice.
You can cancel active invoices with this endpoint.


This endpoint returns structured Invoice objects.
As with all Kantata OX API endpoints, the returned data will be referenced in sorted order in the results array
and will be indexed by ID in the invoices top-level JSON key.
Please see our Response Format section for more information.


Request 
path Parameters
id
required
integer
The ID of the Model.


 
query Parameters
include
string
Any of the below associations can be included in your request by providing the include param, e.g. include=association1,association2.


    

  • additional_items (AdditionalItem) - When included, the additional_item_ids array will reference all additional items included in the invoice.
    • 

  • expenses (Expense) - When included, the expense_ids array will reference all expenses included in the invoice.
    • 

  • external_references (ExternalReference) - Includes references to external integrations for this object.
    • 

  • fixed_fee_items (FixedFeeItem) - When included, the fixed_fee_items array will reference all fixed fee items included in the invoice.
    • 

  • recipient (User) - The User who received the invoice. Namely, the client lead at the time that the invoice
was created (or null, if no lead client existed at the time).
    • 

  • time_entries (TimeEntry) - When included, the time_entry_ids array will reference all time entries included in the invoice.
    • 

  • user (User) - The user who created the invoice.
    • 

  • workspaces (Workspace) - When included, the workspace_ids array will reference all projects covered by the invoice.
    • 



 
Responses 
200
Invoice has been updated.


Response Schema: application/json
count
integer <int32> 
 
object
 
Array of objects
 
object
 
object
 
object
 
object
 
object
 
object
 
object
 
object
 
400
Bad Request


401
Unauthorized request


403
Forbidden request


404
Page Not Found


422
Unprocessable Entity


503
Service is unavailable


put/invoices/{id}/cancel
Request samples 
Response samples 
application/json
{
  • "count": 0,
  • "meta": {
    },
  • "results": [
    ],
  • "invoices": {
    },
  • "external_references": {
    },
  • "users": {
    },
  • "workspaces": {
    },
  • "additional_items": {
    },
  • "time_entries": {
    },
  • "expenses": {
    },
  • "fixed_fee_items": {
    }
}
➔ Next to Workspace Invoice Preferences