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
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 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
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;
Example response:
{
"account_name": "Acme Corp",
"number_of_lines": 0,
"total": 0.0,
"account_id": 1,
"other_ref": null,
"company_id": 1,
"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,
"address_country": null,
"id": 1
},
"name": "Acme Corp",
"default_tax": null,
"bank_details": [],
"timezone": null,
"incoming_sharing_agreements": [],
"id": 1
},
"locations": [],
"id": "SCO"
},
"date_issued": "2017-10-17T12:38:14Z",
"lines": [],
"uri": "/php/viewedit/salesinvoice/4",
"number": "1",
"currency": {
"id": "GBP"
},
"account": {
"is_employee": false,
"shipping_address_locality": null,
"address_unit": null,
"telephone": null,
"company_number": null,
"no_publicity": null,
"shipping_telephone": null,
"num_invoices": 1,
"owner": 0,
"vat_number": null,
"is_supplier": false,
"billing_address_country_id": null,
"address_country": null,
"id": 1,
"shipping_address_postcode": null,
"num_purchases": 0,
"address_street": null,
"address_region": null,
"address_postcode": null,
"is_venue": false,
"company_id": null,
"is_individual": false,
"source": null,
"source_details": null,
"billing_contact_person": null,
"billing_address_locality": null,
"is_partner": false,
"type": null,
"email": "[email protected]",
"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,
"name": "Acme Corp",
"partner_type": 1,
"mobile": null,
"shipping_contact_person": null,
"address_country_id": null,
"shipping_address_unit": null,
"bank_details": null,
"address_locality": null,
"billing_address_region": null,
"shipping_address_street": null,
"category_id": null,
"notes": null,
"billing_address_town": null
},
"lifecycle_status": "Draft",
"is_contact_notified": false,
"company": {
"account": {
"industries": [],
"num_purchases": 0,
"name": "Acme Corp",
"shipping_address_country": null,
"billing_address_country": null,
"num_invoices": 1,
"address_country": null,
"id": 1
},
"name": "Acme Corp",
"default_tax": null,
"id": 1,
"incoming_sharing_agreements": [],
"bank_details": []
},
"id": 4,
"currency_code": "GBP"
}
Getting more than one Invoice¶
- GET /api/v2.5/finance/invoices¶
| statuscode 200: | no error |
|---|
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
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;
Example response:
[
{
"account_name": "Acme Corp",
"number_of_lines": 0,
"total": 0.0,
"account_id": 1,
"other_ref": null,
"company_id": 1,
"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,
"address_country": null,
"id": 1
},
"name": "Acme Corp",
"default_tax": null,
"bank_details": [],
"timezone": null,
"incoming_sharing_agreements": [],
"id": 1
},
"locations": [],
"id": "SCO"
},
"date_issued": "2017-10-17T12:38:15Z",
"lines": [],
"uri": "/php/viewedit/salesinvoice/12",
"number": "1",
"currency": {
"id": "GBP"
},
"account": {
"is_employee": false,
"shipping_address_locality": null,
"address_unit": null,
"telephone": null,
"company_number": null,
"no_publicity": null,
"shipping_telephone": null,
"num_invoices": 1,
"owner": 0,
"vat_number": null,
"is_supplier": false,
"billing_address_country_id": null,
"address_country": null,
"id": 1,
"shipping_address_postcode": null,
"num_purchases": 0,
"address_street": null,
"address_region": null,
"address_postcode": null,
"is_venue": false,
"company_id": null,
"is_individual": false,
"source": null,
"source_details": null,
"billing_contact_person": null,
"billing_address_locality": null,
"is_partner": false,
"type": null,
"email": "[email protected]",
"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,
"name": "Acme Corp",
"partner_type": 1,
"mobile": null,
"shipping_contact_person": null,
"address_country_id": null,
"shipping_address_unit": null,
"bank_details": null,
"address_locality": null,
"billing_address_region": null,
"shipping_address_street": null,
"category_id": null,
"notes": null,
"billing_address_town": null
},
"lifecycle_status": "Draft",
"is_contact_notified": false,
"company": {
"account": {
"industries": [],
"num_purchases": 0,
"name": "Acme Corp",
"shipping_address_country": null,
"billing_address_country": null,
"num_invoices": 1,
"address_country": null,
"id": 1
},
"name": "Acme Corp",
"default_tax": null,
"id": 1,
"incoming_sharing_agreements": [],
"bank_details": []
},
"id": 12,
"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 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
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;
Example response:
{
"account_name": "Tom Inc",
"number_of_lines": 0,
"total": 0.0,
"account_id": 2,
"other_ref": null,
"company_id": 1,
"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,
"address_country": null,
"id": 1
},
"name": "Acme Corp",
"default_tax": null,
"bank_details": [],
"timezone": null,
"incoming_sharing_agreements": [],
"id": 1
},
"locations": [],
"id": "SCO"
},
"date_issued": "2017-10-17T12:38:15Z",
"lines": [],
"uri": "/php/viewedit/salesinvoice/13",
"number": "1",
"currency": {
"id": "GBP"
},
"account": {
"is_employee": false,
"shipping_address_locality": null,
"address_unit": null,
"telephone": null,
"company_number": null,
"no_publicity": null,
"shipping_telephone": null,
"num_invoices": 1,
"owner": 0,
"vat_number": null,
"is_supplier": false,
"billing_address_country_id": null,
"address_country": null,
"id": 2,
"shipping_address_postcode": null,
"num_purchases": 0,
"address_street": null,
"address_region": null,
"address_postcode": null,
"is_venue": false,
"company_id": null,
"is_individual": false,
"source": null,
"source_details": null,
"billing_contact_person": null,
"billing_address_locality": null,
"is_partner": false,
"type": null,
"email": "[email protected]",
"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,
"name": "Tom Inc",
"partner_type": 1,
"mobile": null,
"shipping_contact_person": null,
"address_country_id": null,
"shipping_address_unit": null,
"bank_details": null,
"address_locality": null,
"billing_address_region": null,
"shipping_address_street": null,
"category_id": null,
"notes": null,
"billing_address_town": null
},
"lifecycle_status": "Draft",
"is_contact_notified": false,
"company": {
"account": {
"industries": [],
"num_purchases": 0,
"name": "Acme Corp",
"shipping_address_country": null,
"billing_address_country": null,
"num_invoices": 0,
"address_country": null,
"id": 1
},
"name": "Acme Corp",
"default_tax": null,
"id": 1,
"incoming_sharing_agreements": [],
"bank_details": []
},
"id": 13,
"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 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
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;
Example response:
{
"account_name": "Tom Inc",
"number_of_lines": 0,
"total": 0.0,
"account_id": 3,
"other_ref": null,
"company_id": 1,
"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,
"address_country": null,
"id": 1
},
"name": "Acme Corp",
"default_tax": null,
"bank_details": [],
"timezone": null,
"incoming_sharing_agreements": [],
"id": 1
},
"locations": [],
"id": "SCO"
},
"date_issued": "2017-10-17T12:38:16Z",
"lines": [],
"uri": "/php/viewedit/salesinvoice/14",
"number": "1",
"currency": {
"id": "GBP"
},
"account": {
"is_employee": false,
"shipping_address_locality": null,
"address_unit": null,
"telephone": null,
"company_number": null,
"no_publicity": null,
"shipping_telephone": null,
"num_invoices": 1,
"owner": 0,
"vat_number": null,
"is_supplier": false,
"billing_address_country_id": null,
"address_country": null,
"id": 3,
"shipping_address_postcode": null,
"num_purchases": 0,
"address_street": null,
"address_region": null,
"address_postcode": null,
"is_venue": false,
"company_id": null,
"is_individual": false,
"source": null,
"source_details": null,
"billing_contact_person": null,
"billing_address_locality": null,
"is_partner": false,
"type": null,
"email": "[email protected]",
"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,
"name": "Tom Inc",
"partner_type": 1,
"mobile": null,
"shipping_contact_person": null,
"address_country_id": null,
"shipping_address_unit": null,
"bank_details": null,
"address_locality": null,
"billing_address_region": null,
"shipping_address_street": null,
"category_id": null,
"notes": null,
"billing_address_town": null
},
"lifecycle_status": "Draft",
"is_contact_notified": false,
"company": {
"account": {
"industries": [],
"num_purchases": 0,
"name": "Acme Corp",
"shipping_address_country": null,
"billing_address_country": null,
"num_invoices": 0,
"address_country": null,
"id": 1
},
"name": "Acme Corp",
"default_tax": null,
"id": 1,
"incoming_sharing_agreements": [],
"bank_details": []
},
"id": 14,
"currency_code": "GBP"
}
Finalising an Invoice¶
- POST /api/v2.5/finance/invoices/finalise/:id¶
| statuscode 200: | no error |
|---|---|
| statuscode 400: | bad request |
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
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;
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 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
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;
Example response:
[
{
"currency": "GBP",
"value": 300.0,
"id": 2,
"reference": "1"
},
{
"currency": "GBP",
"value": 200.0,
"id": 3,
"reference": "2"
}
]
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 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
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;
Example response:
{
"currency": "GBP",
"value": 900.0,
"id": 5,
"reference": "3"
}
Please note that payments are not able to be created via the API for Companies that are linked to Xero.
REST API
Administrate API - Invoices
Administrate API - Invoices