# Usage Reports

Received's usage API collects **usage data** from customer software. 

{% code title="Endpoint on this page" lineNumbers="true" %}

```javascript
POST https://api.received.ai/api/usage/event
POST https://api.received.ai/api/usage/event/formatted
POST https://api.received.ai/api/usage/event/update
POST https://api.received.ai/api/usage/event/formatted/update
DELETE https://api.received.ai/api/usage/event/<event_ref>
```

{% endcode %}

{% hint style="info" %}
Don't forget! APIs must include:

1. **Bearer Token** - return from the login call
2. **API version** - {"Version": "V0"}
   {% endhint %}

## Reporting Customer Usage

The usage API is built out of a **main API** (Default) and an **API add-on** (Formatted):

1. **Default Usage API -** This is the main API used to collect usage data. When a user **does not have** a customized usage format, this API will be used with no add-ons. In this scenario, the usage data will be formatted according to Received's default format.
2. **Formatted Usage API -** This API is used as an add-on when the user has created a customized usage format in the system. In this scenario, the data will be formatted according to the user's bespoke format.

### Report Default Usage

{% code lineNumbers="true" %}

```javascript
POST https://api.received.ai/api/usage/event
```

{% endcode %}

{% code lineNumbers="true" %}

```javascript
{
  "timestamp": "2024-02-06T11:37:38.872Z",
  "customer_ref": "eaa65954-9eb7-4246-a96c-7f6bc3aac42f",
  "usage_product_ref": "94434ff8-8537-4f72-a5df-a45cca271544",
  "quantity": 10,
  "additional_report_data": {
    "note": "User-specific note"
  },
  "validations": {
    "currency": "USD",
    "entity_ref": "27db2a0c-a11f-4b2e-bfab-8032d0a5a7a1"
  }
}
```

{% endcode %}

#### Response

{% code lineNumbers="true" %}

```javascript
{
  "event_ref": "d1d3416c-0b33-479e-a42f-dbb74effd290",
  "related_document_ref": "fffb529d-e5ad-4d87-b1e5-fa5085a675b5",
  "related_document_numbers": "US-INV-1234"
}
```

{% endcode %}

#### Schema

<table><thead><tr><th width="278">Term</th><th width="108">Type </th><th width="344">Description</th><th width="380">Example</th></tr></thead><tbody><tr><td><code>timestamp</code><mark style="color:red;">*</mark></td><td><mark style="color:purple;">String</mark></td><td>Date and time.<br>Standard time format "ISO 8601"</td><td>2024-02-05T19:03:39.784Z</td></tr><tr><td><code>customer_ref</code><mark style="color:red;">*</mark></td><td><mark style="color:purple;">String</mark></td><td>The ID of the related customer </td><td>eaa65954-9eb7-4246-a96c-7f6bc3aac42f</td></tr><tr><td><code>usage_product_ref</code><mark style="color:red;">*</mark></td><td><mark style="color:purple;">String</mark></td><td>The ID of the related usage product </td><td>94434ff8-8537-4f72-a5df-a45cca271544</td></tr><tr><td><code>quantity</code><mark style="color:red;">*</mark></td><td><mark style="color:purple;">String</mark></td><td>Usage quantity</td><td>10</td></tr><tr><td><code>additional_report_data</code></td><td><mark style="color:purple;">String</mark></td><td>Key-value set for the usage report use. <br>Will added as a new column in the report.</td><td><pre><code>{
    "note": "User-specific note"
}
</code></pre></td></tr><tr><td><code>validations</code></td><td><mark style="color:purple;">String</mark></td><td>Validate the usage event match the related document properties: Currency, <br> Entity reference</td><td>USD <br><br>27db2a0c-a11f-4b2e-bfab-8032d0a5a7a1 </td></tr></tbody></table>

#### Response Schema

<table><thead><tr><th width="272">Term</th><th width="97">Type</th><th width="273">Description</th><th width="344">Example</th></tr></thead><tbody><tr><td>event_ref</td><td><mark style="color:purple;">String</mark></td><td>Event reference</td><td>d1d3416c-0b33-479e-a42f-dbb74effd290</td></tr><tr><td>related_document_ref</td><td><mark style="color:purple;">String</mark></td><td>The ID of the related document (Invoice, Credit, Debit)</td><td>fffb529d-e5ad-4d87-b1e5-fa5085a675b5</td></tr><tr><td>related_document_numbers</td><td><mark style="color:purple;">String</mark></td><td>Related document numbers</td><td>US-INV-1234</td></tr></tbody></table>

### **Report Formatted Usage**

<pre class="language-javascript" data-line-numbers><code class="lang-javascript"><strong>POST https://api.received.ai/api/usage/event/formatted
</strong></code></pre>

{% code lineNumbers="true" %}

```javascript
{
  "format_name": "Default Format",
  "event": {}
}
```

{% endcode %}

#### Response

{% code lineNumbers="true" %}

