Invoices API

• List invoices
• Get a single invoice
• Create a invoice
• Update a invoice
• Fields

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 the fields listed below are available.

Please note When creating an invoice, depending the type of invoice you want to create, you need to specify a value for exactly one of the following fields:

• flsa_id
• sla_id
• contract_id
• project_id
• ci_ids

Once an invoice is created its type can no longer be changed. When one of the first 4 fields above is used, the reference cannot be changed. If the invoice is linked to Configuration Items one can add and remove items later, via the nested configuration items endpoint.

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

ci_ids

Only supported on create array of references to Configuration Items — The configuration items linked to be linked to the created invoice. Once the invoice has been created the linked configuration items can be managed via the nested configuration items endpoint.

This field cannot be specified in the ?fields= parameter.

contract

Readonly 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 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.

financialID

Optional string (max 128) — The unique identifier by which the invoice is known in the financial system.

flsa

Readonly 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

Readonly reference to Project — The Project linked to this invoice.

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

Readonly 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_at value.

workflow

Readonly reference to Workflow — The workflow linked to this invoice.

This field cannot be specified in the ?fields= parameter.