API docs by Redocly

Invoice Ninja API Reference. (5.12.55)

Download OpenAPI specification:

Invoice Ninja Support: [email protected] URL: https://www.invoiceninja.com License: Elastic License Terms of Service

Invoice Ninja

Client Libraries

Introduction

Welcome to the Invoice Ninja API documentation, your comprehensive guide to integrating Invoice Ninja's powerful features into your applications. Whether you're building a custom client, automating workflows, or integrating with other systems, our API provides the tools you need to streamline your invoicing and billing processes.

What is Invoice Ninja?

Invoice Ninja is a robust source-available platform designed to simplify invoicing, billing, and payment management for freelancers, small businesses, and enterprises alike. With a user-friendly interface, customizable templates, and a suite of powerful features, Invoice Ninja empowers businesses to create professional invoices, track expenses, manage clients, and get paid faster.

Client Libraries

PHP SDK can be found here Go SDK can be found here

Why use the Invoice Ninja API?

The Invoice Ninja API allows developers to extend the functionality of Invoice Ninja by programmatically accessing and manipulating data within their Invoice Ninja accounts. With the API, you can automate repetitive tasks, integrate with third-party services, and build custom solutions tailored to your specific business needs.

Getting Started

To get started with the Invoice Ninja API, you'll need an active Invoice Ninja account (or your own self hosted installation) and API credentials. If you haven't already done so, sign up for an account at Invoice Ninja and generate your API keys from the settings section.

Once you have your API credentials, you can start exploring the API endpoints, authentication methods, request and response formats, and more using the documentation provided here.

Explore the Documentation

This documentation is organized into sections to help you navigate and understand the various aspects of the Invoice Ninja API:

  • Authentication: Learn how to authenticate your requests to the API using API tokens.
  • Endpoints: Explore the available API endpoints for managing invoices, clients, payments, expenses, and more.
  • Request and Response Formats: Understand the structure of API requests and responses, including parameters, headers, and payloads.
  • Error Handling: Learn about error codes, status messages, and best practices for handling errors gracefully.
  • Code Examples: Find code examples and tutorials to help you get started with integrating the Invoice Ninja API into your applications.

Need Help?

If you have any questions, encounter any issues, or need assistance with using the Invoice Ninja API, don't hesitate to reach out to our support team or join our community forums. We're here to help you succeed with Invoice Ninja and make the most of our API.

Let's start building together!

Endpoints

Production: https://invoicing.co

Demo: https://demo.invoiceninja.com

Client Libraries

PHP SDK can be found here Go SDK can be found here

Authentication:

Invoice Ninja uses API tokens to authenticate requests. You can view and manage your API keys in Settings > Account Management > Integrations > API tokens

API requests must be made over HTTPS. Calls made to HTTP will fail.

Errors:

Invoice Ninja uses standard HTTP response codes to indicate the success or failure of a request. below is a table of standard status codes and responses

Status Code Explanation
200 OK: The request has succeeded. The information returned with the response is dependent on the method used in the request.
301 Moved Permanently: This and all future requests should be directed to the given URI.
303 See Other: The response to the request can be found under another URI using the GET method.
400 Bad Request: The server cannot or will not process the request due to an apparent client error.
401 Unauthorized: Similar to 403 Forbidden, but specifically for use when authentication is required and has failed or has not yet been provided.
403 Forbidden: The request was valid, but the server is refusing action.
404 Not Found: The requested resource could not be found but may be available in the future.
405 Method Not Allowed: A request method is not supported for the requested resource.
409 Conflict: Indicates that the request could not be processed because of conflict in the request.
422 Unprocessable Entity: The request was well-formed but was unable to be followed due to semantic errors.
429 Too Many Requests: The user has sent too many requests in a given amount of time ("rate limiting").
500 Internal Server Error: A generic error message, given when an unexpected condition was encountered and no more specific message is suitable.

Pagination

When using index routes to retrieve lists of data, by default we limit the number of records returned to 20. You can using standard pagination to paginate results, ie: ?per_page=50

Authentication

Attempts to authenticate with the API using a email/password combination.

After authenticating with the API, the returned object is a CompanyUser object which is a bridge linking the user to the company.

The company user object contains the users permissions (admin/owner or fine grained permissions) You will most likely want to also include in the response of this object both the company and the user object, this can be done by using the include parameter.

/api/v1/login?include=company,user

Login

Authorizations:
ApiKeyAuth
query Parameters
include
string
Examples:
  • include=user - include=user will include the Cser object in the response
  • include=company - include=company will include the Company object in the response
  • include=token - include=token will include the Company Token object in the response
  • include=account - include=account will include the Account object in the response

Include child relations of the CompanyUser object, format is comma separated.


Note: it is possible to chain multiple includes together, ie. include=account,token



Available includes:

  user
  company
  token
  account
include_static
string
Example: include_static=include_static=true

This include will return the full set of static variables used in the application including:

  • Currencies
  • Countries
  • Languages
  • Payment Types
  • Email Templatees
  • Industries
clear_cache
string
Example: clear_cache=clear_cache=true

Clears cache

Clears (and rebuilds) the static variable cache.

header Parameters
X-API-SECRET
string
Example: password

The API secret as defined by the .env variable API_SECRET. Only needed for self hosted users, and only applicable on the login route.

X-API-TOKEN
required
string
Example: TOKEN

The API token to be used for authentication

X-Requested-With
required
string
Example: XMLHttpRequest

Used to send the XMLHttpRequest header

Request Body schema: application/json
required

User credentials

{
  "email" : "[email protected]",
  "password" : "magicpassword123",
  "one_time_password" : "12345",
}
email
required
string

The users email address.

password
required
string

The user password. Must meet minimum criteria ~ > 6 characters

one_time_password
string

The one time password if 2FA is enabled

Responses

Request samples

Content type
application/json
{}

Response samples

Content type
application/json
{
  • "permissions": "create_invoice,create_client,view_client",
  • "settings": { },
  • "react_settings": { },
  • "is_owner": true,
  • "is_admin": true,
  • "is_locked": true,
  • "updated_at": 1231232312321,
  • "deleted_at": 12312312321,
  • "account": {
    },
  • "company": {
    },
  • "user": {
    },
  • "token": {
    }
}

Clients

The Clients API provides endpoints for managing client records within your company. A client represents a customer or business entity that you provide services or products to.

Key Features

  • Create, read, update, and delete client records
  • Manage client contact information and billing details
  • View client-specific transaction history
  • Handle multiple contacts per client
  • Track client-specific settings and preferences

Client Statuses

  • Active: Client is currently active and can be billed
  • Archived: Client is archived and hidden from active lists
  • Deleted: Client is marked for deletion but retained in the database

Best Practices

  • Always validate client email addresses
  • Use unique client numbers for easy reference
  • Keep contact information up to date
  • Set appropriate client-specific currency and tax settings

List clients

GET /api/v1/clients

When retrieving a list of clients you can also chain query parameters in order to filter the dataset that is returned. For example, you can send a request to the following URL to retrieve clients that have a balance greater than 1000

/api/v1/clients?balance=gt:1000

You can also sort the results by adding a sort parameter. The following example will sort the results by the client name in descending order

/api/v1/clients?sort=name|desc

You can also combine multiple filters together. The following example will return clients that have a balance greater than 1000 and are not deleted and have a name that starts with "Bob"

/api/v1/clients?balance=gt:1000&name=Bob*

If you wish to retrieve child relations, you can also combine the query parameter ?include= with a comma separated list of relationships

/api/v1/clients?include=activities,ledger,system_logs'

The per_page and page variables allow pagination of the list of clients. The following example will return the second page of clients with 15 clients per page

/api/v1/clients?per_page=15&page=2

The default per_page value is 20.

Authorizations:
ApiKeyAuth
query Parameters
include
string
Examples:
  • include=activities - include=activities will include the activities object in the response
  • include=ledger - include=ledger will include the ledger object in the response
  • include=system_logs - include=system_logs will include the system_logs object in the response

Include child relationships of the Client Object. ie ?include=documents,system_logs

Available includes:

contacts [All contacts related to the client]
documents [All documents related to the client]
gateway_tokens [All payment tokens related to the client]
activities [All activities related to the client]
ledger [The client ledger]
system_logs [System logs related to the client]
group_settings [The group settings object the client is assigned to]

Usage:

/api/v1/clients?include=contacts,documents,activities
index
string
Example: index=user

Replaces the default response index from data to a user specific string

ie.

  ?index=new_index

response is wrapped

  {
    'new_index' : [
      .....  
    ]
  }
per_page
integer
Example: per_page=20

The number of records to return for each request, default is 20

page
integer
Example: page=1

The page number to return for this request (when performing pagination), default is 1

status
string
Example: status=?status=archived,deleted

Filter the entity based on their status. ie active / archived / deleted. Format is a comma separated string with any of the following options:

  • active
  • archived
  • deleted
GET /api/v1/invoices?status=archived,deleted
Returns only archived and deleted invoices
created_at
integer
Example: created_at=1641772800

Filters the entity list by the created at timestamp. Parameter value can be a datetime string or unix timestamp

GET /api/v1/invoices?created_at=2022-01-10
Returns entities created on January 10th, 2022
updated_at
integer
Example: updated_at=1641772800

Filters the entity list by the updated at timestamp. Parameter value can be a datetime string or unix timestamp

GET /api/v1/invoices?updated_at=2022-01-10
Returns entities last updated on January 10th, 2022
is_deleted
boolean
Example: is_deleted=true

Filters the entity list by entities that have been deleted.

GET /api/v1/invoices?is_deleted=true
Returns only soft-deleted entities
filter_deleted_clients
string
Example: filter_deleted_clients=?filter_deleted_clients=true

Filters the entity list and only returns entities for clients that have not been deleted

GET /api/v1/invoices?filter_deleted_clients=true
Returns only invoices for active (non-deleted) clients
name
string
Example: name=bob

Filter by client name 

?name=bob
balance
string
Example: balance=lt:10

Filter by client balance, format uses an operator and value separated by a colon. lt,lte, gt, gte, eq

?balance=lt:10

ie all clients whose balance is less than 10

between_balance
string
Example: between_balance=10:100

Filter between client balances, format uses two values separated by a colon

?between_balance=10:100
email
string

Filter by client email

[email protected]
id_number
string
Example: id_number=a1039883

Filter by client id_number

?id_number=0001
number
string
Example: number=a1039883

Filter by client number

?number=0002
filter
string
Example: filter=a1039883

Broad filter which targets multiple client columns:

  name, 
  id_number, 
  contact.first_name 
  contact.last_name, 
  contact.email, 
  contact.phone
  custom_value1,
  custom_value2,
  custom_value3,
  custom_value4,

?filter=Bobby
sort
string
Example: sort=id|desc name|desc balance|asc

Returns the list sorted by column in ascending or descending order.

Ensure you use column | direction, ie.

  ?sort=id|desc
group
string
Example: group=X89sjd8

Returns the list of clients assigned to {group_id}

  ?group=X89sjd8
client_id
string
Example: client_id=X89sjd8

Returns the list of clients with {client_id} - proxy call to retrieve a client_id wrapped in an array

  ?client_id=X89sjd8
header Parameters
X-API-TOKEN
required
string
Example: TOKEN

The API token to be used for authentication

X-Requested-With
required
string
Example: XMLHttpRequest

Used to send the XMLHttpRequest header

Responses

Request samples 

$ninja = new InvoiceNinja("your_token");
$invoices = $ninja->clients->all([
    'balance' => 'lt:10', // get all clients with a balance less than 10
    'per_page' => 10, // return 10 results per page
    'page' => 2, // paginate to page 2
    'include' => 'documents', // include the documents relationship
]);

Response samples

Content type
application/json
{
  • "data": [
    ],
  • "meta": {
    }
}

Create client

POST /api/v1/clients

Adds a client to a company

🚨 Important
When creating (or updating) a client you must include the child contacts with all mutating requests. Client contacts cannot be modified in isolation.

Authorizations:
ApiKeyAuth
query Parameters
index
string
Example: index=user

Replaces the default response index from data to a user specific string

ie.

  ?index=new_index

response is wrapped

  {
    'new_index' : [
      .....  
    ]
  }
include
string
Examples:
  • include=activities - include=activities will include the activities object in the response
  • include=ledger - include=ledger will include the ledger object in the response
  • include=system_logs - include=system_logs will include the system_logs object in the response

Include child relationships of the Client Object. ie ?include=documents,system_logs

Available includes:

contacts [All contacts related to the client]
documents [All documents related to the client]
gateway_tokens [All payment tokens related to the client]
activities [All activities related to the client]
ledger [The client ledger]
system_logs [System logs related to the client]
group_settings [The group settings object the client is assigned to]

Usage:

/api/v1/clients?include=contacts,documents,activities
header Parameters
X-API-TOKEN
required
string
Example: TOKEN

The API token to be used for authentication

X-Requested-With
required
string
Example: XMLHttpRequest

Used to send the XMLHttpRequest header

Request Body schema: application/json
required
required
Array of objects (ClientContactRequest)

A list of contacts associated with the client

name
string

The name of the client company or organization

website
string

The website URL of the client company or organization

private_notes
string

Notes that are only visible to the user who created the client

industry_id
number

The unique identifier of the industry the client operates in

size_id
number

The unique identifier for the size category of the client company or organization

address1
string

First line of the client's address

address2
string

Second line of the client's address, if needed

city
string

The city the client is located in

state
string

The state, province, or locality the client is located in

postal_code
string

The postal code or ZIP code of the client

phone
string

The client's phone number

required
Country Types (integer) (CountryType)
custom_value1
string

A custom field for storing additional information

custom_value2
string

A custom field for storing additional information

custom_value3
string

A custom field for storing additional information

custom_value4
string

A custom field for storing additional information

vat_number
string

The client's VAT (Value Added Tax) number, if applicable

id_number
string

A unique identification number for the client, such as a tax ID or business registration number

number
string

A system-assigned unique number for the client, typically used for invoicing purposes

shipping_address1
string

First line of the client's shipping address

shipping_address2
string

Second line of the client's shipping address, if needed

shipping_city
string

The city of the client's shipping address

shipping_state
string

The state, province, or locality of the client's shipping address

shipping_postal_code
string

The postal code or ZIP code of the client's shipping address

shipping_country_id
number <integer>

The unique identifier of the client's shipping country expressed by the countries ISO number.

Optionally, instead of the shipping_country_id you can pass either the iso_3166_2 or iso_3166_3 country code into the shipping_country_code property.

group_settings_id
string

The group settings assigned to the client

routing_id
string

The routing address id for e-invoicing for this client

is_tax_exempt
boolean

Flag which defines if the client is exempt from taxes

has_valid_vat_number
boolean

Flag which defines if the client has a valid VAT number

classification
string

The classification of the client

object (ClientSettings)

Responses

Request samples

Content type
application/json
{
  • "contacts": [
    ],
  • "name": "Bob & Co Housekeeping",
  • "website": "https://www.boandco-housekeeping.com",
  • "private_notes": "Client prefers email communication over phone calls",
  • "industry_id": 5,
  • "size_id": 2,
  • "address1": "123 Main St",
  • "address2": "Apt 4B",
  • "city": "Beverly Hills",
  • "state": "California",
  • "postal_code": "90210",
  • "phone": "555-3434-3434",
  • "country_id": 0,
  • "custom_value1": "Preferred contact: Email",
  • "custom_value2": "Account manager: John Doe",
  • "custom_value3": "VIP client: Yes",
  • "custom_value4": "Annual contract value: $50,000",
  • "vat_number": "VAT123456",
  • "id_number": "string",
  • "number": "CL-0001",
  • "shipping_address1": "5 Wallaby Way",
  • "shipping_address2": "Suite 5",
  • "shipping_city": "Perth",
  • "shipping_state": "Western Australia",
  • "shipping_postal_code": "6110",
  • "shipping_country_id": 4,
  • "group_settings_id": "Opnel5aKBz",
  • "routing_id": "Opnel5aKBz3489-dfkiu-2239-sdsd",
  • "is_tax_exempt": false,
  • "has_valid_vat_number": false,
  • "classification": "individual",
  • "settings": {
    }
}

Response samples

Content type
application/json
{
  • "id": "Opnel5aKBz",
  • "contacts": [
    ],
  • "user_id": "Ua6Rw4pVbS",
  • "assigned_user_id": "Ua6Rw4pVbS",
  • "name": "Jim's Housekeeping",
  • "website": "https://www.jims-housekeeping.com",
  • "private_notes": "Client prefers email communication over phone calls",
  • "client_hash": "asdfkjhk342hjhbfdvmnfb1",
  • "industry_id": 5,
  • "size_id": 2,
  • "address1": "123 Main St",
  • "address2": "Apt 4B",
  • "city": "Beverly Hills",
  • "state": "California",
  • "postal_code": "90210",
  • "phone": "555-3434-3434",
  • "country_id": 0,
  • "custom_value1": "Preferred contact: Email",
  • "custom_value2": "Account manager: John Doe",
  • "custom_value3": "VIP client: Yes",
  • "custom_value4": "Annual contract value: $50,000",
  • "vat_number": "VAT123456",
  • "id_number": "string",
  • "number": "CL-0001",
  • "shipping_address1": "5 Wallaby Way",
  • "shipping_address2": "Suite 5",
  • "shipping_city": "Perth",
  • "shipping_state": "Western Australia",
  • "shipping_postal_code": "6110",
  • "shipping_country_id": 4,
  • "is_deleted": false,
  • "balance": 500,
  • "paid_to_date": 2000,
  • "credit_balance": 100,
  • "last_login": 1628686031,
  • "created_at": 1617629031,
  • "updated_at": 1628445631,
  • "group_settings_id": "Opnel5aKBz",
  • "routing_id": "Opnel5aKBz3489-dfkiu-2239-sdsd",
  • "is_tax_exempt": false,
  • "has_valid_vat_number": false,
  • "payment_balance": 100,
  • "settings": {
    },
  • "classification": "VIP",
  • "public_notes": "These are public notes visible to clients"
}

Show client

GET /api/v1/clients/{id}

Displays a client by id

Authorizations:
ApiKeyAuth
path Parameters
id
required
string <string>
Example: D2J234DFA

The Client Hashed ID

query Parameters
index
string
Example: index=user

Replaces the default response index from data to a user specific string

ie.

  ?index=new_index

response is wrapped

  {
    'new_index' : [
      .....  
    ]
  }
include
string
Examples:
  • include=activities - include=activities will include the activities object in the response
  • include=ledger - include=ledger will include the ledger object in the response
  • include=system_logs - include=system_logs will include the system_logs object in the response

Include child relationships of the Client Object. ie ?include=documents,system_logs

Available includes:

contacts [All contacts related to the client]
documents [All documents related to the client]
gateway_tokens [All payment tokens related to the client]
activities [All activities related to the client]
ledger [The client ledger]
system_logs [System logs related to the client]
group_settings [The group settings object the client is assigned to]

Usage:

/api/v1/clients?include=contacts,documents,activities
header Parameters
X-API-TOKEN
required
string
Example: TOKEN

The API token to be used for authentication

X-Requested-With
required
string
Example: XMLHttpRequest

Used to send the XMLHttpRequest header

Responses

Request samples 

$ninja = new InvoiceNinja("YOUR-TOKEN");
$client = $ninja->clients->show('clientId123');

Response samples

Content type
application/json
{
  • "id": "Opnel5aKBz",
  • "contacts": [
    ],
  • "user_id": "Ua6Rw4pVbS",
  • "assigned_user_id": "Ua6Rw4pVbS",
  • "name": "Jim's Housekeeping",
  • "website": "https://www.jims-housekeeping.com",
  • "private_notes": "Client prefers email communication over phone calls",
  • "client_hash": "asdfkjhk342hjhbfdvmnfb1",
  • "industry_id": 5,
  • "size_id": 2,
  • "address1": "123 Main St",
  • "address2": "Apt 4B",
  • "city": "Beverly Hills",
  • "state": "California",
  • "postal_code": "90210",
  • "phone": "555-3434-3434",
  • "country_id": 0,
  • "custom_value1": "Preferred contact: Email",
  • "custom_value2": "Account manager: John Doe",
  • "custom_value3": "VIP client: Yes",
  • "custom_value4": "Annual contract value: $50,000",
  • "vat_number": "VAT123456",
  • "id_number": "string",
  • "number": "CL-0001",
  • "shipping_address1": "5 Wallaby Way",
  • "shipping_address2": "Suite 5",
  • "shipping_city": "Perth",
  • "shipping_state": "Western Australia",
  • "shipping_postal_code": "6110",
  • "shipping_country_id": 4,
  • "is_deleted": false,
  • "balance": 500,
  • "paid_to_date": 2000,
  • "credit_balance": 100,
  • "last_login": 1628686031,
  • "created_at": 1617629031,
  • "updated_at": 1628445631,
  • "group_settings_id": "Opnel5aKBz",
  • "routing_id": "Opnel5aKBz3489-dfkiu-2239-sdsd",
  • "is_tax_exempt": false,
  • "has_valid_vat_number": false,
  • "payment_balance": 100,
  • "settings": {
    },
  • "classification": "VIP",
  • "public_notes": "These are public notes visible to clients"
}

Update client

PUT /api/v1/clients/{id}

Handles the updating of a client by id

🚨 Important
When creating (or updating) a client you must include the child contacts with all mutating requests. Client contacts cannot be modified in isolation.

Authorizations:
ApiKeyAuth
path Parameters
id
required
string <string>
Example: D2J234DFA

The Client Hashed ID

query Parameters
index
string
Example: index=user

Replaces the default response index from data to a user specific string

ie.

  ?index=new_index

response is wrapped

  {
    'new_index' : [
      .....  
    ]
  }
include
string
Examples:
  • include=activities - include=activities will include the activities object in the response
  • include=ledger - include=ledger will include the ledger object in the response
  • include=system_logs - include=system_logs will include the system_logs object in the response

Include child relationships of the Client Object. ie ?include=documents,system_logs

Available includes:

contacts [All contacts related to the client]
documents [All documents related to the client]
gateway_tokens [All payment tokens related to the client]
activities [All activities related to the client]
ledger [The client ledger]
system_logs [System logs related to the client]
group_settings [The group settings object the client is assigned to]

Usage:

/api/v1/clients?include=contacts,documents,activities
header Parameters
X-API-TOKEN
required
string
Example: TOKEN

The API token to be used for authentication

X-Requested-With
required
string
Example: XMLHttpRequest

Used to send the XMLHttpRequest header

Request Body schema: application/json
required

Client object that needs to be updated

required
Array of objects (ClientContactRequest)

A list of contacts associated with the client

name
string

The name of the client company or organization

website
string

The website URL of the client company or organization

private_notes
string

Notes that are only visible to the user who created the client

industry_id
number

The unique identifier of the industry the client operates in

size_id
number

The unique identifier for the size category of the client company or organization

address1
string

First line of the client's address

address2
string

Second line of the client's address, if needed

city
string

The city the client is located in

state
string

The state, province, or locality the client is located in

postal_code
string

The postal code or ZIP code of the client

phone
string

The client's phone number

required
Country Types (integer) (CountryType)
custom_value1
string

A custom field for storing additional information

custom_value2
string

A custom field for storing additional information

custom_value3
string

A custom field for storing additional information

custom_value4
string

A custom field for storing additional information

vat_number
string

The client's VAT (Value Added Tax) number, if applicable

id_number
string

A unique identification number for the client, such as a tax ID or business registration number

number
string

A system-assigned unique number for the client, typically used for invoicing purposes

shipping_address1
string

First line of the client's shipping address

shipping_address2
string

Second line of the client's shipping address, if needed

shipping_city
string

The city of the client's shipping address

shipping_state
string

The state, province, or locality of the client's shipping address

shipping_postal_code
string

The postal code or ZIP code of the client's shipping address

shipping_country_id
number <integer>

The unique identifier of the client's shipping country expressed by the countries ISO number.

Optionally, instead of the shipping_country_id you can pass either the iso_3166_2 or iso_3166_3 country code into the shipping_country_code property.

group_settings_id
string

The group settings assigned to the client

routing_id
string

The routing address id for e-invoicing for this client

is_tax_exempt
boolean

Flag which defines if the client is exempt from taxes

has_valid_vat_number
boolean

Flag which defines if the client has a valid VAT number

classification
string

The classification of the client

object (ClientSettings)

Responses

Request samples

Content type
application/json
{
  • "contacts": [
    ],
  • "name": "Bob & Co Housekeeping",
  • "website": "https://www.boandco-housekeeping.com",
  • "private_notes": "Client prefers email communication over phone calls",
  • "industry_id": 5,
  • "size_id": 2,
  • "address1": "123 Main St",
  • "address2": "Apt 4B",
  • "city": "Beverly Hills",
  • "state": "California",
  • "postal_code": "90210",
  • "phone": "555-3434-3434",
  • "country_id": 0,
  • "custom_value1": "Preferred contact: Email",
  • "custom_value2": "Account manager: John Doe",
  • "custom_value3": "VIP client: Yes",
  • "custom_value4": "Annual contract value: $50,000",
  • "vat_number": "VAT123456",
  • "id_number": "string",
  • "number": "CL-0001",
  • "shipping_address1": "5 Wallaby Way",
  • "shipping_address2": "Suite 5",
  • "shipping_city": "Perth",
  • "shipping_state": "Western Australia",
  • "shipping_postal_code": "6110",
  • "shipping_country_id": 4,
  • "group_settings_id": "Opnel5aKBz",
  • "routing_id": "Opnel5aKBz3489-dfkiu-2239-sdsd",
  • "is_tax_exempt": false,
  • "has_valid_vat_number": false,
  • "classification": "individual",
  • "settings": {
    }
}

Response samples

Content type
application/json
{
  • "id": "Opnel5aKBz",
  • "contacts": [
    ],
  • "user_id": "Ua6Rw4pVbS",
  • "assigned_user_id": "Ua6Rw4pVbS",
  • "name": "Jim's Housekeeping",
  • "website": "https://www.jims-housekeeping.com",
  • "private_notes": "Client prefers email communication over phone calls",
  • "client_hash": "asdfkjhk342hjhbfdvmnfb1",
  • "industry_id": 5,
  • "size_id": 2,
  • "address1": "123 Main St",
  • "address2": "Apt 4B",
  • "city": "Beverly Hills",
  • "state": "California",
  • "postal_code": "90210",
  • "phone": "555-3434-3434",
  • "country_id": 0,
  • "custom_value1": "Preferred contact: Email",
  • "custom_value2": "Account manager: John Doe",
  • "custom_value3": "VIP client: Yes",
  • "custom_value4": "Annual contract value: $50,000",
  • "vat_number": "VAT123456",
  • "id_number": "string",
  • "number": "CL-0001",
  • "shipping_address1": "5 Wallaby Way",
  • "shipping_address2": "Suite 5",
  • "shipping_city": "Perth",
  • "shipping_state": "Western Australia",
  • "shipping_postal_code": "6110",
  • "shipping_country_id": 4,
  • "is_deleted": false,
  • "balance": 500,
  • "paid_to_date": 2000,
  • "credit_balance": 100,
  • "last_login": 1628686031,
  • "created_at": 1617629031,
  • "updated_at": 1628445631,
  • "group_settings_id": "Opnel5aKBz",
  • "routing_id": "Opnel5aKBz3489-dfkiu-2239-sdsd",
  • "is_tax_exempt": false,
  • "has_valid_vat_number": false,
  • "payment_balance": 100,
  • "settings": {
    },
  • "classification": "VIP",
  • "public_notes": "These are public notes visible to clients"
}

Delete client

DELETE /api/v1/clients/{id}

Handles the deletion of a client by id

❗ Note Deleting a client does not purge the client from the system. The delete action will remove the clients data from all views in the application but keep it on file in case it needs to be restored.

A Client can be later restored reversing this action.

To permanently wipe a client and all of their records from the system, use the /purge route

Authorizations:
ApiKeyAuth
path Parameters
id
required
string <string>
Example: D2J234DFA

The Client Hashed ID

query Parameters
index
string
Example: index=user

Replaces the default response index from data to a user specific string

ie.

  ?index=new_index

response is wrapped

  {
    'new_index' : [
      .....  
    ]
  }
include
string
Examples:
  • include=activities - include=activities will include the activities object in the response
  • include=ledger - include=ledger will include the ledger object in the response
  • include=system_logs - include=system_logs will include the system_logs object in the response

Include child relationships of the Client Object. ie ?include=documents,system_logs

Available includes:

contacts [All contacts related to the client]
documents [All documents related to the client]
gateway_tokens [All payment tokens related to the client]
activities [All activities related to the client]
ledger [The client ledger]
system_logs [System logs related to the client]
group_settings [The group settings object the client is assigned to]

Usage:

/api/v1/clients?include=contacts,documents,activities
header Parameters
X-API-TOKEN
required
string
Example: TOKEN

The API token to be used for authentication

X-Requested-With
required
string
Example: XMLHttpRequest

Used to send the XMLHttpRequest header

Responses

Request samples 

$ninja = new InvoiceNinja("YOUR-TOKEN");
$ninja->clients->delete('clientId123');

Response samples

Content type
application/json
{
  • "message": "These credentials do not match our records / Invalid Token"
}

Edit Client

GET /api/v1/clients/{id}/edit

Displays a client by id, essentially an alias of the show route

Authorizations:
ApiKeyAuth
path Parameters
id
required
string <string>
Example: D2J234DFA

The Client Hashed ID

query Parameters
index
string
Example: index=user

Replaces the default response index from data to a user specific string

ie.

  ?index=new_index

response is wrapped

  {
    'new_index' : [
      .....  
    ]
  }
include
string
Examples:
  • include=activities - include=activities will include the activities object in the response
  • include=ledger - include=ledger will include the ledger object in the response
  • include=system_logs - include=system_logs will include the system_logs object in the response

Include child relationships of the Client Object. ie ?include=documents,system_logs

Available includes:

contacts [All contacts related to the client]
documents [All documents related to the client]
gateway_tokens [All payment tokens related to the client]
activities [All activities related to the client]
ledger [The client ledger]
system_logs [System logs related to the client]
group_settings [The group settings object the client is assigned to]

Usage:

/api/v1/clients?include=contacts,documents,activities
header Parameters
X-API-TOKEN
required
string
Example: TOKEN

The API token to be used for authentication

X-Requested-With
required
string
Example: XMLHttpRequest

Used to send the XMLHttpRequest header

Responses

Request samples 

$ninja = new InvoiceNinja("YOUR-TOKEN");
$client = $ninja->clients->show('clientId123');

Response samples

Content type
application/json
{
  • "id": "Opnel5aKBz",
  • "contacts": [
    ],
  • "user_id": "Ua6Rw4pVbS",
  • "assigned_user_id": "Ua6Rw4pVbS",
  • "name": "Jim's Housekeeping",
  • "website": "https://www.jims-housekeeping.com",
  • "private_notes": "Client prefers email communication over phone calls",
  • "client_hash": "asdfkjhk342hjhbfdvmnfb1",
  • "industry_id": 5,
  • "size_id": 2,
  • "address1": "123 Main St",
  • "address2": "Apt 4B",
  • "city": "Beverly Hills",
  • "state": "California",
  • "postal_code": "90210",
  • "phone": "555-3434-3434",
  • "country_id": 0,
  • "custom_value1": "Preferred contact: Email",
  • "custom_value2": "Account manager: John Doe",
  • "custom_value3": "VIP client: Yes",
  • "custom_value4": "Annual contract value: $50,000",
  • "vat_number": "VAT123456",
  • "id_number": "string",
  • "number": "CL-0001",
  • "shipping_address1": "5 Wallaby Way",
  • "shipping_address2": "Suite 5",
  • "shipping_city": "Perth",
  • "shipping_state": "Western Australia",
  • "shipping_postal_code": "6110",
  • "shipping_country_id": 4,
  • "is_deleted": false,
  • "balance": 500,
  • "paid_to_date": 2000,
  • "credit_balance": 100,
  • "last_login": 1628686031,
  • "created_at": 1617629031,
  • "updated_at": 1628445631,
  • "group_settings_id": "Opnel5aKBz",
  • "routing_id": "Opnel5aKBz3489-dfkiu-2239-sdsd",
  • "is_tax_exempt": false,
  • "has_valid_vat_number": false,
  • "payment_balance": 100,
  • "settings": {
    },
  • "classification": "VIP",
  • "public_notes": "These are public notes visible to clients"
}

Blank Client

GET /api/v1/clients/create

Returns a blank object with default values

Authorizations:
ApiKeyAuth
query Parameters
index
string
Example: index=user

Replaces the default response index from data to a user specific string

ie.

  ?index=new_index

response is wrapped

  {
    'new_index' : [
      .....  
    ]
  }
include
string
Examples:
  • include=activities - include=activities will include the activities object in the response
  • include=ledger - include=ledger will include the ledger object in the response
  • include=system_logs - include=system_logs will include the system_logs object in the response

Include child relationships of the Client Object. ie ?include=documents,system_logs

Available includes:

contacts [All contacts related to the client]
documents [All documents related to the client]
gateway_tokens [All payment tokens related to the client]
activities [All activities related to the client]
ledger [The client ledger]
system_logs [System logs related to the client]
group_settings [The group settings object the client is assigned to]

Usage:

/api/v1/clients?include=contacts,documents,activities
header Parameters
X-API-TOKEN
required
string
Example: TOKEN

The API token to be used for authentication

X-Requested-With
required
string
Example: XMLHttpRequest

Used to send the XMLHttpRequest header

Responses

Request samples 

$ninja = new InvoiceNinja("YOUR-TOKEN");
$client = $ninja->clients->model();

Response samples

Content type
application/json
{
  • "id": "Opnel5aKBz",
  • "contacts": [
    ],
  • "user_id": "Ua6Rw4pVbS",
  • "assigned_user_id": "Ua6Rw4pVbS",
  • "name": "Jim's Housekeeping",
  • "website": "https://www.jims-housekeeping.com",
  • "private_notes": "Client prefers email communication over phone calls",
  • "client_hash": "asdfkjhk342hjhbfdvmnfb1",
  • "industry_id": 5,
  • "size_id": 2,
  • "address1": "123 Main St",
  • "address2": "Apt 4B",
  • "city": "Beverly Hills",
  • "state": "California",
  • "postal_code": "90210",
  • "phone": "555-3434-3434",
  • "country_id": 0,
  • "custom_value1": "Preferred contact: Email",
  • "custom_value2": "Account manager: John Doe",
  • "custom_value3": "VIP client: Yes",
  • "custom_value4": "Annual contract value: $50,000",
  • "vat_number": "VAT123456",
  • "id_number": "string",
  • "number": "CL-0001",
  • "shipping_address1": "5 Wallaby Way",
  • "shipping_address2": "Suite 5",
  • "shipping_city": "Perth",
  • "shipping_state": "Western Australia",
  • "shipping_postal_code": "6110",
  • "shipping_country_id": 4,
  • "is_deleted": false,
  • "balance": 500,
  • "paid_to_date": 2000,
  • "credit_balance": 100,
  • "last_login": 1628686031,
  • "created_at": 1617629031,
  • "updated_at": 1628445631,
  • "group_settings_id": "Opnel5aKBz",
  • "routing_id": "Opnel5aKBz3489-dfkiu-2239-sdsd",
  • "is_tax_exempt": false,
  • "has_valid_vat_number": false,
  • "payment_balance": 100,
  • "settings": {
    },
  • "classification": "VIP",
  • "public_notes": "These are public notes visible to clients"
}

Bulk client actions

POST /api/v1/clients/bulk

Bulk actions allow to make changes to multiple clients in a single request the following actions are supported

  • archive
  • restore
  • delete
  • template requires template,template_id properties also
  • assign_group requires group_settings_id also
  • bulk_update requires column,new_value also

All of these actions require an array of client ids to perform the requested action on ie.

"ids":['id1','id2']

actions such as template, assign_group and bulk_update also require additional properties to be passed in the request

  • template

The template bulk action allows the creation of a custom template using the provided template_id to be run against the array of clients provided.

  • assign_group

Allows setting multiple clients to a single group

  • bulk_update

