Invoices API
List Invoices
List all invoices for an account:
GET /invoices
Response
Status: 200 OK[
{
"id": 351,
"sourceID": null,
"description": "HP ProLiant BL260c servers",
"invoice_nr": "36798292-A",
"invoice_date": "2017-11-19",
"amount": "7200.0",
"created_at": "2017-11-22T14:32:28-06:00",
"updated_at": "2017-11-22T14:33:06-06:00",
"project": {
"id": 7497,
"subject": "Digital Operations Center (DOC)"
}
},
{
"id": 396,
"sourceID": null,
"description": "APC NetShelter rack",
"invoice_nr": "170092403",
"invoice_date": "2017-11-20",
"amount": "1408.0",
"created_at": "2017-11-28T12:01:50-06:00",
"updated_at": "2017-11-28T12:01:50-06:00",
"project": {
"id": 7497,
"subject": "Digital Operations Center (DOC)"
}
},
"..."
]
The response contains these fields by default. Filtering and pagination are available to reduce/limit the collection of invoices.
Collection Fields
By default the following fields will appear in collections of invoices:
id sourceID description invoice_type invoice_nr invoice_date amount created_at updated_at
Obtain a different set of fields using the ?fields=parameter.
Filtering
Filtering is available for the following fields:
id source sourceID description invoice_type po_nr invoice_nr invoice_date created_at updated_at
Sorting
By default a collection of invoices is sorted descending by invoice_date.
The following fields are accepted by the ?sort=parameter:
id sourceID description invoice_nr invoice_date created_at updated_at
Get a Single Invoice
GET /invoices/:id
Response
Status: 200 OK{
"amount": "7200.0",
"attachments": [
{
"name": "HP 36798292-A.pdf",
"uri": "https://itrp.s3-accelerate.dualstack.amazonaws.com/...",
"inline": false,
"size": 520410
}
],
"capital_expenditure": true,
"created_at": "2017-11-22T14:32:28-06:00",
"description": "HP ProLiant BL260c servers",
"id": 351,
"invoice_date": "2017-11-19",
"invoice_nr": "36798292-A",
"po_nr": "PO33729-01",
"quantity": 2,
"remarks": "These are the 2 servers for the DOC project.",
"service": {
"id": 24,
"name": "Service Management (ITRP)",
"localized_name": "Service Management (ITRP)",
"provider": {
"id": 45,
"name": "Widget Data Center, External IT",
"account": {
"id": "widget",
"name": "Widget International"
}
}
},
"source": "4me",
"sourceID": null,
"supplier": {
"id": 32,
"name": "HP"
},
"unit_price": "3600.0",
"updated_at": "2017-11-22T14:32:28-06:00",
"project": {
"id": 7497,
"subject": "Digital Operations Center (DOC)"
}
}
The response contains these fields.
Create a Invoice
POST /invoices
When creating a new invoice these fields are available.
Response
Status: 201 Created{
"amount": "...",
"...": "..."
}
The response contains all fields of the created invoice and is similar to the response in Get a single invoice
Update a Invoice
PATCH /invoices/:id
When updating a invoice these fields are available.
Response
Status: 200 OK{
"amount": "...",
"...": "..."
}
The response contains all fields of the updated invoice and is similar to the response in Get a single invoice
Fields
- amount
- Readonly decimal — The Amount field contains the product of the Unit price field value and the Quantity field value.
- amortize
- Optional boolean — Whether the invoice amount is to be amortized over time.
- amortization_start
- Optional datetime — The start date of the period over which the invoice is to be amortized.
- amortization_end
- Optional datetime — The end date of the period over which the invoice is to be amortized.
- attachments
- Readonly aggregated Attachments
- contract
- Optional reference to Contract — The contract linked to this invoice.
-
This field cannot be specified in the ?fields= parameter.
- currency
- Optional enum — The currency of the Amount field value of the invoice. For valid values, see the list of currencies in the Currency field of the Account API.
- created_at
- Readonly datetime — The date and time at which the invoice was created.
- depreciation_method
- Required enum — Whether or not the invoice should be depreciated and if so, which depreciation method is to be applied. When creating a new invoice and a value is not specified for this field, and the invoice is related to a configuration item, the value is set to the depreciation method of the product of the configuration item.
Valid values are:
not_depreciated: Not Depreciateddouble_declining_balance: Double Declining Balancereducing_balance: Reducing Balance (or Diminishing Value)straight_line: Straight Line (or Prime Cost)sum_of_the_years_digits: Sum of the Year’s Digits
- depreciation_start
- Required date — The date on which to start depreciating the asset.
- description
- Required string (max 220) — The Description field is used to enter a short description of what was acquired.
- flsa
- Optional reference to First Line Support Agreement — The first line support agreement linked to this invoice.
-
This field cannot be specified in the ?fields= parameter.
- id
- Readonly integer — The unique ID of the invoice.
- invoice_date
- Required date — The Invoice date field is used to specify the date on which the invoice was sent out by the supplier.
- invoice_nr
- Required string (max 128) — The Invoice number field is used to enter the invoice number that the supplier specified on the invoice.
- invoice_type
- Readonly string — The type of the record that is linked to the invoice. One of:
workflow,project,sla,flsa,cis,contract - po_nr
- Optional string (max 128) — The PO number field is used to enter the number of the purchase order that was sent to supplier.
- project
- Required reference to Project — The Project field is set to the project for which the costs specified in the Amount field were incurred.
-
This field cannot be specified in the ?fields= parameter.
- quantity
- Required decimal, default:
1— The Quantity field is used to enter the number of units that were acquired. - rate
- Optional integer — The Rate field is used to specify the yearly rate that should be applied to calculate the depreciation of the linked configuration items using the reducing balance (or diminishing value) method. When creating a new invoice and a value is not specified for this field, it is set to the rate of the product that the configuration items belong to.
- remarks
- Optional text (max 64KB) — The Remarks field is used to add any additional information about the contract that might prove useful.
- remarks_attachments
- Writeonly attachments The attachments used in the Remarks field.
- salvage_value
- Optional decimal — The value of this invoice at the end of its useful life (i.e. at the end of its depreciation period). When a value is not specified for this field, it is set to zero.
- salvage_value_currency
- Optional enum — The currency of the Salvage value field value of the invoice. For valid values, see the list of currencies in the Currency field of the Account API.
- sla
- Optional reference to Service Level Agreement — The service level agreement linked to this invoice.
-
This field cannot be specified in the ?fields= parameter.
- service
- Readonly reference to Service — The Service field is automatically set to the “service”:/help/service that is linked to the workflow, service level agreement, project or configuration item.
- source
- Optional string (max 30) - See source
- sourceID
- Optional string (max 128) - See source
- supplier
- Optional reference to Organization — The Supplier field is used to select the organization from which the invoice was received.
- unit_price
- Optional decimal — The Unit price field is used to enter the amount that the supplier has charged per unit that was acquired.
- useful_life
- Optional integer — The Useful life field is used to enter the number of years within which the linked configuration items are to be depreciated. When creating a new invoice and a value is not specified for this field, it is set to the useful life of the product that the configuration items belong to.
- updated_at
- Readonly datetime — The date and time of the last update of the invoice. If the invoice has no updates it contains the
created_atvalue. - workflow
- Optional reference to Workflow — The workflow linked to this invoice.
-
This field cannot be specified in the ?fields= parameter.