Invoices

NOTE: The invoices endpoint is part of Version 2.5 (v2.5) of the REST API.

Invoices represent sales in the system.

Fields

Attributes:

• account_id
• account_name
• company_id
• currency_code
• date_issued
• financial_organisation_id
• id
• is_contact_notified
• lifecycle_status
• number
• number_of_lines
• total
• uri
• other_ref - a reference to the invoice in an external system
• po_ref

Relations:

• account - Account
• company - Company
• currency - Currency
• lines - LineItem
• region - Region

LineItem:

Attributes:

• id
• quantity
• value
• amount
• description
• tax_amount
• last_modified_timestamp
• custom_discount_rate
• date
• service_date
• is_taxable

Relations:

• credit_account - NominalAccount
• tax_type - TaxType

TaxType

Attributes:

• id
• name
• rate

NominalAccount

Attributes:

• id
• name
• code

Getting Invoices

GET (/api/v2.5/finance/invoices/:id()

• statuscode 200

  no error

• statuscode 404

  does not exist

Using Curl:

curl https://YOUR-SUBDOMAIN.administrateapp.com/api/v2.5/finance/invoices/4 \
    -k -u (login):(password)

Using PHP:

<?php
$credentials = '(username):(password)';
$url = 'https://YOUR-SUBDOMAIN.administrateapp.com/api/v2.5/finance/invoices/4';

$options = array(
  'http' => array(
    'method'  => 'GET',
    'header'=>  "Accept: application/json\r\n" .
                "Authorization: Basic " . base64_encode($credentials)
    )
);

$context  = stream_context_create($options);
$result = file_get_contents($url, false, $context);
echo $result;

Using Python:

import json
import requests

response = requests.get('http://YOUR-SUBDOMAIN.administrateapp.com/api/v2.5/finance/invoices/4',
                auth=('<username>', '<password>'))

print response.json

Example response:

{
    "number_of_lines": 0,
    "date_issued": "2020-01-22T20:14:04Z",
    "number": "1",
    "account_id": 1,
    "uri": "/php/viewedit/salesinvoice/4",
    "currency": {
        "id": "GBP"
    },
    "lines": [],
    "region": {
        "name": "Scotland",
        "default_tax": null,
        "countries": [],
        "company": {
            "account": {
                "industries": [],
                "num_purchases": 0,
                "name": "Acme Corp",
                "shipping_address_country": null,
                "billing_address_country": null,
                "num_invoices": 1,
                "root_account": null,
                "address_country": null,
                "id": 1
            },
            "name": "Acme Corp",
            "default_tax": null,
            "id": 1,
            "timezone": null,
            "incoming_sharing_agreements": [],
            "bank_details": []
        },
        "locations": [],
        "id": "SCO"
    },
    "po_ref": null,
    "account": {
        "is_employee": false,
        "shipping_address_locality": null,
        "default_price_level_id": null,
        "telephone": null,
        "shipping_address_unit": null,
        "no_publicity": null,
        "shipping_telephone": null,
        "num_invoices": 1,
        "owner": 0,
        "vat_number": null,
        "is_supplier": false,
        "billing_address_country_id": null,
        "address_street": null,
        "address_postcode": null,
        "shipping_address_postcode": null,
        "address_country": null,
        "num_purchases": 0,
        "parent_id": null,
        "address_region": null,
        "id": 1,
        "is_venue": false,
        "company_id": null,
        "is_individual": false,
        "source": null,
        "source_details": null,
        "billing_contact_person": null,
        "address_unit": null,
        "billing_address_locality": null,
        "is_partner": false,
        "type": null,
        "email": "acme@corp.com",
        "website": null,
        "custom": {},
        "fax": null,
        "billing_address_unit": null,
        "shipping_address_country": null,
        "billing_telephone": null,
        "address_town": null,
        "billing_address_postcode": null,
        "shipping_address_town": null,
        "billing_address_street": null,
        "shipping_address_region": null,
        "shipping_address_country_id": null,
        "shipping_contact_person": null,
        "name": "Acme Corp",
        "partner_type": 1,
        "mobile": null,
        "notes": null,
        "address_country_id": null,
        "company_number": null,
        "address_locality": null,
        "billing_address_region": null,
        "shipping_address_street": null,
        "category_id": null,
        "bank_details": null,
        "billing_address_town": null
    },
    "company_id": 1,
    "is_contact_notified": false,
    "other_ref": null,
    "id": 4,
    "lifecycle_status": "Draft",
    "total": 0.0,
    "company": {
        "account": {
            "industries": [],
            "num_purchases": 0,
            "name": "Acme Corp",
            "shipping_address_country": null,
            "billing_address_country": null,
            "num_invoices": 1,
            "root_account": null,
            "address_country": null,
            "id": 1
        },
        "name": "Acme Corp",
        "default_tax": null,
        "id": 1,
        "incoming_sharing_agreements": [],
        "bank_details": []
    },
    "account_name": "Acme Corp",
    "currency_code": "GBP"
}

Getting more than one Invoice

GET (/api/v2.5/finance/invoices()

• statuscode 200

  no error

Using Curl:

curl https://YOUR-SUBDOMAIN.administrateapp.com/api/v2.5/finance/invoices \
    -k -u (login):(password)

Using PHP:

<?php
$credentials = '(username):(password)';
$url = 'https://YOUR-SUBDOMAIN.administrateapp.com/api/v2.5/finance/invoices';

$options = array(
  'http' => array(
    'method'  => 'GET',
    'header'=>  "Accept: application/json\r\n" .
                "Authorization: Basic " . base64_encode($credentials)
    )
);

$context  = stream_context_create($options);
$result = file_get_contents($url, false, $context);
echo $result;

Using Python:

import json
import requests

response = requests.get('http://YOUR-SUBDOMAIN.administrateapp.com/api/v2.5/finance/invoices',
                auth=('<username>', '<password>'))

print response.json

Example response:

[
    {
        "number_of_lines": 0,
        "date_issued": "2020-01-22T20:14:06Z",
        "number": "1",
        "account_id": 1,
        "uri": "/php/viewedit/salesinvoice/12",
        "currency": {
            "id": "GBP"
        },
        "lines": [],
        "region": {
            "name": "Scotland",
            "default_tax": null,
            "countries": [],
            "company": {
                "account": {
                    "industries": [],
                    "num_purchases": 0,
                    "name": "Acme Corp",
                    "shipping_address_country": null,
                    "billing_address_country": null,
                    "num_invoices": 1,
                    "root_account": null,
                    "address_country": null,
                    "id": 1
                },
                "name": "Acme Corp",
                "default_tax": null,
                "id": 1,
                "timezone": null,
                "incoming_sharing_agreements": [],
                "bank_details": []
            },
            "locations": [],
            "id": "SCO"
        },
        "po_ref": null,
        "account": {
            "is_employee": false,
            "shipping_address_locality": null,
            "default_price_level_id": null,
            "telephone": null,
            "shipping_address_unit": null,
            "no_publicity": null,
            "shipping_telephone": null,
            "num_invoices": 1,
            "owner": 0,
            "vat_number": null,
            "is_supplier": false,
            "billing_address_country_id": null,
            "address_street": null,
            "address_postcode": null,
            "shipping_address_postcode": null,
            "address_country": null,
            "num_purchases": 0,
            "parent_id": null,
            "address_region": null,
            "id": 1,
            "is_venue": false,
            "company_id": null,
            "is_individual": false,
            "source": null,
            "source_details": null,
            "billing_contact_person": null,
            "address_unit": null,
            "billing_address_locality": null,
            "is_partner": false,
            "type": null,
            "email": "acme@corp.com",
            "website": null,
            "custom": {},
            "fax": null,
            "billing_address_unit": null,
            "shipping_address_country": null,
            "billing_telephone": null,
            "address_town": null,
            "billing_address_postcode": null,
            "shipping_address_town": null,
            "billing_address_street": null,
            "shipping_address_region": null,
            "shipping_address_country_id": null,
            "shipping_contact_person": null,
            "name": "Acme Corp",
            "partner_type": 1,
            "mobile": null,
            "notes": null,
            "address_country_id": null,
            "company_number": null,
            "address_locality": null,
            "billing_address_region": null,
            "shipping_address_street": null,
            "category_id": null,
            "bank_details": null,
            "billing_address_town": null
        },
        "company_id": 1,
        "is_contact_notified": false,
        "other_ref": null,
        "id": 12,
        "lifecycle_status": "Draft",
        "total": 0.0,
        "company": {
            "account": {
                "industries": [],
                "num_purchases": 0,
                "name": "Acme Corp",
                "shipping_address_country": null,
                "billing_address_country": null,
                "num_invoices": 1,
                "root_account": null,
                "address_country": null,
                "id": 1
            },
            "name": "Acme Corp",
            "default_tax": null,
            "id": 1,
            "incoming_sharing_agreements": [],
            "bank_details": []
        },
        "account_name": "Acme Corp",
        "currency_code": "GBP"
    }
]

Filtering

The results for a list of invoices can be filtered. See Version 2.5 (v2.5) for more details.

Creating an Invoice

POST (/api/v2.5/finance/invoices()

• statuscode 200

  no error

• statuscode 400

  bad request

Using Curl:

curl https://YOUR-SUBDOMAIN.administrateapp.com/api/v2.5/finance/invoices \
    -H "Content-Type: application/json" \
    -d '{
    "currency": {
      "id": "GBP"
    },
    "account": {
      "id": 2
    },
    "region": {
      "id": "SCO"
    },
    "company": {
      "id": 1
    }
  }' \
    -X POST \
    -k -u (login):(password)

Using PHP:

<?php
$credentials = '(username):(password)';
$url = 'https://YOUR-SUBDOMAIN.administrateapp.com/api/v2.5/finance/invoices';

$data = array("currency" => array("id" => "GBP"),
  "account" => array("id" => 2),
  "region" => array("id" => "SCO"),
  "company" => array("id" => 1));
$options = array(
  'http' => array(
  'method'  => 'POST',
  'content' => json_encode($data),
  'header'=>  "Content-Type: application/json\r\n" .
        "Accept: application/json\r\n" .
        "Authorization: Basic " . base64_encode($credentials)
  )
);

$context  = stream_context_create($options);
$result = file_get_contents($url, false, $context);
echo $result;

Using Python:

import json
import requests

data = {'currency': {'id': u'GBP'}, 'account': {'id': 2L}, 'region': {'id': u'SCO'}, 'company': {'id': 1L}}

response = requests.post('http://YOUR-SUBDOMAIN.administrateapp.com/api/v2.5/finance/invoices',
                data=json.dumps(data),
                headers={'content-type': 'application/json'},
                auth=('<username>', '<password>'))

print response.json

Example response:

{
    "number_of_lines": 0,
    "date_issued": "2020-01-22T20:14:06Z",
    "number": "1",
    "account_id": 2,
    "uri": "/php/viewedit/salesinvoice/13",
    "currency": {
        "id": "GBP"
    },
    "lines": [],
    "region": {
        "name": "Scotland",
        "default_tax": null,
        "countries": [],
        "company": {
            "account": {
                "industries": [],
                "num_purchases": 0,
                "name": "Acme Corp",
                "shipping_address_country": null,
                "billing_address_country": null,
                "num_invoices": 0,
                "root_account": null,
                "address_country": null,
                "id": 1
            },
            "name": "Acme Corp",
            "default_tax": null,
            "id": 1,
            "timezone": null,
            "incoming_sharing_agreements": [],
            "bank_details": []
        },
        "locations": [],
        "id": "SCO"
    },
    "po_ref": null,
    "account": {
        "is_employee": false,
        "shipping_address_locality": null,
        "default_price_level_id": null,
        "telephone": null,
        "shipping_address_unit": null,
        "no_publicity": null,
        "shipping_telephone": null,
        "num_invoices": 1,
        "owner": 0,
        "vat_number": null,
        "is_supplier": false,
        "billing_address_country_id": null,
        "address_street": null,
        "address_postcode": null,
        "shipping_address_postcode": null,
        "address_country": null,
        "num_purchases": 0,
        "parent_id": null,
        "address_region": null,
        "id": 2,
        "is_venue": false,
        "company_id": null,
        "is_individual": false,
        "source": null,
        "source_details": null,
        "billing_contact_person": null,
        "address_unit": null,
        "billing_address_locality": null,
        "is_partner": false,
        "type": null,
        "email": "tom@inc.com",
        "website": null,
        "custom": {},
        "fax": null,
        "billing_address_unit": null,
        "shipping_address_country": null,
        "billing_telephone": null,
        "address_town": null,
        "billing_address_postcode": null,
        "shipping_address_town": null,
        "billing_address_street": null,
        "shipping_address_region": null,
        "shipping_address_country_id": null,
        "shipping_contact_person": null,
        "name": "Tom Inc",
        "partner_type": 1,
        "mobile": null,
        "notes": null,
        "address_country_id": null,
        "company_number": null,
        "address_locality": null,
        "billing_address_region": null,
        "shipping_address_street": null,
        "category_id": null,
        "bank_details": null,
        "billing_address_town": null
    },
    "company_id": 1,
    "is_contact_notified": false,
    "other_ref": null,
    "id": 13,
    "lifecycle_status": "Draft",
    "total": 0.0,
    "company": {
        "account": {
            "industries": [],
            "num_purchases": 0,
            "name": "Acme Corp",
            "shipping_address_country": null,
            "billing_address_country": null,
            "num_invoices": 0,
            "root_account": null,
            "address_country": null,
            "id": 1
        },
        "name": "Acme Corp",
        "default_tax": null,
        "id": 1,
        "incoming_sharing_agreements": [],
        "bank_details": []
    },
    "account_name": "Tom Inc",
    "currency_code": "GBP"
}

Updating an Invoice

PUT (/api/v2.5/finance/invoices/:id()

• statuscode 200

  no error

• statuscode 400

  bad request

Note that finalised invoices do not allow significant updates to the invoice. Submitting an significant update to a finalised invoice will result in a 403 Forbidden error.

Using Curl:

curl https://YOUR-SUBDOMAIN.administrateapp.com/api/v2.5/finance/invoices/17 \
    -H "Content-Type: application/json" \
    -d '{
    "account": {
      "id": 3
    }
  }' \
    -X PUT \
    -k -u (login):(password)

Using PHP:

<?php
$credentials = '(username):(password)';
$url = 'https://YOUR-SUBDOMAIN.administrateapp.com/api/v2.5/finance/invoices/17';

$data = array("account" => array("id" => 3));
$options = array(
  'http' => array(
  'method'  => 'PUT',
  'content' => json_encode($data),
  'header'=>  "Content-Type: application/json\r\n" .
        "Accept: application/json\r\n" .
        "Authorization: Basic " . base64_encode($credentials)
  )
);

$context  = stream_context_create($options);
$result = file_get_contents($url, false, $context);
echo $result;

Using Python:

import json
import requests

data = {'account': {'id': 3L}}

response = requests.put('http://YOUR-SUBDOMAIN.administrateapp.com/api/v2.5/finance/invoices/17',
                data=json.dumps(data),
                headers={'content-type': 'application/json'},
                auth=('<username>', '<password>'))

print response.json

Example response:

{
    "number_of_lines": 0,
    "date_issued": "2020-01-22T20:14:07Z",
    "number": "1",
    "account_id": 3,
    "uri": "/php/viewedit/salesinvoice/14",
    "currency": {
        "id": "GBP"
    },
    "lines": [],
    "region": {
        "name": "Scotland",
        "default_tax": null,
        "countries": [],
        "company": {
            "account": {
                "industries": [],
                "num_purchases": 0,
                "name": "Acme Corp",
                "shipping_address_country": null,
                "billing_address_country": null,
                "num_invoices": 0,
                "root_account": null,
                "address_country": null,
                "id": 1
            },
            "name": "Acme Corp",
            "default_tax": null,
            "id": 1,
            "timezone": null,
            "incoming_sharing_agreements": [],
            "bank_details": []
        },
        "locations": [],
        "id": "SCO"
    },
    "po_ref": null,
    "account": {
        "is_employee": false,
        "shipping_address_locality": null,
        "default_price_level_id": null,
        "telephone": null,
        "shipping_address_unit": null,
        "no_publicity": null,
        "shipping_telephone": null,
        "num_invoices": 1,
        "owner": 0,
        "vat_number": null,
        "is_supplier": false,
        "billing_address_country_id": null,
        "address_street": null,
        "address_postcode": null,
        "shipping_address_postcode": null,
        "address_country": null,
        "num_purchases": 0,
        "parent_id": null,
        "address_region": null,
        "id": 3,
        "is_venue": false,
        "company_id": null,
        "is_individual": false,
        "source": null,
        "source_details": null,
        "billing_contact_person": null,
        "address_unit": null,
        "billing_address_locality": null,
        "is_partner": false,
        "type": null,
        "email": "tom@inc.com",
        "website": null,
        "custom": {},
        "fax": null,
        "billing_address_unit": null,
        "shipping_address_country": null,
        "billing_telephone": null,
        "address_town": null,
        "billing_address_postcode": null,
        "shipping_address_town": null,
        "billing_address_street": null,
        "shipping_address_region": null,
        "shipping_address_country_id": null,
        "shipping_contact_person": null,
        "name": "Tom Inc",
        "partner_type": 1,
        "mobile": null,
        "notes": null,
        "address_country_id": null,
        "company_number": null,
        "address_locality": null,
        "billing_address_region": null,
        "shipping_address_street": null,
        "category_id": null,
        "bank_details": null,
        "billing_address_town": null
    },
    "company_id": 1,
    "is_contact_notified": false,
    "other_ref": null,
    "id": 14,
    "lifecycle_status": "Draft",
    "total": 0.0,
    "company": {
        "account": {
            "industries": [],
            "num_purchases": 0,
            "name": "Acme Corp",
            "shipping_address_country": null,
            "billing_address_country": null,
            "num_invoices": 0,
            "root_account": null,
            "address_country": null,
            "id": 1
        },
        "name": "Acme Corp",
        "default_tax": null,
        "id": 1,
        "incoming_sharing_agreements": [],
        "bank_details": []
    },
    "account_name": "Tom Inc",
    "currency_code": "GBP"
}

Finalising an Invoice

POST (/api/v2.5/finance/invoices/finalise/:id()

• statuscode 200

  no error

• statuscode 400

  bad request

Using Curl:

curl https://YOUR-SUBDOMAIN.administrateapp.com/api/v2.5/finance/invoices/finalise/3 \
    -H "Content-Type: application/json" \
    -d 'null' \
    -X POST \
    -k -u (login):(password)

Using PHP:

<?php
$credentials = '(username):(password)';
$url = 'https://YOUR-SUBDOMAIN.administrateapp.com/api/v2.5/finance/invoices/finalise/3';

$data = None;
$options = array(
  'http' => array(
  'method'  => 'POST',
  'content' => json_encode($data),
  'header'=>  "Content-Type: application/json\r\n" .
        "Accept: application/json\r\n" .
        "Authorization: Basic " . base64_encode($credentials)
  )
);

$context  = stream_context_create($options);
$result = file_get_contents($url, false, $context);
echo $result;

Using Python:

import json
import requests

data = None

response = requests.post('http://YOUR-SUBDOMAIN.administrateapp.com/api/v2.5/finance/invoices/finalise/3',
                data=json.dumps(data),
                headers={'content-type': 'application/json'},
                auth=('<username>', '<password>'))

print response.json

Example response:

{
    "lifecycle_status": "Final",
    "document_id": 3
}

Create from Registration

POST (/api/v2.5/finance/invoices/create_from_registration/:registration_id()

• statuscode 200

  no error

• statuscode 400

  bad request

List Payments for an Invoice

GET (/api/v2.5/finance/invoices/:id/payments()

• statuscode 200

  no error

Using Curl:

curl https://YOUR-SUBDOMAIN.administrateapp.com/api/v2.5/finance/invoices/1/payments \
    -k -u (login):(password)

Using PHP:

<?php
$credentials = '(username):(password)';
$url = 'https://YOUR-SUBDOMAIN.administrateapp.com/api/v2.5/finance/invoices/1/payments';

$options = array(
  'http' => array(
    'method'  => 'GET',
    'header'=>  "Accept: application/json\r\n" .
                "Authorization: Basic " . base64_encode($credentials)
    )
);

$context  = stream_context_create($options);
$result = file_get_contents($url, false, $context);
echo $result;

Using Python:

import json
import requests

response = requests.get('http://YOUR-SUBDOMAIN.administrateapp.com/api/v2.5/finance/invoices/1/payments',
                auth=('<username>', '<password>'))

print response.json

Example response:

[
    {
        "reference": "1",
        "currency": "GBP",
        "id": 2,
        "value": 300.0
    },
    {
        "reference": "2",
        "currency": "GBP",
        "id": 3,
        "value": 200.0
    }
]

Create a Payment for an Invoice

POST (/api/v2.5/finance/invoices/:id/payments()

• statuscode 200

  no error

The value field on the payment is optional. If none is supplied, the value will be automatically set to the outstanding balance of the invoice. If you do supply a value you will be required to provide the currency code and it needs to match the currency on the invoice.

Using Curl:

curl https://YOUR-SUBDOMAIN.administrateapp.com/api/v2.5/finance/invoices/2/payments \
    -H "Content-Type: application/json" \
    -d '{
    "payment_type_id": 1,
    "credit_account_code": 2000
  }' \
    -X POST \
    -k -u (login):(password)

Using PHP:

<?php
$credentials = '(username):(password)';
$url = 'https://YOUR-SUBDOMAIN.administrateapp.com/api/v2.5/finance/invoices/2/payments';

$data = array("payment_type_id" => 1,
  "credit_account_code" => 2000);
$options = array(
  'http' => array(
  'method'  => 'POST',
  'content' => json_encode($data),
  'header'=>  "Content-Type: application/json\r\n" .
        "Accept: application/json\r\n" .
        "Authorization: Basic " . base64_encode($credentials)
  )
);

$context  = stream_context_create($options);
$result = file_get_contents($url, false, $context);
echo $result;

Using Python:

import json
import requests

data = {'payment_type_id': 1L, 'credit_account_code': 2000}

response = requests.post('http://YOUR-SUBDOMAIN.administrateapp.com/api/v2.5/finance/invoices/2/payments',
                data=json.dumps(data),
                headers={'content-type': 'application/json'},
                auth=('<username>', '<password>'))

print response.json

Example response:

{
    "reference": "3",
    "currency": "GBP",
    "id": 5,
    "value": 900.0
}

Please note that payments are not able to be created via the API for Companies that are linked to Xero.