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 datetime — 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
change
Optional reference to Change — The change linked to this invoice.
contract
Optional reference to Contract — The contract linked to this invoice.
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 Depreciated
  • double_declining_balance: Double Declining Balance
  • reducing_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 Level Support Agreement — The first line support agreement linked to this invoice.
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: change, 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.
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 ivoice.
service
Readonly reference to Service — The Service field is automatically set to the “service”:/help/service that is linked to the change, 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_at value.