Allows updating certain columns on the client model in bulk. the current list of supported columns that can be updated archived_at:

  • public_notes
  • industry_id
  • size_id
  • country_id
  • custom_value1
  • custom_value2
  • custom_value3
  • custom_value4
Authorizations:
ApiKeyAuth
query Parameters
index
string
Example: index=user

Replaces the default response index from data to a user specific string

ie.

  ?index=new_index

response is wrapped

  {
    'new_index' : [
      .....  
    ]
  }
include
string
Examples:
  • include=activities - include=activities will include the activities object in the response
  • include=ledger - include=ledger will include the ledger object in the response
  • include=system_logs - include=system_logs will include the system_logs object in the response

Include child relationships of the Client Object. ie ?include=documents,system_logs

Available includes:

contacts [All contacts related to the client]
documents [All documents related to the client]
gateway_tokens [All payment tokens related to the client]
activities [All activities related to the client]
ledger [The client ledger]
system_logs [System logs related to the client]
group_settings [The group settings object the client is assigned to]

Usage:

/api/v1/clients?include=contacts,documents,activities
header Parameters
X-API-TOKEN
required
string
Example: TOKEN

The API token to be used for authentication

X-Requested-With
required
string
Example: XMLHttpRequest

Used to send the XMLHttpRequest header

Request Body schema: application/json
required

Bulk action array

action
string

The action to perform ie. archive / restore / delete

ids
Array of strings <string> [ items <string > ]

Responses

Request samples

Content type
application/json
{
  • "action": "archive",
  • "ids": [
    ]
}

Response samples

Content type
application/json
{
  • "id": "Opnel5aKBz",
  • "contacts": [
    ],
  • "user_id": "Ua6Rw4pVbS",
  • "assigned_user_id": "Ua6Rw4pVbS",
  • "name": "Jim's Housekeeping",
  • "website": "https://www.jims-housekeeping.com",
  • "private_notes": "Client prefers email communication over phone calls",
  • "client_hash": "asdfkjhk342hjhbfdvmnfb1",
  • "industry_id": 5,
  • "size_id": 2,
  • "address1": "123 Main St",
  • "address2": "Apt 4B",
  • "city": "Beverly Hills",
  • "state": "California",
  • "postal_code": "90210",
  • "phone": "555-3434-3434",
  • "country_id": 0,
  • "custom_value1": "Preferred contact: Email",
  • "custom_value2": "Account manager: John Doe",
  • "custom_value3": "VIP client: Yes",
  • "custom_value4": "Annual contract value: $50,000",
  • "vat_number": "VAT123456",
  • "id_number": "string",
  • "number": "CL-0001",
  • "shipping_address1": "5 Wallaby Way",
  • "shipping_address2": "Suite 5",
  • "shipping_city": "Perth",
  • "shipping_state": "Western Australia",
  • "shipping_postal_code": "6110",
  • "shipping_country_id": 4,
  • "is_deleted": false,
  • "balance": 500,
  • "paid_to_date": 2000,
  • "credit_balance": 100,
  • "last_login": 1628686031,
  • "created_at": 1617629031,
  • "updated_at": 1628445631,
  • "group_settings_id": "Opnel5aKBz",
  • "routing_id": "Opnel5aKBz3489-dfkiu-2239-sdsd",
  • "is_tax_exempt": false,
  • "has_valid_vat_number": false,
  • "payment_balance": 100,
  • "settings": {
    },
  • "classification": "VIP",
  • "public_notes": "These are public notes visible to clients"
}

Add client document

POST /api/v1/clients/{id}/upload

Handles the uploading of a document to a client, please note due to a quirk in REST you will need to use a _method parameter with value of POST

Authorizations:
ApiKeyAuth
path Parameters
id
required
string <string>
Example: D2J234DFA

The Client Hashed ID

query Parameters
index
string
Example: index=user

Replaces the default response index from data to a user specific string

ie.

  ?index=new_index

response is wrapped

  {
    'new_index' : [
      .....  
    ]
  }
include
string
Examples:
  • include=activities - include=activities will include the activities object in the response
  • include=ledger - include=ledger will include the ledger object in the response
  • include=system_logs - include=system_logs will include the system_logs object in the response

Include child relationships of the Client Object. ie ?include=documents,system_logs

Available includes:

contacts [All contacts related to the client]
documents [All documents related to the client]
gateway_tokens [All payment tokens related to the client]
activities [All activities related to the client]
ledger [The client ledger]
system_logs [System logs related to the client]
group_settings [The group settings object the client is assigned to]

Usage:

/api/v1/clients?include=contacts,documents,activities
header Parameters
X-API-TOKEN
required
string
Example: TOKEN

The API token to be used for authentication

X-Requested-With
required
string
Example: XMLHttpRequest

Used to send the XMLHttpRequest header

Request Body schema: multipart/form-data
required
_method
string
documents[]
Array of strings <binary> [ items <binary > ]

Array of files to upload. The files should be sent with the key name 'documents[]'.

Supported file types:

  • PDF (.pdf)
  • Word (.doc, .docx)
  • Excel (.xls, .xlsx)
  • Images (.jpg, .jpeg, .png)
  • Text (.txt)

Maximum file size: 20MB per file

Responses

Request samples 

$ninja = new InvoiceNinja("YOUR-TOKEN");
$ninja->clients->upload('clientId123', '/path/to/document.pdf');

Response samples

Content type
application/json
{
  • "id": "Opnel5aKBz",
  • "contacts": [
    ],
  • "user_id": "Ua6Rw4pVbS",
  • "assigned_user_id": "Ua6Rw4pVbS",
  • "name": "Jim's Housekeeping",
  • "website": "https://www.jims-housekeeping.com",
  • "private_notes": "Client prefers email communication over phone calls",
  • "client_hash": "asdfkjhk342hjhbfdvmnfb1",
  • "industry_id": 5,
  • "size_id": 2,
  • "address1": "123 Main St",
  • "address2": "Apt 4B",
  • "city": "Beverly Hills",
  • "state": "California",
  • "postal_code": "90210",
  • "phone": "555-3434-3434",
  • "country_id": 0,
  • "custom_value1": "Preferred contact: Email",
  • "custom_value2": "Account manager: John Doe",
  • "custom_value3": "VIP client: Yes",
  • "custom_value4": "Annual contract value: $50,000",
  • "vat_number": "VAT123456",
  • "id_number": "string",
  • "number": "CL-0001",
  • "shipping_address1": "5 Wallaby Way",
  • "shipping_address2": "Suite 5",
  • "shipping_city": "Perth",
  • "shipping_state": "Western Australia",
  • "shipping_postal_code": "6110",
  • "shipping_country_id": 4,
  • "is_deleted": false,
  • "balance": 500,
  • "paid_to_date": 2000,
  • "credit_balance": 100,
  • "last_login": 1628686031,
  • "created_at": 1617629031,
  • "updated_at": 1628445631,
  • "group_settings_id": "Opnel5aKBz",
  • "routing_id": "Opnel5aKBz3489-dfkiu-2239-sdsd",
  • "is_tax_exempt": false,
  • "has_valid_vat_number": false,
  • "payment_balance": 100,
  • "settings": {
    },
  • "classification": "VIP",
  • "public_notes": "These are public notes visible to clients"
}

Purge client

POST /api/v1/clients/{id}/purge

Handles purging a client.

❗ Note This is a destructive action. This action will remove all data associated with the client and cannot be undone.

Authorizations:
ApiKeyAuth
path Parameters
id
required
string <string>
Example: D2J234DFA

The Client Hashed ID

header Parameters
X-API-TOKEN
required
string
Example: TOKEN

The API token to be used for authentication

X-Requested-With
required
string
Example: XMLHttpRequest

Used to send the XMLHttpRequest header

X-API-PASSWORD
required
string
Example: supersecretpassword

The login password when challenged on certain protected routes

Responses

Request samples 

$ninja = new InvoiceNinja("YOUR-TOKEN");
$ninja->clients->purge('clientId123');

Response samples

Content type
application/json
{
  • "message": "These credentials do not match our records / Invalid Token"
}

Merge client

POST /api/v1/clients/{id}/{mergeable_client_hashed_id}/merge

Handles merging 2 clients

The id parameter is the client that will be the primary client after the merge has completed.

The mergeable_client_hashed_id is the client that will be merged into the primary client, this clients records will be updated and associated with the primary client.

🚨 Important
This action requires elevated permissions, please note the X-API-PASSWORD header requirements for this route.

Authorizations:
ApiKeyAuth
path Parameters
id
required
string <string>
Example: D2J234DFA

The Client Hashed ID

mergeable_client_hashed_id
required
string <string>
Example: D2J234DFA

The Mergeable Client Hashed ID

query Parameters
index
string
Example: index=user

Replaces the default response index from data to a user specific string

ie.

  ?index=new_index

response is wrapped

  {
    'new_index' : [
      .....  
    ]
  }
include
string
Examples:
  • include=activities - include=activities will include the activities object in the response
  • include=ledger - include=ledger will include the ledger object in the response
  • include=system_logs - include=system_logs will include the system_logs object in the response

Include child relationships of the Client Object. ie ?include=documents,system_logs

Available includes:

contacts [All contacts related to the client]
documents [All documents related to the client]
gateway_tokens [All payment tokens related to the client]
activities [All activities related to the client]
ledger [The client ledger]
system_logs [System logs related to the client]
group_settings [The group settings object the client is assigned to]

Usage:

/api/v1/clients?include=contacts,documents,activities
header Parameters
X-API-TOKEN
required
string
Example: TOKEN

The API token to be used for authentication

X-Requested-With
required
string
Example: XMLHttpRequest

Used to send the XMLHttpRequest header

X-API-PASSWORD
required
string
Example: supersecretpassword

The login password when challenged on certain protected routes

Responses

Request samples 

$ninja = new InvoiceNinja("YOUR-TOKEN");
$ninja->clients->merge('primaryClientId', 'mergeableClientId');

Response samples

Content type
application/json
{
  • "message": "These credentials do not match our records / Invalid Token"
}

Client statement PDF

POST /api/v1/client_statement

Return a PDF of the client statement

Authorizations:
ApiKeyAuth
query Parameters
index
string
Example: index=user

Replaces the default response index from data to a user specific string

ie.

  ?index=new_index

response is wrapped

  {
    'new_index' : [
      .....  
    ]
  }
include
string
Examples:
  • include=activities - include=activities will include the activities object in the response
  • include=ledger - include=ledger will include the ledger object in the response
  • include=system_logs - include=system_logs will include the system_logs object in the response

Include child relationships of the Client Object. ie ?include=documents,system_logs

Available includes:

contacts [All contacts related to the client]
documents [All documents related to the client]
gateway_tokens [All payment tokens related to the client]
activities [All activities related to the client]
ledger [The client ledger]
system_logs [System logs related to the client]
group_settings [The group settings object the client is assigned to]

Usage:

/api/v1/clients?include=contacts,documents,activities
header Parameters
X-API-TOKEN
required
string
Example: TOKEN

The API token to be used for authentication

X-Requested-With
required
string
Example: XMLHttpRequest

Used to send the XMLHttpRequest header

Request Body schema: application/json
required

Statement Options

start_date
string

The start date of the statement period - format Y-m-d

end_date
string

The start date of the statement period - format Y-m-d

client_id
string

The hashed ID of the client

show_payments_table
boolean

Flag which determines if the payments table is shown

show_credits_table
boolean

Flag which determines if the credits table is shown

show_aging_table
boolean

Flag which determines if the aging table is shown

Responses

Request samples

Content type
application/json
{
  • "start_date": "string",
  • "end_date": "string",
  • "client_id": "string",
  • "show_payments_table": true,
  • "show_credits_table": true,
  • "show_aging_table": true
}

Response samples

Content type
application/json
{
  • "id": "Opnel5aKBz",
  • "contacts": [
    ],
  • "user_id": "Ua6Rw4pVbS",
  • "assigned_user_id": "Ua6Rw4pVbS",
  • "name": "Jim's Housekeeping",
  • "website": "https://www.jims-housekeeping.com",
  • "private_notes": "Client prefers email communication over phone calls",
  • "client_hash": "asdfkjhk342hjhbfdvmnfb1",
  • "industry_id": 5,
  • "size_id": 2,
  • "address1": "123 Main St",
  • "address2": "Apt 4B",
  • "city": "Beverly Hills",
  • "state": "California",
  • "postal_code": "90210",
  • "phone": "555-3434-3434",
  • "country_id": 0,
  • "custom_value1": "Preferred contact: Email",
  • "custom_value2": "Account manager: John Doe",
  • "custom_value3": "VIP client: Yes",
  • "custom_value4": "Annual contract value: $50,000",
  • "vat_number": "VAT123456",
  • "id_number": "string",
  • "number": "CL-0001",
  • "shipping_address1": "5 Wallaby Way",
  • "shipping_address2": "Suite 5",
  • "shipping_city": "Perth",
  • "shipping_state": "Western Australia",
  • "shipping_postal_code": "6110",
  • "shipping_country_id": 4,
  • "is_deleted": false,
  • "balance": 500,
  • "paid_to_date": 2000,
  • "credit_balance": 100,
  • "last_login": 1628686031,
  • "created_at": 1617629031,
  • "updated_at": 1628445631,
  • "group_settings_id": "Opnel5aKBz",
  • "routing_id": "Opnel5aKBz3489-dfkiu-2239-sdsd",
  • "is_tax_exempt": false,
  • "has_valid_vat_number": false,
  • "payment_balance": 100,
  • "settings": {
    },
  • "classification": "VIP",
  • "public_notes": "These are public notes visible to clients"
}

Removes email suppression of a user in the system

POST /api/v1/reactivate_email/{bounce_id}

Emails are suppressed by PostMark, when they receive a Hard bounce / Spam Complaint. This endpoint allows you to remove the suppression and send emails to the user again.

Authorizations:
ApiKeyAuth
path Parameters
bounce_id
required
string <string>
Example: 123243

The postmark Bounce ID reference

query Parameters
index
string
Example: index=user

Replaces the default response index from data to a user specific string

ie.

  ?index=new_index

response is wrapped

  {
    'new_index' : [
      .....  
    ]
  }
include
string
Examples:
  • include=activities - include=activities will include the activities object in the response
  • include=ledger - include=ledger will include the ledger object in the response
  • include=system_logs - include=system_logs will include the system_logs object in the response

Include child relationships of the Client Object. ie ?include=documents,system_logs

Available includes:

contacts [All contacts related to the client]
documents [All documents related to the client]
gateway_tokens [All payment tokens related to the client]
activities [All activities related to the client]
ledger [The client ledger]
system_logs [System logs related to the client]
group_settings [The group settings object the client is assigned to]

Usage:

/api/v1/clients?include=contacts,documents,activities
header Parameters
X-API-TOKEN
required
string
Example: TOKEN

The API token to be used for authentication

X-Requested-With
required
string
Example: XMLHttpRequest

Used to send the XMLHttpRequest header

Responses

Request samples 

$ninja = new InvoiceNinja("YOUR-TOKEN");
$ninja->clients->reactivateEmail("bounce_id_123");

Response samples

Content type
application/json
{
  • "message": "These credentials do not match our records / Invalid Token"
}

Update tax data

POST /api/v1/clients/{client}/updateTaxData

Updates the clients tax data - if their address has changed

Authorizations:
ApiKeyAuth
path Parameters
client
required
string <string>
Example: V2J234DFA

The Client Hashed ID reference

query Parameters
index
string
Example: index=user

Replaces the default response index from data to a user specific string

ie.

  ?index=new_index

response is wrapped

  {
    'new_index' : [
      .....  
    ]
  }
include
string
Examples:
  • include=activities - include=activities will include the activities object in the response
  • include=ledger - include=ledger will include the ledger object in the response
  • include=system_logs - include=system_logs will include the system_logs object in the response

Include child relationships of the Client Object. ie ?include=documents,system_logs

Available includes:

contacts [All contacts related to the client]
documents [All documents related to the client]
gateway_tokens [All payment tokens related to the client]
activities [All activities related to the client]
ledger [The client ledger]
system_logs [System logs related to the client]
group_settings [The group settings object the client is assigned to]

Usage:

/api/v1/clients?include=contacts,documents,activities
header Parameters
X-API-TOKEN
required
string
Example: TOKEN

The API token to be used for authentication

X-Requested-With
required
string
Example: XMLHttpRequest

Used to send the XMLHttpRequest header

Responses

Request samples 

$ninja = new InvoiceNinja("YOUR-TOKEN");
$ninja->clients->updateTaxData("D2J234DFA", [
    'address1' => '123 New Street',
    'city' => 'New York',
    'state' => 'NY',
    'postal_code' => '10001',
    'country_id' => '1'
]);

Response samples

Content type
application/json
{
  • "message": "These credentials do not match our records / Invalid Token"
}

Locations

The Locations API provides endpoints for managing location records within your company. A location represents a physical address where you provide services or products to a client OR vendor.

List locations

GET /api/v1/locations

Locations are additional addresses that are applicable to a client. This is useful when a client has multiple addresses for shipping, billing, etc.

When retrieving a list of locations you can chain query parameters to filter the dataset. For example:

/api/v1/locations?name=warehouse*

You can also sort the results:

/api/v1/locations?sort=name|desc

For pagination, use per_page and page parameters:

/api/v1/locations?per_page=15&page=2

The default per_page value is 20.

Authorizations:
ApiKeyAuth
query Parameters
index
string
Example: index=user

Replaces the default response index from data to a user specific string

ie.

  ?index=new_index

response is wrapped

  {
    'new_index' : [
      .....  
    ]
  }
per_page
integer
Example: per_page=20

The number of records to return for each request, default is 20

page
integer
Example: page=1

The page number to return for this request (when performing pagination), default is 1

name
string
Example: name=warehouse

Filter by location name

?name=warehouse
sort
string
Example: sort=name|desc

Returns the list sorted by column in ascending or descending order.

  ?sort=name|desc
header Parameters
X-API-TOKEN
required
string
Example: TOKEN

The API token to be used for authentication

X-Requested-With
required
string
Example: XMLHttpRequest

Used to send the XMLHttpRequest header

Responses

Request samples 

$ninja = new InvoiceNinja("your_token");
$invoices = $ninja->locations->all([]);

Response samples

Content type
application/json
{
  • "data": [
    ]
}

Create location

POST /api/v1/locations

Adds a location to a company

Authorizations:
ApiKeyAuth
query Parameters
index
string
Example: index=user

Replaces the default response index from data to a user specific string

ie.

  ?index=new_index

response is wrapped

  {
    'new_index' : [
      .....  
    ]
  }
header Parameters
X-API-TOKEN
required
string
Example: TOKEN

The API token to be used for authentication

X-Requested-With
required
string
Example: XMLHttpRequest

Used to send the XMLHttpRequest header

Request Body schema: application/json
required

Location object that needs to be added to the company

name
string

The location name

address1
string

The first line of the address

address2
string

The second line of the address

city
string

The city name

state
string

The state or region

postal_code
string

The postal or zip code

country_id
string

The ID of the associated country

custom_value1
string or null

Custom field value 1

custom_value2
string or null

Custom field value 2

custom_value3
string or null

Custom field value 3

custom_value4
string or null

Custom field value 4

is_shipping_location
boolean

Indicates if this is a shipping location

assigned_user_id
string

The assigned user hashed id

client_id
string

The client hashed id

vendor_id
string

The vendor hashed id

Responses

Request samples

Content type
application/json
{
  • "name": "Warehouse A",
  • "address1": "123 Business Street",
  • "address2": "Suite 100",
  • "city": "San Francisco",
  • "state": "CA",
  • "postal_code": "94107",
  • "country_id": "840",
  • "custom_value1": "string",
  • "custom_value2": "string",
  • "custom_value3": "string",
  • "custom_value4": "string",
  • "is_shipping_location": true,
  • "assigned_user_id": "Opnel5aKBz",
  • "client_id": "Opnel5aKBz",
  • "vendor_id": "Opnel5aKBz"
}

Response samples

Content type
application/json
{
  • "id": "Kd5S2M",
  • "name": "Warehouse A",
  • "address1": "123 Business Street",
  • "address2": "Suite 100",
  • "city": "San Francisco",
  • "state": "CA",
  • "postal_code": "94107",
  • "country_id": "840",
  • "custom_value1": "string",
  • "custom_value2": "string",
  • "custom_value3": "string",
  • "custom_value4": "string",
  • "is_deleted": false,
  • "is_shipping_location": true,
  • "user_id": "Opnel5aKBz",
  • "assigned_user_id": "Opnel5aKBz",
  • "client_id": "Opnel5aKBz",
  • "vendor_id": "Opnel5aKBz",
  • "created_at": 1623456789,
  • "updated_at": 1623456999
}

Show location

GET /api/v1/locations/{id}

Displays a location by id

Authorizations:
ApiKeyAuth
path Parameters
id
required
string <string>
Example: D2J234DFA

The Location Hashed ID

query Parameters
index
string
Example: index=user

Replaces the default response index from data to a user specific string

ie.

  ?index=new_index

response is wrapped

  {
    'new_index' : [
      .....  
    ]
  }
header Parameters
X-API-TOKEN
required
string
Example: TOKEN

The API token to be used for authentication

X-Requested-With
required
string
Example: XMLHttpRequest

Used to send the XMLHttpRequest header

Responses

Request samples 

$ninja = new InvoiceNinja("YOUR-TOKEN");
$location = $ninja->locations->show("D2J234DFA");

Response samples

Content type
application/json
{
  • "id": "Kd5S2M",
  • "name": "Warehouse A",
  • "address1": "123 Business Street",
  • "address2": "Suite 100",
  • "city": "San Francisco",
  • "state": "CA",
  • "postal_code": "94107",
  • "country_id": "840",
  • "custom_value1": "string",
  • "custom_value2": "string",
  • "custom_value3": "string",
  • "custom_value4": "string",
  • "is_deleted": false,
  • "is_shipping_location": true,
  • "user_id": "Opnel5aKBz",
  • "assigned_user_id": "Opnel5aKBz",
  • "client_id": "Opnel5aKBz",
  • "vendor_id": "Opnel5aKBz",
  • "created_at": 1623456789,
  • "updated_at": 1623456999
}

Update location

PUT /api/v1/locations/{id}

Handles the updating of a location by id

Authorizations:
ApiKeyAuth
path Parameters
id
required
string <string>
Example: D2J234DFA

The Location Hashed ID

query Parameters
index
string
Example: index=user

Replaces the default response index from data to a user specific string

ie.

  ?index=new_index

response is wrapped

  {
    'new_index' : [
      .....  
    ]
  }
header Parameters
X-API-TOKEN
required
string
Example: TOKEN

The API token to be used for authentication

X-Requested-With
required
string
Example: XMLHttpRequest

Used to send the XMLHttpRequest header

Request Body schema: application/json
required

Location object that needs to be updated

name
string

The location name

address1
string

The first line of the address

address2
string

The second line of the address

city
string

The city name

state
string

The state or region

postal_code
string

The postal or zip code

country_id
string

The ID of the associated country

custom_value1
string or null

Custom field value 1

custom_value2
string or null

Custom field value 2

custom_value3
string or null

Custom field value 3

custom_value4
string or null

Custom field value 4

is_shipping_location
boolean

Indicates if this is a shipping location

assigned_user_id
string

The assigned user hashed id

client_id
string

The client hashed id

vendor_id
string

The vendor hashed id

Responses

Request samples

Content type
application/json
{
  • "name": "Warehouse A",
  • "address1": "123 Business Street",
  • "address2": "Suite 100",
  • "city": "San Francisco",
  • "state": "CA",
  • "postal_code": "94107",
  • "country_id": "840",
  • "custom_value1": "string",
  • "custom_value2": "string",
  • "custom_value3": "string",
  • "custom_value4": "string",
  • "is_shipping_location": true,
  • "assigned_user_id": "Opnel5aKBz",
  • "client_id": "Opnel5aKBz",
  • "vendor_id": "Opnel5aKBz"
}

Response samples

Content type
application/json
{
  • "id": "Kd5S2M",
  • "name": "Warehouse A",
  • "address1": "123 Business Street",
  • "address2": "Suite 100",
  • "city": "San Francisco",
  • "state": "CA",
  • "postal_code": "94107",
  • "country_id": "840",
  • "custom_value1": "string",
  • "custom_value2": "string",
  • "custom_value3": "string",
  • "custom_value4": "string",
  • "is_deleted": false,
  • "is_shipping_location": true,
  • "user_id": "Opnel5aKBz",
  • "assigned_user_id": "Opnel5aKBz",
  • "client_id": "Opnel5aKBz",
  • "vendor_id": "Opnel5aKBz",
  • "created_at": 1623456789,
  • "updated_at": 1623456999
}

Delete location

DELETE /api/v1/locations/{id}

Handles the deletion of a location by id

Authorizations:
ApiKeyAuth
path Parameters
id
required
string <string>
Example: D2J234DFA

The Location Hashed ID

header Parameters
X-API-TOKEN
required
string
Example: TOKEN

The API token to be used for authentication

X-Requested-With
required
string
Example: XMLHttpRequest

Used to send the XMLHttpRequest header

Responses

Request samples 

$ninja = new InvoiceNinja("YOUR-TOKEN");
$ninja->locations->delete("D2J234DFA");

Response samples

Content type
application/json
{
  • "message": "These credentials do not match our records / Invalid Token"
}

Blank Location

GET /api/v1/locations/create

Returns a blank object with default values

Authorizations:
ApiKeyAuth
query Parameters
index
string
Example: index=user

Replaces the default response index from data to a user specific string

ie.

  ?index=new_index

response is wrapped

  {
    'new_index' : [
      .....  
    ]
  }
header Parameters
X-API-TOKEN
required
string
Example: TOKEN

The API token to be used for authentication

X-Requested-With
required
string
Example: XMLHttpRequest

Used to send the XMLHttpRequest header

Responses

Request samples 

$ninja = new InvoiceNinja("YOUR-TOKEN");
$location = $ninja->locations->model();

Response samples

Content type
application/json
{
  • "id": "Kd5S2M",
  • "name": "Warehouse A",
  • "address1": "123 Business Street",
  • "address2": "Suite 100",
  • "city": "San Francisco",
  • "state": "CA",
  • "postal_code": "94107",
  • "country_id": "840",
  • "custom_value1": "string",
  • "custom_value2": "string",
  • "custom_value3": "string",
  • "custom_value4": "string",
  • "is_deleted": false,
  • "is_shipping_location": true,
  • "user_id": "Opnel5aKBz",
  • "assigned_user_id": "Opnel5aKBz",
  • "client_id": "Opnel5aKBz",
  • "vendor_id": "Opnel5aKBz",
  • "created_at": 1623456789,
  • "updated_at": 1623456999
}

Bulk location actions

POST /api/v1/locations/bulk

Bulk actions allow to make changes to multiple locations in a single request. The following actions are supported:

  • archive
  • restore
  • delete

All of these actions require an array of location ids to perform the requested action on ie.

"ids":['id1','id2']

Authorizations:
ApiKeyAuth
query Parameters
index
string
Example: index=user

Replaces the default response index from data to a user specific string

ie.

  ?index=new_index

response is wrapped

  {
    'new_index' : [
      .....  
    ]
  }
header Parameters
X-API-TOKEN
required
string
Example: TOKEN

The API token to be used for authentication

X-Requested-With
required
string
Example: XMLHttpRequest

Used to send the XMLHttpRequest header

Request Body schema: application/json
required

Bulk action array

action
string

The action to perform ie. archive / restore / delete

ids
Array of strings <string> [ items <string > ]

Responses

Request samples

Content type
application/json
{
  • "action": "archive",
  • "ids": [
    ]
}

Response samples

Content type
application/json
{
  • "id": "Kd5S2M",
  • "name": "Warehouse A",
  • "address1": "123 Business Street",
  • "address2": "Suite 100",
  • "city": "San Francisco",
  • "state": "CA",
  • "postal_code": "94107",
  • "country_id": "840",
  • "custom_value1": "string",
  • "custom_value2": "string",
  • "custom_value3": "string",
  • "custom_value4": "string",
  • "is_deleted": false,
  • "is_shipping_location": true,
  • "user_id": "Opnel5aKBz",
  • "assigned_user_id": "Opnel5aKBz",
  • "client_id": "Opnel5aKBz",
  • "vendor_id": "Opnel5aKBz",
  • "created_at": 1623456789,
  • "updated_at": 1623456999
}

Products

Endpoint definitions for interacting with products.

List products

GET /api/v1/products

Lists products within your company.

You can search and filter the result set using query parameters. These can be chained together allowing fine grained lists to be generated.

Authorizations:
ApiKeyAuth
query Parameters
include
string
Example: include=first_load

Includes child relationships in the response, format is comma separated. Check each model for the list of associated includes

index
string
Example: index=user

Replaces the default response index from data to a user specific string

ie.

  ?index=new_index

response is wrapped

  {
    'new_index' : [
      .....  
    ]
  }
per_page
integer
Example: per_page=20

The number of records to return for each request, default is 20

page
integer
Example: page=1

The page number to return for this request (when performing pagination), default is 1

status
string
Example: status=?status=archived,deleted

Filter the entity based on their status. ie active / archived / deleted. Format is a comma separated string with any of the following options:

  • active
  • archived
  • deleted
GET /api/v1/invoices?status=archived,deleted
Returns only archived and deleted invoices
client_id
string
Example: client_id=?client_id={client_id}

Filters the entity list by client_id. Suitable when you only want the entities of a specific client.

GET /api/v1/invoices?client_id=AxB7Hjk9
Returns only invoices for the specified client
created_at
integer
Example: created_at=1641772800

Filters the entity list by the created at timestamp. Parameter value can be a datetime string or unix timestamp

GET /api/v1/invoices?created_at=2022-01-10
Returns entities created on January 10th, 2022
updated_at
integer
Example: updated_at=1641772800

Filters the entity list by the updated at timestamp. Parameter value can be a datetime string or unix timestamp

GET /api/v1/invoices?updated_at=2022-01-10
Returns entities last updated on January 10th, 2022
is_deleted
boolean
Example: is_deleted=true

Filters the entity list by entities that have been deleted.

GET /api/v1/invoices?is_deleted=true
Returns only soft-deleted entities
filter_deleted_clients
string
Example: filter_deleted_clients=?filter_deleted_clients=true

Filters the entity list and only returns entities for clients that have not been deleted

GET /api/v1/invoices?filter_deleted_clients=true
Returns only invoices for active (non-deleted) clients
vendor_id
string
Example: vendor_id=?vendor_id={vendor_id}

Filters the entity list by an associated vendor

GET /api/v1/purchases?vendor_id=AxB7Hjk9
Returns only purchases for the specified vendor
filter
string
Example: filter=bob

Filter by product name

product_key
string
Example: product_key=bob

Filter by product key

sort
string
Example: sort=id|desc product_key|desc

Returns the list sorted by column in ascending or descending order.

header Parameters
X-API-TOKEN
required
string
Example: TOKEN

The API token to be used for authentication

X-Requested-With
required
string
Example: XMLHttpRequest

Used to send the XMLHttpRequest header

Responses

Request samples 

$ninja = new InvoiceNinja("your_token");
$products = $ninja->products->all([
  'filter' => 'search',
  'per_page' => 20,
  'page' => 1,
  'include' => 'documents'
]);

Response samples

Content type
application/json
{
  • "data": [
    ],
  • "meta": {
    }
}

Create Product

POST /api/v1/products

Adds a product to a company

Authorizations:
ApiKeyAuth
query Parameters
include
string
Example: include=first_load

Includes child relationships in the response, format is comma separated. Check each model for the list of associated includes

header Parameters
X-API-TOKEN
required
string
Example: TOKEN

The API token to be used for authentication

X-Requested-With
required
string
Example: XMLHttpRequest

Used to send the XMLHttpRequest header

Request Body schema: application/json
required

Product object that needs to be added to the company

assigned_user_id
string

The hashed ID of the user assigned to this product.

project_id
string

The hashed ID of the project that this product is associated with.

vendor_id
string

The hashed ID of the vendor that this product is associated with.

custom_value1
string

Custom value field 1.

custom_value2
string

Custom value field 2.

custom_value3
string

Custom value field 3.

custom_value4
string

Custom value field 4.

product_key
string

The product key.

notes
string

Notes about the product.

cost
number <double>

The cost of the product.

price
number <double>

The price of the product.

quantity
number <double>
Default: 1

The quantity of the product.

tax_name1
string

The default tax name associated with this product

tax_rate1
number <double>

The default tax rate for this product

tax_name2
string

The default tax name associated with this product

tax_rate2
number <double>

The default tax rate for this product

tax_name3
string

The default tax name associated with this product

tax_rate3
number <double>

The default tax rate for this product

in_stock_quantity
integer <int32>
Default: 0

The quantity of the product that is currently in stock.

note this field is not mutable without passing an extra query parameter which will allow modification of this value.

The query parameter ?update_in_stock_quantity=true MUST be passed if you wish to update this value manually.

stock_notification
boolean
Default: true

Indicates whether stock notifications are enabled for this product

stock_notification_threshold
integer <int32>
Default: 0

The minimum quantity threshold for which stock notifications will be triggered

max_quantity
integer <int32>

The maximum quantity that can be ordered for this product

product_image
string <uri-reference>

The URL of the product image

tax_id
string
Default: "1"

The tax category id for this product.'

The following constants are available (default = '1')

PRODUCT_TYPE_PHYSICAL = '1'
PRODUCT_TYPE_SERVICE = '2'
PRODUCT_TYPE_DIGITAL = '3'
PRODUCT_TYPE_SHIPPING = '4'
PRODUCT_TYPE_EXEMPT = '5'
PRODUCT_TYPE_REDUCED_TAX = '6'
PRODUCT_TYPE_OVERRIDE_TAX = '7'
PRODUCT_TYPE_ZERO_RATED = '8'
PRODUCT_TYPE_REVERSE_TAX = '9'

Responses

Request samples

Content type
application/json
{
  • "assigned_user_id": "pR0j3",
  • "project_id": "pR0j3",
  • "vendor_id": "pR0j3",
  • "custom_value1": "Custom value 1",
  • "custom_value2": "Custom value 2",
  • "custom_value3": "Custom value 3",
  • "custom_value4": "Custom value 4",
  • "product_key": "1234",
  • "notes": "These are some notes about the product.",
  • "cost": 10,
  • "price": 20,
  • "quantity": 5,
  • "tax_name1": "Tax 1",
  • "tax_rate1": 10,
  • "tax_name2": "Tax 2",
  • "tax_rate2": 5,
  • "tax_name3": "Tax 3",
  • "tax_rate3": 0,
  • "in_stock_quantity": 0,
  • "stock_notification": true,
  • "stock_notification_threshold": 0,
  • "max_quantity": 0,
  • "product_image": "../dictionary",
  • "tax_id": "1"
}

Response samples

Content type
application/json
{
  • "id": "eP01N",
  • "user_id": "n30m4",
  • "assigned_user_id": "pR0j3",
  • "project_id": "pR0j3",
  • "vendor_id": "pR0j3",
  • "custom_value1": "Custom value 1",
  • "custom_value2": "Custom value 2",
  • "custom_value3": "Custom value 3",
  • "custom_value4": "Custom value 4",
  • "product_key": "1234",
  • "notes": "These are some notes about the product.",
  • "cost": 10,
  • "price": 20,
  • "quantity": 5,
  • "tax_name1": "Tax 1",
  • "tax_rate1": 10,
  • "tax_name2": "Tax 2",
  • "tax_rate2": 5,
  • "tax_name3": "Tax 3",
  • "tax_rate3": 0,
  • "archived_at": 1647604800,
  • "created_at": 1647604800,
  • "updated_at": 1647691496,
  • "is_deleted": false,
  • "in_stock_quantity": 0,
  • "stock_notification": true,
  • "stock_notification_threshold": 0,
  • "max_quantity": 0,
  • "product_image": "../dictionary",
  • "tax_id": "1"
}

Show product

GET /api/v1/products/{id}

Displays a product by id

