Fetch usage processing status

This topic is about Metered usage V2. Marketplaces use the Metered usage V1 API, Metered usage V2 API, or both, to support metered usage billing. See also: Metered usage V1.

Description: Retrieve the status of metered usage events submitted with Billing Usage v2 requests (see Send preconfigured metered usage and Send preconfigured and custom metered usage). To do so, reference the response for the Billing Usage v2 request and either

• use the unique, preformatted URL provided in the response
• insert the requestId, which uniquely identifies the request and events submitted with it, from the response, in this endpoint

Endpoint URL: {base marketplace URL}/api/integration/v2/billing/usage/requests/{requestId}

The {base marketplace URL} is the base URL for the marketplace that hosts the user account.

Request operation: GET

Mandatory parameters in the request:

• requestId—Unique system-assigned identifier for the API request used to submit the metered usage; returned with the Billing Usage v2 submission response.

Response

The response includes, but is not limited to, the following information:

• status—Status of the call
• totalUsagesCount—Number of usage events submitted
• processedUsagesCount—Number of usage events for which processing was successful
• failedUsagesCount—Number of usage events for which processing failed
• failedUsages—An array of failed usage events with event identifiers, error codes, and error descriptions

The statuses are defined as follows:

• Successful—Processing for all preconfigured and custom pricing usage events sent with the request was successful
• Failed—Processing for at least one preconfigured and custom pricing usage event sent with the request failed
• Ready—Volume pricing usage events were saved, ready for processing at the end of the billing period when the total volume is rated
• Processing—Event processing is in progress

Response examples

The following JSON response examples are for calls made to fetch the status of metered usage events for the following request identifiers:

• 8153589e-f024-477e-96af-1a8fe12a33c7
• 8153589e-f024-477e-96af-1a8fe12a33c8
• 8153589e-f024-477e-96af-1a8fe12a33c9
• 8153589e-f024-477e-96af-1a8fe12a33d0

Response Example 1

In this scenario, 11 events were sent. The request status is SUCCESSFUL because processing for all the events was successful.

{
  "requestId": "8153589e-f024-477e-96af-1a8fe12a33c7",
  "idempotencyKey": "1234567ABCDEFG",
  "status": "SUCCESSFUL",
  "totalUsagesCount": "11",
  "processedUsagesCount": "11",
  "failedUsagesCount": "0",
  "failedUsages":[]
}

Response Example 2

In this scenario, 11 events were sent. The request status is FAILED because processing for two of the 11 events failed. The errorDescription provides an explanation for the failures.

{
  "requestId" : "8153589e-f024-477e-96af-1a8fe12a33c8",
  "idempotencyKey" : "1234567ABCDEFH",
  "status" : "FAILED"
  "totalUsagesCount": 11,
  "processedUsagesCount": 9,
  "failedUsagesCount": 2,
  "failedUsages": [
    {
      "accountId": “123”,
      "eventId":"19eaa1cdab86766021e94b70a262d12543544ebdf4956bf14fce63d4da6e2b50",
      "errorCode": "BAD_DATA",
      "errorDescription" : "Usage Submitted has a timestamp outside of the billing period on the Subscription"
    },
    {
      "accountId": “1234”,
      "eventId":"19eaa1cdab86766021e94b70a262d12543544ebdf4956bf14fce63d4da6e2b51",
      "errorCode": "BAD_DATA",
      "errorDescription" : "Usage Submitted has a timestamp outside of the billing period on the Subscription"
    }
  ]
}

Response Example 3

In this scenario, two events were sent. The request status is FAILED because processing for both events failed. The errorDescription provides an explanation for the failures.

{
  "requestId" : "8153589e-f024-477e-96af-1a8fe12a33c7",
  "idempotencyKey" : "1234567ABCDEFI",
  "status" : "FAILED"
  "totalUsagesCount": 2,
  "processedUsagesCount": 0,
  "failedUsagesCount": 2,
  "failedUsages": [
    {
      "accountId": “12345”,
      "eventId":"19eaa1cdab86766021e94b70a262d12543544ebdf4956bf14fce63d4da6e2b52",
      "errorCode": "BAD_DATA",
      “errorDescription”: “Usage submitted after 6 PM UTC on the last day of billing period. Cut off to submit usage for Volume based rating is breached. Usage submitted for this request is discarded.”,
    },
    {
      "accountId": “123456”,
      "eventId":"19eaa1cdab86766021e94b70a262d12543544ebdf4956bf14fce63d4da6e2b53",
      "errorCode": "BAD_DATA",
      “errorDescription”: “Usage submitted after 6 PM UTC on the last day of billing period. Cut off to submit usage for Volume based rating is breached. Usage submitted for this request is discarded.”
    }
  ]
}

Response Example 4

In this scenario, five volume pricing events were sent. The request status is READY because all the events were saved for processing at the end of the billing period.

{
  "requestId": "8153589e-f024-477e-96af-1a8fe12a33d0",
  "idempotencyKey": "1234567ABCDEFJ",
  "status": "READY",
  "totalUsagesCount": "5",
  "processedUsagesCount": "5",
  "failedUsagesCount": "0",
  "failedUsages":[]
}