Bills
Minimum access level: Bills
, unless stated otherwise.
Attributes
Required | Attribute | Description | Kind |
---|---|---|---|
url | The unique identifier for the bill | URI | |
✔ | contact | Contact being billed | URI |
✔ | reference | Free-text reference | String |
✔ | dated_on | Date of bill | Date |
✔ | due_on | Due date of bill | Date |
paid_on | Date of most recent payment, only returned for fully paid bills and bill refunds [Learn more about bill refunds] | Date | |
status |
Bill's payment status, determined based on the presence of associated bank transaction explanations. Can be one of the following:
|
String | |
long_status |
Bill's payment status along with the due date as a relative date to 'today' For example: Open - due in 21 days |
String | |
currency |
Bill's currency Defaults to the company's native currency |
String | |
✔ | total_value |
Total value of the bill Use negative value for a Bill Refund |
Decimal |
exchange_rate |
Rate at which bill amount is converted into company's native currency |
Decimal | |
ec_status |
Bill's VAT status for reporting purposes. One of the following:
Please note that You should use |
String | |
✔ | category | Bill's accounting category | URI |
comments | Free-text comments | String | |
project | Project billed for | URI | |
? | rebill_type |
One of the following, if rebilling a project:
|
String |
? | rebill_factor |
How much to rebill for Required whenrebill_type is markup or price
|
Decimal |
rebill_to_project | Same as project |
URI | |
recurring | true if the bill should recur, false otherwise |
Boolean | |
recurring_end_date | When the bill should stop recurring in YYYY-MM-DD format |
Date | |
attachment |
Explanation attachment (max 5MB), in the following format:
|
Object | |
created_at | Creation of the bill resource (UTC) | Timestamp | |
updated_at | When the bill resource was last updated (UTC) | Timestamp | |
Sales tax attributes – see Sales Tax for which attribute should be included | |||
sales_tax_rate | One of the standard sales tax rates | Decimal | |
sales_tax_value | Total value of sales tax | Decimal | |
second_sales_tax_rate | [Universal accounts only] One of the standard second sales tax rates | Decimal | |
second_sales_tax_value | [Universal accounts only] Total value of second sales tax | Decimal | |
manual_sales_tax_amount | Manual amount of sales tax | Decimal | |
sales_tax_status | Indicates whether the item is TAXABLE , EXEMPT or OUT_OF_SCOPE for
sales tax |
String | |
second_sales_tax_status | [Universal accounts only] Similar to sales_tax_status, returned only if the relevant sales tax period defines a second sales tax | String |
List all bills
GET https://api.freeagent.com/v2/bills
Input
View Filters
GET https://api.freeagent.com/v2/bills?view=open
all
: (default)open
: Show only open bills.overdue
: Show only overdue bills.open_or_overdue
: Show only open or overdue bills.paid
: Show only paid bills.recurring
: Show only recurring bills.
Date Filters
GET https://api.freeagent.com/v2/bills?from_date=2012-01-01&to_date=2012-03-31
GET https://api.freeagent.com/v2/bills?updated_since=2017-05-22T09:00:00.000Z
from_date
to_date
updated_since
Response
Status: 200 OK
{ "bills":[{
"url":"https://api.freeagent.com/v2/bills/1",
"contact":"https://api.freeagent.com/v2/contacts/1",
"category":"https://api.freeagent.com/v2/categories/285",
"reference":"acsad",
"dated_on":"2011-07-28",
"due_on":"2011-08-27",
"currency":"GBP",
"total_value":"213.0",
"exchange_rate":"0.61342",
"paid_value":"200.0",
"due_value":"13.0",
"sales_tax_value":"-35.5",
"sales_tax_rate":"20.0",
"sales_tax_status": "TAXABLE",
"status":"Open",
"long_status": "Open - due in about 1 month",
"rebill_type": "price",
"rebill_factor": "20",
"rebill_to_project": "https://api.freeagent.com/v2/projects/1",
"rebilled_on_invoice_item": "https://api.freeagent.com/v2/invoices/1",
"updated_at":"2011-07-28T12:43:36Z",
"created_at":"2011-07-28T12:43:36Z",
"attachment":
{
"url":"https://api.freeagent.com/v2/attachments/3",
"content_src":"https://s3.amazonaws.com/freeagent-dev/attachments/1/original.png?AWSAccessKeyId=1K3MW21E6T8KWBY84B02&Expires=1314281186&Signature=GFAKDo%2Bi%2FsUMTYEgg6ZWGysB4k4%3D",
"content_type":"image/png",
"file_name":"barcode.png",
"file_size":7673
}
}
]}
Show as XML<?xml version="1.0" encoding="UTF-8"?>
<freeagent>
<bills type="array">
<bill>
<url>https://api.freeagent.com/v2/bills/1</url>
<contact>https://api.freeagent.com/v2/contacts/1</contact>
<category>https://api.freeagent.com/v2/categories/285</category>
<reference>acsad</reference>
<dated-on type="date">2011-07-28</dated-on>
<due-on type="date">2011-08-27</due-on>
<currency>GBP</currency>
<total-value type="decimal">213.0</total-value>
<exchange-rate type="decimal">0.61342</exchange-rate>
<paid-value type="decimal">200.0</paid-value>
<due-value type="decimal">13.0</due-value>
<sales-tax-value type="decimal">-35.5</sales-tax-value>
<sales-tax-rate type="decimal">20.0</sales-tax-rate>
<status>Open</status>
<long-status>Open - due in about 1 month</long-status>
<rebill-type>price</rebill-type>
<rebill-factor type="decimal">20</rebill-factor>
<rebill-to-project>https://api.freeagent.com/v2/projects/1</rebill-to-project>
<rebilled-on-invoice-item>https://api.freeagent.com/v2/invoices/1</rebilled-on-invoice-item>
<updated-at type="datetime">2011-07-28T12:43:36Z</updated-at>
<created-at type="datetime">2011-07-28T12:43:36Z</created-at>
<attachment>
<url>https://api.freeagent.com/v2/attachments/3</url>
<content-src>https://s3.amazonaws.com/freeagent-dev/attachments/1/original.png?AWSAccessKeyId=1K3MW21E6T8KWBY84B02&Expires=1314281298&Signature=jhGeAgqdnDwyFKHJoPI6AKU%2Fb2s%3D</content-src>
<content-type>image/png</content-type>
<file-name>barcode.png</file-name>
<file-size type="integer">7673</file-size>
</attachment>
</bill>
</bills>
</freeagent>
Show as JSONGet a single bill
GET https://api.freeagent.com/v2/bills/:id
Response
Status: 200 OK
{ "bill":{
"url":"https://api.freeagent.com/v2/bills/1",
"contact":"https://api.freeagent.com/v2/contacts/1",
"category":"https://api.freeagent.com/v2/categories/285",
"reference":"sdasd",
"dated_on":"2011-09-14",
"due_on":"2011-10-14",
"currency":"GBP",
"total_value":"100.0",
"exchange_rate":"0.673193",
"paid_value":"80.0",
"due_value":"20.0",
"sales_tax_value":"-16.67",
"sales_tax_rate":"20.0",
"sales_tax_status": "TAXABLE",
"status":"Open",
"long_status":"Open - due in about 1 month",
"rebill_type": "price",
"rebill_factor": "20",
"rebill_to_project": "https://api.freeagent.com/v2/projects/1",
"rebilled_on_invoice_item": "https://api.freeagent.com/v2/invoices/1",
"updated_at":"2011-09-14T16:00:41Z",
"created_at":"2011-09-14T16:00:41Z",
"attachment":
{
"url":"https://api.freeagent.com/v2/attachments/3",
"content_src":"https://s3.amazonaws.com/freeagent-dev/attachments/1/original.png?AWSAccessKeyId=1K3MW21E6T8KWBY84B02&Expires=1314281186&Signature=GFAKDo%2Bi%2FsUMTYEgg6ZWGysB4k4%3D",
"content_type":"image/png",
"file_name":"barcode.png",
"file_size":7673
}
}
}
Show as XML<?xml version="1.0" encoding="UTF-8"?>
<freeagent>
<bill>
<url>https://api.freeagent.com/v2/bills/1</url>
<contact>https://api.freeagent.com/v2/contacts/1</contact>
<category>https://api.freeagent.com/v2/categories/285</category>
<reference>sdasd</reference>
<dated-on type="date">2011-09-14</dated-on>
<due-on type="date">2011-10-14</due-on>
<currency>GBP</currency>
<total-value type="decimal">100.0</total-value>
<paid-value type="decimal">80.0<paid-value>
<exchange-rate type="decimal">0.67319</exchange-rate>
<due-value type="decimal">20.0</due-value>
<sales-tax-value type="decimal">-16.67</sales-tax-value>
<sales-tax-rate type="decimal">20.0</sales-tax-rate>
<status>Open</status>
<long-status>Open - due in about 1 month</long-status>
<rebill-type>price</rebill-type>
<rebill-factor type="decimal">20</rebill-factor>
<rebill-to-project>https://api.freeagent.com/v2/projects/1</rebill-to-project>
<rebilled-on-invoice-item>https://api.freeagent.com/v2/invoices/1</rebilled-on-invoice-item>
<updated-at type="datetime">2011-09-14T16:00:41Z</updated-at>
<created-at type="datetime">2011-09-14T16:00:41Z</created-at>
<attachment>
<url>https://api.freeagent.com/v2/attachments/3</url>
<content-src>https://s3.amazonaws.com/freeagent-dev/attachments/1/original.png?AWSAccessKeyId=1K3MW21E6T8KWBY84B02&Expires=1314281298&Signature=jhGeAgqdnDwyFKHJoPI6AKU%2Fb2s%3D</content-src>
<content-type>image/png</content-type>
<file-name>barcode.png</file-name>
<file-size type="integer">7673</file-size>
</attachment>
</bill>
</freeagent>
Show as JSONList all bills related to a contact
GET https://api.freeagent.com/v2/bills?contact=https://api.freeagent.com/v2/contacts/2
List all bills related to a project
GET https://api.freeagent.com/v2/bills?project=https://api.freeagent.com/v2/projects/2
Create a bill
POST https://api.freeagent.com/v2/bills
Payload should have a root bill
element, containing elements listed
under Attributes.
Response
Status: 201 Created
Location: https://api.freeagent.com/v2/bills/12
{ "bill":{
"contact":"https://api.freeagent.com/v2/contacts/1",
"category":"https://api.freeagent.com/v2/categories/285",
"reference":"sdasd",
"dated_on":"2011-09-14",
"due_on":"2011-10-14",
"currency":"GBP",
"total_value":"100.0",
"exchange_rate":"0.67319",
"paid_value":"80.0",
"due_value":"20.0",
"sales_tax_value":"-16.67",
"sales_tax_rate":"20.0",
"sales_tax_status": "TAXABLE",
"status":"Open",
"long_status":"Open - due in about 1 month",
"rebill_type": "price",
"rebill_factor": "20",
"rebill_to_project": "https://api.freeagent.com/v2/projects/1",
"rebilled_on_invoice_item": "https://api.freeagent.com/v2/invoices/1",
"updated_at":"2011-09-14T16:00:41Z",
"created_at":"2011-09-14T16:00:41Z",
"attachment":
{
"url":"https://api.freeagent.com/v2/attachments/3",
"content_src":"https://s3.amazonaws.com/freeagent-dev/attachments/1/original.png?AWSAccessKeyId=1K3MW21E6T8KWBY84B02&Expires=1314281186&Signature=GFAKDo%2Bi%2FsUMTYEgg6ZWGysB4k4%3D",
"content_type":"image/png",
"file_name":"barcode.png",
"file_size":7673
}
}
}
Show as XML<?xml version="1.0" encoding="UTF-8"?>
<freeagent>
<bill>
<contact>https://api.freeagent.com/v2/contacts/1</contact>
<category>https://api.freeagent.com/v2/categories/285</category>
<reference>sdasd</reference>
<dated-on type="date">2011-09-14</dated-on>
<due-on type="date">2011-10-14</due-on>
<currency>GBP</currency>
<total-value type="decimal">100.0</total-value>
<exchange-rate>0.93183</exchanage-rate>
<paid-value type="decimal">80.0</paid-value>
<due-value type="decimal">20.0</due-value>
<sales-tax-value type="decimal">-16.67</sales-tax-value>
<sales-tax-rate type="decimal">20.0</sales-tax-rate>
<status>Open</status>
<long-status>Open - due in about 1 month</long-status>
<rebill-type>price</rebill-type>
<rebill-factor type="decimal">20</rebill-factor>
<rebill-to-project>https://api.freeagent.com/v2/projects/1</rebill-to-project>
<rebilled-on-invoice-item>https://api.freeagent.com/v2/invoices/1</rebilled-on-invoice-item>
<updated-at type="datetime">2011-09-14T16:00:41Z</updated-at>
<created-at type="datetime">2011-09-14T16:00:41Z</created-at>
<attachment>
<url>https://api.freeagent.com/v2/attachments/3</url>
<content-src>https://s3.amazonaws.com/freeagent-dev/attachments/1/original.png?AWSAccessKeyId=1K3MW21E6T8KWBY84B02&Expires=1314281298&Signature=jhGeAgqdnDwyFKHJoPI6AKU%2Fb2s%3D</content-src>
<content-type>image/png</content-type>
<file-name>barcode.png</file-name>
<file-size type="integer">7673</file-size>
</attachment>
</bill>
</freeagent>
Show as JSONUpdate a bill
PUT https://api.freeagent.com/v2/bills/:id
Payload should have a root bill
element, containing elements listed
under Attributes that should be updated.
Response
Status: 200 OK
Delete a bill
DELETE https://api.freeagent.com/v2/bills/:id
Response
Status: 200 OK