Service request invoices

Once a service request that is Quote and Perform Service, Service Only, or Unmanaged reaches the Work Complete stage, invoices can be created for the service request.

An invoice consists of:

  • A description
  • An optional reference number
  • One or more line items. Each line item consists of:
    • A monetary amount (an amount and currency)
    • A category
    • An optional description

Once an invoice has been added, it can be approved. Approving an invoice signifies that the invoice is acceptable and is ready to be paid. You can also mark an invoice as paid.

Note that there are mechanisms for suspending further work on both accepted service requests and service request invoices. But the verb used for each mechanism is different.

  • To stop further work on an accepted service request, you cancel it (or internal-cancel it).
  • To stop further work on an invoice, you withdraw it.
Note: You cannot create or update the child objects of a service request (such as service request invoices) in a composite request.

Querying for invoices

The following Claim API endpoints can be used to request information about service request invoices:

Endpoint Response
GET /claims/{claimId}/service-requests/{serviceRequestId}/invoices All invoices for the specified service request
GET /claims/{claimId}/servicerequests/{serviceRequestId}/invoices/{invoiceId} The specified invoice. Note that in order to get information about a specific invoice, you must access the invoice from its parent claim and service request.
Endpoint Response
GET /claims/{claimId}/service-requests/{serviceRequestId}/invoices All invoices for the specified service request
GET /claims/{claimId}/servicerequests/{serviceRequestId}/invoices/{invoiceId} The specified invoice. Note that in order to get information about a specific invoice, you must access the invoice from its parent claim and service request.

Creating invoices for service requests

To create an invoice for a service request, use:

  • POST /claims/{claimId}/service-requests/{serviceRequestId}/invoices

Minimum creation criteria

An invoice must have the following information:

  • A description
  • A set of one of more line items. Each line item must specify:
    • A monetary amount (with amount and currency values)
    • A category (a code from the ServiceRequestStatementLineItemCategory typelist)

The following creates an invoice for service request cc:9. The invoice contains two line items: a $150 USD charge for labor, and a $50 USD charge for parts. It also includes an optional reference number for the invoice, and optional descriptions for each line item.

POST /claim/v1/claims/demo_sample:20/service-requests/cc:9/invoices

{
  "data": {
    "attributes": {
            "description": "Invoice submitted using system APIs",
            "referenceNumber": "771-DX5667",
            "lineItems": [
              {
                "amount": {
                  "amount": "150.00",
                  "currency": "usd"
                  },
                "category": {
                  "code": "labor"
                },
                "description": "Invoiced labor"
              },
              {
                "amount": {
                  "amount": "50.00",
                  "currency": "usd"
                  },
                "category": {
                  "code": "parts"
                },
                "description": "Invoiced parts"
              }
            ]
    }
  }
}
Java

Approving service request invoices

To approve an invoice, use:

  • POST /claims/{claimId}/service-requests/{serviceRequestId}/invoices/{invoice-id}/approve

The POST invoices/{invoice-id}/approve endpoint does not require a request body.

The following approves invoice cc:06 for service request cc:9.

POST /claim/v1/claims/demo_sample:20/service-requests/cc:9/invoices/cc:6/approve

(no request body)
Java

Marking invoices as paid

To mark an invoice as paid, use:

  • POST /claims/{claimId}/service-requests/{serviceRequestId}/invoices/{invoice-id}/mark-as-paid

When an invoice is marked as paid, there must be an associated check (which was presumably used to pay the invoice). In the /mark-as-paid request payload, you must include a check attribute with the ID of the associated check. For example, the following payload marks invoice cc:6 (for service request cc:9 on claim demo_sample:20) as paid. The associated check is cc:413.

POST /claim/v1/claims/demo_sample:20/service-requests/cc:9/invoices/cc:6/mark-as-paid

{
  "data": {
    "attributes": {
        "check": {
            "id": "cc:413"
        }
    }
  }
}
Java

Note that ClaimCenter has validation rules that limit the ability to mark an invoice as paid based on the invoice's state.

Withdrawing service request invoices

To withdraw an invoice, use:

  • POST /claims/{claimId}/service-requests/{serviceRequestId}/invoices/{invoice-id}/withdraw

When withdrawing an invoice, you must specify a reason. This can be set to any string value.

When you withdraw an invoice, the invoice is flagged as withdrawn in the user interface.

The following withdraws invoice cc:06 for service request cc:9.

POST /claim/v1/claims/demo_sample:20/service-requests/cc:9/invoices/cc:6/withdraw

{
  "data": {
    "attributes": {
            "reason": "Invoice submitted in error"
    }
  }
}
Java