Authorizations:
ApiKeyAuth
path Parameters
id
required
string <string>
Example: D2J234DFA

The Product Hashed ID

query Parameters
include
string
Example: include=first_load

Includes child relationships in the response, format is comma separated. Check each model for the list of associated includes

header Parameters
X-API-TOKEN
required
string
Example: TOKEN

The API token to be used for authentication

X-Requested-With
required
string
Example: XMLHttpRequest

Used to send the XMLHttpRequest header

Responses

Request samples 

$ninja = new InvoiceNinja("your_token");
$product = $ninja->products->show("{id}");

Response samples

Content type
application/json
{
  • "id": "eP01N",
  • "user_id": "n30m4",
  • "assigned_user_id": "pR0j3",
  • "project_id": "pR0j3",
  • "vendor_id": "pR0j3",
  • "custom_value1": "Custom value 1",
  • "custom_value2": "Custom value 2",
  • "custom_value3": "Custom value 3",
  • "custom_value4": "Custom value 4",
  • "product_key": "1234",
  • "notes": "These are some notes about the product.",
  • "cost": 10,
  • "price": 20,
  • "quantity": 5,
  • "tax_name1": "Tax 1",
  • "tax_rate1": 10,
  • "tax_name2": "Tax 2",
  • "tax_rate2": 5,
  • "tax_name3": "Tax 3",
  • "tax_rate3": 0,
  • "archived_at": 1647604800,
  • "created_at": 1647604800,
  • "updated_at": 1647691496,
  • "is_deleted": false,
  • "in_stock_quantity": 0,
  • "stock_notification": true,
  • "stock_notification_threshold": 0,
  • "max_quantity": 0,
  • "product_image": "../dictionary",
  • "tax_id": "1"
}

Update product

PUT /api/v1/products/{id}

Handles the updating of a product by id

Authorizations:
ApiKeyAuth
path Parameters
id
required
string <string>
Example: D2J234DFA

The Product Hashed ID

query Parameters
include
string
Example: include=first_load

Includes child relationships in the response, format is comma separated. Check each model for the list of associated includes

header Parameters
X-API-TOKEN
required
string
Example: TOKEN

The API token to be used for authentication

X-Requested-With
required
string
Example: XMLHttpRequest

Used to send the XMLHttpRequest header

Request Body schema: application/json
required

Product object that needs to be added to the company

assigned_user_id
string

The hashed ID of the user assigned to this product.

project_id
string

The hashed ID of the project that this product is associated with.

vendor_id
string

The hashed ID of the vendor that this product is associated with.

custom_value1
string

Custom value field 1.

custom_value2
string

Custom value field 2.

custom_value3
string

Custom value field 3.

custom_value4
string

Custom value field 4.

product_key
string

The product key.

notes
string

Notes about the product.

cost
number <double>

The cost of the product.

price
number <double>

The price of the product.

quantity
number <double>
Default: 1

The quantity of the product.

tax_name1
string

The default tax name associated with this product

tax_rate1
number <double>

The default tax rate for this product

tax_name2
string

The default tax name associated with this product

tax_rate2
number <double>

The default tax rate for this product

tax_name3
string

The default tax name associated with this product

tax_rate3
number <double>

The default tax rate for this product

in_stock_quantity
integer <int32>
Default: 0

The quantity of the product that is currently in stock.

note this field is not mutable without passing an extra query parameter which will allow modification of this value.

The query parameter ?update_in_stock_quantity=true MUST be passed if you wish to update this value manually.

stock_notification
boolean
Default: true

Indicates whether stock notifications are enabled for this product

stock_notification_threshold
integer <int32>
Default: 0

The minimum quantity threshold for which stock notifications will be triggered

max_quantity
integer <int32>

The maximum quantity that can be ordered for this product

product_image
string <uri-reference>

The URL of the product image

tax_id
string
Default: "1"

The tax category id for this product.'

The following constants are available (default = '1')

PRODUCT_TYPE_PHYSICAL = '1'
PRODUCT_TYPE_SERVICE = '2'
PRODUCT_TYPE_DIGITAL = '3'
PRODUCT_TYPE_SHIPPING = '4'
PRODUCT_TYPE_EXEMPT = '5'
PRODUCT_TYPE_REDUCED_TAX = '6'
PRODUCT_TYPE_OVERRIDE_TAX = '7'
PRODUCT_TYPE_ZERO_RATED = '8'
PRODUCT_TYPE_REVERSE_TAX = '9'

Responses

Request samples

Content type
application/json
{
  • "assigned_user_id": "pR0j3",
  • "project_id": "pR0j3",
  • "vendor_id": "pR0j3",
  • "custom_value1": "Custom value 1",
  • "custom_value2": "Custom value 2",
  • "custom_value3": "Custom value 3",
  • "custom_value4": "Custom value 4",
  • "product_key": "1234",
  • "notes": "These are some notes about the product.",
  • "cost": 10,
  • "price": 20,
  • "quantity": 5,
  • "tax_name1": "Tax 1",
  • "tax_rate1": 10,
  • "tax_name2": "Tax 2",
  • "tax_rate2": 5,
  • "tax_name3": "Tax 3",
  • "tax_rate3": 0,
  • "in_stock_quantity": 0,
  • "stock_notification": true,
  • "stock_notification_threshold": 0,
  • "max_quantity": 0,
  • "product_image": "../dictionary",
  • "tax_id": "1"
}

Response samples

Content type
application/json
{
  • "id": "eP01N",
  • "user_id": "n30m4",
  • "assigned_user_id": "pR0j3",
  • "project_id": "pR0j3",
  • "vendor_id": "pR0j3",
  • "custom_value1": "Custom value 1",
  • "custom_value2": "Custom value 2",
  • "custom_value3": "Custom value 3",
  • "custom_value4": "Custom value 4",
  • "product_key": "1234",
  • "notes": "These are some notes about the product.",
  • "cost": 10,
  • "price": 20,
  • "quantity": 5,
  • "tax_name1": "Tax 1",
  • "tax_rate1": 10,
  • "tax_name2": "Tax 2",
  • "tax_rate2": 5,
  • "tax_name3": "Tax 3",
  • "tax_rate3": 0,
  • "archived_at": 1647604800,
  • "created_at": 1647604800,
  • "updated_at": 1647691496,
  • "is_deleted": false,
  • "in_stock_quantity": 0,
  • "stock_notification": true,
  • "stock_notification_threshold": 0,
  • "max_quantity": 0,
  • "product_image": "../dictionary",
  • "tax_id": "1"
}

Delete product

DELETE /api/v1/products/{id}

Handles the deletion of a product by id

Authorizations:
ApiKeyAuth
path Parameters
id
required
string <string>
Example: D2J234DFA

The Product Hashed ID

query Parameters
include
string
Example: include=first_load

Includes child relationships in the response, format is comma separated. Check each model for the list of associated includes

header Parameters
X-API-TOKEN
required
string
Example: TOKEN

The API token to be used for authentication

X-Requested-With
required
string
Example: XMLHttpRequest

Used to send the XMLHttpRequest header

Responses

Request samples 

$ninja = new InvoiceNinja("your_token");
$ninja->products->bulk([
    'action' => 'delete',
    'ids' => ['productId1', 'productId2']
]);

Response samples

Content type
application/json
{
  • "message": "These credentials do not match our records / Invalid Token"
}

Edit product

GET /api/v1/products/{id}/edit

Displays an Product by id

Authorizations:
ApiKeyAuth
path Parameters
id
required
string <string>
Example: D2J234DFA

The Product Hashed ID

query Parameters
include
string
Example: include=first_load

Includes child relationships in the response, format is comma separated. Check each model for the list of associated includes

header Parameters
X-API-TOKEN
required
string
Example: TOKEN

The API token to be used for authentication

X-Requested-With
required
string
Example: XMLHttpRequest

Used to send the XMLHttpRequest header

Responses

Request samples 

$ninja = new InvoiceNinja("your_token");
$product = $ninja->products->show("{id}");

Response samples

Content type
application/json
{
  • "id": "eP01N",
  • "user_id": "n30m4",
  • "assigned_user_id": "pR0j3",
  • "project_id": "pR0j3",
  • "vendor_id": "pR0j3",
  • "custom_value1": "Custom value 1",
  • "custom_value2": "Custom value 2",
  • "custom_value3": "Custom value 3",
  • "custom_value4": "Custom value 4",
  • "product_key": "1234",
  • "notes": "These are some notes about the product.",
  • "cost": 10,
  • "price": 20,
  • "quantity": 5,
  • "tax_name1": "Tax 1",
  • "tax_rate1": 10,
  • "tax_name2": "Tax 2",
  • "tax_rate2": 5,
  • "tax_name3": "Tax 3",
  • "tax_rate3": 0,
  • "archived_at": 1647604800,
  • "created_at": 1647604800,
  • "updated_at": 1647691496,
  • "is_deleted": false,
  • "in_stock_quantity": 0,
  • "stock_notification": true,
  • "stock_notification_threshold": 0,
  • "max_quantity": 0,
  • "product_image": "../dictionary",
  • "tax_id": "1"
}

Blank product

GET /api/v1/products/create

Returns a blank product object with default values

Authorizations:
ApiKeyAuth
query Parameters
include
string
Example: include=first_load

Includes child relationships in the response, format is comma separated. Check each model for the list of associated includes

header Parameters
X-API-TOKEN
required
string
Example: TOKEN

The API token to be used for authentication

X-Requested-With
required
string
Example: XMLHttpRequest

Used to send the XMLHttpRequest header

Responses

Request samples 

$ninja = new InvoiceNinja("your_token");
$product = $ninja->products->model();

Response samples

Content type
application/json
{
  • "id": "eP01N",
  • "user_id": "n30m4",
  • "assigned_user_id": "pR0j3",
  • "project_id": "pR0j3",
  • "vendor_id": "pR0j3",
  • "custom_value1": "Custom value 1",
  • "custom_value2": "Custom value 2",
  • "custom_value3": "Custom value 3",
  • "custom_value4": "Custom value 4",
  • "product_key": "1234",
  • "notes": "These are some notes about the product.",
  • "cost": 10,
  • "price": 20,
  • "quantity": 5,
  • "tax_name1": "Tax 1",
  • "tax_rate1": 10,
  • "tax_name2": "Tax 2",
  • "tax_rate2": 5,
  • "tax_name3": "Tax 3",
  • "tax_rate3": 0,
  • "archived_at": 1647604800,
  • "created_at": 1647604800,
  • "updated_at": 1647691496,
  • "is_deleted": false,
  • "in_stock_quantity": 0,
  • "stock_notification": true,
  • "stock_notification_threshold": 0,
  • "max_quantity": 0,
  • "product_image": "../dictionary",
  • "tax_id": "1"
}

Bulk product actions

POST /api/v1/products/bulk

Archive / Restore / Delete / Set tax id in bulk

Authorizations:
ApiKeyAuth
query Parameters
index
string
Example: index=user

Replaces the default response index from data to a user specific string

ie.

  ?index=new_index

response is wrapped

  {
    'new_index' : [
      .....  
    ]
  }
header Parameters
X-API-TOKEN
required
string
Example: TOKEN

The API token to be used for authentication

X-Requested-With
required
string
Example: XMLHttpRequest

Used to send the XMLHttpRequest header

Request Body schema: application/json
required

Bulk action array

action
required
string

The action to perform ie. archive / restore / delete / set_tax_id

ids
required
Array of strings <string> [ items <string > ]
tax_id
string

The tax rate id to set on the list of products

The following constants are available (default = '1')

PRODUCT_TYPE_PHYSICAL = '1'
PRODUCT_TYPE_SERVICE = '2'
PRODUCT_TYPE_DIGITAL = '3'
PRODUCT_TYPE_SHIPPING = '4'
PRODUCT_TYPE_EXEMPT = '5'
PRODUCT_TYPE_REDUCED_TAX = '6'
PRODUCT_TYPE_OVERRIDE_TAX = '7'
PRODUCT_TYPE_ZERO_RATED = '8'
PRODUCT_TYPE_REVERSE_TAX = '9'

Responses

Request samples

Content type
application/json
{
  • "action": "archive",
  • "ids": [
    ],
  • "tax_id": "1"
}

Response samples

Content type
application/json
{
  • "id": "eP01N",
  • "user_id": "n30m4",
  • "assigned_user_id": "pR0j3",
  • "project_id": "pR0j3",
  • "vendor_id": "pR0j3",
  • "custom_value1": "Custom value 1",
  • "custom_value2": "Custom value 2",
  • "custom_value3": "Custom value 3",
  • "custom_value4": "Custom value 4",
  • "product_key": "1234",
  • "notes": "These are some notes about the product.",
  • "cost": 10,
  • "price": 20,
  • "quantity": 5,
  • "tax_name1": "Tax 1",
  • "tax_rate1": 10,
  • "tax_name2": "Tax 2",
  • "tax_rate2": 5,
  • "tax_name3": "Tax 3",
  • "tax_rate3": 0,
  • "archived_at": 1647604800,
  • "created_at": 1647604800,
  • "updated_at": 1647691496,
  • "is_deleted": false,
  • "in_stock_quantity": 0,
  • "stock_notification": true,
  • "stock_notification_threshold": 0,
  • "max_quantity": 0,
  • "product_image": "../dictionary",
  • "tax_id": "1"
}

Add product document

POST /api/v1/products/{id}/upload

Handles the uploading of a document to a product"

Authorizations:
ApiKeyAuth
path Parameters
id
required
string <string>
Example: D2J234DFA

The Product Hashed ID

query Parameters
include
string
Examples:
  • include=activities - include=activities will include the activities object in the response
  • include=ledger - include=ledger will include the ledger object in the response
  • include=system_logs - include=system_logs will include the system_logs object in the response

Include child relationships of the Client Object. ie ?include=documents,system_logs

Available includes:

contacts [All contacts related to the client]
documents [All documents related to the client]
gateway_tokens [All payment tokens related to the client]
activities [All activities related to the client]
ledger [The client ledger]
system_logs [System logs related to the client]
group_settings [The group settings object the client is assigned to]

Usage:

/api/v1/clients?include=contacts,documents,activities
header Parameters
X-API-TOKEN
required
string
Example: TOKEN

The API token to be used for authentication

X-Requested-With
required
string
Example: XMLHttpRequest

Used to send the XMLHttpRequest header

Request Body schema: multipart/form-data
required
_method
string
documents
Array of any <binary> [ items <binary > ]

Responses

Request samples 

$ninja = new InvoiceNinja("your_token");
$product = $ninja->products->upload("id", "document");

Response samples

Content type
application/json
{
  • "id": "eP01N",
  • "user_id": "n30m4",
  • "assigned_user_id": "pR0j3",
  • "project_id": "pR0j3",
  • "vendor_id": "pR0j3",
  • "custom_value1": "Custom value 1",
  • "custom_value2": "Custom value 2",
  • "custom_value3": "Custom value 3",
  • "custom_value4": "Custom value 4",
  • "product_key": "1234",
  • "notes": "These are some notes about the product.",
  • "cost": 10,
  • "price": 20,
  • "quantity": 5,
  • "tax_name1": "Tax 1",
  • "tax_rate1": 10,
  • "tax_name2": "Tax 2",
  • "tax_rate2": 5,
  • "tax_name3": "Tax 3",
  • "tax_rate3": 0,
  • "archived_at": 1647604800,
  • "created_at": 1647604800,
  • "updated_at": 1647691496,
  • "is_deleted": false,
  • "in_stock_quantity": 0,
  • "stock_notification": true,
  • "stock_notification_threshold": 0,
  • "max_quantity": 0,
  • "product_image": "../dictionary",
  • "tax_id": "1"
}

Invoices

Invoice Statuses

  • STATUS_DRAFT = 1
    • Draft invoices are not visible in the client portal, are not active and they do not impact the client balance
  • STATUS_SENT = 2
    • Send invoices are visible in the client portal, are active and impact the client balance
  • STATUS_PARTIAL = 3
    • An invoice which has been partially paid
  • STATUS_PAID = 4
    • An invoice which has been fully paid
  • STATUS_CANCELLED = 5
    • When a invoice is cancelled the invoice balance is set to zero and the status updated to Cancelled, the client balance is also adjusted down. If payments have been applied to the invoice these will remain linked to the invoice
  • STATUS_REVERSED = 6
    • When a invoice has been reversed, the previous payments relationships are unlinked and cannot be restored
  • STATUS_OVERDUE = -1
    • An invoice which is still payable past its due date
  • STATUS_UNPAID = -2
    • An invoice which is not yet due, but also, not paid

List invoices

GET /api/v1/invoices

Lists invoices with the option to chain multiple query parameters allowing fine grained filtering of the list.

Authorizations:
ApiKeyAuth
query Parameters
include
string
Example: include=first_load

Includes child relationships in the response, format is comma separated. Check each model for the list of associated includes

index
string
Example: index=user

Replaces the default response index from data to a user specific string

ie.

  ?index=new_index

response is wrapped

  {
    'new_index' : [
      .....  
    ]
  }
per_page
integer
Example: per_page=20

The number of records to return for each request, default is 20

page
integer
Example: page=1

The page number to return for this request (when performing pagination), default is 1

status
string
Example: status=?status=archived,deleted

Filter the entity based on their status. ie active / archived / deleted. Format is a comma separated string with any of the following options:

  • active
  • archived
  • deleted
GET /api/v1/invoices?status=archived,deleted
Returns only archived and deleted invoices
client_id
string
Example: client_id=?client_id={client_id}

Filters the entity list by client_id. Suitable when you only want the entities of a specific client.

GET /api/v1/invoices?client_id=AxB7Hjk9
Returns only invoices for the specified client
created_at
integer
Example: created_at=1641772800

Filters the entity list by the created at timestamp. Parameter value can be a datetime string or unix timestamp

GET /api/v1/invoices?created_at=2022-01-10
Returns entities created on January 10th, 2022
updated_at
integer
Example: updated_at=1641772800

Filters the entity list by the updated at timestamp. Parameter value can be a datetime string or unix timestamp

GET /api/v1/invoices?updated_at=2022-01-10
Returns entities last updated on January 10th, 2022
is_deleted
boolean
Example: is_deleted=true

Filters the entity list by entities that have been deleted.

GET /api/v1/invoices?is_deleted=true
Returns only soft-deleted entities
filter_deleted_clients
string
Example: filter_deleted_clients=?filter_deleted_clients=true

Filters the entity list and only returns entities for clients that have not been deleted

GET /api/v1/invoices?filter_deleted_clients=true
Returns only invoices for active (non-deleted) clients
vendor_id
string
Example: vendor_id=?vendor_id={vendor_id}

Filters the entity list by an associated vendor

GET /api/v1/purchases?vendor_id=AxB7Hjk9
Returns only purchases for the specified vendor
client_status
string
Example: client_status=?client_status=paid,unpaid

A comma separated list of invoice status strings. Valid options include:

  • all
  • paid
  • unpaid
  • overdue
number
string
Example: number=?number=INV-001

Search invoices by invoice number

filter
string
Example: filter=?filter=bob

Searches across a range of columns including:

  • number
  • po_number
  • date
  • amount
  • balance
  • custom_value1
  • custom_value2
  • custom_value3
  • custom_value4
  • client.name
  • client.contacts.[first_name, last_name, email]
  • line_items.[product_key, notes]
without_deleted_clients
string
Example: without_deleted_clients=?without_deleted_clients=

Returns the invoice list without the invoices of deleted clients.

overdue
string
Example: overdue=?overdue=

Returns the list of invoices that are overdue

payable
string
Example: payable=?payable={client_id}

Returns the invoice list that are payable for a defined client. Please note, you must pass the client_id as the value for this query parameter

sort
string
Example: sort=id|desc number|desc balance|asc

Returns the list sorted by column in ascending or descending order.

private_notes
string
Example: private_notes=?private_notes=super secret

Searches on the private_notes field of the invoices

date
string
Example: date=?date=2022-01-01

Filters the invoices by invoice date returns a list of invoices after (and including) the date

date_range
string
Example: date_range=?date_range=2022-01-01,2022-01-31

Filters the invoices by invoice date returns a list of invoices between two dates

status_id
integer
Example: status_id=1

Filters the invoices by status id

  STATUS_DRAFT = 1;
  STATUS_SENT = 2;
  STATUS_PARTIAL = 3;
  STATUS_PAID = 4;
  STATUS_CANCELLED = 5;
  STATUS_REVERSED = 6;
header Parameters
X-API-TOKEN
required
string
Example: TOKEN

The API token to be used for authentication

X-Requested-With
required
string
Example: XMLHttpRequest

Used to send the XMLHttpRequest header

Responses

Request samples 

$ninja = new InvoiceNinja("your_token");
$invoices = $ninja->invoices->all([
  'per_page' => 10,
  'page' => 1,
  'sort' => 'number|asc'
]);

Response samples

Content type
application/json
{
  • "data": [
    ],
  • "meta": {
    }
}

Create invoice

POST /api/v1/invoices

Creates an invoice for a client.

Triggered actions are available when updating or creating an invoice.

These are query parameters that can be chained in order to perform additional actions on the entity, these include:

?send_email=true [Saves and sends the invoice]
?mark_sent=true [Saves and marks the invoice as sent]
?paid=true [Saves and marks the invoice as paid]
?amount_paid=100 [Saves and marks the invoice as paid with the given amount]
?cancel=true [Saves and marks the invoice as cancelled]
?save_default_footer=true [Saves the current footer as the default footer]
?save_default_terms=true [Saves the current terms as the default terms]
?retry_e_send=true [Saves and retries the e-send for the invoice]
?redirect=https://example.com [Saves and redirects to the given url]
Authorizations:
ApiKeyAuth
query Parameters
include
string
Example: include=first_load

Includes child relationships in the response, format is comma separated. Check each model for the list of associated includes

header Parameters
X-API-TOKEN
required
string
Example: TOKEN

The API token to be used for authentication

X-Requested-With
required
string
Example: XMLHttpRequest

Used to send the XMLHttpRequest header

Request Body schema: application/json
required
user_id
string

The user hashed id

assigned_user_id
string

The assigned user hashed id

client_id
required
string

The client hashed id

location_id
string

The location id of the client this request related to

number
string

The invoice number - is a unique alpha numeric number per invoice per company

po_number
string

The purchase order associated with this invoice

terms
string

The invoice terms

public_notes
string

The public notes of the invoice

private_notes
string

The private notes of the invoice

footer
string

The invoice footer notes

custom_value1
string

A custom field value

custom_value2
string

A custom field value

custom_value3
string

A custom field value

custom_value4
string

A custom field value

tax_name1
string

The tax name

tax_name2
string

The tax name

tax_rate1
number <float>

The tax rate

tax_rate2
number <float>

The tax rate

tax_name3
string

The tax name

tax_rate3
number <float>

The tax rate

Array of objects (InvoiceItem)

An array of objects which define the line items of the invoice

Array of objects (InvoiceInvitationRequest)

An array of objects which define the invitations of the invoice

discount
number <float>

The invoice discount, can be an amount or a percentage

partial
number <float>

The deposit/partial amount

is_amount_discount
boolean

Flag determining if the discount is an amount or a percentage

uses_inclusive_taxes
boolean

Defines the type of taxes used as either inclusive or exclusive

date
string <date>

The Invoice Date

partial_due_date
string <date>

The due date for the deposit/partial amount

due_date
string <date>

The due date of the invoice

custom_surcharge1
number <float>

First Custom Surcharge

custom_surcharge2
number <float>

Second Custom Surcharge

custom_surcharge3
number <float>

Third Custom Surcharge

custom_surcharge4
number <float>

Fourth Custom Surcharge

custom_surcharge_tax1
boolean

Toggles charging taxes on custom surcharge amounts

custom_surcharge_tax2
boolean

Toggles charging taxes on custom surcharge amounts

custom_surcharge_tax3
boolean

Toggles charging taxes on custom surcharge amounts

custom_surcharge_tax4
boolean

Toggles charging taxes on custom surcharge amounts

project_id
string

The project associated with this invoice

Responses

Request samples

Content type
application/json
{
  • "user_id": "AxP7K9nY5z",
  • "assigned_user_id": "Bw2M8vR4qL",
  • "client_id": "Ht5N9cX3jK",
  • "location_id": "Opnel5aKBz",
  • "number": "INV-2024-0001",
  • "po_number": "PO-2024-0123",
  • "terms": "Net 30 - Payment is due within 30 days of invoice date",
  • "public_notes": "Thank you for your business. Please include invoice number with payment.",
  • "private_notes": "Client requested expedited delivery - premium rates apply",
  • "footer": "Payment accepted via bank transfer or credit card",
  • "custom_value1": "Department: Sales",
  • "custom_value2": "Region: North America",
  • "custom_value3": "Contract: C-2024-156",
  • "custom_value4": "Priority: High",
  • "tax_name1": "VAT",
  • "tax_name2": "GST",
  • "tax_rate1": 20,
  • "tax_rate2": 5,
  • "tax_name3": "State Tax",
  • "tax_rate3": 8.5,
  • "line_items": [
    ],
  • "invitations": [
    ],
  • "discount": 15,
  • "partial": 250,
  • "is_amount_discount": true,
  • "uses_inclusive_taxes": true,
  • "date": "2024-03-15",
  • "partial_due_date": "2024-03-29",
  • "due_date": "2024-04-14",
  • "custom_surcharge1": 25,
  • "custom_surcharge2": 35,
  • "custom_surcharge3": 45,
  • "custom_surcharge4": 55,
  • "custom_surcharge_tax1": true,
  • "custom_surcharge_tax2": true,
  • "custom_surcharge_tax3": true,
  • "custom_surcharge_tax4": true,
  • "project_id": "Opnel5aKBz"
}

Response samples

Content type
application/json
{
  • "id": "Opnel5aKBz",
  • "user_id": "Opnel5aKBz",
  • "assigned_user_id": "Opnel5aKBz",
  • "client_id": "Opnel5aKBz",
  • "status_id": "4",
  • "number": "INV_101",
  • "po_number": "PO-1234",
  • "terms": "These are invoice terms",
  • "public_notes": "These are some public notes",
  • "private_notes": "These are some private notes",
  • "footer": "",
  • "custom_value1": "2022-10-01",
  • "custom_value2": "Something custom",
  • "custom_value3": "",
  • "custom_value4": "",
  • "tax_name1": "",
  • "tax_name2": "",
  • "tax_rate1": 10,
  • "tax_rate2": 10,
  • "tax_name3": "",
  • "tax_rate3": 10,
  • "total_taxes": 10,
  • "line_items": [
    ],
  • "invitations": [
    ],
  • "amount": 10,
  • "balance": 10,
  • "paid_to_date": 10,
  • "discount": 10,
  • "partial": 10,
  • "is_amount_discount": true,
  • "is_deleted": true,
  • "uses_inclusive_taxes": true,
  • "date": "1994-07-30",
  • "last_sent_date": "1994-07-30",
  • "next_send_date": "1994-07-30",
  • "partial_due_date": "1994-07-30",
  • "due_date": "1994-07-30",
  • "last_viewed": 1434342123,
  • "updated_at": 1434342123,
  • "archived_at": 1434342123,
  • "custom_surcharge1": 10,
  • "custom_surcharge2": 10,
  • "custom_surcharge3": 10,
  • "custom_surcharge4": 10,
  • "custom_surcharge_tax1": true,
  • "custom_surcharge_tax2": true,
  • "custom_surcharge_tax3": true,
  • "custom_surcharge_tax4": true,
  • "project_id": "Opnel5aKBz",
  • "auto_bill_tries": 1,
  • "auto_bill_enabled": true,
  • "subscription_id": "Opnel5aKBz",
  • "location_id": "Opnel5aKBz",
  • "design_id": "Opnel5aKBz",
  • "e_invoice": { },
  • "exchange_rate": 1,
  • "vendor_id": "Opnel5aKBz"
}

Show invoice

GET /api/v1/invoices/{id}

Displays an invoice by id

Authorizations:
ApiKeyAuth
path Parameters
id
required
string <string>
Example: D2J234DFA

The Invoice Hashed ID

query Parameters
include
string
Example: include=first_load

Includes child relationships in the response, format is comma separated. Check each model for the list of associated includes

header Parameters
X-API-TOKEN
required
string
Example: TOKEN

The API token to be used for authentication

X-Requested-With
required
string
Example: XMLHttpRequest

Used to send the XMLHttpRequest header

Responses

Request samples 

$ninja = new InvoiceNinja("your_token");
$invoice = $ninja->invoices->get("D2J234DFA");

Response samples

Content type
application/json
{
  • "id": "Opnel5aKBz",
  • "user_id": "Opnel5aKBz",
  • "assigned_user_id": "Opnel5aKBz",
  • "client_id": "Opnel5aKBz",
  • "status_id": "4",
  • "number": "INV_101",
  • "po_number": "PO-1234",
  • "terms": "These are invoice terms",
  • "public_notes": "These are some public notes",
  • "private_notes": "These are some private notes",
  • "footer": "",
  • "custom_value1": "2022-10-01",
  • "custom_value2": "Something custom",
  • "custom_value3": "",
  • "custom_value4": "",
  • "tax_name1": "",
  • "tax_name2": "",
  • "tax_rate1": 10,
  • "tax_rate2": 10,
  • "tax_name3": "",
  • "tax_rate3": 10,
  • "total_taxes": 10,
  • "line_items": [
    ],
  • "invitations": [
    ],
  • "amount": 10,
  • "balance": 10,
  • "paid_to_date": 10,
  • "discount": 10,
  • "partial": 10,
  • "is_amount_discount": true,
  • "is_deleted": true,
  • "uses_inclusive_taxes": true,
  • "date": "1994-07-30",
  • "last_sent_date": "1994-07-30",
  • "next_send_date": "1994-07-30",
  • "partial_due_date": "1994-07-30",
  • "due_date": "1994-07-30",
  • "last_viewed": 1434342123,
  • "updated_at": 1434342123,
  • "archived_at": 1434342123,
  • "custom_surcharge1": 10,
  • "custom_surcharge2": 10,
  • "custom_surcharge3": 10,
  • "custom_surcharge4": 10,
  • "custom_surcharge_tax1": true,
  • "custom_surcharge_tax2": true,
  • "custom_surcharge_tax3": true,
  • "custom_surcharge_tax4": true,
  • "project_id": "Opnel5aKBz",
  • "auto_bill_tries": 1,
  • "auto_bill_enabled": true,
  • "subscription_id": "Opnel5aKBz",
  • "location_id": "Opnel5aKBz",
  • "design_id": "Opnel5aKBz",
  • "e_invoice": { },
  • "exchange_rate": 1,
  • "vendor_id": "Opnel5aKBz"
}

Update invoice

PUT /api/v1/invoices/{id}

Handles the updating of an invoice by id.

Triggered actions are available when updating or creating an invoice.
These are query parameters that can be chained in order to perform additional actions on the entity, these include:

?send_email=true [Saves and sends the invoice]
?mark_sent=true [Saves and marks the invoice as sent]
?paid=true [Saves and marks the invoice as paid]
?amount_paid=100 [Saves and marks the invoice as paid with the given amount]
?cancel=true [Saves and marks the invoice as cancelled]
?save_default_footer=true [Saves the current footer as the default footer]
?save_default_terms=true [Saves the current terms as the default terms]
?retry_e_send=true [Saves and retries the e-send for the invoice]
?redirect=https://example.com [Saves and redirects to the given url]
Authorizations:
ApiKeyAuth
path Parameters
id
required
string <string>
Example: D2J234DFA

The Invoice Hashed ID

query Parameters
include
string
Example: include=first_load

Includes child relationships in the response, format is comma separated. Check each model for the list of associated includes

header Parameters
X-API-TOKEN
required
string
Example: TOKEN

The API token to be used for authentication

X-Requested-With
required
string
Example: XMLHttpRequest

Used to send the XMLHttpRequest header

Responses

Request samples 

$ninja = new InvoiceNinja("your_token");
$invoice = $ninja->invoices->update("D2J234DFA", [
  'date' => '2022-01-01',
  'due_date' => '2022-01-31',
  'private_notes' => 'super secret',
  'public_notes' => 'public notes',
  'line_items' => [
    [
      'product_key' => 'sku_4_u',
      'notes' => 'The actual product description',
    ]
  ]
]);

Response samples

Content type
application/json
{
  • "id": "Opnel5aKBz",
  • "user_id": "Opnel5aKBz",
  • "assigned_user_id": "Opnel5aKBz",
  • "client_id": "Opnel5aKBz",
  • "status_id": "4",
  • "number": "INV_101",
  • "po_number": "PO-1234",
  • "terms": "These are invoice terms",
  • "public_notes": "These are some public notes",
  • "private_notes": "These are some private notes",
  • "footer": "",
  • "custom_value1": "2022-10-01",
  • "custom_value2": "Something custom",
  • "custom_value3": "",
  • "custom_value4": "",
  • "tax_name1": "",
  • "tax_name2": "",
  • "tax_rate1": 10,
  • "tax_rate2": 10,
  • "tax_name3": "",
  • "tax_rate3": 10,
  • "total_taxes": 10,
  • "line_items": [
    ],
  • "invitations": [
    ],
  • "amount": 10,
  • "balance": 10,
  • "paid_to_date": 10,
  • "discount": 10,
  • "partial": 10,
  • "is_amount_discount": true,
  • "is_deleted": true,
  • "uses_inclusive_taxes": true,
  • "date": "1994-07-30",
  • "last_sent_date": "1994-07-30",
  • "next_send_date": "1994-07-30",
  • "partial_due_date": "1994-07-30",
  • "due_date": "1994-07-30",
  • "last_viewed": 1434342123,
  • "updated_at": 1434342123,
  • "archived_at": 1434342123,
  • "custom_surcharge1": 10,
  • "custom_surcharge2": 10,
  • "custom_surcharge3": 10,
  • "custom_surcharge4": 10,
  • "custom_surcharge_tax1": true,
  • "custom_surcharge_tax2": true,
  • "custom_surcharge_tax3": true,
  • "custom_surcharge_tax4": true,
  • "project_id": "Opnel5aKBz",
  • "auto_bill_tries": 1,
  • "auto_bill_enabled": true,
  • "subscription_id": "Opnel5aKBz",
  • "location_id": "Opnel5aKBz",
  • "design_id": "Opnel5aKBz",
  • "e_invoice": { },
  • "exchange_rate": 1,
  • "vendor_id": "Opnel5aKBz"
}

Delete invoice

DELETE /api/v1/invoices/{id}

Handles the deletion of an invoice by id.

Authorizations:
ApiKeyAuth
path Parameters
id
required
string <string>
Example: D2J234DFA

The Invoice Hashed ID

query Parameters
include
string
Example: include=first_load

Includes child relationships in the response, format is comma separated. Check each model for the list of associated includes

header Parameters
X-API-TOKEN
required
string
Example: TOKEN

The API token to be used for authentication

X-Requested-With
required
string
Example: XMLHttpRequest

Used to send the XMLHttpRequest header

Responses

Request samples 

$ninja = new InvoiceNinja("your_token");
$ninja->invoices->delete("D2J234DFA");

Response samples

Content type
application/json
{
  • "message": "These credentials do not match our records / Invalid Token"
}

Edit invoice

GET /api/v1/invoices/{id}/edit

Displays an invoice by id for editting

Authorizations:
ApiKeyAuth
path Parameters
id
required
string <string>
Example: D2J234DFA

The Invoice Hashed ID

query Parameters
include
string
Example: include=first_load

Includes child relationships in the response, format is comma separated. Check each model for the list of associated includes

header Parameters
X-API-TOKEN
required
string
Example: TOKEN

The API token to be used for authentication

X-Requested-With
required
string
Example: XMLHttpRequest

Used to send the XMLHttpRequest header

Responses

Request samples 

$ninja = new InvoiceNinja("your_token");
$invoice = $ninja->invoices->show("D2J234DFA");

Response samples