```javascript
{
  "event_ref": "d1d3416c-0b33-479e-a42f-dbb74effd290",
  "related_document_ref": "fffb529d-e5ad-4d87-b1e5-fa5085a675b5",
  "related_document_numbers": "US-INV-1234",
  "related_parent_document_ref": "cb88774f-fbdd-42ef-b9eb-822e6c581ee1",
  "related_parent_document_numbers": "US-INV-12345",
  "timestamp": "2024-02-06T11:55:00.037Z",
  "customer_ref": "eaa65954-9eb7-4246-a96c-7f6bc3aac42f",
  "customer_name": "ACME",
  "usage_product_ref": "94434ff8-8537-4f72-a5df-a45cca271544",
  "usage_product_name": "Units",
  "quantity": 10,
  "additional_report_data": {
    "note": "User-specific note"
  }
}
```

{% endcode %}

#### Request Schema

| Term                                           | Type                                      | Description                                             | Example        |
| ---------------------------------------------- | ----------------------------------------- | ------------------------------------------------------- | -------------- |
| format\_name<mark style="color:red;">\*</mark> | <mark style="color:purple;">String</mark> | Look for the relevant format if ref is undefined        | Default Format |
| event<mark style="color:red;">\*</mark>        | <mark style="color:purple;">String</mark> | Any key value pair that will be processed by the format |                |

#### Response Schema

<table><thead><tr><th width="357">Term</th><th>Type </th><th width="365">Description</th><th width="363">Example</th></tr></thead><tbody><tr><td><code>event_ref</code></td><td><mark style="color:purple;">String</mark></td><td>Event reference</td><td>d1d3416c-0b33-479e-a42f-dbb74effd290</td></tr><tr><td><code>related_document_ref</code></td><td><mark style="color:purple;">String</mark></td><td>Related document reference </td><td>fffb529d-e5ad-4d87-b1e5-fa5085a675b5</td></tr><tr><td><code>related_document_numbers</code></td><td><mark style="color:purple;">String</mark></td><td>Related document numbers </td><td>US-INV-1234</td></tr><tr><td><code>related_parent_document_ref</code></td><td><mark style="color:purple;">String</mark></td><td>Related parent document reference ( In case of 'Due upon usage' return also the parent invoice)</td><td>cb88774f-fbdd-42ef-b9eb-822e6c581ee1</td></tr><tr><td><code>related_parent_document_numbers</code></td><td><mark style="color:purple;">String</mark></td><td>Related parent document numbers<br>( In case of 'Due upon usage' return also the parent invoice)</td><td>US-INV-12345</td></tr><tr><td><code>timestamp</code></td><td><mark style="color:purple;">String</mark></td><td>Date and time</td><td>($date-time)</td></tr><tr><td><code>customer_ref</code></td><td><mark style="color:purple;">String</mark></td><td>Customer reference</td><td>eaa65954-9eb7-4246-a96c-7f6bc3aac42f</td></tr><tr><td><code>customer_name</code></td><td><mark style="color:purple;">String</mark></td><td>Customer name</td><td>Acme</td></tr><tr><td><code>usage_product_ref</code></td><td><mark style="color:purple;">String</mark></td><td>Usage product reference</td><td>94434ff8-8537-4f72-a5df-a45cca271544</td></tr><tr><td><code>usage_product_name</code></td><td><mark style="color:purple;">String</mark></td><td>Usage product type<br> (Look for the relevant usage product if ref is undefined</td><td>Units</td></tr><tr><td><code>quantity</code></td><td><mark style="color:purple;">Number</mark></td><td>Quantity </td><td>10</td></tr><tr><td><code>additional_report_data</code></td><td><mark style="color:purple;">String</mark></td><td>Additional data<br>(User-specific note)</td><td>OrderedMap</td></tr></tbody></table>

## Explore More APIs

### Edit Usage Event

Updating usage events via API by specifying date, quantity, or additional information allows for real-time adjustments to consumption records, ensuring accurate billing and a transparent overview of service utilization for both providers and clients.

{% code lineNumbers="true" %}

```javascript
POST https://api.received.ai/api/usage/event/update
```

{% endcode %}

{% code lineNumbers="true" %}

```javascript
{
  "event_ref": "ccd65954-0eb7-5246-a96c-7f6kc3atc42g"
  "timestamp": "2024-02-06T11:37:38.872Z",
  "quantity": 10,
  "additional_report_data": {
    "note": "User-specific note"
  }
}
```

{% endcode %}

#### Response

Updated usage event

### Edit Formatted Usage Event

Applying changes to usage events via API according to some format, by adjusting attributes like date, quantity, or ancillary data, enables dynamic updates to loosely defined entities, fostering flexibility in managing and reflecting real-world variations in service or product usage.

{% code lineNumbers="true" %}

```javascript
POST https://api.received.ai/api/usage/event/formatted/update
```

{% endcode %}

{% code lineNumbers="true" %}

```javascript
{
  "event_ref": "ccd65954-0eb7-5246-a96c-7f6kc3atc42g",
  "format_name": "Default Format",
  "event": {}
}
```

{% endcode %}

#### Response

Updated usage event

### Delete Usage Event

```javascript
DELETE https://api.received.ai/api/usage/event/<event_ref>
```