Content type
application/json
{
  • "id": "Opnel5aKBz",
  • "user_id": "Opnel5aKBz",
  • "assigned_user_id": "Opnel5aKBz",
  • "client_id": "Opnel5aKBz",
  • "status_id": "4",
  • "number": "INV_101",
  • "po_number": "PO-1234",
  • "terms": "These are invoice terms",
  • "public_notes": "These are some public notes",
  • "private_notes": "These are some private notes",
  • "footer": "",
  • "custom_value1": "2022-10-01",
  • "custom_value2": "Something custom",
  • "custom_value3": "",
  • "custom_value4": "",
  • "tax_name1": "",
  • "tax_name2": "",
  • "tax_rate1": 10,
  • "tax_rate2": 10,
  • "tax_name3": "",
  • "tax_rate3": 10,
  • "total_taxes": 10,
  • "line_items": [
    ],
  • "invitations": [
    ],
  • "amount": 10,
  • "balance": 10,
  • "paid_to_date": 10,
  • "discount": 10,
  • "partial": 10,
  • "is_amount_discount": true,
  • "is_deleted": true,
  • "uses_inclusive_taxes": true,
  • "date": "1994-07-30",
  • "last_sent_date": "1994-07-30",
  • "next_send_date": "1994-07-30",
  • "partial_due_date": "1994-07-30",
  • "due_date": "1994-07-30",
  • "last_viewed": 1434342123,
  • "updated_at": 1434342123,
  • "archived_at": 1434342123,
  • "custom_surcharge1": 10,
  • "custom_surcharge2": 10,
  • "custom_surcharge3": 10,
  • "custom_surcharge4": 10,
  • "custom_surcharge_tax1": true,
  • "custom_surcharge_tax2": true,
  • "custom_surcharge_tax3": true,
  • "custom_surcharge_tax4": true,
  • "project_id": "Opnel5aKBz",
  • "auto_bill_tries": 1,
  • "auto_bill_enabled": true,
  • "subscription_id": "Opnel5aKBz",
  • "location_id": "Opnel5aKBz",
  • "design_id": "Opnel5aKBz",
  • "e_invoice": { },
  • "exchange_rate": 1,
  • "vendor_id": "Opnel5aKBz"
}

Blank invoice

GET /api/v1/invoices/create

Returns a blank object with default values

Authorizations:
ApiKeyAuth

Responses

Request samples 

$ninja = new InvoiceNinja("your_token");
$invoice = $ninja->invoices->model();

Response samples

Content type
application/json
{
  • "id": "Opnel5aKBz",
  • "user_id": "Opnel5aKBz",
  • "assigned_user_id": "Opnel5aKBz",
  • "client_id": "Opnel5aKBz",
  • "status_id": "4",
  • "number": "INV_101",
  • "po_number": "PO-1234",
  • "terms": "These are invoice terms",
  • "public_notes": "These are some public notes",
  • "private_notes": "These are some private notes",
  • "footer": "",
  • "custom_value1": "2022-10-01",
  • "custom_value2": "Something custom",
  • "custom_value3": "",
  • "custom_value4": "",
  • "tax_name1": "",
  • "tax_name2": "",
  • "tax_rate1": 10,
  • "tax_rate2": 10,
  • "tax_name3": "",
  • "tax_rate3": 10,
  • "total_taxes": 10,
  • "line_items": [
    ],
  • "invitations": [
    ],
  • "amount": 10,
  • "balance": 10,
  • "paid_to_date": 10,
  • "discount": 10,
  • "partial": 10,
  • "is_amount_discount": true,
  • "is_deleted": true,
  • "uses_inclusive_taxes": true,
  • "date": "1994-07-30",
  • "last_sent_date": "1994-07-30",
  • "next_send_date": "1994-07-30",
  • "partial_due_date": "1994-07-30",
  • "due_date": "1994-07-30",
  • "last_viewed": 1434342123,
  • "updated_at": 1434342123,
  • "archived_at": 1434342123,
  • "custom_surcharge1": 10,
  • "custom_surcharge2": 10,
  • "custom_surcharge3": 10,
  • "custom_surcharge4": 10,
  • "custom_surcharge_tax1": true,
  • "custom_surcharge_tax2": true,
  • "custom_surcharge_tax3": true,
  • "custom_surcharge_tax4": true,
  • "project_id": "Opnel5aKBz",
  • "auto_bill_tries": 1,
  • "auto_bill_enabled": true,
  • "subscription_id": "Opnel5aKBz",
  • "location_id": "Opnel5aKBz",
  • "design_id": "Opnel5aKBz",
  • "e_invoice": { },
  • "exchange_rate": 1,
  • "vendor_id": "Opnel5aKBz"
}

Bulk invoice actions

POST /api/v1/invoices/bulk

There are multiple actions that are available including:

Authorizations:
ApiKeyAuth
query Parameters
index
string
Example: index=user

Replaces the default response index from data to a user specific string

ie.

  ?index=new_index

response is wrapped

  {
    'new_index' : [
      .....  
    ]
  }
header Parameters
X-API-TOKEN
required
string
Example: TOKEN

The API token to be used for authentication

X-Requested-With
required
string
Example: XMLHttpRequest

Used to send the XMLHttpRequest header

Request Body schema: application/json
required

Bulk action details

email_type
string

The email type to be sent, when bulk emailing invoices options include:

  • invoice (default)
  • quote
  • credit
  • payment
  • payment_partial
  • statement
  • reminder1
  • reminder2
  • reminder3
  • reminder_endless
  • custom1
  • custom2
  • custom3
  • purchase_order
  • email_quote_template_reminder1
action
string

The action to be performed, options include:

  • bulk_download
    Bulk download an array of invoice PDFs (These are sent to the admin via email.)
  • download
    Download a single PDF. (Returns a single PDF object)
  • bulk_print
    Merges an array of Invoice PDFs for easy one click printing.
  • auto_bill
    Attempts to automatically bill the invoices with the payment method on file.
  • clone_to_invoice
    Returns a clone of the invoice.
  • clone_to_quote
    Returns a quote cloned using the properties of the given invoice.
  • mark_paid
    Marks an array of invoices as paid.
  • mark_sent
    Marks an array of invoices as sent.
  • restore
    Restores an array of invoices
  • delete
    Deletes an array of invoices
  • archive
    Archives an array of invoices
  • cancel
    Cancels an array of invoices
  • email
    Emails an array of invoices
  • send_email
    Emails an array of invoices. Requires additional properties to be sent. email_type
ids
Array of strings

Responses

Request samples

Content type
application/json
{
  • "action": "bulk_download",
  • "ids": [
    ]
}

Response samples

Content type
application/json
{
  • "message": "These credentials do not match our records / Invalid Token"
}

Custom invoice action Deprecated

Performs a custom action on an invoice.
The current range of actions are as follows

  • clone_to_invoice
  • clone_to_quote
  • history
  • delivery_note
  • mark_paid
  • download
  • archive
  • delete
  • email
Authorizations:
ApiKeyAuth
path Parameters
id
required
string <string>
Example: D2J234DFA

The Invoice Hashed ID

action
required
string <string>
Example: clone_to_quote

The action string to be performed

query Parameters
include
string
Example: include=first_load

Includes child relationships in the response, format is comma separated. Check each model for the list of associated includes

header Parameters
X-API-TOKEN
required
string
Example: TOKEN

The API token to be used for authentication

X-Requested-With
required
string
Example: XMLHttpRequest

Used to send the XMLHttpRequest header

Responses

Response samples

Content type
application/json
{
  • "id": "Opnel5aKBz",
  • "user_id": "Opnel5aKBz",
  • "assigned_user_id": "Opnel5aKBz",
  • "client_id": "Opnel5aKBz",
  • "status_id": "4",
  • "number": "INV_101",
  • "po_number": "PO-1234",
  • "terms": "These are invoice terms",
  • "public_notes": "These are some public notes",
  • "private_notes": "These are some private notes",
  • "footer": "",
  • "custom_value1": "2022-10-01",
  • "custom_value2": "Something custom",
  • "custom_value3": "",
  • "custom_value4": "",
  • "tax_name1": "",
  • "tax_name2": "",
  • "tax_rate1": 10,
  • "tax_rate2": 10,
  • "tax_name3": "",
  • "tax_rate3": 10,
  • "total_taxes": 10,
  • "line_items": [
    ],
  • "invitations": [
    ],
  • "amount": 10,
  • "balance": 10,
  • "paid_to_date": 10,
  • "discount": 10,
  • "partial": 10,
  • "is_amount_discount": true,
  • "is_deleted": true,
  • "uses_inclusive_taxes": true,
  • "date": "1994-07-30",
  • "last_sent_date": "1994-07-30",
  • "next_send_date": "1994-07-30",
  • "partial_due_date": "1994-07-30",
  • "due_date": "1994-07-30",
  • "last_viewed": 1434342123,
  • "updated_at": 1434342123,
  • "archived_at": 1434342123,
  • "custom_surcharge1": 10,
  • "custom_surcharge2": 10,
  • "custom_surcharge3": 10,
  • "custom_surcharge4": 10,
  • "custom_surcharge_tax1": true,
  • "custom_surcharge_tax2": true,
  • "custom_surcharge_tax3": true,
  • "custom_surcharge_tax4": true,
  • "project_id": "Opnel5aKBz",
  • "auto_bill_tries": 1,
  • "auto_bill_enabled": true,
  • "subscription_id": "Opnel5aKBz",
  • "location_id": "Opnel5aKBz",
  • "design_id": "Opnel5aKBz",
  • "e_invoice": { },
  • "exchange_rate": 1,
  • "vendor_id": "Opnel5aKBz"
}

Download invoice PDF

GET /api/v1/invoice/{invitation_key}/download

Downloads a specific invoice

Authorizations:
ApiKeyAuth
path Parameters
invitation_key
required
string <string>
Example: D2J234DFA

The Invoice Invitation Key

query Parameters
include
string
Example: include=first_load

Includes child relationships in the response, format is comma separated. Check each model for the list of associated includes

header Parameters
X-API-TOKEN
required
string
Example: TOKEN

The API token to be used for authentication

X-Requested-With
required
string
Example: XMLHttpRequest

Used to send the XMLHttpRequest header

Responses

Request samples 

$ninja = new InvoiceNinja("your_token");
$invoice = $ninja->invoices->download("D2J234DFA");

Response samples

Content type
application/json
{
  • "message": "These credentials do not match our records / Invalid Token"
}

Download delivery note

GET /api/v1/invoices/{id}/delivery_note

Downloads a specific invoice delivery notes

Authorizations:
ApiKeyAuth
path Parameters
id
required
string <string>
Example: D2J234DFA

The Invoice Hahsed Id

query Parameters
include
string
Example: include=first_load

Includes child relationships in the response, format is comma separated. Check each model for the list of associated includes

header Parameters
X-API-TOKEN
required
string
Example: TOKEN

The API token to be used for authentication

X-Requested-With
required
string
Example: XMLHttpRequest

Used to send the XMLHttpRequest header

Responses

Request samples 

$ninja = new InvoiceNinja("your_token");
$invoice = $ninja->invoices->deliveryNote("D2J234DFA");

Response samples

Content type
application/json
{
  • "message": "These credentials do not match our records / Invalid Token"
}

Add invoice document

POST /api/v1/invoices/{id}/upload

Handles the uploading of a document to a invoice

Authorizations:
ApiKeyAuth
path Parameters
id
required
string <string>
Example: D2J234DFA

The Invoice Hashed ID

query Parameters
include
string
Example: include=first_load

Includes child relationships in the response, format is comma separated. Check each model for the list of associated includes

header Parameters
X-API-TOKEN
required
string
Example: TOKEN

The API token to be used for authentication

X-Requested-With
required
string
Example: XMLHttpRequest

Used to send the XMLHttpRequest header

Request Body schema: multipart/form-data
required

File Upload Body

_method
string
documents
Array of strings <binary> [ items <binary > ]

Responses

Request samples 

$ninja = new InvoiceNinja("your_token");
$invoice = $ninja->invoices->upload("D2J234DFA");

Response samples

Content type
application/json
{
  • "id": "Opnel5aKBz",
  • "user_id": "Opnel5aKBz",
  • "assigned_user_id": "Opnel5aKBz",
  • "client_id": "Opnel5aKBz",
  • "status_id": "4",
  • "number": "INV_101",
  • "po_number": "PO-1234",
  • "terms": "These are invoice terms",
  • "public_notes": "These are some public notes",
  • "private_notes": "These are some private notes",
  • "footer": "",
  • "custom_value1": "2022-10-01",
  • "custom_value2": "Something custom",
  • "custom_value3": "",
  • "custom_value4": "",
  • "tax_name1": "",
  • "tax_name2": "",
  • "tax_rate1": 10,
  • "tax_rate2": 10,
  • "tax_name3": "",
  • "tax_rate3": 10,
  • "total_taxes": 10,
  • "line_items": [
    ],
  • "invitations": [
    ],
  • "amount": 10,
  • "balance": 10,
  • "paid_to_date": 10,
  • "discount": 10,
  • "partial": 10,
  • "is_amount_discount": true,
  • "is_deleted": true,
  • "uses_inclusive_taxes": true,
  • "date": "1994-07-30",
  • "last_sent_date": "1994-07-30",
  • "next_send_date": "1994-07-30",
  • "partial_due_date": "1994-07-30",
  • "due_date": "1994-07-30",
  • "last_viewed": 1434342123,
  • "updated_at": 1434342123,
  • "archived_at": 1434342123,
  • "custom_surcharge1": 10,
  • "custom_surcharge2": 10,
  • "custom_surcharge3": 10,
  • "custom_surcharge4": 10,
  • "custom_surcharge_tax1": true,
  • "custom_surcharge_tax2": true,
  • "custom_surcharge_tax3": true,
  • "custom_surcharge_tax4": true,
  • "project_id": "Opnel5aKBz",
  • "auto_bill_tries": 1,
  • "auto_bill_enabled": true,
  • "subscription_id": "Opnel5aKBz",
  • "location_id": "Opnel5aKBz",
  • "design_id": "Opnel5aKBz",
  • "e_invoice": { },
  • "exchange_rate": 1,
  • "vendor_id": "Opnel5aKBz"
}

Recurring Invoices

Endpoint definitions for interacting with recurring_invoices.

List recurring invoices

GET /api/v1/recurring_invoices

Lists invoices with the option to chain multiple query parameters allowing fine grained filtering of the list.

Authorizations:
ApiKeyAuth
query Parameters
include
string
Example: include=first_load

Includes child relationships in the response, format is comma separated. Check each model for the list of associated includes

index
string
Example: index=user

Replaces the default response index from data to a user specific string

ie.

  ?index=new_index

response is wrapped

  {
    'new_index' : [
      .....  
    ]
  }
per_page
integer
Example: per_page=20

The number of records to return for each request, default is 20

page
integer
Example: page=1

The page number to return for this request (when performing pagination), default is 1

client_id
string
Example: client_id=?client_id={client_id}

Filters the entity list by client_id. Suitable when you only want the entities of a specific client.

GET /api/v1/invoices?client_id=AxB7Hjk9
Returns only invoices for the specified client
created_at
integer
Example: created_at=1641772800

Filters the entity list by the created at timestamp. Parameter value can be a datetime string or unix timestamp

GET /api/v1/invoices?created_at=2022-01-10
Returns entities created on January 10th, 2022
updated_at
integer
Example: updated_at=1641772800

Filters the entity list by the updated at timestamp. Parameter value can be a datetime string or unix timestamp

GET /api/v1/invoices?updated_at=2022-01-10
Returns entities last updated on January 10th, 2022
is_deleted
boolean
Example: is_deleted=true

Filters the entity list by entities that have been deleted.

GET /api/v1/invoices?is_deleted=true
Returns only soft-deleted entities
filter_deleted_clients
string
Example: filter_deleted_clients=?filter_deleted_clients=true

Filters the entity list and only returns entities for clients that have not been deleted

GET /api/v1/invoices?filter_deleted_clients=true
Returns only invoices for active (non-deleted) clients
vendor_id
string
Example: vendor_id=?vendor_id={vendor_id}

Filters the entity list by an associated vendor

GET /api/v1/purchases?vendor_id=AxB7Hjk9
Returns only purchases for the specified vendor
filter
string
Example: filter=?filter=bob

Searches across a range of columns including:

  • custom_value1
  • custom_value2
  • custom_value3
  • custom_value4
client_status
string
Example: client_status=?client_status=active,paused

A comma separated list of invoice status strings. Valid options include:

  • all
  • active
  • paused
  • completed
sort
string
Example: sort=id|desc number|desc balance|asc

Returns the list sorted by column in ascending or descending order.

number
string
Example: number=?number=123

Filters the list by number.

product_key
string
Example: product_key=?product_key=123

Filters the list by product_key.

next_send_between
string
Example: next_send_between=?next_send_between=2025-01-01|2025-01-31

Filters the list by next_send_between.

frequency_id
string
Example: frequency_id=?frequency_id=1,2,3

Filters the list by frequency_id.

header Parameters
X-API-TOKEN
required
string
Example: TOKEN

The API token to be used for authentication

X-Requested-With
required
string
Example: XMLHttpRequest

Used to send the XMLHttpRequest header

Responses

Request samples 

$ninja = new InvoiceNinja("your_token");
$invoices = $ninja->recurring_invoices->all([
  'per_page' => 10,
  'page' => 1,
  'sort' => 'number|asc'
]);

Response samples

Content type
application/json
{
  • "data": [
    ],
  • "meta": {
    }
}

Create recurring invoice

POST /api/v1/recurring_invoices

Adds a Recurring Invoice to the system

Authorizations:
ApiKeyAuth
query Parameters
include
string
Example: include=first_load

Includes child relationships in the response, format is comma separated. Check each model for the list of associated includes

header Parameters
X-API-TOKEN
required
string
Example: TOKEN

The API token to be used for authentication

X-Requested-With
required
string
Example: XMLHttpRequest

Used to send the XMLHttpRequest header

Request Body schema: application/json
required

Recurring invoice object that needs to be added to the company

client_id
required
string

The hashed ID of the client

date
required
string <date>

Recurring invoice date

due_date
required
string <date>

Due date for the recurring invoice

frequency_id
required
string

Frequency ID for recurring invoice

remaining_cycles
string

Number of remaining cycles

private_notes
string

Private notes for the recurring invoice

public_notes
string

Public notes for the recurring invoice

custom_value1
string

Custom field value 1

custom_value2
string

Custom field value 2

custom_value3
string

Custom field value 3

custom_value4
string

Custom field value 4

Array of objects (InvoiceItem)

An array of objects which define the line items of the invoice

Responses

Request samples

Content type
application/json
{
  • "client_id": "D2J234DFA",
  • "date": "2024-01-01",
  • "due_date": "2024-01-31",
  • "frequency_id": "1",
  • "remaining_cycles": "5",
  • "private_notes": "Internal notes about this recurring invoice",
  • "public_notes": "Thank you for your business!",
  • "custom_value1": "Custom value 1",
  • "custom_value2": "Custom value 2",
  • "custom_value3": "Custom value 3",
  • "custom_value4": "Custom value 4",
  • "line_items": [
    ]
}

Response samples

Content type
application/json
{
  • "id": "Opnel5aKBz",
  • "user_id": "Opnel5aKBz",
  • "assigned_user_id": "Opnel5aKBz",
  • "client_id": "Opnel5aKBz",
  • "status_id": "4",
  • "frequency_id": 4,
  • "remaining_cycles": 4,
  • "number": "INV_101",
  • "po_number": "PO-1234",
  • "terms": "These are invoice terms",
  • "public_notes": "These are some public notes",
  • "private_notes": "These are some private notes",
  • "footer": "",
  • "custom_value1": "2022-10-01",
  • "custom_value2": "Something custom",
  • "custom_value3": "",
  • "custom_value4": "",
  • "tax_name1": "",
  • "tax_name2": "",
  • "tax_rate1": 10,
  • "tax_rate2": 10,
  • "tax_name3": "",
  • "tax_rate3": 10,
  • "total_taxes": 10,
  • "line_items": { },
  • "amount": 10,
  • "balance": 10,
  • "paid_to_date": 10,
  • "discount": 10,
  • "partial": 10,
  • "is_amount_discount": true,
  • "is_deleted": true,
  • "uses_inclusive_taxes": true,
  • "date": "1994-07-30",
  • "last_sent_date": "1994-07-30",
  • "next_send_date": "1994-07-30",
  • "partial_due_date": "1994-07-30",
  • "due_date": "1994-07-30",
  • "settings": {
    },
  • "last_viewed": 1434342123,
  • "updated_at": 1434342123,
  • "archived_at": 1434342123,
  • "custom_surcharge1": 10,
  • "custom_surcharge2": 10,
  • "custom_surcharge3": 10,
  • "custom_surcharge4": 10,
  • "custom_surcharge_tax1": true,
  • "custom_surcharge_tax2": true,
  • "custom_surcharge_tax3": true,
  • "custom_surcharge_tax4": true,
  • "location_id": "Opnel5aKBz",
  • "auto_bill": "always",
  • "auto_bill_enabled": true,
  • "design_id": "Opnel5aKBz",
  • "due_date_days": 30,
  • "e_invoice": { },
  • "exchange_rate": 1,
  • "next_send_date_client": "2024-12-31",
  • "project_id": "Opnel5aKBz",
  • "vendor_id": "Opnel5aKBz"
}

Show recurring invoice

Displays an RecurringInvoice by id

Authorizations:
ApiKeyAuth
path Parameters
id
required
string <string>
Example: D2J234DFA

The RecurringInvoice Hashed ID

query Parameters
include
string
Example: include=first_load

Includes child relationships in the response, format is comma separated. Check each model for the list of associated includes

header Parameters
X-API-TOKEN
required
string
Example: TOKEN

The API token to be used for authentication

X-Requested-With
required
string
Example: XMLHttpRequest

Used to send the XMLHttpRequest header

Responses

Request samples 

$ninja = new InvoiceNinja("YOUR-TOKEN");
$recurringInvoice = $ninja->recurringInvoices->show("D2J234DFA");

Response samples

Content type
application/json
{
  • "id": "Opnel5aKBz",
  • "user_id": "Opnel5aKBz",
  • "assigned_user_id": "Opnel5aKBz",
  • "client_id": "Opnel5aKBz",
  • "status_id": "4",
  • "frequency_id": 4,
  • "remaining_cycles": 4,
  • "number": "INV_101",
  • "po_number": "PO-1234",
  • "terms": "These are invoice terms",
  • "public_notes": "These are some public notes",
  • "private_notes": "These are some private notes",
  • "footer": "",
  • "custom_value1": "2022-10-01",
  • "custom_value2": "Something custom",
  • "custom_value3": "",
  • "custom_value4": "",
  • "tax_name1": "",
  • "tax_name2": "",
  • "tax_rate1": 10,
  • "tax_rate2": 10,
  • "tax_name3": "",
  • "tax_rate3": 10,
  • "total_taxes": 10,
  • "line_items": { },
  • "amount": 10,
  • "balance": 10,
  • "paid_to_date": 10,
  • "discount": 10,
  • "partial": 10,
  • "is_amount_discount": true,
  • "is_deleted": true,
  • "uses_inclusive_taxes": true,
  • "date": "1994-07-30",
  • "last_sent_date": "1994-07-30",
  • "next_send_date": "1994-07-30",
  • "partial_due_date": "1994-07-30",
  • "due_date": "1994-07-30",
  • "settings": {
    },
  • "last_viewed": 1434342123,
  • "updated_at": 1434342123,
  • "archived_at": 1434342123,
  • "custom_surcharge1": 10,
  • "custom_surcharge2": 10,
  • "custom_surcharge3": 10,
  • "custom_surcharge4": 10,
  • "custom_surcharge_tax1": true,
  • "custom_surcharge_tax2": true,
  • "custom_surcharge_tax3": true,
  • "custom_surcharge_tax4": true,
  • "location_id": "Opnel5aKBz",
  • "auto_bill": "always",
  • "auto_bill_enabled": true,
  • "design_id": "Opnel5aKBz",
  • "due_date_days": 30,
  • "e_invoice": { },
  • "exchange_rate": 1,
  • "next_send_date_client": "2024-12-31",
  • "project_id": "Opnel5aKBz",
  • "vendor_id": "Opnel5aKBz"
}

Update recurring invoice

Handles the updating of an RecurringInvoice by id

Authorizations:
ApiKeyAuth
path Parameters
id
required
string <string>
Example: D2J234DFA

The RecurringInvoice Hashed ID

query Parameters
include
string
Example: include=first_load

Includes child relationships in the response, format is comma separated. Check each model for the list of associated includes

header Parameters
X-API-TOKEN
required
string
Example: TOKEN

The API token to be used for authentication

X-Requested-With
required
string
Example: XMLHttpRequest

Used to send the XMLHttpRequest header

Responses

Response samples

Content type
application/json
{
  • "id": "Opnel5aKBz",
  • "user_id": "Opnel5aKBz",
  • "assigned_user_id": "Opnel5aKBz",
  • "client_id": "Opnel5aKBz",
  • "status_id": "4",
  • "frequency_id": 4,
  • "remaining_cycles": 4,
  • "number": "INV_101",
  • "po_number": "PO-1234",
  • "terms": "These are invoice terms",
  • "public_notes": "These are some public notes",
  • "private_notes": "These are some private notes",
  • "footer": "",
  • "custom_value1": "2022-10-01",
  • "custom_value2": "Something custom",
  • "custom_value3": "",
  • "custom_value4": "",
  • "tax_name1": "",
  • "tax_name2": "",
  • "tax_rate1": 10,
  • "tax_rate2": 10,
  • "tax_name3": "",
  • "tax_rate3": 10,
  • "total_taxes": 10,
  • "line_items": { },
  • "amount": 10,
  • "balance": 10,
  • "paid_to_date": 10,
  • "discount": 10,
  • "partial": 10,
  • "is_amount_discount": true,
  • "is_deleted": true,
  • "uses_inclusive_taxes": true,
  • "date": "1994-07-30",
  • "last_sent_date": "1994-07-30",
  • "next_send_date": "1994-07-30",
  • "partial_due_date": "1994-07-30",
  • "due_date": "1994-07-30",
  • "settings": {
    },
  • "last_viewed": 1434342123,
  • "updated_at": 1434342123,
  • "archived_at": 1434342123,
  • "custom_surcharge1": 10,
  • "custom_surcharge2": 10,
  • "custom_surcharge3": 10,
  • "custom_surcharge4": 10,
  • "custom_surcharge_tax1": true,
  • "custom_surcharge_tax2": true,
  • "custom_surcharge_tax3": true,
  • "custom_surcharge_tax4": true,
  • "location_id": "Opnel5aKBz",
  • "auto_bill": "always",
  • "auto_bill_enabled": true,
  • "design_id": "Opnel5aKBz",
  • "due_date_days": 30,
  • "e_invoice": { },
  • "exchange_rate": 1,
  • "next_send_date_client": "2024-12-31",
  • "project_id": "Opnel5aKBz",
  • "vendor_id": "Opnel5aKBz"
}

Delete recurring invoice

Handles the deletion of an RecurringInvoice by id

Authorizations:
ApiKeyAuth
path Parameters
id
required
string <string>
Example: D2J234DFA

The RecurringInvoice Hashed ID

query Parameters
include
string
Example: include=first_load

Includes child relationships in the response, format is comma separated. Check each model for the list of associated includes

header Parameters
X-API-TOKEN
required
string
Example: TOKEN

The API token to be used for authentication

X-Requested-With
required
string
Example: XMLHttpRequest

Used to send the XMLHttpRequest header

Responses

Response samples

Content type
application/json
{
  • "message": "These credentials do not match our records / Invalid Token"
}

Edit recurring invoice

Displays an RecurringInvoice by id

Authorizations:
ApiKeyAuth
path Parameters
id
required
string <string>
Example: D2J234DFA

The RecurringInvoice Hashed ID

query Parameters
include
string
Example: include=first_load

Includes child relationships in the response, format is comma separated. Check each model for the list of associated includes

header Parameters
X-API-TOKEN
required
string
Example: TOKEN

The API token to be used for authentication

X-Requested-With
required
string
Example: XMLHttpRequest

Used to send the XMLHttpRequest header

Responses

Response samples

Content type
application/json
{
  • "id": "Opnel5aKBz",
  • "user_id": "Opnel5aKBz",
  • "assigned_user_id": "Opnel5aKBz",
  • "client_id": "Opnel5aKBz",
  • "status_id": "4",
  • "frequency_id": 4,
  • "remaining_cycles": 4,
  • "number": "INV_101",
  • "po_number": "PO-1234",
  • "terms": "These are invoice terms",
  • "public_notes": "These are some public notes",
  • "private_notes": "These are some private notes",
  • "footer": "",
  • "custom_value1": "2022-10-01",
  • "custom_value2": "Something custom",
  • "custom_value3": "",
  • "custom_value4": "",
  • "tax_name1": "",
  • "tax_name2": "",
  • "tax_rate1": 10,
  • "tax_rate2": 10,
  • "tax_name3": "",
  • "tax_rate3": 10,
  • "total_taxes": 10,
  • "line_items": { },
  • "amount": 10,
  • "balance": 10,
  • "paid_to_date": 10,
  • "discount": 10,
  • "partial": 10,
  • "is_amount_discount": true,
  • "is_deleted": true,
  • "uses_inclusive_taxes": true,
  • "date": "1994-07-30",
  • "last_sent_date": "1994-07-30",
  • "next_send_date": "1994-07-30",
  • "partial_due_date": "1994-07-30",
  • "due_date": "1994-07-30",
  • "settings": {
    },
  • "last_viewed": 1434342123,
  • "updated_at": 1434342123,
  • "archived_at": 1434342123,
  • "custom_surcharge1": 10,
  • "custom_surcharge2": 10,
  • "custom_surcharge3": 10,
  • "custom_surcharge4": 10,
  • "custom_surcharge_tax1": true,
  • "custom_surcharge_tax2": true,
  • "custom_surcharge_tax3": true,
  • "custom_surcharge_tax4": true,
  • "location_id": "Opnel5aKBz",
  • "auto_bill": "always",
  • "auto_bill_enabled": true,
  • "design_id": "Opnel5aKBz",
  • "due_date_days": 30,
  • "e_invoice": { },
  • "exchange_rate": 1,
  • "next_send_date_client": "2024-12-31",
  • "project_id": "Opnel5aKBz",
  • "vendor_id": "Opnel5aKBz"
}

Blank recurring invoice

Returns a blank object with default values

Authorizations:
ApiKeyAuth
query Parameters
include
string
Example: include=first_load

Includes child relationships in the response, format is comma separated. Check each model for the list of associated includes

header Parameters
X-API-TOKEN
required
string
Example: TOKEN

The API token to be used for authentication

X-Requested-With
required
string
Example: XMLHttpRequest

Used to send the XMLHttpRequest header

Responses

Response samples

Content type
application/json
{
  • "id": "Opnel5aKBz",
  • "user_id": "Opnel5aKBz",
  • "assigned_user_id": "Opnel5aKBz",
  • "client_id": "Opnel5aKBz",
  • "status_id": "4",
  • "frequency_id": 4,
  • "remaining_cycles": 4,
  • "number": "INV_101",
  • "po_number": "PO-1234",
  • "terms": "These are invoice terms",
  • "public_notes": "These are some public notes",
  • "private_notes": "These are some private notes",
  • "footer": "",
  • "custom_value1": "2022-10-01",
  • "custom_value2": "Something custom",
  • "custom_value3": "",
  • "custom_value4": "",
  • "tax_name1": "",
  • "tax_name2": "",
  • "tax_rate1": 10,
  • "tax_rate2": 10,
  • "tax_name3": "",
  • "tax_rate3": 10,
  • "total_taxes": 10,
  • "line_items": { },
  • "amount": 10,
  • "balance": 10,
  • "paid_to_date": 10,
  • "discount": 10,
  • "partial": 10,
  • "is_amount_discount": true,
  • "is_deleted": true,
  • "uses_inclusive_taxes": true,
  • "date": "1994-07-30",
  • "last_sent_date": "1994-07-30",
  • "next_send_date": "1994-07-30",
  • "partial_due_date": "1994-07-30",
  • "due_date": "1994-07-30",
  • "settings": {
    },
  • "last_viewed": 1434342123,
  • "updated_at": 1434342123,
  • "archived_at": 1434342123,
  • "custom_surcharge1": 10,
  • "custom_surcharge2": 10,
  • "custom_surcharge3": 10,
  • "custom_surcharge4": 10,
  • "custom_surcharge_tax1": true,
  • "custom_surcharge_tax2": true,
  • "custom_surcharge_tax3": true,
  • "custom_surcharge_tax4": true,
  • "location_id": "Opnel5aKBz",
  • "auto_bill": "always",
  • "auto_bill_enabled": true,
  • "design_id": "Opnel5aKBz",
  • "due_date_days": 30,
  • "e_invoice": { },
  • "exchange_rate": 1,
  • "next_send_date_client": "2024-12-31",
  • "project_id": "Opnel5aKBz",
  • "vendor_id": "Opnel5aKBz"
}

Bulk recurring invoice actions

There are multiple actions that are available including:

Authorizations:
ApiKeyAuth
query Parameters
index
string
Example: index=user

Replaces the default response index from data to a user specific string

ie.

  ?index=new_index

response is wrapped

  {
    'new_index' : [
      .....  
    ]
  }
header Parameters
X-API-TOKEN
required
string
Example: TOKEN

The API token to be used for authentication

X-Requested-With
required
string
Example: XMLHttpRequest

Used to send the XMLHttpRequest header

Request Body schema: application/json
required

Bulk action details

action
string

The action to be performed, options include:

  • start
    Starts (or restarts) the recurring invoice. note if the recurring invoice has been stopped for a long time, it will attempt to catch back up firing a new Invoice every hour per interval that has been missed.
    If you do not wish to have the recurring invoice catch up, you should set the next_send_date to the correct date you wish the recurring invoice to commence from.
  • stop
    Stops the recurring invoice.
  • send_now
    Force sends the recurring invoice - this option is only available when the recurring invoice is in a draft state.
  • restore
    Restores the recurring invoice from an archived or deleted state.
  • archive
    Archives the recurring invoice. The recurring invoice will not fire in this state.
  • delete
    Deletes a recurring invoice.
ids
Array of strings

Responses

Request samples

Content type
application/json
{
  • "action": "start",
  • "ids": [
    ]
}

Response samples

Content type
application/json
{
  • "id": "Opnel5aKBz",
  • "user_id": "Opnel5aKBz",
  • "assigned_user_id": "Opnel5aKBz",
  • "client_id": "Opnel5aKBz",
  • "status_id": "4",
  • "frequency_id": 4,
  • "remaining_cycles": 4,
  • "number": "INV_101",
  • "po_number": "PO-1234",
  • "terms": "These are invoice terms",
  • "public_notes": "These are some public notes",
  • "private_notes": "These are some private notes",
  • "footer": "",
  • "custom_value1": "2022-10-01",
  • "custom_value2": "Something custom",
  • "custom_value3": "",
  • "custom_value4": "",
  • "tax_name1": "",
  • "tax_name2": "",
  • "tax_rate1": 10,
  • "tax_rate2": 10,
  • "tax_name3": "",
  • "tax_rate3": 10,
  • "total_taxes": 10,
  • "line_items": { },
  • "amount": 10,
  • "balance": 10,
  • "paid_to_date": 10,
  • "discount": 10,
  • "partial": 10,
  • "is_amount_discount": true,
  • "is_deleted": true,
  • "uses_inclusive_taxes": true,
  • "date": "1994-07-30",
  • "last_sent_date": "1994-07-30",
  • "next_send_date": "1994-07-30",
  • "partial_due_date": "1994-07-30",
  • "due_date": "1994-07-30",
  • "settings": {
    },
  • "last_viewed": 1434342123,
  • "updated_at": 1434342123,
  • "archived_at": 1434342123,
  • "custom_surcharge1": 10,
  • "custom_surcharge2": 10,
  • "custom_surcharge3": 10,
  • "custom_surcharge4": 10,
  • "custom_surcharge_tax1": true,
  • "custom_surcharge_tax2": true,
  • "custom_surcharge_tax3": true,
  • "custom_surcharge_tax4": true,
  • "location_id": "Opnel5aKBz",
  • "auto_bill": "always",
  • "auto_bill_enabled": true,
  • "design_id": "Opnel5aKBz",
  • "due_date_days": 30,
  • "e_invoice": { },
  • "exchange_rate": 1,
  • "next_send_date_client": "2024-12-31",
  • "project_id": "Opnel5aKBz",
  • "vendor_id": "Opnel5aKBz"
}

Custom recurring invoice action Deprecated

Performs a custom action on an RecurringInvoice.

The current range of actions are as follows
- clone_to_RecurringInvoice
- clone_to_quote
- history
- delivery_note
- mark_paid
- download
- archive
- delete
- email
Authorizations:
ApiKeyAuth
path Parameters
id
required
string <string>
Example: D2J234DFA

The RecurringInvoice Hashed ID

action
required
string <string>
Example: clone_to_quote

The action string to be performed

query Parameters
include
string
Example: include=first_load

Includes child relationships in the response, format is comma separated. Check each model for the list of associated includes

header Parameters
X-API-TOKEN
required
string
Example: TOKEN

The API token to be used for authentication

X-Requested-With
required
string
Example: XMLHttpRequest

Used to send the XMLHttpRequest header

Responses

Response samples

Content type
application/json
{
  • "id": "Opnel5aKBz",
  • "user_id": "Opnel5aKBz",
  • "assigned_user_id": "Opnel5aKBz",
  • "client_id": "Opnel5aKBz",
  • "status_id": "4",
  • "frequency_id": 4,
  • "remaining_cycles": 4,
  • "number": "INV_101",
  • "po_number": "PO-1234",
  • "terms": "These are invoice terms",
  • "public_notes": "These are some public notes",
  • "private_notes": "These are some private notes",
  • "footer": "",
  • "custom_value1": "2022-10-01",
  • "custom_value2": "Something custom",
  • "custom_value3": "",
  • "custom_value4": "",
  • "tax_name1": "",
  • "tax_name2": "",
  • "tax_rate1": 10,
  • "tax_rate2": 10,
  • "tax_name3": "",
  • "tax_rate3": 10,
  • "total_taxes": 10,
  • "line_items": { },
  • "amount": 10,
  • "balance": 10,
  • "paid_to_date": 10,
  • "discount": 10,
  • "partial": 10,
  • "is_amount_discount": true,
  • "is_deleted": true,
  • "uses_inclusive_taxes": true,
  • "date": "1994-07-30",
  • "last_sent_date": "1994-07-30",
  • "next_send_date": "1994-07-30",
  • "partial_due_date": "1994-07-30",
  • "due_date": "1994-07-30",
  • "settings": {
    },
  • "last_viewed": 1434342123,
  • "updated_at": 1434342123,
  • "archived_at": 1434342123,
  • "custom_surcharge1": 10,
  • "custom_surcharge2": 10,
  • "custom_surcharge3": 10,
  • "custom_surcharge4": 10,
  • "custom_surcharge_tax1": true,
  • "custom_surcharge_tax2": true,
  • "custom_surcharge_tax3": true,
  • "custom_surcharge_tax4": true,
  • "location_id": "Opnel5aKBz",
  • "auto_bill": "always",
  • "auto_bill_enabled": true,
  • "design_id": "Opnel5aKBz",
  • "due_date_days": 30,
  • "e_invoice": { },
  • "exchange_rate": 1,
  • "next_send_date_client": "2024-12-31",
  • "project_id": "Opnel5aKBz",
  • "vendor_id": "Opnel5aKBz"
}

Download recurring invoice PDF

Downloads a specific invoice

Authorizations:
ApiKeyAuth
path Parameters
invitation_key
required
string <string>
Example: D2J234DFA

The Recurring Invoice Invitation Key

query Parameters
include
string
Example: include=first_load

Includes child relationships in the response, format is comma separated. Check each model for the list of associated includes

header Parameters
X-API-TOKEN
required
string
Example: TOKEN

The API token to be used for authentication

X-Requested-With
required
string
Example: XMLHttpRequest

Used to send the XMLHttpRequest header

Responses

Response samples

Content type
application/json
{
  • "message": "These credentials do not match our records / Invalid Token"
}

Add recurring invoice document

Handles the uploading of a document to a recurring_invoice

Authorizations:
ApiKeyAuth
path Parameters
id
required
string <string>
Example: D2J234DFA

The RecurringInvoice Hashed ID

query Parameters
include
string
Example: include=first_load

Includes child relationships in the response, format is comma separated. Check each model for the list of associated includes

header Parameters
X-API-TOKEN
required
string
Example: TOKEN

The API token to be used for authentication

X-Requested-With
required
string
Example: XMLHttpRequest

Used to send the XMLHttpRequest header

Request Body schema: multipart/form-data
required

File Upload Body

_method
string
documents
Array of strings <binary> [ items <binary > ]

Responses

Response samples

Content type
application/json
{
  • "id": "Opnel5aKBz",
  • "user_id": "Opnel5aKBz",
  • "assigned_user_id": "Opnel5aKBz",
  • "client_id": "Opnel5aKBz",
  • "status_id": "4",
  • "frequency_id": 4,
  • "remaining_cycles": 4,
  • "number": "INV_101",
  • "po_number": "PO-1234",
  • "terms": "These are invoice terms",
  • "public_notes": "These are some public notes",
  • "private_notes": "These are some private notes",
  • "footer": "",
  • "custom_value1": "2022-10-01",
  • "custom_value2": "Something custom",
  • "custom_value3": "",
  • "custom_value4": "",
  • "tax_name1": "",
  • "tax_name2": "",
  • "tax_rate1": 10,
  • "tax_rate2": 10,
  • "tax_name3": "",
  • "tax_rate3": 10,
  • "total_taxes": 10,
  • "line_items": { },
  • "amount": 10,
  • "balance": 10,
  • "paid_to_date": 10,
  • "discount": 10,
  • "partial": 10,
  • "is_amount_discount": true,
  • "is_deleted": true,
  • "uses_inclusive_taxes": true,
  • "date": "1994-07-30",
  • "last_sent_date": "1994-07-30",
  • "next_send_date": "1994-07-30",
  • "partial_due_date": "1994-07-30",
  • "due_date": "1994-07-30",
  • "settings": {
    },
  • "last_viewed": 1434342123,
  • "updated_at": 1434342123,
  • "archived_at": 1434342123,
  • "custom_surcharge1": 10,
  • "custom_surcharge2": 10,
  • "custom_surcharge3": 10,
  • "custom_surcharge4": 10,
  • "custom_surcharge_tax1": true,
  • "custom_surcharge_tax2": true,
  • "custom_surcharge_tax3": true,
  • "custom_surcharge_tax4": true,
  • "location_id": "Opnel5aKBz",
  • "auto_bill": "always",
  • "auto_bill_enabled": true,
  • "design_id": "Opnel5aKBz",
  • "due_date_days": 30,
  • "e_invoice": { },
  • "exchange_rate": 1,
  • "next_send_date_client": "2024-12-31",
  • "project_id": "Opnel5aKBz",
  • "vendor_id": "Opnel5aKBz"
}

Recurring Invoices

Endpoint definitions for interacting with recurring_invoices.

Payments

Endpoint definitions for interacting with payments.

List payments

Lists payments, search and filters allow fine grained lists to be generated.

    Query parameters can be added to performed more fine grained filtering of the payments, these are handled by the PaymentFilters class which defines the methods available
Authorizations:
ApiKeyAuth
query Parameters
include
string
Example: include=first_load

Includes child relationships in the response, format is comma separated. Check each model for the list of associated includes

index
string
Example: index=user

Replaces the default response index from data to a user specific string

ie.

  ?index=new_index

response is wrapped

  {
    'new_index' : [
      .....  
    ]
  }
per_page
integer
Example: per_page=20

The number of records to return for each request, default is 20

page
integer
Example: page=1

The page number to return for this request (when performing pagination), default is 1

status
string
Example: status=?status=archived,deleted

Filter the entity based on their status. ie active / archived / deleted. Format is a comma separated string with any of the following options:

  • active
  • archived
  • deleted
GET /api/v1/invoices?status=archived,deleted
Returns only archived and deleted invoices
client_id
string
Example: client_id=?client_id={client_id}

Filters the entity list by client_id. Suitable when you only want the entities of a specific client.

GET /api/v1/invoices?client_id=AxB7Hjk9
Returns only invoices for the specified client
created_at
integer
Example: created_at=1641772800

Filters the entity list by the created at timestamp. Parameter value can be a datetime string or unix timestamp

GET /api/v1/invoices?created_at=2022-01-10
Returns entities created on January 10th, 2022
updated_at
integer
Example: updated_at=1641772800

Filters the entity list by the updated at timestamp. Parameter value can be a datetime string or unix timestamp

GET /api/v1/invoices?updated_at=2022-01-10
Returns entities last updated on January 10th, 2022
is_deleted
boolean
Example: is_deleted=true

Filters the entity list by entities that have been deleted.

GET /api/v1/invoices?is_deleted=true
Returns only soft-deleted entities
filter_deleted_clients
string
Example: filter_deleted_clients=?filter_deleted_clients=true

Filters the entity list and only returns entities for clients that have not been deleted

GET /api/v1/invoices?filter_deleted_clients=true
Returns only invoices for active (non-deleted) clients
vendor_id
string
Example: vendor_id=?vendor_id={vendor_id}

Filters the entity list by an associated vendor

GET /api/v1/purchases?vendor_id=AxB7Hjk9
Returns only purchases for the specified vendor
filter
string
Example: filter=?filter=10

Searches across a range of columns including:

  • amount
  • date
  • custom_value1
  • custom_value2
  • custom_value3
  • custom_value4
number
string
Example: number=?number=0001

Search payments by payment number

sort
string
Example: sort=id|desc number|desc balance|asc

Returns the list sorted by column in ascending or descending order.

header Parameters
X-API-TOKEN
required
string
Example: TOKEN

The API token to be used for authentication

X-Requested-With
required
string
Example: XMLHttpRequest

Used to send the XMLHttpRequest header

Responses

Request samples 

$ninja = new InvoiceNinja("YOUR-TOKEN");
$payments = $ninja->payments->all([
    'per_page' => 10,
    'page' => 1
]);

Response samples

Content type
application/json
{
  • "data": [
    ],
  • "meta": {
    }
}

Create payment

Adds an Payment to the system

Authorizations:
ApiKeyAuth
query Parameters
include
string
Example: include=first_load

Includes child relationships in the response, format is comma separated. Check each model for the list of associated includes

email_receipt
boolean

If true, the payment will be emailed to the client. If false, no email will be sent. This will override any other email settings for payments.

header Parameters
X-API-TOKEN
required
string
Example: TOKEN

The API token to be used for authentication

X-Requested-With
required
string
Example: XMLHttpRequest

Used to send the XMLHttpRequest header

Request Body schema: application/json
required

The payment request can be as simple as a client id and amount, or as complex as a full payment with invoices and associated credits that should be applied.

client_id
string

The client hashed id

client_contact_id
string

The client contact hashed id

user_id
string

The user hashed id

type_id
string (PaymentType)
Enum Description
1

Bank Transfer

2

Cash

3

Debit

4

ACH

5

Visa Card

6

MasterCard

7

American Express

8

Discover Card

9

Diners Card

10

EuroCard

11

Nova

12

Credit Card Other

13

PayPal

14

Google Wallet

15

Check

16

Carte Blanche

17

UnionPay

18

JCB

19

Laser

20

Maestro

21

Solo

22

Switch

23

iZettle

24

Swish

25

Venmo

26

Money Order

27

Alipay

28

Sofort

29

SEPA Direct Debit

30

GoCardless

31

Cryptocurrency

32

Credit

33

Zelle

The payment type used to complete this payment

date
string

The Payment date

transaction_reference
string

The transaction reference as defined by the payment gateway

assigned_user_id
string

The assigned user hashed id

private_notes
string

The private notes of the payment

amount
number

The amount of this payment

Array of objects (InvoicePaymentable)
Array of objects (CreditPaymentable)
number
string

The payment number - is a unique alpha numeric number per payment per company

Responses

Request samples

Content type
application/json
{
  • "client_id": "Opnel5aKBz",
  • "client_contact_id": "Opnel5aKBz",
  • "user_id": "Opnel5aKBz",
  • "type_id": "1",
  • "date": "1-1-2014",
  • "transaction_reference": "xcsSxcs124asd",
  • "assigned_user_id": "Opnel5aKBz",
  • "private_notes": "The payment was refunded due to error",
  • "amount": 10,
  • "invoices": [
    ],
  • "credits": [
    ],
  • "number": "PAY_101"
}

Response samples

Content type
application/json
{
  • "id": "Opnel5aKBz",
  • "client_id": "Opnel5aKBz",
  • "invitation_id": "Opnel5aKBz",
  • "client_contact_id": "Opnel5aKBz",
  • "user_id": "Opnel5aKBz",
  • "type_id": "1",
  • "date": "1-1-2014",
  • "transaction_reference": "xcsSxcs124asd",
  • "assigned_user_id": "Opnel5aKBz",
  • "private_notes": "The payment was refunded due to error",
  • "is_manual": true,
  • "is_deleted": true,
  • "amount": 10,
  • "refunded": 10,
  • "updated_at": 1434342123,
  • "archived_at": 1434342123,
  • "company_gateway_id": "3",
  • "paymentables": {
    },
  • "invoices": [
    ],
  • "credits": [
    ],
  • "number": "PAY_101",
  • "category_id": "Opnel5aKBz",
  • "custom_value1": "Payment reference 123",
  • "custom_value2": "Approved by John",
  • "custom_value3": "Urgent payment",
  • "custom_value4": "Q1 2024",
  • "exchange_currency_id": "2",
  • "exchange_rate": 1,
  • "idempotency_key": "key_1234567890abcdef"
}

Show payment

Displays an Payment by id

Authorizations:
ApiKeyAuth
path Parameters
id
required
string <string>
Example: D2J234DFA

The Payment Hashed ID

query Parameters
include
string
Example: include=first_load

Includes child relationships in the response, format is comma separated. Check each model for the list of associated includes

header Parameters
X-API-TOKEN
required
string
Example: TOKEN

The API token to be used for authentication

X-Requested-With
required
string
Example: XMLHttpRequest

Used to send the XMLHttpRequest header

Responses

Request samples 

$ninja = new InvoiceNinja("YOUR-TOKEN");
$payment = $ninja->payments->show("D2J234DFA");

Response samples

Content type
application/json
{
  • "id": "Opnel5aKBz",
  • "client_id": "Opnel5aKBz",
  • "invitation_id": "Opnel5aKBz",
  • "client_contact_id": "Opnel5aKBz",
  • "user_id": "Opnel5aKBz",
  • "type_id": "1",
  • "date": "1-1-2014",
  • "transaction_reference": "xcsSxcs124asd",
  • "assigned_user_id": "Opnel5aKBz",
  • "private_notes": "The payment was refunded due to error",
  • "is_manual": true,
  • "is_deleted": true,
  • "amount": 10,
  • "refunded": 10,
  • "updated_at": 1434342123,
  • "archived_at": 1434342123,
  • "company_gateway_id": "3",
  • "paymentables": {
    },
  • "invoices": [
    ],
  • "credits": [
    ],
  • "number": "PAY_101",
  • "category_id": "Opnel5aKBz",
  • "custom_value1": "Payment reference 123",
  • "custom_value2": "Approved by John",
  • "custom_value3": "Urgent payment",
  • "custom_value4": "Q1 2024",
  • "exchange_currency_id": "2",
  • "exchange_rate": 1,
  • "idempotency_key": "key_1234567890abcdef"
}

Update payment

Handles the updating of an Payment by id

Authorizations:
ApiKeyAuth
path Parameters
id
required
string <string>
Example: D2J234DFA

The Payment Hashed ID

query Parameters
include
string
Example: include=first_load

Includes child relationships in the response, format is comma separated. Check each model for the list of associated includes

header Parameters
X-API-TOKEN
required
string
Example: TOKEN

The API token to be used for authentication

X-Requested-With
required
string
Example: XMLHttpRequest

Used to send the XMLHttpRequest header

Responses

Response samples

Content type
application/json
{
  • "id": "Opnel5aKBz",
  • "client_id": "Opnel5aKBz",
  • "invitation_id": "Opnel5aKBz",
  • "client_contact_id": "Opnel5aKBz",
  • "user_id": "Opnel5aKBz",
  • "type_id": "1",
  • "date": "1-1-2014",
  • "transaction_reference": "xcsSxcs124asd",
  • "assigned_user_id": "Opnel5aKBz",
  • "private_notes": "The payment was refunded due to error",
  • "is_manual": true,
  • "is_deleted": true,
  • "amount": 10,
  • "refunded": 10,
  • "updated_at": 1434342123,
  • "archived_at": 1434342123,
  • "company_gateway_id": "3",
  • "paymentables": {
    },
  • "invoices": [
    ],
  • "credits": [
    ],
  • "number": "PAY_101",
  • "category_id": "Opnel5aKBz",
  • "custom_value1": "Payment reference 123",
  • "custom_value2": "Approved by John",
  • "custom_value3": "Urgent payment",
  • "custom_value4": "Q1 2024",
  • "exchange_currency_id": "2",
  • "exchange_rate": 1,
  • "idempotency_key": "key_1234567890abcdef"
}

Delete payment

Handles the deletion of an Payment by id

Authorizations:
ApiKeyAuth
path Parameters
id
required
string <string>
Example: D2J234DFA

The Payment Hashed ID

query Parameters
include
string
Example: include=first_load

Includes child relationships in the response, format is comma separated. Check each model for the list of associated includes

header Parameters
X-API-TOKEN
required
string
Example: TOKEN

The API token to be used for authentication

X-Requested-With
required
string
Example: XMLHttpRequest

Used to send the XMLHttpRequest header

Responses

Request samples 

$ninja = new InvoiceNinja("YOUR-TOKEN");
$ninja->payments->delete("D2J234DFA");

Response samples

Content type
application/json
{
  • "message": "These credentials do not match our records / Invalid Token"
}

Edit payment

Displays an Payment by id

Authorizations:
ApiKeyAuth
path Parameters
id
required
string <string>
Example: D2J234DFA

The Payment Hashed ID

query Parameters
include
string
Example: include=first_load

Includes child relationships in the response, format is comma separated. Check each model for the list of associated includes

header Parameters
X-API-TOKEN
required
string
Example: TOKEN

The API token to be used for authentication

X-Requested-With
required
string
Example: XMLHttpRequest

Used to send the XMLHttpRequest header

Responses

Response samples

Content type
application/json
{
  • "id": "Opnel5aKBz",
  • "client_id": "Opnel5aKBz",
  • "invitation_id": "Opnel5aKBz",
  • "client_contact_id": "Opnel5aKBz",
  • "user_id": "Opnel5aKBz",
  • "type_id": "1",
  • "date": "1-1-2014",
  • "transaction_reference": "xcsSxcs124asd",
  • "assigned_user_id": "Opnel5aKBz",
  • "private_notes": "The payment was refunded due to error",
  • "is_manual": true,
  • "is_deleted": true,
  • "amount": 10,
  • "refunded": 10,
  • "updated_at": 1434342123,
  • "archived_at": 1434342123,
  • "company_gateway_id": "3",
  • "paymentables": {
    },
  • "invoices": [
    ],
  • "credits": [
    ],
  • "number": "PAY_101",
  • "category_id": "Opnel5aKBz",
  • "custom_value1": "Payment reference 123",
  • "custom_value2": "Approved by John",
  • "custom_value3": "Urgent payment",
  • "custom_value4": "Q1 2024",
  • "exchange_currency_id": "2",
  • "exchange_rate": 1,
  • "idempotency_key": "key_1234567890abcdef"
}

Blank payment

Returns a blank object with default values

Authorizations:
ApiKeyAuth
query Parameters
include
string
Example: include=first_load

Includes child relationships in the response, format is comma separated. Check each model for the list of associated includes

header Parameters
X-API-TOKEN
required
string
Example: TOKEN

The API token to be used for authentication

X-Requested-With
required
string
Example: XMLHttpRequest

Used to send the XMLHttpRequest header

Responses

Response samples

Content type
application/json
{
  • "id": "Opnel5aKBz",
  • "client_id": "Opnel5aKBz",
  • "invitation_id": "Opnel5aKBz",
  • "client_contact_id": "Opnel5aKBz",
  • "user_id": "Opnel5aKBz",
  • "type_id": "1",
  • "date": "1-1-2014",
  • "transaction_reference": "xcsSxcs124asd",
  • "assigned_user_id": "Opnel5aKBz",
  • "private_notes": "The payment was refunded due to error",
  • "is_manual": true,
  • "is_deleted": true,
  • "amount": 10,
  • "refunded": 10,
  • "updated_at": 1434342123,
  • "archived_at": 1434342123,
  • "company_gateway_id": "3",
  • "paymentables": {
    },
  • "invoices": [
    ],
  • "credits": [
    ],
  • "number": "PAY_101",
  • "category_id": "Opnel5aKBz",
  • "custom_value1": "Payment reference 123",
  • "custom_value2": "Approved by John",
  • "custom_value3": "Urgent payment",
  • "custom_value4": "Q1 2024",
  • "exchange_currency_id": "2",
  • "exchange_rate": 1,
  • "idempotency_key": "key_1234567890abcdef"
}

Refund payment

Adds an Refund to the system

Authorizations:
ApiKeyAuth
query Parameters
include
string
Example: include=first_load

Includes child relationships in the response, format is comma separated. Check each model for the list of associated includes

header Parameters
X-API-TOKEN
required
string
Example: TOKEN

The API token to be used for authentication

X-Requested-With
required
string
Example: XMLHttpRequest

Used to send the XMLHttpRequest header

Request Body schema: application/json
required

The refund request

id
string

The payment hashed id

client_id
string

The client hashed id

invitation_id
string

The invitation hashed id

client_contact_id
string

The client contact hashed id

user_id
string

The user hashed id

type_id
string (PaymentType)
Enum Description
1

Bank Transfer

2

Cash

3

Debit

4

ACH

5

Visa Card

6

MasterCard

7

American Express

8

Discover Card

9

Diners Card

10

EuroCard

11

Nova

12

Credit Card Other

13

PayPal

14

Google Wallet

15

Check

16

Carte Blanche

17

UnionPay

18

JCB

19

Laser

20

Maestro

21

Solo

22

Switch

23

iZettle

24

Swish

25

Venmo

26

Money Order

27

Alipay

28

Sofort

29

SEPA Direct Debit

30

GoCardless

31

Cryptocurrency

32

Credit

33

Zelle

The payment type used to complete this payment

date
string

The Payment date

transaction_reference
string

The transaction reference as defined by the payment gateway

assigned_user_id
string

The assigned user hashed id

private_notes
string

The private notes of the payment

is_manual
boolean

Flags whether the payment was made manually or processed via a gateway

is_deleted
boolean

Defines if the payment has been deleted

amount
number

The amount of this payment

refunded
number

The refunded amount of this payment

updated_at
number <integer>

Timestamp

archived_at
number <integer>

Timestamp

company_gateway_id
string

The company gateway id

object (Paymentable)
Array of objects (InvoicePaymentable)
Array of objects (CreditPaymentable)
number
string

The payment number - is a unique alpha numeric number per payment per company

category_id
string

The unique identifier of the payment category

custom_value1
string

Custom field for storing additional information

custom_value2
string

Custom field for storing additional information

custom_value3
string

Custom field for storing additional information

custom_value4
string

Custom field for storing additional information

exchange_currency_id
string

The unique identifier of the exchange currency

exchange_rate
number <float>

The exchange rate used for currency conversion

idempotency_key
string

Unique key to ensure idempotent payment processing

Responses

Request samples

Content type
application/json
{
  • "id": "Opnel5aKBz",
  • "client_id": "Opnel5aKBz",
  • "invitation_id": "Opnel5aKBz",
  • "client_contact_id": "Opnel5aKBz",
  • "user_id": "Opnel5aKBz",
  • "type_id": "1",
  • "date": "1-1-2014",
  • "transaction_reference": "xcsSxcs124asd",
  • "assigned_user_id": "Opnel5aKBz",
  • "private_notes": "The payment was refunded due to error",
  • "is_manual": true,
  • "is_deleted": true,
  • "amount": 10,
  • "refunded": 10,
  • "updated_at": 1434342123,
  • "archived_at": 1434342123,
  • "company_gateway_id": "3",
  • "paymentables": {
    },
  • "invoices": [
    ],
  • "credits": [
    ],
  • "number": "PAY_101",
  • "category_id": "Opnel5aKBz",
  • "custom_value1": "Payment reference 123",
  • "custom_value2": "Approved by John",
  • "custom_value3": "Urgent payment",
  • "custom_value4": "Q1 2024",
  • "exchange_currency_id": "2",
  • "exchange_rate": 1,
  • "idempotency_key": "key_1234567890abcdef"
}

Response samples

Content type
application/json
{
  • "id": "Opnel5aKBz",
  • "client_id": "Opnel5aKBz",
  • "invitation_id": "Opnel5aKBz",
  • "client_contact_id": "Opnel5aKBz",
  • "user_id": "Opnel5aKBz",
  • "type_id": "1",
  • "date": "1-1-2014",
  • "transaction_reference": "xcsSxcs124asd",
  • "assigned_user_id": "Opnel5aKBz",
  • "private_notes": "The payment was refunded due to error",
  • "is_manual": true,
  • "is_deleted": true,
  • "amount": 10,
  • "refunded": 10,
  • "updated_at": 1434342123,
  • "archived_at": 1434342123,
  • "company_gateway_id": "3",
  • "paymentables": {
    },
  • "invoices": [
    ],
  • "credits": [
    ],
  • "number": "PAY_101",
  • "category_id": "Opnel5aKBz",
  • "custom_value1": "Payment reference 123",
  • "custom_value2": "Approved by John",
  • "custom_value3": "Urgent payment",
  • "custom_value4": "Q1 2024",
  • "exchange_currency_id": "2",
  • "exchange_rate": 1,
  • "idempotency_key": "key_1234567890abcdef"
}

Bulk payment actions

Authorizations:
ApiKeyAuth
query Parameters
index
string
Example: index=user

Replaces the default response index from data to a user specific string

ie.

  ?index=new_index

response is wrapped

  {
    'new_index' : [
      .....  
    ]
  }
header Parameters
X-API-TOKEN
required
string
Example: TOKEN

The API token to be used for authentication

X-Requested-With
required
string
Example: XMLHttpRequest

Used to send the XMLHttpRequest header

Request Body schema: application/json
required

User credentials

Array
integer

Array of hashed IDs to be bulk 'actioned

Responses

Request samples

Content type
application/json
[
  • 0
]

Response samples

Content type
application/json
{
  • "id": "Opnel5aKBz",
  • "client_id": "Opnel5aKBz",
  • "invitation_id": "Opnel5aKBz",
  • "client_contact_id": "Opnel5aKBz",
  • "user_id": "Opnel5aKBz",
  • "type_id": "1",
  • "date": "1-1-2014",
  • "transaction_reference": "xcsSxcs124asd",
  • "assigned_user_id": "Opnel5aKBz",
  • "private_notes": "The payment was refunded due to error",
  • "is_manual": true,
  • "is_deleted": true,
  • "amount": 10,
  • "refunded": 10,
  • "updated_at": 1434342123,
  • "archived_at": 1434342123,
  • "company_gateway_id": "3",
  • "paymentables": {
    },
  • "invoices": [
    ],
  • "credits": [
    ],
  • "number": "PAY_101",
  • "category_id": "Opnel5aKBz",
  • "custom_value1": "Payment reference 123",
  • "custom_value2": "Approved by John",
  • "custom_value3": "Urgent payment",
  • "custom_value4": "Q1 2024",
  • "exchange_currency_id": "2",
  • "exchange_rate": 1,
  • "idempotency_key": "key_1234567890abcdef"
}

Custom payment actions Deprecated

Performs a custom action on an Payment.

The current range of actions are as follows
- clone_to_Payment
- clone_to_quote
- history
- delivery_note
- mark_paid
- download
- archive
- delete
- email
Authorizations:
ApiKeyAuth
path Parameters
id
required
string <string>
Example: D2J234DFA

The Payment Hashed ID

action
required
string <string>
Example: clone_to_quote

The action string to be performed

query Parameters
include
string
Example: include=first_load

Includes child relationships in the response, format is comma separated. Check each model for the list of associated includes

header Parameters
X-API-TOKEN
required
string
Example: TOKEN

The API token to be used for authentication

X-Requested-With
required
string
Example: XMLHttpRequest

Used to send the XMLHttpRequest header

Responses

Response samples

Content type
application/json
{
  • "id": "Opnel5aKBz",
  • "client_id": "Opnel5aKBz",
  • "invitation_id": "Opnel5aKBz",
  • "client_contact_id": "Opnel5aKBz",
  • "user_id": "Opnel5aKBz",
  • "type_id": "1",
  • "date": "1-1-2014",
  • "transaction_reference": "xcsSxcs124asd",
  • "assigned_user_id": "Opnel5aKBz",
  • "private_notes": "The payment was refunded due to error",
  • "is_manual": true,
  • "is_deleted": true,
  • "amount": 10,
  • "refunded": 10,
  • "updated_at": 1434342123,
  • "archived_at": 1434342123,
  • "company_gateway_id": "3",
  • "paymentables": {
    },
  • "invoices": [
    ],
  • "credits": [
    ],
  • "number": "PAY_101",
  • "category_id": "Opnel5aKBz",
  • "custom_value1": "Payment reference 123",
  • "custom_value2": "Approved by John",
  • "custom_value3": "Urgent payment",
  • "custom_value4": "Q1 2024",
  • "exchange_currency_id": "2",
  • "exchange_rate": 1,
  • "idempotency_key": "key_1234567890abcdef"
}

Upload a payment document

Handles the uploading of a document to a payment

Authorizations:
ApiKeyAuth
path Parameters
id
required
string <string>
Example: D2J234DFA

The Payment Hashed ID

query Parameters
include
string
Example: include=first_load

Includes child relationships in the response, format is comma separated. Check each model for the list of associated includes

header Parameters
X-API-TOKEN
required
string
Example: TOKEN

The API token to be used for authentication

X-Requested-With
required
string
Example: XMLHttpRequest

Used to send the XMLHttpRequest header

Request Body schema: multipart/form-data
required

File Upload Body

_method
string
documents
Array of strings <binary> [ items <binary > ]

Responses

Response samples

Content type
application/json
{
  • "id": "Opnel5aKBz",
  • "client_id": "Opnel5aKBz",
  • "invitation_id": "Opnel5aKBz",
  • "client_contact_id": "Opnel5aKBz",
  • "user_id": "Opnel5aKBz",
  • "type_id": "1",
  • "date": "1-1-2014",
  • "transaction_reference": "xcsSxcs124asd",
  • "assigned_user_id": "Opnel5aKBz",
  • "private_notes": "The payment was refunded due to error",
  • "is_manual": true,
  • "is_deleted": true,
  • "amount": 10,
  • "refunded": 10,
  • "updated_at": 1434342123,
  • "archived_at": 1434342123,
  • "company_gateway_id": "3",
  • "paymentables": {
    },
  • "invoices": [
    ],
  • "credits": [
    ],
  • "number": "PAY_101",
  • "category_id": "Opnel5aKBz",
  • "custom_value1": "Payment reference 123",
  • "custom_value2": "Approved by John",
  • "custom_value3": "Urgent payment",
  • "custom_value4": "Q1 2024",
  • "exchange_currency_id": "2",
  • "exchange_rate": 1,
  • "idempotency_key": "key_1234567890abcdef"
}

Quotes

Endpoint definitions for interacting with quotes.

Download quote PDF

Downloads a specific quote

Authorizations:
ApiKeyAuth
path Parameters
invitation_key
required
string <string>
Example: D2J234DFA

The Credit Invitation Key

query Parameters
include
string
Example: include=first_load

Includes child relationships in the response, format is comma separated. Check each model for the list of associated includes

header Parameters
X-API-TOKEN
required
string
Example: TOKEN

The API token to be used for authentication

X-Requested-With
required
string
Example: XMLHttpRequest

Used to send the XMLHttpRequest header

Responses

Response samples

Content type
application/json
{
  • "message": "These credentials do not match our records / Invalid Token"
}

List quotes

GET /api/v1/quotes

Lists quotes, search and filters allow fine grained lists to be generated.

Query parameters can be added to performed more fine grained filtering of the quotes, these are handled by the QuoteFilters class which defines the methods available

Authorizations:
ApiKeyAuth
query Parameters
include
string
Example: include=first_load

Includes child relationships in the response, format is comma separated. Check each model for the list of associated includes

index
string
Example: index=user

Replaces the default response index from data to a user specific string

ie.

  ?index=new_index

response is wrapped

  {
    'new_index' : [
      .....  
    ]
  }
per_page
integer
Example: per_page=20

The number of records to return for each request, default is 20

page
integer
Example: page=1

The page number to return for this request (when performing pagination), default is 1

status
string
Example: status=?status=archived,deleted

Filter the entity based on their status. ie active / archived / deleted. Format is a comma separated string with any of the following options:

  • active
  • archived
  • deleted
GET /api/v1/invoices?status=archived,deleted
Returns only archived and deleted invoices
client_id
string
Example: client_id=?client_id={client_id}

Filters the entity list by client_id. Suitable when you only want the entities of a specific client.

GET /api/v1/invoices?client_id=AxB7Hjk9
Returns only invoices for the specified client
created_at
integer
Example: created_at=1641772800

Filters the entity list by the created at timestamp. Parameter value can be a datetime string or unix timestamp

GET /api/v1/invoices?created_at=2022-01-10
Returns entities created on January 10th, 2022
updated_at
integer
Example: updated_at=1641772800

Filters the entity list by the updated at timestamp. Parameter value can be a datetime string or unix timestamp

GET /api/v1/invoices?updated_at=2022-01-10
Returns entities last updated on January 10th, 2022
is_deleted
boolean
Example: is_deleted=true

Filters the entity list by entities that have been deleted.

GET /api/v1/invoices?is_deleted=true
Returns only soft-deleted entities
filter_deleted_clients
string
Example: filter_deleted_clients=?filter_deleted_clients=true

Filters the entity list and only returns entities for clients that have not been deleted

GET /api/v1/invoices?filter_deleted_clients=true
Returns only invoices for active (non-deleted) clients
vendor_id
string
Example: vendor_id=?vendor_id={vendor_id}

Filters the entity list by an associated vendor

GET /api/v1/purchases?vendor_id=AxB7Hjk9
Returns only purchases for the specified vendor
filter
string
Example: filter=?filter=bob

Searches across a range of columns including:

  • number
  • custom_value1
  • custom_value2
  • custom_value3
  • custom_value4
client_status
string
Example: client_status=?client_status=paid,unpaid

A comma separated list of quote status strings. Valid options include:

  • all
  • draft
  • sent
  • approved
  • expired
  • upcoming
number
string
Example: number=?number=Q-001

Search quote by quote number

sort
string
Example: sort=id|desc number|desc balance|asc

Returns the list sorted by column in ascending or descending order.

header Parameters
X-API-TOKEN
required
string
Example: TOKEN

The API token to be used for authentication

X-Requested-With
required
string
Example: XMLHttpRequest

Used to send the XMLHttpRequest header

Responses

Request samples 

$ninja = new InvoiceNinja("your_token");
$quotes = $ninja->quotes->all([
  'per_page' => 10,
  'page' => 1,
  'sort' => 'number|asc'
]);

Response samples

Content type
application/json
{
  • "data": [
    ],
  • "meta": {
    }
}

Create quote

POST /api/v1/quotes

Creates an quote for a client.

Triggered actions are available when updating or creating an quote.

These are query parameters that can be chained in order to perform additional actions on the entity, these include:

?send_email=true [Saves and sends the quote]
?mark_sent=true [Saves and marks the quote as sent]
?approve=true [Saves and approves the quote]
?convert=true [Saves and converts the quote to an invoice]
?save_default_footer=true [Saves the current footer as the default footer]
?save_default_terms=true [Saves the current terms as the default terms]
Authorizations:
ApiKeyAuth
query Parameters
include
string
Example: include=first_load

Includes child relationships in the response, format is comma separated. Check each model for the list of associated includes

header Parameters
X-API-TOKEN
required
string
Example: TOKEN

The API token to be used for authentication

X-Requested-With
required
string
Example: XMLHttpRequest

Used to send the XMLHttpRequest header

Request Body schema: application/json
required

Quote object that needs to be added to the company

client_id
required
string

The hashed ID of the client

date
required
string <date>

Quote date

due_date
required
string <date>

Due date for the quote

private_notes
string

Private notes for the quote

public_notes
string

Public notes for the quote

custom_value1
string

Custom field value 1

custom_value2
string

Custom field value 2

custom_value3
string

Custom field value 3

custom_value4
string

Custom field value 4

Array of objects (InvoiceItem)

An array of objects which define the line items of the quote

Responses

Request samples

Content type
application/json
{
  • "client_id": "D2J234DFA",
  • "date": "2024-01-01",
  • "due_date": "2024-01-31",
  • "private_notes": "Internal notes about this quote",
  • "public_notes": "Thank you for your business!",
  • "custom_value1": "Custom value 1",
  • "custom_value2": "Custom value 2",
  • "custom_value3": "Custom value 3",
  • "custom_value4": "Custom value 4",
  • "line_items": [
    ]
}

Response samples

Content type
application/json
{
  • "id": "Opnel5aKBz",
  • "user_id": "",
  • "assigned_user_id": "",
  • "client_id": "",
  • "status_id": "",
  • "number": "QUOTE_101",
  • "po_number": "PO-1234",
  • "terms": "These are some quote terms. Valid for 14 days.",
  • "public_notes": "These are public notes which the client may see",
  • "private_notes": "These are private notes, not to be disclosed to the client",
  • "footer": "The text goes in the footer of the quote",
  • "custom_value1": "A custom value",
  • "custom_value2": "A custom value",
  • "custom_value3": "A custom value",
  • "custom_value4": "A custom value",
  • "tax_name1": "GST",
  • "tax_name2": "VAT",
  • "tax_rate1": 10,
  • "tax_rate2": 10,
  • "tax_name3": "",
  • "tax_rate3": 10,
  • "total_taxes": 10,
  • "line_items": [
    ],
  • "amount": 10,
  • "balance": 10,
  • "paid_to_date": 10,
  • "discount": 10,
  • "partial": 10,
  • "is_amount_discount": true,
  • "is_deleted": false,
  • "uses_inclusive_taxes": true,
  • "date": "1994-07-30",
  • "last_sent_date": "1994-07-30",
  • "next_send_date": "1994-07-30",
  • "partial_due_date": "1994-07-30",
  • "due_date": "1994-07-30",
  • "settings": {
    },
  • "last_viewed": 1434342123,
  • "updated_at": 1434342123,
  • "archived_at": 1434342123,
  • "custom_surcharge1": 10,
  • "custom_surcharge2": 10,
  • "custom_surcharge3": 10,
  • "custom_surcharge4": 10,
  • "custom_surcharge_tax1": true,
  • "custom_surcharge_tax2": true,
  • "custom_surcharge_tax3": true,
  • "custom_surcharge_tax4": true,
  • "location_id": "Opnel5aKBz",
  • "design_id": "Opnel5aKBz",
  • "exchange_rate": 1,
  • "project_id": "Opnel5aKBz",
  • "subscription_id": "Opnel5aKBz",
  • "vendor_id": "Opnel5aKBz"
}

Show quote

GET /api/v1/quotes/{id}

Displays an Quote by id

Authorizations:
ApiKeyAuth
path Parameters
id
required
string <string>
Example: D2J234DFA

The Quote Hashed ID

query Parameters
include
string
Example: include=first_load

Includes child relationships in the response, format is comma separated. Check each model for the list of associated includes

header Parameters
X-API-TOKEN
required
string
Example: TOKEN

The API token to be used for authentication

X-Requested-With
required
string
Example: XMLHttpRequest

Used to send the XMLHttpRequest header

Responses

Request samples 

$ninja = new InvoiceNinja("your_token");
$quote = $ninja->quotes->get("D2J234DFA");

Response samples

Content type
application/json
{
  • "id": "Opnel5aKBz",
  • "user_id": "",
  • "assigned_user_id": "",
  • "client_id": "",
  • "status_id": "",
  • "number": "QUOTE_101",
  • "po_number": "PO-1234",
  • "terms": "These are some quote terms. Valid for 14 days.",
  • "public_notes": "These are public notes which the client may see",
  • "private_notes": "These are private notes, not to be disclosed to the client",
  • "footer": "The text goes in the footer of the quote",
  • "custom_value1": "A custom value",
  • "custom_value2": "A custom value",
  • "custom_value3": "A custom value",
  • "custom_value4": "A custom value",
  • "tax_name1": "GST",
  • "tax_name2": "VAT",
  • "tax_rate1": 10,
  • "tax_rate2": 10,
  • "tax_name3": "",
  • "tax_rate3": 10,
  • "total_taxes": 10,
  • "line_items": [
    ],
  • "amount": 10,
  • "balance": 10,
  • "paid_to_date": 10,
  • "discount": 10,
  • "partial": 10,
  • "is_amount_discount": true,
  • "is_deleted": false,
  • "uses_inclusive_taxes": true,
  • "date": "1994-07-30",
  • "last_sent_date": "1994-07-30",
  • "next_send_date": "1994-07-30",
  • "partial_due_date": "1994-07-30",
  • "due_date": "1994-07-30",
  • "settings": {
    },
  • "last_viewed": 1434342123,
  • "updated_at": 1434342123,
  • "archived_at": 1434342123,
  • "custom_surcharge1": 10,
  • "custom_surcharge2": 10,
  • "custom_surcharge3": 10,
  • "custom_surcharge4": 10,
  • "custom_surcharge_tax1": true,
  • "custom_surcharge_tax2": true,
  • "custom_surcharge_tax3": true,
  • "custom_surcharge_tax4": true,
  • "location_id": "Opnel5aKBz",
  • "design_id": "Opnel5aKBz",
  • "exchange_rate": 1,
  • "project_id": "Opnel5aKBz",
  • "subscription_id": "Opnel5aKBz",
  • "vendor_id": "Opnel5aKBz"
}

Update quote

PUT /api/v1/quotes/{id}

Handles the updating of an Quote by id.

Triggered actions are available when updating or creating an quote.

These are query parameters that can be chained in order to perform additional actions on the entity, these include:

?send_email=true [Saves and sends the quote]
?mark_sent=true [Saves and marks the quote as sent]
?approve=true [Saves and approves the quote]
?convert=true [Saves and converts the quote to an invoice]
?save_default_footer=true [Saves the current footer as the default footer]
?save_default_terms=true [Saves the current terms as the default terms]
Authorizations:
ApiKeyAuth
path Parameters
id
required
string <string>
Example: D2J234DFA

The Quote Hashed ID

query Parameters
include
string
Example: include=first_load

Includes child relationships in the response, format is comma separated. Check each model for the list of associated includes

header Parameters
X-API-TOKEN
required
string
Example: TOKEN

The API token to be used for authentication

X-Requested-With
required
string
Example: XMLHttpRequest

Used to send the XMLHttpRequest header

Request Body schema: application/json
required

Quote object that needs to be updated

client_id
required
string

The hashed ID of the client

date
required
string <date>

Quote date

due_date
required
string <date>

Due date for the quote

private_notes
string

Private notes for the quote

public_notes
string

Public notes for the quote

custom_value1
string

Custom field value 1

custom_value2
string

Custom field value 2

custom_value3
string

Custom field value 3

custom_value4
string

Custom field value 4

Array of objects (InvoiceItem)

An array of objects which define the line items of the quote

Responses

Request samples

Content type
application/json
{
  • "client_id": "D2J234DFA",
  • "date": "2024-01-01",
  • "due_date": "2024-01-31",
  • "private_notes": "Internal notes about this quote",
  • "public_notes": "Thank you for your business!",
  • "custom_value1": "Custom value 1",
  • "custom_value2": "Custom value 2",
  • "custom_value3": "Custom value 3",
  • "custom_value4": "Custom value 4",
  • "line_items": [
    ]
}

Response samples

Content type
application/json
{
  • "id": "Opnel5aKBz",
  • "user_id": "",
  • "assigned_user_id": "",
  • "client_id": "",
  • "status_id": "",
  • "number": "QUOTE_101",
  • "po_number": "PO-1234",
  • "terms": "These are some quote terms. Valid for 14 days.",
  • "public_notes": "These are public notes which the client may see",
  • "private_notes": "These are private notes, not to be disclosed to the client",
  • "footer": "The text goes in the footer of the quote",
  • "custom_value1": "A custom value",
  • "custom_value2": "A custom value",
  • "custom_value3": "A custom value",
  • "custom_value4": "A custom value",
  • "tax_name1": "GST",
  • "tax_name2": "VAT",
  • "tax_rate1": 10,
  • "tax_rate2": 10,
  • "tax_name3": "",
  • "tax_rate3": 10,
  • "total_taxes": 10,
  • "line_items": [
    ],
  • "amount": 10,
  • "balance": 10,
  • "paid_to_date": 10,
  • "discount": 10,
  • "partial": 10,
  • "is_amount_discount": true,
  • "is_deleted": false,
  • "uses_inclusive_taxes": true,
  • "date": "1994-07-30",
  • "last_sent_date": "1994-07-30",
  • "next_send_date": "1994-07-30",
  • "partial_due_date": "1994-07-30",
  • "due_date": "1994-07-30",
  • "settings": {
    },
  • "last_viewed": 1434342123,
  • "updated_at": 1434342123,
  • "archived_at": 1434342123,
  • "custom_surcharge1": 10,
  • "custom_surcharge2": 10,
  • "custom_surcharge3": 10,
  • "custom_surcharge4": 10,
  • "custom_surcharge_tax1": true,
  • "custom_surcharge_tax2": true,
  • "custom_surcharge_tax3": true,
  • "custom_surcharge_tax4": true,
  • "location_id": "Opnel5aKBz",
  • "design_id": "Opnel5aKBz",
  • "exchange_rate": 1,
  • "project_id": "Opnel5aKBz",
  • "subscription_id": "Opnel5aKBz",
  • "vendor_id": "Opnel5aKBz"
}

Delete quote

DELETE /api/v1/quotes/{id}

Handles the deletion of an Quote by id.

Authorizations:
ApiKeyAuth
path Parameters
id
required
string <string>
Example: D2J234DFA

The Quote Hashed ID

query Parameters
include
string
Example: include=first_load

Includes child relationships in the response, format is comma separated. Check each model for the list of associated includes

header Parameters
X-API-TOKEN
required
string
Example: TOKEN

The API token to be used for authentication

X-Requested-With
required
string
Example: XMLHttpRequest

Used to send the XMLHttpRequest header

Responses

Request samples 

$ninja = new InvoiceNinja("your_token");
$ninja->quotes->delete("D2J234DFA");

Response samples

Content type
application/json
{
  • "message": "These credentials do not match our records / Invalid Token"
}

Edit quote

GET /api/v1/quotes/{id}/edit

Displays an Quote by id for editting

Authorizations:
ApiKeyAuth
path Parameters
id
required
string <string>
Example: D2J234DFA

The Quote Hashed ID

query Parameters
include
string
Example: include=first_load

Includes child relationships in the response, format is comma separated. Check each model for the list of associated includes

header Parameters
X-API-TOKEN
required
string
Example: TOKEN

The API token to be used for authentication

X-Requested-With
required
string
Example: XMLHttpRequest

Used to send the XMLHttpRequest header

Responses

Request samples 

$ninja = new InvoiceNinja("your_token");
$quote = $ninja->quotes->edit("D2J234DFA");

Response samples

Content type
application/json
{
  • "id": "Opnel5aKBz",
  • "user_id": "",
  • "assigned_user_id": "",
  • "client_id": "",
  • "status_id": "",
  • "number": "QUOTE_101",
  • "po_number": "PO-1234",
  • "terms": "These are some quote terms. Valid for 14 days.",
  • "public_notes": "These are public notes which the client may see",
  • "private_notes": "These are private notes, not to be disclosed to the client",
  • "footer": "The text goes in the footer of the quote",
  • "custom_value1": "A custom value",
  • "custom_value2": "A custom value",
  • "custom_value3": "A custom value",
  • "custom_value4": "A custom value",
  • "tax_name1": "GST",
  • "tax_name2": "VAT",
  • "tax_rate1": 10,
  • "tax_rate2": 10,
  • "tax_name3": "",
  • "tax_rate3": 10,
  • "total_taxes": 10,
  • "line_items": [
    ],
  • "amount": 10,
  • "balance": 10,
  • "paid_to_date": 10,
  • "discount": 10,
  • "partial": 10,
  • "is_amount_discount": true,
  • "is_deleted": false,
  • "uses_inclusive_taxes": true,
  • "date": "1994-07-30",
  • "last_sent_date": "1994-07-30",
  • "next_send_date": "1994-07-30",
  • "partial_due_date": "1994-07-30",
  • "due_date": "1994-07-30",
  • "settings": {
    },
  • "last_viewed": 1434342123,
  • "updated_at": 1434342123,
  • "archived_at": 1434342123,
  • "custom_surcharge1": 10,
  • "custom_surcharge2": 10,
  • "custom_surcharge3": 10,
  • "custom_surcharge4": 10,
  • "custom_surcharge_tax1": true,
  • "custom_surcharge_tax2": true,
  • "custom_surcharge_tax3": true,
  • "custom_surcharge_tax4": true,
  • "location_id": "Opnel5aKBz",
  • "design_id": "Opnel5aKBz",
  • "exchange_rate": 1,
  • "project_id": "Opnel5aKBz",
  • "subscription_id": "Opnel5aKBz",
  • "vendor_id": "Opnel5aKBz"
}

Blank quote

GET /api/v1/quotes/create

Returns a blank object with default values

Authorizations:
ApiKeyAuth
query Parameters
include
string
Example: include=first_load

Includes child relationships in the response, format is comma separated. Check each model for the list of associated includes

header Parameters
X-API-TOKEN
required
string
Example: TOKEN

The API token to be used for authentication

X-Requested-With
required
string
Example: XMLHttpRequest

Used to send the XMLHttpRequest header

Responses

Request samples 

$ninja = new InvoiceNinja("your_token");
$quote = $ninja->quotes->create();

Response samples

Content type
application/json
{
  • "id": "Opnel5aKBz",
  • "user_id": "",
  • "assigned_user_id": "",
  • "client_id": "",
  • "status_id": "",
  • "number": "QUOTE_101",
  • "po_number": "PO-1234",
  • "terms": "These are some quote terms. Valid for 14 days.",
  • "public_notes": "These are public notes which the client may see",
  • "private_notes": "These are private notes, not to be disclosed to the client",
  • "footer": "The text goes in the footer of the quote",
  • "custom_value1": "A custom value",
  • "custom_value2": "A custom value",
  • "custom_value3": "A custom value",
  • "custom_value4": "A custom value",
  • "tax_name1": "GST",
  • "tax_name2": "VAT",
  • "tax_rate1": 10,
  • "tax_rate2": 10,
  • "tax_name3": "",
  • "tax_rate3": 10,
  • "total_taxes": 10,
  • "line_items": [
    ],
  • "amount": 10,
  • "balance": 10,
  • "paid_to_date": 10,
  • "discount": 10,
  • "partial": 10,
  • "is_amount_discount": true,
  • "is_deleted": false,
  • "uses_inclusive_taxes": true,
  • "date": "1994-07-30",
  • "last_sent_date": "1994-07-30",
  • "next_send_date": "1994-07-30",
  • "partial_due_date": "1994-07-30",
  • "due_date": "1994-07-30",
  • "settings": {
    },
  • "last_viewed": 1434342123,
  • "updated_at": 1434342123,
  • "archived_at": 1434342123,
  • "custom_surcharge1": 10,
  • "custom_surcharge2": 10,
  • "custom_surcharge3": 10,
  • "custom_surcharge4": 10,
  • "custom_surcharge_tax1": true,
  • "custom_surcharge_tax2": true,
  • "custom_surcharge_tax3": true,
  • "custom_surcharge_tax4": true,
  • "location_id": "Opnel5aKBz",
  • "design_id": "Opnel5aKBz",
  • "exchange_rate": 1,
  • "project_id": "Opnel5aKBz",
  • "subscription_id": "Opnel5aKBz",
  • "vendor_id": "Opnel5aKBz"
}

Bulk quote actions

POST /api/v1/quotes/bulk

Performs bulk actions on an array of quotes

Authorizations:
ApiKeyAuth
query Parameters
index
string
Example: index=user

Replaces the default response index from data to a user specific string

ie.

  ?index=new_index

response is wrapped

  {
    'new_index' : [
      .....  
    ]
  }
header Parameters
X-API-TOKEN
required
string
Example: TOKEN

The API token to be used for authentication

X-Requested-With
required
string
Example: XMLHttpRequest

Used to send the XMLHttpRequest header

Request Body schema: application/json
required

Bulk action details

action
string

The action to be performed, options include:

  • approve
    Bulk approve an array of quotes
  • convert
    Bulk convert an array of quotes to invoices
  • send_email
    Bulk send an array of quotes as emails
  • mark_sent
    Bulk mark an array of quotes as sent
  • restore
    Restores an array of quotes
  • delete
    Deletes an array of invoices
  • archive
    Archives an array of invoices
ids
Array of strings

Responses

Request samples

Content type
application/json
{
  • "action": "convert",
  • "ids": [
    ]
}

Response samples

Content type
application/json
{
  • "id": "Opnel5aKBz",
  • "user_id": "",
  • "assigned_user_id": "",
  • "client_id": "",
  • "status_id": "",
  • "number": "QUOTE_101",
  • "po_number": "PO-1234",
  • "terms": "These are some quote terms. Valid for 14 days.",
  • "public_notes": "These are public notes which the client may see",
  • "private_notes": "These are private notes, not to be disclosed to the client",
  • "footer": "The text goes in the footer of the quote",
  • "custom_value1": "A custom value",
  • "custom_value2": "A custom value",
  • "custom_value3": "A custom value",
  • "custom_value4": "A custom value",
  • "tax_name1": "GST",
  • "tax_name2": "VAT",
  • "tax_rate1": 10,
  • "tax_rate2": 10,
  • "tax_name3": "",
  • "tax_rate3": 10,
  • "total_taxes": 10,
  • "line_items": [
    ],
  • "amount": 10,
  • "balance": 10,
  • "paid_to_date": 10,
  • "discount": 10,
  • "partial": 10,
  • "is_amount_discount": true,
  • "is_deleted": false,
  • "uses_inclusive_taxes": true,
  • "date": "1994-07-30",
  • "last_sent_date": "1994-07-30",
  • "next_send_date": "1994-07-30",
  • "partial_due_date": "1994-07-30",
  • "due_date": "1994-07-30",
  • "settings": {
    },
  • "last_viewed": 1434342123,
  • "updated_at": 1434342123,
  • "archived_at": 1434342123,
  • "custom_surcharge1": 10,
  • "custom_surcharge2": 10,
  • "custom_surcharge3": 10,
  • "custom_surcharge4": 10,
  • "custom_surcharge_tax1": true,
  • "custom_surcharge_tax2": true,
  • "custom_surcharge_tax3": true,
  • "custom_surcharge_tax4": true,
  • "location_id": "Opnel5aKBz",
  • "design_id": "Opnel5aKBz",
  • "exchange_rate": 1,
  • "project_id": "Opnel5aKBz",
  • "subscription_id": "Opnel5aKBz",
  • "vendor_id": "Opnel5aKBz"
}

Performs a custom action on an Quote Deprecated

Performs a custom action on an Quote.

The current range of actions are as follows
- clone_to_quote
- history
- delivery_note
- mark_paid
- download
- archive
- delete
- convert
- convert_to_invoice
- email
Authorizations:
ApiKeyAuth
path Parameters
id
required
string <string>
Example: D2J234DFA

The Quote Hashed ID

action
required
string <string>
Example: clone_to_quote

The action string to be performed

query Parameters
include
string
Example: include=first_load

Includes child relationships in the response, format is comma separated. Check each model for the list of associated includes

header Parameters
X-API-TOKEN
required
string
Example: TOKEN

The API token to be used for authentication

X-Requested-With
required
string
Example: XMLHttpRequest

Used to send the XMLHttpRequest header

Responses

Response samples

Content type
application/json
{
  • "id": "Opnel5aKBz",
  • "user_id": "",
  • "assigned_user_id": "",
  • "client_id": "",
  • "status_id": "",
  • "number": "QUOTE_101",
  • "po_number": "PO-1234",
  • "terms": "These are some quote terms. Valid for 14 days.",
  • "public_notes": "These are public notes which the client may see",
  • "private_notes": "These are private notes, not to be disclosed to the client",
  • "footer": "The text goes in the footer of the quote",
  • "custom_value1": "A custom value",
  • "custom_value2": "A custom value",
  • "custom_value3": "A custom value",
  • "custom_value4": "A custom value",
  • "tax_name1": "GST",
  • "tax_name2": "VAT",
  • "tax_rate1": 10,
  • "tax_rate2": 10,
  • "tax_name3": "",
  • "tax_rate3": 10,
  • "total_taxes": 10,
  • "line_items": [
    ],
  • "amount": 10,
  • "balance": 10,
  • "paid_to_date": 10,
  • "discount": 10,
  • "partial": 10,
  • "is_amount_discount": true,
  • "is_deleted": false,
  • "uses_inclusive_taxes": true,
  • "date": "1994-07-30",
  • "last_sent_date": "1994-07-30",
  • "next_send_date": "1994-07-30",
  • "partial_due_date": "1994-07-30",
  • "due_date": "1994-07-30",
  • "settings": {
    },
  • "last_viewed": 1434342123,
  • "updated_at": 1434342123,
  • "archived_at": 1434342123,
  • "custom_surcharge1": 10,
  • "custom_surcharge2": 10,
  • "custom_surcharge3": 10,
  • "custom_surcharge4": 10,
  • "custom_surcharge_tax1": true,
  • "custom_surcharge_tax2": true,
  • "custom_surcharge_tax3": true,
  • "custom_surcharge_tax4": true,
  • "location_id": "Opnel5aKBz",
  • "design_id": "Opnel5aKBz",
  • "exchange_rate": 1,
  • "project_id": "Opnel5aKBz",
  • "subscription_id": "Opnel5aKBz",
  • "vendor_id": "Opnel5aKBz"
}

Download quote PDF

Downloads a specific quote

Authorizations:
ApiKeyAuth
path Parameters
invitation_key
required
string <string>
Example: D2J234DFA

The Quote Invitation Key

query Parameters
include
string
Example: include=first_load

Includes child relationships in the response, format is comma separated. Check each model for the list of associated includes

header Parameters
X-API-TOKEN
required
string
Example: TOKEN

The API token to be used for authentication

X-Requested-With
required
string
Example: XMLHttpRequest

Used to send the XMLHttpRequest header

Responses

Response samples

Content type
application/json
{
  • "message": "These credentials do not match our records / Invalid Token"
}

Upload a quote document

Handles the uploading of a document to a quote

Authorizations:
ApiKeyAuth
path Parameters
id
required
string <string>
Example: D2J234DFA

The Quote Hashed ID

query Parameters
include
string
Example: include=first_load

Includes child relationships in the response, format is comma separated. Check each model for the list of associated includes

header Parameters
X-API-TOKEN
required
string
Example: TOKEN

The API token to be used for authentication

X-Requested-With
required
string
Example: XMLHttpRequest

Used to send the XMLHttpRequest header

Request Body schema: multipart/form-data
required

File Upload Body

_method
string
documents
Array of strings <binary> [ items <binary > ]

Responses

Response samples

Content type
application/json
{
  • "id": "Opnel5aKBz",
  • "user_id": "",
  • "assigned_user_id": "",
  • "client_id": "",
  • "status_id": "",
  • "number": "QUOTE_101",
  • "po_number": "PO-1234",
  • "terms": "These are some quote terms. Valid for 14 days.",
  • "public_notes": "These are public notes which the client may see",
  • "private_notes": "These are private notes, not to be disclosed to the client",
  • "footer": "The text goes in the footer of the quote",
  • "custom_value1": "A custom value",
  • "custom_value2": "A custom value",
  • "custom_value3": "A custom value",
  • "custom_value4": "A custom value",
  • "tax_name1": "GST",
  • "tax_name2": "VAT",
  • "tax_rate1": 10,
  • "tax_rate2": 10,
  • "tax_name3": "",
  • "tax_rate3": 10,
  • "total_taxes": 10,
  • "line_items": [
    ],
  • "amount": 10,
  • "balance": 10,
  • "paid_to_date": 10,
  • "discount": 10,
  • "partial": 10,
  • "is_amount_discount": true,
  • "is_deleted": false,
  • "uses_inclusive_taxes": true,
  • "date": "1994-07-30",
  • "last_sent_date": "1994-07-30",
  • "next_send_date": "1994-07-30",
  • "partial_due_date": "1994-07-30",
  • "due_date": "1994-07-30",
  • "settings": {
    },
  • "last_viewed": 1434342123,
  • "updated_at": 1434342123,
  • "archived_at": 1434342123,
  • "custom_surcharge1": 10,
  • "custom_surcharge2": 10,
  • "custom_surcharge3": 10,
  • "custom_surcharge4": 10,
  • "custom_surcharge_tax1": true,
  • "custom_surcharge_tax2": true,
  • "custom_surcharge_tax3": true,
  • "custom_surcharge_tax4": true,
  • "location_id": "Opnel5aKBz",
  • "design_id": "Opnel5aKBz",
  • "exchange_rate": 1,
  • "project_id": "Opnel5aKBz",
  • "subscription_id": "Opnel5aKBz",
  • "vendor_id": "Opnel5aKBz"
}

Credits

Endpoint definitions for interacting with credits.

List credits

Lists credits, search and filters allow fine grained lists to be generated. * * Query parameters can be added to performed more fine grained filtering of the credits, these are handled by the CreditFilters class which defines the methods available

Authorizations:
ApiKeyAuth
query Parameters
include
string
Example: include=first_load

Includes child relationships in the response, format is comma separated. Check each model for the list of associated includes

index
string
Example: index=user

Replaces the default response index from data to a user specific string

ie.

  ?index=new_index

response is wrapped

  {
    'new_index' : [
      .....  
    ]
  }
per_page
integer
Example: per_page=20

The number of records to return for each request, default is 20

page
integer
Example: page=1

The page number to return for this request (when performing pagination), default is 1

header Parameters
X-API-TOKEN
required
string
Example: TOKEN

The API token to be used for authentication

X-Requested-With
required
string
Example: XMLHttpRequest

Used to send the XMLHttpRequest header

Responses

Request samples 

$ninja = new InvoiceNinja("YOUR-TOKEN");
$credits = $ninja->credits->all([
    'per_page' => 10,
    'page' => 1
]);

Response samples

Content type
application/json
{
  • "data": [
    ],
  • "meta": {
    }
}

Create credit

Adds an credit to the system

Authorizations:
ApiKeyAuth
query Parameters
include
string
Example: include=first_load

Includes child relationships in the response, format is comma separated. Check each model for the list of associated includes

header Parameters
X-API-TOKEN
required
string
Example: TOKEN

The API token to be used for authentication

X-Requested-With
required
string
Example: XMLHttpRequest

Used to send the XMLHttpRequest header

Request Body schema: application/json
required
user_id
string

The user hashed id

assigned_user_id
string

The assigned user hashed id

client_id
required
string

The client hashed id

number
string

The credit number - is a unique alpha numeric number per credit per company

po_number
string

The purchase order associated with this credit

terms
string

The credit terms

public_notes
string

The public notes of the credit

private_notes
string

The private notes of the credit

footer
string

The credit footer notes

custom_value1
string

A custom field value

custom_value2
string

A custom field value

custom_value3
string

A custom field value

custom_value4
string

A custom field value

tax_name1
string

The tax name

tax_name2
string

The tax name

tax_rate1
number <float>

The tax rate

tax_rate2
number <float>

The tax rate

tax_name3
string

The tax name

tax_rate3
number <float>

The tax rate

Array of objects (InvoiceItem)

An array of objects which define the line items of the credit

Array of objects (CreditInvitationRequest)

An array of objects which define the invitations of the credit

discount
number <float>

The credit discount, can be an amount or a percentage

partial
number <float>

The deposit/partial amount

is_amount_discount
boolean

Flag determining if the discount is an amount or a percentage

uses_inclusive_taxes
boolean

Defines the type of taxes used as either inclusive or exclusive

date
string <date>

The credit Date

partial_due_date
string <date>

The due date for the deposit/partial amount

due_date
string <date>

The due date of the credit

custom_surcharge1
number <float>

First Custom Surcharge

custom_surcharge2
number <float>

Second Custom Surcharge

custom_surcharge3
number <float>

Third Custom Surcharge

custom_surcharge4
number <float>

Fourth Custom Surcharge

custom_surcharge_tax1
boolean

Toggles charging taxes on custom surcharge amounts

custom_surcharge_tax2
boolean

Toggles charging taxes on custom surcharge amounts

custom_surcharge_tax3
boolean

Toggles charging taxes on custom surcharge amounts

custom_surcharge_tax4
boolean

Toggles charging taxes on custom surcharge amounts

project_id
string

The project associated with this credit

Responses

Request samples

Content type
application/json
{
  • "user_id": "AxP7K9nY5z",
  • "assigned_user_id": "Bw2M8vR4qL",
  • "client_id": "Ht5N9cX3jK",
  • "number": "INV-2024-0001",
  • "po_number": "PO-2024-0123",
  • "terms": "Net 30 - Payment is due within 30 days of credit date",
  • "public_notes": "Thank you for your business. Please include credit number with payment.",
  • "private_notes": "Client requested expedited delivery - premium rates apply",
  • "footer": "Payment accepted via bank transfer or credit card",
  • "custom_value1": "Department: Sales",
  • "custom_value2": "Region: North America",
  • "custom_value3": "Contract: C-2024-156",
  • "custom_value4": "Priority: High",
  • "tax_name1": "VAT",
  • "tax_name2": "GST",
  • "tax_rate1": 20,
  • "tax_rate2": 5,
  • "tax_name3": "State Tax",
  • "tax_rate3": 8.5,
  • "line_items": [
    ],
  • "invitations": [
    ],
  • "discount": 15,
  • "partial": 250,
  • "is_amount_discount": true,
  • "uses_inclusive_taxes": true,
  • "date": "2024-03-15",
  • "partial_due_date": "2024-03-29",
  • "due_date": "2024-04-14",
  • "custom_surcharge1": 25,
  • "custom_surcharge2": 35,
  • "custom_surcharge3": 45,
  • "custom_surcharge4": 55,
  • "custom_surcharge_tax1": true,
  • "custom_surcharge_tax2": true,
  • "custom_surcharge_tax3": true,
  • "custom_surcharge_tax4": true,
  • "project_id": "Opnel5aKBz"
}

Response samples

Content type
application/json
{
  • "id": "Opnel5aKBz",
  • "user_id": "1a2b3c4d5e",
  • "assigned_user_id": "6f7g8h9i0j",
  • "client_id": "p1q2r3s4t5",
  • "status_id": "3",
  • "invoice_id": "u1v2w3x4y5",
  • "number": "QUOTE_101",
  • "po_number": "PO_12345",
  • "terms": "Net 30",
  • "public_notes": "Thank you for your business.",
  • "private_notes": "Client is requesting a discount.",
  • "footer": "Footer text goes here.",
  • "custom_value1": "Custom data 1",
  • "custom_value2": "Custom data 2",
  • "custom_value3": "Custom data 3",
  • "custom_value4": "Custom data 4",
  • "tax_name1": "VAT",
  • "tax_name2": "GST",
  • "tax_rate1": 10,
  • "tax_rate2": 5,
  • "tax_name3": "PST",
  • "tax_rate3": 8,
  • "total_taxes": 23,
  • "line_items": [
    ],
  • "invitations": [
    ],
  • "amount": 100,
  • "balance": 50,
  • "paid_to_date": 50,
  • "discount": 10,
  • "partial": 20,
  • "is_amount_discount": true,
  • "is_deleted": false,
  • "uses_inclusive_taxes": true,
  • "date": "1994-07-30",
  • "last_sent_date": "1994-07-30",
  • "next_send_date": "1994-07-30",
  • "partial_due_date": "1994-07-30",
  • "due_date": "1994-07-30",
  • "settings": {
    },
  • "last_viewed": 1434342123,
  • "updated_at": 1434342123,
  • "archived_at": 1434342123,
  • "custom_surcharge1": 10,
  • "custom_surcharge2": 10,
  • "custom_surcharge3": 10,
  • "custom_surcharge4": 10,
  • "custom_surcharge_tax1": true,
  • "custom_surcharge_tax2": true,
  • "custom_surcharge_tax3": true,
  • "custom_surcharge_tax4": true,
  • "location_id": "Opnel5aKBz",
  • "design_id": "Opnel5aKBz",
  • "exchange_rate": 1,
  • "project_id": "Opnel5aKBz",
  • "subscription_id": "Opnel5aKBz",
  • "vendor_id": "Opnel5aKBz"
}

Show credit

Displays an credit by id

Authorizations:
ApiKeyAuth
path Parameters
id
required
string <string>
Example: D2J234DFA

The Credit Hashed ID

query Parameters
include
string
Example: include=first_load

Includes child relationships in the response, format is comma separated. Check each model for the list of associated includes

header Parameters
X-API-TOKEN
required
string
Example: TOKEN

The API token to be used for authentication

X-Requested-With
required
string
Example: XMLHttpRequest

Used to send the XMLHttpRequest header

Responses

Request samples 

$ninja = new InvoiceNinja("YOUR-TOKEN");
$credit = $ninja->credits->show("D2J234DFA");

Response samples

Content type
application/json
{
  • "id": "Opnel5aKBz",
  • "user_id": "1a2b3c4d5e",
  • "assigned_user_id": "6f7g8h9i0j",
  • "client_id": "p1q2r3s4t5",
  • "status_id": "3",
  • "invoice_id": "u1v2w3x4y5",
  • "number": "QUOTE_101",
  • "po_number": "PO_12345",
  • "terms": "Net 30",
  • "public_notes": "Thank you for your business.",
  • "private_notes": "Client is requesting a discount.",
  • "footer": "Footer text goes here.",
  • "custom_value1": "Custom data 1",
  • "custom_value2": "Custom data 2",
  • "custom_value3": "Custom data 3",
  • "custom_value4": "Custom data 4",
  • "tax_name1": "VAT",
  • "tax_name2": "GST",
  • "tax_rate1": 10,
  • "tax_rate2": 5,
  • "tax_name3": "PST",
  • "tax_rate3": 8,
  • "total_taxes": 23,
  • "line_items": [
    ],
  • "invitations": [
    ],
  • "amount": 100,
  • "balance": 50,
  • "paid_to_date": 50,
  • "discount": 10,
  • "partial": 20,
  • "is_amount_discount": true,
  • "is_deleted": false,
  • "uses_inclusive_taxes": true,
  • "date": "1994-07-30",
  • "last_sent_date": "1994-07-30",
  • "next_send_date": "1994-07-30",
  • "partial_due_date": "1994-07-30",
  • "due_date": "1994-07-30",
  • "settings": {
    },
  • "last_viewed": 1434342123,
  • "updated_at": 1434342123,
  • "archived_at": 1434342123,
  • "custom_surcharge1": 10,
  • "custom_surcharge2": 10,
  • "custom_surcharge3": 10,
  • "custom_surcharge4": 10,
  • "custom_surcharge_tax1": true,
  • "custom_surcharge_tax2": true,
  • "custom_surcharge_tax3": true,
  • "custom_surcharge_tax4": true,
  • "location_id": "Opnel5aKBz",
  • "design_id": "Opnel5aKBz",
  • "exchange_rate": 1,
  • "project_id": "Opnel5aKBz",
  • "subscription_id": "Opnel5aKBz",
  • "vendor_id": "Opnel5aKBz"
}

Delete credit

Handles the deletion of an credit by id

Authorizations:
ApiKeyAuth
path Parameters
id
required
string <string>
Example: D2J234DFA

The Credit Hashed ID

query Parameters
include
string
Example: include=first_load

Includes child relationships in the response, format is comma separated. Check each model for the list of associated includes

header Parameters
X-API-TOKEN
required
string
Example: TOKEN

The API token to be used for authentication

X-Requested-With
required
string
Example: XMLHttpRequest

Used to send the XMLHttpRequest header

Responses

Request samples 

$ninja = new InvoiceNinja("YOUR-TOKEN");
$ninja->credits->delete("D2J234DFA");

Response samples

Content type
application/json
{
  • "message": "These credentials do not match our records / Invalid Token"
}

Edit credit

Displays an credit by id

Authorizations:
ApiKeyAuth
path Parameters
id
required
string <string>
Example: D2J234DFA

The Invoice Hashed ID

query Parameters
include
string
Example: include=first_load

Includes child relationships in the response, format is comma separated. Check each model for the list of associated includes

header Parameters
X-API-TOKEN
required
string
Example: TOKEN

The API token to be used for authentication

X-Requested-With
required
string
Example: XMLHttpRequest

Used to send the XMLHttpRequest header

Responses

Response samples

Content type
application/json
{
  • "id": "Opnel5aKBz",
  • "user_id": "Opnel5aKBz",
  • "assigned_user_id": "Opnel5aKBz",
  • "client_id": "Opnel5aKBz",
  • "status_id": "4",
  • "number": "INV_101",
  • "po_number": "PO-1234",
  • "terms": "These are invoice terms",
  • "public_notes": "These are some public notes",
  • "private_notes": "These are some private notes",
  • "footer": "",
  • "custom_value1": "2022-10-01",
  • "custom_value2": "Something custom",
  • "custom_value3": "",
  • "custom_value4": "",
  • "tax_name1": "",
  • "tax_name2": "",
  • "tax_rate1": 10,
  • "tax_rate2": 10,
  • "tax_name3": "",
  • "tax_rate3": 10,
  • "total_taxes": 10,
  • "line_items": [
    ],
  • "invitations": [
    ],
  • "amount": 10,
  • "balance": 10,
  • "paid_to_date": 10,
  • "discount": 10,
  • "partial": 10,
  • "is_amount_discount": true,
  • "is_deleted": true,
  • "uses_inclusive_taxes": true,
  • "date": "1994-07-30",
  • "last_sent_date": "1994-07-30",
  • "next_send_date": "1994-07-30",
  • "partial_due_date": "1994-07-30",
  • "due_date": "1994-07-30",
  • "last_viewed": 1434342123,
  • "updated_at": 1434342123,
  • "archived_at": 1434342123,
  • "custom_surcharge1": 10,
  • "custom_surcharge2": 10,
  • "custom_surcharge3": 10,
  • "custom_surcharge4": 10,
  • "custom_surcharge_tax1": true,
  • "custom_surcharge_tax2": true,
  • "custom_surcharge_tax3": true,
  • "custom_surcharge_tax4": true,
  • "project_id": "Opnel5aKBz",
  • "auto_bill_tries": 1,
  • "auto_bill_enabled": true,
  • "subscription_id": "Opnel5aKBz",
  • "location_id": "Opnel5aKBz",
  • "design_id": "Opnel5aKBz",
  • "e_invoice": { },
  • "exchange_rate": 1,
  • "vendor_id": "Opnel5aKBz"
}

Blank credit

Returns a blank object with default values

Authorizations:
ApiKeyAuth
query Parameters
include
string
Example: include=first_load

Includes child relationships in the response, format is comma separated. Check each model for the list of associated includes

header Parameters
X-API-TOKEN
required
string
Example: TOKEN

The API token to be used for authentication

X-Requested-With
required
string
Example: XMLHttpRequest

Used to send the XMLHttpRequest header

Responses

Response samples

Content type
application/json
{
  • "id": "Opnel5aKBz",
  • "user_id": "1a2b3c4d5e",
  • "assigned_user_id": "6f7g8h9i0j",
  • "client_id": "p1q2r3s4t5",
  • "status_id": "3",
  • "invoice_id": "u1v2w3x4y5",
  • "number": "QUOTE_101",
  • "po_number": "PO_12345",
  • "terms": "Net 30",
  • "public_notes": "Thank you for your business.",
  • "private_notes": "Client is requesting a discount.",
  • "footer": "Footer text goes here.",
  • "custom_value1": "Custom data 1",
  • "custom_value2": "Custom data 2",
  • "custom_value3": "Custom data 3",
  • "custom_value4": "Custom data 4",
  • "tax_name1": "VAT",
  • "tax_name2": "GST",
  • "tax_rate1": 10,
  • "tax_rate2": 5,
  • "tax_name3": "PST",
  • "tax_rate3": 8,
  • "total_taxes": 23,
  • "line_items": [
    ],
  • "invitations": [
    ],
  • "amount": 100,
  • "balance": 50,
  • "paid_to_date": 50,
  • "discount": 10,
  • "partial": 20,
  • "is_amount_discount": true,
  • "is_deleted": false,
  • "uses_inclusive_taxes": true,
  • "date": "1994-07-30",
  • "last_sent_date": "1994-07-30",
  • "next_send_date": "1994-07-30",
  • "partial_due_date": "1994-07-30",
  • "due_date": "1994-07-30",
  • "settings": {
    },
  • "last_viewed": 1434342123,
  • "updated_at": 1434342123,
  • "archived_at": 1434342123,
  • "custom_surcharge1": 10,
  • "custom_surcharge2": 10,
  • "custom_surcharge3": 10,
  • "custom_surcharge4": 10,
  • "custom_surcharge_tax1": true,
  • "custom_surcharge_tax2": true,
  • "custom_surcharge_tax3": true,
  • "custom_surcharge_tax4": true,
  • "location_id": "Opnel5aKBz",
  • "design_id": "Opnel5aKBz",
  • "exchange_rate": 1,
  • "project_id": "Opnel5aKBz",
  • "subscription_id": "Opnel5aKBz",
  • "vendor_id": "Opnel5aKBz"
}

Bulk credit actions

Authorizations:
ApiKeyAuth
query Parameters
index
string
Example: index=user

Replaces the default response index from data to a user specific string

ie.

  ?index=new_index

response is wrapped

  {
    'new_index' : [
      .....  
    ]
  }
header Parameters
X-API-TOKEN
required
string
Example: TOKEN

The API token to be used for authentication

X-Requested-With
required
string
Example: XMLHttpRequest

Used to send the XMLHttpRequest header

Request Body schema: application/json
required

User credentials

Array
string

Array of hashed IDs to be bulk 'actioned

Responses

Request samples

Content type
application/json
[
  • "[D2J234DFA,D2J234DFA,D2J234DFA]"
]

Response samples

Content type
application/json
{
  • "message": "These credentials do not match our records / Invalid Token"
}

Upload a credit document

Handles the uploading of a document to a credit

Authorizations:
ApiKeyAuth
path Parameters
id
required
string <string>
Example: D2J234DFA

The Credit Hashed ID

query Parameters
include
string
Example: include=first_load

Includes child relationships in the response, format is comma separated. Check each model for the list of associated includes

header Parameters
X-API-TOKEN
required
string
Example: TOKEN

The API token to be used for authentication

X-Requested-With
required
string
Example: XMLHttpRequest

Used to send the XMLHttpRequest header

Request Body schema: multipart/form-data
required

File Upload Body

_method
string
documents
Array of strings <binary> [ items <binary > ]

Responses

Response samples

Content type
application/json
{
  • "id": "Opnel5aKBz",
  • "user_id": "1a2b3c4d5e",
  • "assigned_user_id": "6f7g8h9i0j",
  • "client_id": "p1q2r3s4t5",
  • "status_id": "3",
  • "invoice_id": "u1v2w3x4y5",
  • "number": "QUOTE_101",
  • "po_number": "PO_12345",
  • "terms": "Net 30",
  • "public_notes": "Thank you for your business.",
  • "private_notes": "Client is requesting a discount.",
  • "footer": "Footer text goes here.",
  • "custom_value1": "Custom data 1",
  • "custom_value2": "Custom data 2",
  • "custom_value3": "Custom data 3",
  • "custom_value4": "Custom data 4",
  • "tax_name1": "VAT",
  • "tax_name2": "GST",
  • "tax_rate1": 10,
  • "tax_rate2": 5,
  • "tax_name3": "PST",
  • "tax_rate3": 8,
  • "total_taxes": 23,
  • "line_items": [
    ],
  • "invitations": [
    ],
  • "amount": 100,
  • "balance": 50,
  • "paid_to_date": 50,
  • "discount": 10,
  • "partial": 20,
  • "is_amount_discount": true,
  • "is_deleted": false,
  • "uses_inclusive_taxes": true,
  • "date": "1994-07-30",
  • "last_sent_date": "1994-07-30",
  • "next_send_date": "1994-07-30",
  • "partial_due_date": "1994-07-30",
  • "due_date": "1994-07-30",
  • "settings": {
    },
  • "last_viewed": 1434342123,
  • "updated_at": 1434342123,
  • "archived_at": 1434342123,
  • "custom_surcharge1": 10,
  • "custom_surcharge2": 10,
  • "custom_surcharge3": 10,
  • "custom_surcharge4": 10,
  • "custom_surcharge_tax1": true,
  • "custom_surcharge_tax2": true,
  • "custom_surcharge_tax3": true,
  • "custom_surcharge_tax4": true,
  • "location_id": "Opnel5aKBz",
  • "design_id": "Opnel5aKBz",
  • "exchange_rate": 1,
  • "project_id": "Opnel5aKBz",
  • "subscription_id": "Opnel5aKBz",
  • "vendor_id": "Opnel5aKBz"
}

Projects

Endpoint definitions for interacting with projects.

List projects

Lists projects

Authorizations:
ApiKeyAuth
query Parameters
include
string
Example: include=first_load

Includes child relationships in the response, format is comma separated. Check each model for the list of associated includes

index
string
Example: index=user

Replaces the default response index from data to a user specific string

ie.

  ?index=new_index

response is wrapped

  {
    'new_index' : [
      .....  
    ]
  }
per_page
integer
Example: per_page=20

The number of records to return for each request, default is 20

page
integer
Example: page=1

The page number to return for this request (when performing pagination), default is 1

header Parameters
X-API-TOKEN
required
string
Example: TOKEN

The API token to be used for authentication

X-Requested-With
required
string
Example: XMLHttpRequest

Used to send the XMLHttpRequest header

Responses

Request samples 

$ninja = new InvoiceNinja("YOUR-TOKEN");
$projects = $ninja->projects->all([
    'per_page' => 10,
    'page' => 1
]);

Response samples

Content type
application/json
{
  • "data": [
    ],
  • "meta": {
    }
}

Create project

Adds an project to a company

Authorizations:
ApiKeyAuth
query Parameters
include
string
Example: include=first_load

Includes child relationships in the response, format is comma separated. Check each model for the list of associated includes

header Parameters
X-API-TOKEN
required
string
Example: TOKEN

The API token to be used for authentication

X-Requested-With
required
string
Example: XMLHttpRequest

Used to send the XMLHttpRequest header

Request Body schema: application/json
required

Project object that needs to be added to the company

name
required
string

Project name

client_id
required
string

The hashed ID of the client

description
string

Project description

budgeted_hours
number

Budgeted hours for the project

task_rate
number

Hourly rate for tasks in this project

due_date
string <date>

Due date for the project

custom_value1
string

Custom field value 1

custom_value2
string

Custom field value 2

custom_value3
string

Custom field value 3

custom_value4
string

Custom field value 4

is_deleted
boolean

Whether the project is deleted

archived_at
integer

Timestamp when project was archived

color
string

Project color for UI display

Responses

Request samples

Content type
application/json
{
  • "name": "Website Redesign Project",
  • "client_id": "D2J234DFA",
  • "description": "Complete redesign of company website",
  • "budgeted_hours": 120.5,
  • "task_rate": 75,
  • "due_date": "2024-03-31",
  • "custom_value1": "Custom value 1",
  • "custom_value2": "Custom value 2",
  • "custom_value3": "Custom value 3",
  • "custom_value4": "Custom value 4",
  • "is_deleted": false,
  • "archived_at": 1640995200,
  • "color": "#FF5733"
}

Response samples

Content type
application/json
{
  • "id": "Opnel5aKBz",
  • "user_id": "Opnel5aKBz",
  • "assigned_user_id": "Opnel5aKBz",
  • "client_id": "Opnel5aKBz",
  • "name": "New Project",
  • "task_rate": 10,
  • "due_date": "2019-01-01",
  • "private_notes": "string",
  • "budgeted_hours": 0.1,
  • "custom_value1": "string",
  • "custom_value2": "string",
  • "custom_value3": "string",
  • "custom_value4": "string",
  • "created_at": 134341234234,
  • "updated_at": 134341234234,
  • "archived_at": 134341234234,
  • "public_notes": "string",
  • "is_deleted": true,
  • "number": "string",
  • "color": "string"
}

Show project

Displays a project by id

Authorizations:
ApiKeyAuth
path Parameters
id
required
string <string>
Example: D2J234DFA

The Project Hashed ID

query Parameters
include
string
Example: include=first_load

Includes child relationships in the response, format is comma separated. Check each model for the list of associated includes

header Parameters
X-API-TOKEN
required
string
Example: TOKEN

The API token to be used for authentication

X-Requested-With
required
string
Example: XMLHttpRequest

Used to send the XMLHttpRequest header

Responses

Request samples 

$ninja = new InvoiceNinja("YOUR-TOKEN");
$project = $ninja->projects->show("D2J234DFA");

Response samples

Content type
application/json
{
  • "id": "Opnel5aKBz",
  • "user_id": "Opnel5aKBz",
  • "assigned_user_id": "Opnel5aKBz",
  • "client_id": "Opnel5aKBz",
  • "name": "New Project",
  • "task_rate": 10,
  • "due_date": "2019-01-01",
  • "private_notes": "string",
  • "budgeted_hours": 0.1,
  • "custom_value1": "string",
  • "custom_value2": "string",
  • "custom_value3": "string",
  • "custom_value4": "string",
  • "created_at": 134341234234,
  • "updated_at": 134341234234,
  • "archived_at": 134341234234,
  • "public_notes": "string",
  • "is_deleted": true,
  • "number": "string",
  • "color": "string"
}

Update project

Handles the updating of a project by id

Authorizations:
ApiKeyAuth
path Parameters
id
required
string <string>
Example: D2J234DFA

The Project Hashed ID

query Parameters
include
string
Example: include=first_load

Includes child relationships in the response, format is comma separated. Check each model for the list of associated includes

header Parameters
X-API-TOKEN
required
string
Example: TOKEN

The API token to be used for authentication

X-Requested-With
required
string
Example: XMLHttpRequest

Used to send the XMLHttpRequest header

Request Body schema: application/json
required

Project object that needs to be updated

name
required
string

Project name

client_id
required
string

The hashed ID of the client

description
string

Project description

budgeted_hours
number

Budgeted hours for the project

task_rate
number

Hourly rate for tasks in this project

due_date
string <date>

Due date for the project

custom_value1
string

Custom field value 1

custom_value2
string

Custom field value 2

custom_value3
string

Custom field value 3

custom_value4
string

Custom field value 4

is_deleted
boolean

Whether the project is deleted

archived_at
integer

Timestamp when project was archived

color
string

Project color for UI display

Responses

Request samples

Content type
application/json
{
  • "name": "Website Redesign Project",
  • "client_id": "D2J234DFA",
  • "description": "Complete redesign of company website",
  • "budgeted_hours": 120.5,
  • "task_rate": 75,
  • "due_date": "2024-03-31",
  • "custom_value1": "Custom value 1",
  • "custom_value2": "Custom value 2",
  • "custom_value3": "Custom value 3",
  • "custom_value4": "Custom value 4",
  • "is_deleted": false,
  • "archived_at": 1640995200,
  • "color": "#FF5733"
}

Response samples

Content type
application/json
{
  • "id": "Opnel5aKBz",
  • "user_id": "Opnel5aKBz",
  • "assigned_user_id": "Opnel5aKBz",
  • "client_id": "Opnel5aKBz",
  • "name": "New Project",
  • "task_rate": 10,
  • "due_date": "2019-01-01",
  • "private_notes": "string",
  • "budgeted_hours": 0.1,
  • "custom_value1": "string",
  • "custom_value2": "string",
  • "custom_value3": "string",
  • "custom_value4": "string",
  • "created_at": 134341234234,
  • "updated_at": 134341234234,
  • "archived_at": 134341234234,
  • "public_notes": "string",
  • "is_deleted": true,
  • "number": "string",
  • "color": "string"
}

Delete project

Handles the deletion of a project by id

Authorizations:
ApiKeyAuth
path Parameters
id
required
string <string>
Example: D2J234DFA

The Project Hashed ID

query Parameters
include
string
Example: include=first_load

Includes child relationships in the response, format is comma separated. Check each model for the list of associated includes

header Parameters
X-API-TOKEN
required
string
Example: TOKEN

The API token to be used for authentication

X-Requested-With
required
string
Example: XMLHttpRequest

Used to send the XMLHttpRequest header

Responses

Request samples 

$ninja = new InvoiceNinja("YOUR-TOKEN");
$ninja->projects->delete("D2J234DFA");

Response samples

Content type
application/json
{
  • "message": "These credentials do not match our records / Invalid Token"
}

Edit project

Displays a project by id

Authorizations:
ApiKeyAuth
path Parameters
id
required
string <string>
Example: D2J234DFA

The Project Hashed ID

query Parameters
include
string
Example: include=first_load

Includes child relationships in the response, format is comma separated. Check each model for the list of associated includes

header Parameters
X-API-TOKEN
required
string
Example: TOKEN

The API token to be used for authentication

X-Requested-With
required
string
Example: XMLHttpRequest

Used to send the XMLHttpRequest header

Responses

Request samples 

$ninja = new InvoiceNinja("YOUR-TOKEN");
$project = $ninja->projects->show("D2J234DFA");

Response samples

Content type
application/json
{
  • "id": "Opnel5aKBz",
  • "user_id": "Opnel5aKBz",
  • "assigned_user_id": "Opnel5aKBz",
  • "client_id": "Opnel5aKBz",
  • "name": "New Project",
  • "task_rate": 10,
  • "due_date": "2019-01-01",
  • "private_notes": "string",
  • "budgeted_hours": 0.1,
  • "custom_value1": "string",
  • "custom_value2": "string",
  • "custom_value3": "string",
  • "custom_value4": "string",
  • "created_at": 134341234234,
  • "updated_at": 134341234234,
  • "archived_at": 134341234234,
  • "public_notes": "string",
  • "is_deleted": true,
  • "number": "string",
  • "color": "string"
}

Blank project

Returns a blank object with default values

Authorizations:
ApiKeyAuth
query Parameters
include
string
Example: include=first_load

Includes child relationships in the response, format is comma separated. Check each model for the list of associated includes

header Parameters
X-API-TOKEN
required
string
Example: TOKEN

The API token to be used for authentication

X-Requested-With
required
string
Example: XMLHttpRequest

Used to send the XMLHttpRequest header

Responses

Request samples 

$ninja = new InvoiceNinja("YOUR-TOKEN");
$project = $ninja->projects->model();

Response samples

Content type
application/json
{
  • "id": "Opnel5aKBz",
  • "user_id": "Opnel5aKBz",
  • "assigned_user_id": "Opnel5aKBz",
  • "client_id": "Opnel5aKBz",
  • "name": "New Project",
  • "task_rate": 10,
  • "due_date": "2019-01-01",
  • "private_notes": "string",
  • "budgeted_hours": 0.1,
  • "custom_value1": "string",
  • "custom_value2": "string",
  • "custom_value3": "string",
  • "custom_value4": "string",
  • "created_at": 134341234234,
  • "updated_at": 134341234234,
  • "archived_at": 134341234234,
  • "public_notes": "string",
  • "is_deleted": true,
  • "number": "string",
  • "color": "string"
}

Bulk project actions

Authorizations:
ApiKeyAuth
query Parameters
index
string
Example: index=user

Replaces the default response index from data to a user specific string

ie.

  ?index=new_index

response is wrapped

  {
    'new_index' : [
      .....  
    ]
  }
header Parameters
X-API-TOKEN
required
string
Example: TOKEN

The API token to be used for authentication

X-Requested-With
required
string
Example: XMLHttpRequest

Used to send the XMLHttpRequest header

Request Body schema: application/json
required

User credentials

Array
integer

Array of hashed IDs to be bulk 'actioned

Responses

Request samples

Content type
application/json
[
  • 0
]

Response samples

Content type
application/json
{
  • "id": "Opnel5aKBz",
  • "user_id": "Opnel5aKBz",
  • "assigned_user_id": "Opnel5aKBz",
  • "client_id": "Opnel5aKBz",
  • "name": "New Project",
  • "task_rate": 10,
  • "due_date": "2019-01-01",
  • "private_notes": "string",
  • "budgeted_hours": 0.1,
  • "custom_value1": "string",
  • "custom_value2": "string",
  • "custom_value3": "string",
  • "custom_value4": "string",
  • "created_at": 134341234234,
  • "updated_at": 134341234234,
  • "archived_at": 134341234234,
  • "public_notes": "string",
  • "is_deleted": true,
  • "number": "string",
  • "color": "string"
}

Uploads a project document

Handles the uploading of a document to a project

Authorizations:
ApiKeyAuth
path Parameters
id
required
string <string>
Example: D2J234DFA

The Project Hashed ID

query Parameters
include
string
Example: include=first_load

Includes child relationships in the response, format is comma separated. Check each model for the list of associated includes

header Parameters
X-API-TOKEN
required
string
Example: TOKEN

The API token to be used for authentication

X-Requested-With
required
string
Example: XMLHttpRequest

Used to send the XMLHttpRequest header

Request Body schema: multipart/form-data
required

File Upload Body

_method
string
documents
Array of strings <binary> [ items <binary > ]

Responses

Response samples

Content type
application/json
{
  • "id": "Opnel5aKBz",
  • "user_id": "Opnel5aKBz",
  • "assigned_user_id": "Opnel5aKBz",
  • "client_id": "Opnel5aKBz",
  • "name": "New Project",
  • "task_rate": 10,
  • "due_date": "2019-01-01",
  • "private_notes": "string",
  • "budgeted_hours": 0.1,
  • "custom_value1": "string",
  • "custom_value2": "string",
  • "custom_value3": "string",
  • "custom_value4": "string",
  • "created_at": 134341234234,
  • "updated_at": 134341234234,
  • "archived_at": 134341234234,
  • "public_notes": "string",
  • "is_deleted": true,
  • "number": "string",
  • "color": "string"
}

Tasks

Endpoint definitions for interacting with tasks.

List tasks

Lists tasks, search and filters allow fine grained lists to be generated. * * Query parameters can be added to performed more fine grained filtering of the tasks, these are handled by the TaskFilters class which defines the methods available

Authorizations:
ApiKeyAuth
query Parameters
include
string
Example: include=first_load

Includes child relationships in the response, format is comma separated. Check each model for the list of associated includes

index
string
Example: index=user

Replaces the default response index from data to a user specific string

ie.

  ?index=new_index

response is wrapped

  {
    'new_index' : [
      .....  
    ]
  }
per_page
integer
Example: per_page=20

The number of records to return for each request, default is 20

page
integer
Example: page=1

The page number to return for this request (when performing pagination), default is 1

header Parameters
X-API-TOKEN
required
string
Example: TOKEN

The API token to be used for authentication

X-Requested-With
required
string
Example: XMLHttpRequest

Used to send the XMLHttpRequest header

Responses

Request samples 

$ninja = new InvoiceNinja("YOUR-TOKEN");
$tasks = $ninja->tasks->all([
    'per_page' => 10,
    'page' => 1,
    'client_id' => 'D2J234DFA'
]);

Response samples

Content type
application/json
{
  • "data": [
    ],
  • "meta": {
    }
}

Create task

Adds an task to a company

Authorizations:
ApiKeyAuth
query Parameters
include
string
Example: include=first_load

Includes child relationships in the response, format is comma separated. Check each model for the list of associated includes

header Parameters
X-API-TOKEN
required
string
Example: TOKEN

The API token to be used for authentication

X-Requested-With
required
string
Example: XMLHttpRequest

Used to send the XMLHttpRequest header

Request Body schema: application/json
required

Task object that needs to be added to the company

description
required
string

Task description

client_id
string

The hashed ID of the client

project_id
string

The hashed ID of the project

time_log
string

Time logged for the task

status_id
integer

Status ID of the task

custom_value1
string

Custom field value 1

custom_value2
string

Custom field value 2

custom_value3
string

Custom field value 3

custom_value4
string

Custom field value 4

is_deleted
boolean

Whether the task is deleted

archived_at
integer

Timestamp when task was archived

due_date
string <date>

Due date for the task

priority
integer

Priority level of the task

Responses

Request samples

Content type
application/json
{
  • "description": "Complete project documentation",
  • "client_id": "D2J234DFA",
  • "project_id": "P2J234DFA",
  • "time_log": "2.5",
  • "status_id": 1,
  • "custom_value1": "Custom value 1",
  • "custom_value2": "Custom value 2",
  • "custom_value3": "Custom value 3",
  • "custom_value4": "Custom value 4",
  • "is_deleted": false,
  • "archived_at": 1640995200,
  • "due_date": "2024-01-31",
  • "priority": 1
}

Response samples

Content type
application/json
{
  • "id": "Opnel5aKBz",
  • "user_id": "Opnel5aKBz",
  • "assigned_user_id": "Opnel5aKBz",
  • "client_id": "Opnel5aKBz",
  • "invoice_id": "Opnel5aKBz",
  • "project_id": "Opnel5aKBz",
  • "number": "TASK-123",
  • "time_log": "[[1,2],[3,4]]",
  • "is_running": true,
  • "is_deleted": true,
  • "task_status_id": "Opnel5aKBz",
  • "description": "A wonder task to work on",
  • "duration": 3600,
  • "task_status_order": 4,
  • "rate": 10,
  • "custom_value1": "2022-10-10",
  • "custom_value2": "$1100",
  • "custom_value3": "I need help",
  • "custom_value4": "INV-3343",
  • "is_date_based": true,
  • "calculated_start_date": "2022-10-10",
  • "invoice_documents": true,
  • "created_at": 1434342123,
  • "updated_at": 1434342123,
  • "archived_at": 1434342123,
  • "hash": "a1b2c3d4e5f6",
  • "meta": { },
  • "status_id": "Opnel5aKBz",
  • "status_order": 1,
  • "status_sort_order": 1
}

Show task

Displays a task by id

Authorizations:
ApiKeyAuth
path Parameters
id
required
string <string>
Example: D2J234DFA

The Task Hashed ID

query Parameters
include
string
Example: include=first_load

Includes child relationships in the response, format is comma separated. Check each model for the list of associated includes

header Parameters
X-API-TOKEN
required
string
Example: TOKEN

The API token to be used for authentication

X-Requested-With
required
string
Example: XMLHttpRequest

Used to send the XMLHttpRequest header

Responses

Request samples 

$ninja = new InvoiceNinja("YOUR-TOKEN");
$task = $ninja->tasks->show("D2J234DFA");

Response samples

Content type
application/json
{
  • "id": "Opnel5aKBz",
  • "user_id": "Opnel5aKBz",
  • "assigned_user_id": "Opnel5aKBz",
  • "client_id": "Opnel5aKBz",
  • "invoice_id": "Opnel5aKBz",
  • "project_id": "Opnel5aKBz",
  • "number": "TASK-123",
  • "time_log": "[[1,2],[3,4]]",
  • "is_running": true,
  • "is_deleted": true,
  • "task_status_id": "Opnel5aKBz",
  • "description": "A wonder task to work on",
  • "duration": 3600,
  • "task_status_order": 4,
  • "rate": 10,
  • "custom_value1": "2022-10-10",
  • "custom_value2": "$1100",
  • "custom_value3": "I need help",
  • "custom_value4": "INV-3343",
  • "is_date_based": true,
  • "calculated_start_date": "2022-10-10",
  • "invoice_documents": true,
  • "created_at": 1434342123,
  • "updated_at": 1434342123,
  • "archived_at": 1434342123,
  • "hash": "a1b2c3d4e5f6",
  • "meta": { },
  • "status_id": "Opnel5aKBz",
  • "status_order": 1,
  • "status_sort_order": 1
}

Update task

Handles the updating of a task by id

Authorizations:
ApiKeyAuth
path Parameters
id
required
string <string>
Example: D2J234DFA

The task Hashed ID

query Parameters
include
string
Example: include=first_load

Includes child relationships in the response, format is comma separated. Check each model for the list of associated includes

header Parameters
X-API-TOKEN
required
string
Example: TOKEN

The API token to be used for authentication

X-Requested-With
required
string
Example: XMLHttpRequest

Used to send the XMLHttpRequest header

Request Body schema: application/json
required

Task object that needs to be updated

description
required
string

Task description

client_id
string

The hashed ID of the client

project_id
string

The hashed ID of the project

time_log
string

Time logged for the task

status_id
integer

Status ID of the task

custom_value1
string

Custom field value 1

custom_value2
string

Custom field value 2

custom_value3
string

Custom field value 3

custom_value4
string

Custom field value 4

is_deleted
boolean

Whether the task is deleted

archived_at
integer

Timestamp when task was archived

due_date
string <date>

Due date for the task

priority
integer

Priority level of the task

Responses

Request samples

Content type
application/json
{
  • "description": "Complete project documentation",
  • "client_id": "D2J234DFA",
  • "project_id": "P2J234DFA",
  • "time_log": "2.5",
  • "status_id": 1,
  • "custom_value1": "Custom value 1",
  • "custom_value2": "Custom value 2",
  • "custom_value3": "Custom value 3",
  • "custom_value4": "Custom value 4",
  • "is_deleted": false,
  • "archived_at": 1640995200,
  • "due_date": "2024-01-31",
  • "priority": 1
}

Response samples

Content type
application/json
{
  • "id": "Opnel5aKBz",
  • "user_id": "Opnel5aKBz",
  • "assigned_user_id": "Opnel5aKBz",
  • "client_id": "Opnel5aKBz",
  • "invoice_id": "Opnel5aKBz",
  • "project_id": "Opnel5aKBz",
  • "number": "TASK-123",
  • "time_log": "[[1,2],[3,4]]",
  • "is_running": true,
  • "is_deleted": true,
  • "task_status_id": "Opnel5aKBz",
  • "description": "A wonder task to work on",
  • "duration": 3600,
  • "task_status_order": 4,
  • "rate": 10,
  • "custom_value1": "2022-10-10",
  • "custom_value2": "$1100",
  • "custom_value3": "I need help",
  • "custom_value4": "INV-3343",
  • "is_date_based": true,
  • "calculated_start_date": "2022-10-10",
  • "invoice_documents": true,
  • "created_at": 1434342123,
  • "updated_at": 1434342123,
  • "archived_at": 1434342123,
  • "hash": "a1b2c3d4e5f6",
  • "meta": { },
  • "status_id": "Opnel5aKBz",
  • "status_order": 1,
  • "status_sort_order": 1
}

Delete task

Handles the deletion of a task by id

Authorizations:
ApiKeyAuth
path Parameters
id
required
string <string>
Example: D2J234DFA

The Task Hashed ID

query Parameters
include
string
Example: include=first_load

Includes child relationships in the response, format is comma separated. Check each model for the list of associated includes

header Parameters
X-API-TOKEN
required
string
Example: TOKEN

The API token to be used for authentication

X-Requested-With
required
string
Example: XMLHttpRequest

Used to send the XMLHttpRequest header

Responses

Request samples 

$ninja = new InvoiceNinja("YOUR-TOKEN");
$ninja->tasks->delete("D2J234DFA");

Response samples

Content type
application/json
{
  • "message": "These credentials do not match our records / Invalid Token"
}

Edit task

Displays a task by id

Authorizations:
ApiKeyAuth
path Parameters
id
required
string <string>
Example: D2J234DFA

The Task Hashed ID

query Parameters
include
string
Example: include=first_load

Includes child relationships in the response, format is comma separated. Check each model for the list of associated includes

header Parameters
X-API-TOKEN
required
string
Example: TOKEN

The API token to be used for authentication

X-Requested-With
required
string
Example: XMLHttpRequest

Used to send the XMLHttpRequest header

Responses

Request samples 

$ninja = new InvoiceNinja("YOUR-TOKEN");
$task = $ninja->tasks->show("D2J234DFA");

Response samples

Content type
application/json
{
  • "id": "Opnel5aKBz",
  • "user_id": "Opnel5aKBz",
  • "assigned_user_id": "Opnel5aKBz",
  • "client_id": "Opnel5aKBz",
  • "invoice_id": "Opnel5aKBz",
  • "project_id": "Opnel5aKBz",
  • "number": "TASK-123",
  • "time_log": "[[1,2],[3,4]]",
  • "is_running": true,
  • "is_deleted": true,
  • "task_status_id": "Opnel5aKBz",
  • "description": "A wonder task to work on",
  • "duration": 3600,
  • "task_status_order": 4,
  • "rate": 10,
  • "custom_value1": "2022-10-10",
  • "custom_value2": "$1100",
  • "custom_value3": "I need help",
  • "custom_value4": "INV-3343",
  • "is_date_based": true,
  • "calculated_start_date": "2022-10-10",
  • "invoice_documents": true,
  • "created_at": 1434342123,
  • "updated_at": 1434342123,
  • "archived_at": 1434342123,
  • "hash": "a1b2c3d4e5f6",
  • "meta": { },
  • "status_id": "Opnel5aKBz",
  • "status_order": 1,
  • "status_sort_order": 1
}

Blank task

Returns a blank task with default values

Authorizations:
ApiKeyAuth
query Parameters
include
string
Example: include=first_load

Includes child relationships in the response, format is comma separated. Check each model for the list of associated includes

header Parameters
X-API-TOKEN
required
string
Example: TOKEN

The API token to be used for authentication

X-Requested-With
required
string
Example: XMLHttpRequest

Used to send the XMLHttpRequest header

Responses

Request samples 

$ninja = new InvoiceNinja("YOUR-TOKEN");
$task = $ninja->tasks->model();

Response samples

Content type
application/json
{
  • "id": "Opnel5aKBz",
  • "user_id": "Opnel5aKBz",
  • "assigned_user_id": "Opnel5aKBz",
  • "client_id": "Opnel5aKBz",
  • "invoice_id": "Opnel5aKBz",
  • "project_id": "Opnel5aKBz",
  • "number": "TASK-123",
  • "time_log": "[[1,2],[3,4]]",
  • "is_running": true,
  • "is_deleted": true,
  • "task_status_id": "Opnel5aKBz",
  • "description": "A wonder task to work on",
  • "duration": 3600,
  • "task_status_order": 4,
  • "rate": 10,
  • "custom_value1": "2022-10-10",
  • "custom_value2": "$1100",
  • "custom_value3": "I need help",
  • "custom_value4": "INV-3343",
  • "is_date_based": true,
  • "calculated_start_date": "2022-10-10",
  • "invoice_documents": true,
  • "created_at": 1434342123,
  • "updated_at": 1434342123,
  • "archived_at": 1434342123,
  • "hash": "a1b2c3d4e5f6",
  • "meta": { },
  • "status_id": "Opnel5aKBz",
  • "status_order": 1,
  • "status_sort_order": 1
}

Bulk task actions

Authorizations:
ApiKeyAuth
query Parameters
index
string
Example: index=user

Replaces the default response index from data to a user specific string

ie.

  ?index=new_index

response is wrapped

  {
    'new_index' : [
      .....  
    ]
  }
header Parameters
X-API-TOKEN
required
string
Example: TOKEN

The API token to be used for authentication

X-Requested-With
required
string
Example: XMLHttpRequest

Used to send the XMLHttpRequest header

Request Body schema: application/json
required

User credentials

Array
integer

Array of hashed IDs to be bulk 'actioned

Responses

Request samples

Content type
application/json
[
  • 0
]

Response samples

Content type
application/json
{
  • "id": "Opnel5aKBz",
  • "user_id": "Opnel5aKBz",
  • "assigned_user_id": "Opnel5aKBz",
  • "client_id": "Opnel5aKBz",
  • "invoice_id": "Opnel5aKBz",
  • "project_id": "Opnel5aKBz",
  • "number": "TASK-123",
  • "time_log": "[[1,2],[3,4]]",
  • "is_running": true,
  • "is_deleted": true,
  • "task_status_id": "Opnel5aKBz",
  • "description": "A wonder task to work on",
  • "duration": 3600,
  • "task_status_order": 4,
  • "rate": 10,
  • "custom_value1": "2022-10-10",
  • "custom_value2": "$1100",
  • "custom_value3": "I need help",
  • "custom_value4": "INV-3343",
  • "is_date_based": true,
  • "calculated_start_date": "2022-10-10",
  • "invoice_documents": true,
  • "created_at": 1434342123,
  • "updated_at": 1434342123,
  • "archived_at": 1434342123,
  • "hash": "a1b2c3d4e5f6",
  • "meta": { },
  • "status_id": "Opnel5aKBz",
  • "status_order": 1,
  • "status_sort_order": 1
}

Uploads a task document

Handles the uploading of a document to a task

Authorizations:
ApiKeyAuth
path Parameters
id
required
string <string>
Example: D2J234DFA

The Task Hashed ID

query Parameters
include
string
Example: include=first_load

Includes child relationships in the response, format is comma separated. Check each model for the list of associated includes

header Parameters
X-API-TOKEN
required
string
Example: TOKEN

The API token to be used for authentication

X-Requested-With
required
string
Example: XMLHttpRequest

Used to send the XMLHttpRequest header

Request Body schema: multipart/form-data
required

File Upload Body

_method
string
documents
Array of strings <binary> [ items <binary > ]

Responses

Response samples

Content type
application/json
{
  • "id": "Opnel5aKBz",
  • "user_id": "Opnel5aKBz",
  • "assigned_user_id": "Opnel5aKBz",
  • "client_id": "Opnel5aKBz",
  • "invoice_id": "Opnel5aKBz",
  • "project_id": "Opnel5aKBz",
  • "number": "TASK-123",
  • "time_log": "[[1,2],[3,4]]",
  • "is_running": true,
  • "is_deleted": true,
  • "task_status_id": "Opnel5aKBz",
  • "description": "A wonder task to work on",
  • "duration": 3600,
  • "task_status_order": 4,
  • "rate": 10,
  • "custom_value1": "2022-10-10",
  • "custom_value2": "$1100",
  • "custom_value3": "I need help",
  • "custom_value4": "INV-3343",
  • "is_date_based": true,
  • "calculated_start_date": "2022-10-10",
  • "invoice_documents": true,
  • "created_at": 1434342123,
  • "updated_at": 1434342123,
  • "archived_at": 1434342123,
  • "hash": "a1b2c3d4e5f6",
  • "meta": { },
  • "status_id": "Opnel5aKBz",
  • "status_order": 1,
  • "status_sort_order": 1
}

Sort tasks on KanBan

Sorts tasks after drag and drop on the KanBan.

Authorizations:
ApiKeyAuth
query Parameters
include
string
Example: include=first_load

Includes child relationships in the response, format is comma separated. Check each model for the list of associated includes

header Parameters
X-API-TOKEN
required
string
Example: TOKEN

The API token to be used for authentication

X-Requested-With
required
string
Example: XMLHttpRequest

Used to send the XMLHttpRequest header

Request Body schema: application/json
required

Task sort order data

task_ids
required
Array of strings

Array of task IDs to be sorted

status_id
integer

Status ID to assign to sorted tasks

sort_order
Array of strings

Array of task IDs in the desired sort order

Responses

Request samples

Content type
application/json
{
  • "task_ids": [
    ],
  • "status_id": 1,
  • "sort_order": [
    ]
}

Response samples

Content type
application/json
{
  • "message": "These credentials do not match our records / Invalid Token"
}

Vendors

Endpoint definitions for interacting with vendors.

List vendors

Lists vendors, search and filters allow fine grained lists to be generated.

Query parameters can be added to performed more fine grained filtering of the vendors, these are handled by the VendorFilters class which defines the methods available
Authorizations:
ApiKeyAuth
query Parameters
include
string
Example: include=first_load

Includes child relationships in the response, format is comma separated. Check each model for the list of associated includes

index
string
Example: index=user

Replaces the default response index from data to a user specific string

ie.

  ?index=new_index

response is wrapped

  {
    'new_index' : [
      .....  
    ]
  }
per_page
integer
Example: per_page=20

The number of records to return for each request, default is 20

page
integer
Example: page=1

The page number to return for this request (when performing pagination), default is 1

header Parameters
X-API-TOKEN
required
string
Example: TOKEN

The API token to be used for authentication

X-Requested-With
required
string
Example: XMLHttpRequest

Used to send the XMLHttpRequest header

Responses

Request samples 

$ninja = new InvoiceNinja("YOUR-TOKEN");
$vendors = $ninja->vendors->all([
    'per_page' => 10,
    'page' => 1
]);

Response samples

Content type
application/json
{
  • "data": [
    ],
  • "meta": {
    }
}

Create vendor

Adds a vendor to a company

Authorizations:
ApiKeyAuth
query Parameters
include
string
Example: include=first_load

Includes child relationships in the response, format is comma separated. Check each model for the list of associated includes

header Parameters
X-API-TOKEN
required
string
Example: TOKEN

The API token to be used for authentication

X-Requested-With
required
string
Example: XMLHttpRequest

Used to send the XMLHttpRequest header

Request Body schema: application/json
required

Vendor object that needs to be added to the company

name
required
string

Vendor name

address1
string

Primary address line

address2
string

Secondary address line

city
string

City

state
string

State or province

postal_code
string

Postal code

country_id
string

Country ID

phone
string

Phone number

email
string <email>

Email address

website
string <uri>

Website URL

custom_value1
string

Custom field value 1

custom_value2
string

Custom field value 2

custom_value3
string

Custom field value 3

custom_value4
string

Custom field value 4

is_deleted
boolean

Whether the vendor is deleted

archived_at
integer

Timestamp when vendor was archived

Array of objects

Array of vendor contacts

Responses

Request samples

Content type
application/json
{
  • "name": "ABC Supply Company",
  • "address1": "123 Main Street",
  • "address2": "Suite 100",
  • "city": "New York",
  • "state": "NY",
  • "postal_code": "10001",
  • "country_id": "1",
  • "phone": "+1-555-123-4567",
  • "email": "[email protected]",
  • "website": "https://www.abcsupply.com",
  • "custom_value1": "Custom value 1",
  • "custom_value2": "Custom value 2",
  • "custom_value3": "Custom value 3",
  • "custom_value4": "Custom value 4",
  • "is_deleted": false,
  • "archived_at": 1640995200,
  • "contacts": [
    ]
}

Response samples

Content type
application/json
{
  • "id": "Opnel5aKBz",
  • "user_id": "Opnel5aKBz",
  • "assigned_user_id": "Opnel5aKBz",
  • "contacts": [
    ],
  • "name": "Harry cafe de wheels",
  • "classification": "individual",
  • "website": "www.harry.com",
  • "private_notes": "Shhh, do not tell the vendor",
  • "industry_id": "1",
  • "size_id": "",
  • "address1": "",
  • "address2": "",
  • "city": "",
  • "state": "",
  • "postal_code": "",
  • "phone": "555-3434-3434",
  • "country_id": "",
  • "currency_id": "4",
  • "custom_value1": "",
  • "custom_value2": "",
  • "custom_value3": "",
  • "custom_value4": "",
  • "vat_number": "",
  • "id_number": "",
  • "number": "11234",
  • "is_deleted": true,
  • "language_id": "1",
  • "vendor_hash": "aaa-sss-www",
  • "transaction_name": "aaa-sss-www",
  • "last_login": 134341234234,
  • "created_at": 134341234234,
  • "updated_at": 134341234234,
  • "display_name": "Bob the vendor",
  • "is_tax_exempt": false,
  • "public_notes": "These are public notes visible to vendors",
  • "routing_id": "0088:12345678901"
}

Show vendor

Displays a vendor by id

Authorizations:
ApiKeyAuth
path Parameters
id
required
string <string>
Example: D2J234DFA

The vendor Hashed ID

query Parameters
include
string
Example: include=first_load

Includes child relationships in the response, format is comma separated. Check each model for the list of associated includes

header Parameters
X-API-TOKEN
required
string
Example: TOKEN

The API token to be used for authentication

X-Requested-With
required
string
Example: XMLHttpRequest

Used to send the XMLHttpRequest header

Responses

Request samples 

$ninja = new InvoiceNinja("YOUR-TOKEN");
$vendor = $ninja->vendors->show("D2J234DFA");

Response samples

Content type
application/json
{
  • "id": "Opnel5aKBz",
  • "user_id": "Opnel5aKBz",
  • "assigned_user_id": "Opnel5aKBz",
  • "contacts": [
    ],
  • "name": "Harry cafe de wheels",
  • "classification": "individual",
  • "website": "www.harry.com",
  • "private_notes": "Shhh, do not tell the vendor",
  • "industry_id": "1",
  • "size_id": "",
  • "address1": "",
  • "address2": "",
  • "city": "",
  • "state": "",
  • "postal_code": "",
  • "phone": "555-3434-3434",
  • "country_id": "",
  • "currency_id": "4",
  • "custom_value1": "",
  • "custom_value2": "",
  • "custom_value3": "",
  • "custom_value4": "",
  • "vat_number": "",
  • "id_number": "",
  • "number": "11234",
  • "is_deleted": true,
  • "language_id": "1",
  • "vendor_hash": "aaa-sss-www",
  • "transaction_name": "aaa-sss-www",
  • "last_login": 134341234234,
  • "created_at": 134341234234,
  • "updated_at": 134341234234,
  • "display_name": "Bob the vendor",
  • "is_tax_exempt": false,
  • "public_notes": "These are public notes visible to vendors",
  • "routing_id": "0088:12345678901"
}

Update vendor

Handles the updating of a vendor by id

Authorizations:
ApiKeyAuth
path Parameters
id
required
string <string>
Example: D2J234DFA

The Vendor Hashed ID

query Parameters
include
string
Example: include=first_load

Includes child relationships in the response, format is comma separated. Check each model for the list of associated includes

header Parameters
X-API-TOKEN
required
string
Example: TOKEN

The API token to be used for authentication

X-Requested-With
required
string
Example: XMLHttpRequest

Used to send the XMLHttpRequest header

Request Body schema: application/json
required

Vendor object that needs to be updated

name
required
string

Vendor name

address1
string

Primary address line

address2
string

Secondary address line

city
string

City

state
string

State or province

postal_code
string

Postal code

country_id
string

Country ID

phone
string

Phone number

email
string <email>

Email address

website
string <uri>

Website URL

custom_value1
string

Custom field value 1

custom_value2
string

Custom field value 2

custom_value3
string

Custom field value 3

custom_value4
string

Custom field value 4

is_deleted
boolean

Whether the vendor is deleted

archived_at
integer

Timestamp when vendor was archived

Array of objects

Array of vendor contacts

Responses

Request samples

Content type
application/json
{
  • "name": "ABC Supply Company",
  • "address1": "123 Main Street",
  • "address2": "Suite 100",
  • "city": "New York",
  • "state": "NY",
  • "postal_code": "10001",
  • "country_id": "1",
  • "phone": "+1-555-123-4567",
  • "email": "[email protected]",
  • "website": "https://www.abcsupply.com",
  • "custom_value1": "Custom value 1",
  • "custom_value2": "Custom value 2",
  • "custom_value3": "Custom value 3",
  • "custom_value4": "Custom value 4",
  • "is_deleted": false,
  • "archived_at": 1640995200,
  • "contacts": [
    ]
}

Response samples

Content type
application/json
{
  • "id": "Opnel5aKBz",
  • "user_id": "Opnel5aKBz",
  • "assigned_user_id": "Opnel5aKBz",
  • "contacts": [
    ],
  • "name": "Harry cafe de wheels",
  • "classification": "individual",
  • "website": "www.harry.com",
  • "private_notes": "Shhh, do not tell the vendor",
  • "industry_id": "1",
  • "size_id": "",
  • "address1": "",
  • "address2": "",
  • "city": "",
  • "state": "",
  • "postal_code": "",
  • "phone": "555-3434-3434",
  • "country_id": "",
  • "currency_id": "4",
  • "custom_value1": "",
  • "custom_value2": "",
  • "custom_value3": "",
  • "custom_value4": "",
  • "vat_number": "",
  • "id_number": "",
  • "number": "11234",
  • "is_deleted": true,
  • "language_id": "1",
  • "vendor_hash": "aaa-sss-www",
  • "transaction_name": "aaa-sss-www",
  • "last_login": 134341234234,
  • "created_at": 134341234234,
  • "updated_at": 134341234234,
  • "display_name": "Bob the vendor",
  • "is_tax_exempt": false,
  • "public_notes": "These are public notes visible to vendors",
  • "routing_id": "0088:12345678901"
}

Delete vendor

Handles the deletion of a vendor by id

Authorizations:
ApiKeyAuth
path Parameters
id
required
string <string>
Example: D2J234DFA

The Vendor Hashed ID

query Parameters
include
string
Example: include=first_load

Includes child relationships in the response, format is comma separated. Check each model for the list of associated includes

header Parameters
X-API-TOKEN
required
string
Example: TOKEN

The API token to be used for authentication

X-Requested-With
required
string
Example: XMLHttpRequest

Used to send the XMLHttpRequest header

Responses

Request samples 

$ninja = new InvoiceNinja("YOUR-TOKEN");
$ninja->vendors->delete("D2J234DFA");

Response samples

Content type
application/json
{
  • "message": "These credentials do not match our records / Invalid Token"
}

Edit vendor

Displays a vendor by id

Authorizations:
ApiKeyAuth
path Parameters
id
required
string <string>
Example: D2J234DFA

The Vendor Hashed ID

query Parameters
include
string
Example: include=first_load

Includes child relationships in the response, format is comma separated. Check each model for the list of associated includes

header Parameters
X-API-TOKEN
required
string
Example: TOKEN

The API token to be used for authentication

X-Requested-With
required
string
Example: XMLHttpRequest

Used to send the XMLHttpRequest header

Responses

Request samples 

$ninja = new InvoiceNinja("YOUR-TOKEN");
$vendor = $ninja->vendors->show("D2J234DFA");

Response samples

Content type
application/json
{
  • "id": "Opnel5aKBz",
  • "user_id": "Opnel5aKBz",
  • "assigned_user_id": "Opnel5aKBz",
  • "contacts": [
    ],
  • "name": "Harry cafe de wheels",
  • "classification": "individual",
  • "website": "www.harry.com",
  • "private_notes": "Shhh, do not tell the vendor",
  • "industry_id": "1",
  • "size_id": "",
  • "address1": "",
  • "address2": "",
  • "city": "",
  • "state": "",
  • "postal_code": "",
  • "phone": "555-3434-3434",
  • "country_id": "",
  • "currency_id": "4",
  • "custom_value1": "",
  • "custom_value2": "",
  • "custom_value3": "",
  • "custom_value4": "",
  • "vat_number": "",
  • "id_number": "",
  • "number": "11234",
  • "is_deleted": true,
  • "language_id": "1",
  • "vendor_hash": "aaa-sss-www",
  • "transaction_name": "aaa-sss-www",
  • "last_login": 134341234234,
  • "created_at": 134341234234,
  • "updated_at": 134341234234,
  • "display_name": "Bob the vendor",
  • "is_tax_exempt": false,
  • "public_notes": "These are public notes visible to vendors",
  • "routing_id": "0088:12345678901"
}

Blank vendor

Returns a blank vendor with default values

Authorizations:
ApiKeyAuth
query Parameters
include
string
Example: include=first_load

Includes child relationships in the response, format is comma separated. Check each model for the list of associated includes

header Parameters
X-API-TOKEN
required
string
Example: TOKEN

The API token to be used for authentication

X-Requested-With
required
string
Example: XMLHttpRequest

Used to send the XMLHttpRequest header

Responses

Request samples 

$ninja = new InvoiceNinja("YOUR-TOKEN");
$vendor = $ninja->vendors->model();

Response samples

Content type
application/json
{
  • "id": "Opnel5aKBz",
  • "user_id": "Opnel5aKBz",
  • "assigned_user_id": "Opnel5aKBz",
  • "contacts": [
    ],
  • "name": "Harry cafe de wheels",
  • "classification": "individual",
  • "website": "www.harry.com",
  • "private_notes": "Shhh, do not tell the vendor",
  • "industry_id": "1",
  • "size_id": "",
  • "address1": "",
  • "address2": "",
  • "city": "",
  • "state": "",
  • "postal_code": "",
  • "phone": "555-3434-3434",
  • "country_id": "",
  • "currency_id": "4",
  • "custom_value1": "",
  • "custom_value2": "",
  • "custom_value3": "",
  • "custom_value4": "",
  • "vat_number": "",
  • "id_number": "",
  • "number": "11234",
  • "is_deleted": true,
  • "language_id": "1",
  • "vendor_hash": "aaa-sss-www",
  • "transaction_name": "aaa-sss-www",
  • "last_login": 134341234234,
  • "created_at": 134341234234,
  • "updated_at": 134341234234,
  • "display_name": "Bob the vendor",
  • "is_tax_exempt": false,
  • "public_notes": "These are public notes visible to vendors",
  • "routing_id": "0088:12345678901"
}

Bulk vendor actions

Authorizations:
ApiKeyAuth
query Parameters
index
string
Example: index=user

Replaces the default response index from data to a user specific string

ie.

  ?index=new_index

response is wrapped

  {
    'new_index' : [
      .....  
    ]
  }
header Parameters
X-API-TOKEN
required
string
Example: TOKEN

The API token to be used for authentication

X-Requested-With
required
string
Example: XMLHttpRequest

Used to send the XMLHttpRequest header

Request Body schema: application/json
required

User credentials

Array
integer

Array of hashed IDs to be bulk 'actioned

Responses

Request samples

Content type
application/json
[
  • 0
]

Response samples

Content type
application/json
{
  • "id": "Opnel5aKBz",
  • "user_id": "Opnel5aKBz",
  • "assigned_user_id": "Opnel5aKBz",
  • "contacts": [
    ],
  • "name": "Harry cafe de wheels",
  • "classification": "individual",
  • "website": "www.harry.com",
  • "private_notes": "Shhh, do not tell the vendor",
  • "industry_id": "1",
  • "size_id": "",
  • "address1": "",
  • "address2": "",
  • "city": "",
  • "state": "",
  • "postal_code": "",
  • "phone": "555-3434-3434",
  • "country_id": "",
  • "currency_id": "4",
  • "custom_value1": "",
  • "custom_value2": "",
  • "custom_value3": "",
  • "custom_value4": "",
  • "vat_number": "",
  • "id_number": "",
  • "number": "11234",
  • "is_deleted": true,
  • "language_id": "1",
  • "vendor_hash": "aaa-sss-www",
  • "transaction_name": "aaa-sss-www",
  • "last_login": 134341234234,
  • "created_at": 134341234234,
  • "updated_at": 134341234234,
  • "display_name": "Bob the vendor",
  • "is_tax_exempt": false,
  • "public_notes": "These are public notes visible to vendors",
  • "routing_id": "0088:12345678901"
}

Uploads a vendor document

Handles the uploading of a document to a vendor

Authorizations:
ApiKeyAuth
path Parameters
id
required
string <string>
Example: D2J234DFA

The Vendor Hashed ID

query Parameters
include
string
Example: include=first_load

Includes child relationships in the response, format is comma separated. Check each model for the list of associated includes

header Parameters
X-API-TOKEN
required
string
Example: TOKEN

The API token to be used for authentication

X-Requested-With
required
string
Example: XMLHttpRequest

Used to send the XMLHttpRequest header

Request Body schema: multipart/form-data
required

File Upload Body

_method
string
documents
Array of strings <binary> [ items <binary > ]

Responses

Response samples

Content type
application/json
{
  • "id": "Opnel5aKBz",
  • "user_id": "Opnel5aKBz",
  • "assigned_user_id": "Opnel5aKBz",
  • "contacts": [
    ],
  • "name": "Harry cafe de wheels",
  • "classification": "individual",
  • "website": "www.harry.com",
  • "private_notes": "Shhh, do not tell the vendor",
  • "industry_id": "1",
  • "size_id": "",
  • "address1": "",
  • "address2": "",
  • "city": "",
  • "state": "",
  • "postal_code": "",
  • "phone": "555-3434-3434",
  • "country_id": "",
  • "currency_id": "4",
  • "custom_value1": "",
  • "custom_value2": "",
  • "custom_value3": "",
  • "custom_value4": "",
  • "vat_number": "",
  • "id_number": "",
  • "number": "11234",
  • "is_deleted": true,
  • "language_id": "1",
  • "vendor_hash": "aaa-sss-www",
  • "transaction_name": "aaa-sss-www",
  • "last_login": 134341234234,
  • "created_at": 134341234234,
  • "updated_at": 134341234234,
  • "display_name": "Bob the vendor",
  • "is_tax_exempt": false,
  • "public_notes": "These are public notes visible to vendors",
  • "routing_id": "0088:12345678901"
}

Purchase Orders

Endpoint definitions for interacting with purchase orders.

List purchase orders

Lists purchase orders, search and filters allow fine grained lists to be generated. * * Query parameters can be added to performed more fine grained filtering of the purchase orders, these are handled by the PurchaseOrderFilters class which defines the methods available

Authorizations:
ApiKeyAuth
query Parameters
include
string
Example: include=first_load

Includes child relationships in the response, format is comma separated. Check each model for the list of associated includes

index
string
Example: index=user

Replaces the default response index from data to a user specific string

ie.

  ?index=new_index

response is wrapped

  {
    'new_index' : [
      .....  
    ]
  }
per_page
integer
Example: per_page=20

The number of records to return for each request, default is 20

page
integer
Example: page=1

The page number to return for this request (when performing pagination), default is 1

header Parameters
X-API-TOKEN
required
string
Example: TOKEN

The API token to be used for authentication

X-Requested-With
required
string
Example: XMLHttpRequest

Used to send the XMLHttpRequest header

Responses

Request samples 

$ninja = new InvoiceNinja("YOUR-TOKEN");
$purchaseOrders = $ninja->purchaseOrders->all([
    'per_page' => 10,
    'page' => 1
]);

Response samples

Content type
application/json
{
  • "data": [
    ],
  • "meta": {
    }
}

Create purchase order

Adds a purchase order to the system

Authorizations:
ApiKeyAuth
query Parameters
include
string
Example: include=first_load

Includes child relationships in the response, format is comma separated. Check each model for the list of associated includes

header Parameters
X-API-TOKEN
required
string
Example: TOKEN

The API token to be used for authentication

X-Requested-With
required
string
Example: XMLHttpRequest

Used to send the XMLHttpRequest header

Request Body schema: application/json
required

Purchase order object that needs to be added to the company

vendor_id
required
string

The hashed ID of the vendor

date
required
string <date>

Purchase order date

due_date
required
string <date>

Due date for the purchase order

private_notes
string

Private notes for the purchase order

public_notes
string

Public notes for the purchase order

custom_value1
string

Custom field value 1

custom_value2
string

Custom field value 2

custom_value3
string

Custom field value 3

custom_value4
string

Custom field value 4

Array of objects

Array of line items for the purchase order

Responses

Request samples

Content type
application/json
{
  • "vendor_id": "D2J234DFA",
  • "date": "2024-01-01",
  • "due_date": "2024-01-31",
  • "private_notes": "Internal notes about this purchase order",
  • "public_notes": "Please deliver to our warehouse",
  • "custom_value1": "Custom value 1",
  • "custom_value2": "Custom value 2",
  • "custom_value3": "Custom value 3",
  • "custom_value4": "Custom value 4",
  • "line_items": [
    ]
}

Response samples

Content type
application/json
{
  • "id": "Opnel5aKBz",
  • "user_id": "",
  • "assigned_user_id": "",
  • "vendor_id": "",
  • "status_id": "",
  • "number": "PO_101",
  • "quote_number": "QUOTE_101",
  • "terms": "These are some purchase order terms. Valid for 14 days.",
  • "public_notes": "These are public notes which the vendor may see",
  • "private_notes": "These are private notes, not to be disclosed to the vendor",
  • "footer": "The text goes in the footer of the purchase order",
  • "custom_value1": "A custom value",
  • "custom_value2": "A custom value",
  • "custom_value3": "A custom value",
  • "custom_value4": "A custom value",
  • "tax_name1": "GST",
  • "tax_name2": "VAT",
  • "tax_rate1": 10,
  • "tax_rate2": 10,
  • "tax_name3": "",
  • "tax_rate3": 10,
  • "total_taxes": 10,
  • "line_items": [
    ],
  • "amount": 10,
  • "balance": 10,
  • "paid_to_date": 10,
  • "discount": 10,
  • "partial": 10,
  • "is_amount_discount": true,
  • "is_deleted": false,
  • "uses_inclusive_taxes": true,
  • "date": "1994-07-30",
  • "last_sent_date": "1994-07-30",
  • "next_send_date": "1994-07-30",
  • "partial_due_date": "1994-07-30",
  • "due_date": "1994-07-30",
  • "settings": {
    },
  • "last_viewed": 1434342123,
  • "updated_at": 1434342123,
  • "archived_at": 1434342123,
  • "custom_surcharge1": 10,
  • "custom_surcharge2": 10,
  • "custom_surcharge3": 10,
  • "custom_surcharge4": 10,
  • "custom_surcharge_tax1": true,
  • "custom_surcharge_tax2": true,
  • "custom_surcharge_tax3": true,
  • "custom_surcharge_tax4": true,
  • "backup": "backup_data.json",
  • "client_id": "Opnel5aKBz",
  • "currency_id": "1",
  • "design_id": "Opnel5aKBz",
  • "exchange_rate": 1,
  • "invoice_id": "Opnel5aKBz",
  • "location_id": "Opnel5aKBz",
  • "po_number": "PO-2024-001",
  • "project_id": "Opnel5aKBz",
  • "recurring_id": "Opnel5aKBz",
  • "reminder1_sent": 1234567890,
  • "reminder2_sent": 1234567890,
  • "reminder3_sent": 1234567890,
  • "reminder_last_sent": 1234567890
}

Show purchase order

Displays an purchase order by id

Authorizations:
ApiKeyAuth
path Parameters
id
required
string <string>
Example: D2J234DFA

The Purchase order Hashed ID

query Parameters
include
string
Example: include=first_load

Includes child relationships in the response, format is comma separated. Check each model for the list of associated includes

header Parameters
X-API-TOKEN
required
string
Example: TOKEN

The API token to be used for authentication

X-Requested-With
required
string
Example: XMLHttpRequest

Used to send the XMLHttpRequest header

Responses

Response samples

Content type
application/json
{
  • "id": "Opnel5aKBz",
  • "user_id": "",
  • "assigned_user_id": "",
  • "vendor_id": "",
  • "status_id": "",
  • "number": "PO_101",
  • "quote_number": "QUOTE_101",
  • "terms": "These are some purchase order terms. Valid for 14 days.",
  • "public_notes": "These are public notes which the vendor may see",
  • "private_notes": "These are private notes, not to be disclosed to the vendor",
  • "footer": "The text goes in the footer of the purchase order",
  • "custom_value1": "A custom value",
  • "custom_value2": "A custom value",
  • "custom_value3": "A custom value",
  • "custom_value4": "A custom value",
  • "tax_name1": "GST",
  • "tax_name2": "VAT",
  • "tax_rate1": 10,
  • "tax_rate2": 10,
  • "tax_name3": "",
  • "tax_rate3": 10,
  • "total_taxes": 10,
  • "line_items": [
    ],
  • "amount": 10,
  • "balance": 10,
  • "paid_to_date": 10,
  • "discount": 10,
  • "partial": 10,
  • "is_amount_discount": true,
  • "is_deleted": false,
  • "uses_inclusive_taxes": true,
  • "date": "1994-07-30",
  • "last_sent_date": "1994-07-30",
  • "next_send_date": "1994-07-30",
  • "partial_due_date": "1994-07-30",
  • "due_date": "1994-07-30",
  • "settings": {
    },
  • "last_viewed": 1434342123,
  • "updated_at": 1434342123,
  • "archived_at": 1434342123,
  • "custom_surcharge1": 10,
  • "custom_surcharge2": 10,
  • "custom_surcharge3": 10,
  • "custom_surcharge4": 10,
  • "custom_surcharge_tax1": true,
  • "custom_surcharge_tax2": true,
  • "custom_surcharge_tax3": true,
  • "custom_surcharge_tax4": true,
  • "backup": "backup_data.json",
  • "client_id": "Opnel5aKBz",
  • "currency_id": "1",
  • "design_id": "Opnel5aKBz",
  • "exchange_rate": 1,
  • "invoice_id": "Opnel5aKBz",
  • "location_id": "Opnel5aKBz",
  • "po_number": "PO-2024-001",
  • "project_id": "Opnel5aKBz",
  • "recurring_id": "Opnel5aKBz",
  • "reminder1_sent": 1234567890,
  • "reminder2_sent": 1234567890,
  • "reminder3_sent": 1234567890,
  • "reminder_last_sent": 1234567890
}

Update purchase order

Handles the updating of a purchase order by id

Authorizations:
ApiKeyAuth
path Parameters
id
required
string <string>
Example: D2J234DFA

The purchase order Hashed ID

query Parameters
include
string
Example: include=first_load

Includes child relationships in the response, format is comma separated. Check each model for the list of associated includes

header Parameters
X-API-TOKEN
required
string
Example: TOKEN

The API token to be used for authentication

X-Requested-With
required
string
Example: XMLHttpRequest

Used to send the XMLHttpRequest header

Request Body schema: application/json
required

Purchase order object that needs to be updated

vendor_id
required
string

The hashed ID of the vendor

date
required
string <date>

Purchase order date

due_date
required
string <date>

Due date for the purchase order

private_notes
string

Private notes for the purchase order

public_notes
string

Public notes for the purchase order

custom_value1
string

Custom field value 1

custom_value2
string

Custom field value 2

custom_value3
string

Custom field value 3

custom_value4
string

Custom field value 4

Array of objects

Array of line items for the purchase order

Responses

Request samples

Content type
application/json
{
  • "vendor_id": "D2J234DFA",
  • "date": "2024-01-01",
  • "due_date": "2024-01-31",
  • "private_notes": "Internal notes about this purchase order",
  • "public_notes": "Please deliver to our warehouse",
  • "custom_value1": "Custom value 1",
  • "custom_value2": "Custom value 2",
  • "custom_value3": "Custom value 3",
  • "custom_value4": "Custom value 4",
  • "line_items": [
    ]
}

Response samples

Content type
application/json
{
  • "id": "Opnel5aKBz",
  • "user_id": "",
  • "assigned_user_id": "",
  • "vendor_id": "",
  • "status_id": "",
  • "number": "PO_101",
  • "quote_number": "QUOTE_101",
  • "terms": "These are some purchase order terms. Valid for 14 days.",
  • "public_notes": "These are public notes which the vendor may see",
  • "private_notes": "These are private notes, not to be disclosed to the vendor",
  • "footer": "The text goes in the footer of the purchase order",
  • "custom_value1": "A custom value",
  • "custom_value2": "A custom value",
  • "custom_value3": "A custom value",
  • "custom_value4": "A custom value",
  • "tax_name1": "GST",
  • "tax_name2": "VAT",
  • "tax_rate1": 10,
  • "tax_rate2": 10,
  • "tax_name3": "",
  • "tax_rate3": 10,
  • "total_taxes": 10,
  • "line_items": [
    ],
  • "amount": 10,
  • "balance": 10,
  • "paid_to_date": 10,
  • "discount": 10,
  • "partial": 10,
  • "is_amount_discount": true,
  • "is_deleted": false,
  • "uses_inclusive_taxes": true,
  • "date": "1994-07-30",
  • "last_sent_date": "1994-07-30",
  • "next_send_date": "1994-07-30",
  • "partial_due_date": "1994-07-30",
  • "due_date": "1994-07-30",
  • "settings": {
    },
  • "last_viewed": 1434342123,
  • "updated_at": 1434342123,
  • "archived_at": 1434342123,
  • "custom_surcharge1": 10,
  • "custom_surcharge2": 10,
  • "custom_surcharge3": 10,
  • "custom_surcharge4": 10,
  • "custom_surcharge_tax1": true,
  • "custom_surcharge_tax2": true,
  • "custom_surcharge_tax3": true,
  • "custom_surcharge_tax4": true,
  • "backup": "backup_data.json",
  • "client_id": "Opnel5aKBz",
  • "currency_id": "1",
  • "design_id": "Opnel5aKBz",
  • "exchange_rate": 1,
  • "invoice_id": "Opnel5aKBz",
  • "location_id": "Opnel5aKBz",
  • "po_number": "PO-2024-001",
  • "project_id": "Opnel5aKBz",
  • "recurring_id": "Opnel5aKBz",
  • "reminder1_sent": 1234567890,
  • "reminder2_sent": 1234567890,
  • "reminder3_sent": 1234567890,
  • "reminder_last_sent": 1234567890
}

Delete purchase order

Handles the deletion of an purchase orders by id

Authorizations:
ApiKeyAuth
path Parameters
id
required
string <string>
Example: D2J234DFA

The purhcase order Hashed ID

query Parameters
include
string
Example: include=first_load

Includes child relationships in the response, format is comma separated. Check each model for the list of associated includes

header Parameters
X-API-TOKEN
required
string
Example: TOKEN

The API token to be used for authentication

X-Requested-With
required
string
Example: XMLHttpRequest

Used to send the XMLHttpRequest header

Responses

Response samples

Content type
application/json
{
  • "message": "These credentials do not match our records / Invalid Token"
}

Edit purchase order

Displays an purchase order by id

Authorizations:
ApiKeyAuth
path Parameters
id
required
string <string>
Example: D2J234DFA

The purchase order Hashed ID

query Parameters
include
string
Example: include=first_load

Includes child relationships in the response, format is comma separated. Check each model for the list of associated includes

header Parameters
X-API-TOKEN
required
string
Example: TOKEN

The API token to be used for authentication

X-Requested-With
required
string
Example: XMLHttpRequest

Used to send the XMLHttpRequest header

Responses

Response samples

Content type
application/json
{
  • "id": "Opnel5aKBz",
  • "user_id": "",
  • "assigned_user_id": "",
  • "vendor_id": "",
  • "status_id": "",
  • "number": "PO_101",
  • "quote_number": "QUOTE_101",
  • "terms": "These are some purchase order terms. Valid for 14 days.",
  • "public_notes": "These are public notes which the vendor may see",
  • "private_notes": "These are private notes, not to be disclosed to the vendor",
  • "footer": "The text goes in the footer of the purchase order",
  • "custom_value1": "A custom value",
  • "custom_value2": "A custom value",
  • "custom_value3": "A custom value",
  • "custom_value4": "A custom value",
  • "tax_name1": "GST",
  • "tax_name2": "VAT",
  • "tax_rate1": 10,
  • "tax_rate2": 10,
  • "tax_name3": "",
  • "tax_rate3": 10,
  • "total_taxes": 10,
  • "line_items": [
    ],
  • "amount": 10,
  • "balance": 10,
  • "paid_to_date": 10,
  • "discount": 10,
  • "partial": 10,
  • "is_amount_discount": true,
  • "is_deleted": false,
  • "uses_inclusive_taxes": true,
  • "date": "1994-07-30",
  • "last_sent_date": "1994-07-30",
  • "next_send_date": "1994-07-30",
  • "partial_due_date": "1994-07-30",
  • "due_date": "1994-07-30",
  • "settings": {