Usage Reports

Automatically collect usage information.

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

Endpoint on this page

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>

Don't forget! APIs must include:

1. Bearer Token - return from the login call

2. API version - {"Version": "V0"}

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

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

{
  "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"
  }
}

Response

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

Schema

Term	Type	Description	Example
timestamp*	String	Date and time. Standard time format "ISO 8601"	2024-02-05T19:03:39.784Z
customer_ref*	String	The ID of the related customer	eaa65954-9eb7-4246-a96c-7f6bc3aac42f
usage_product_ref*	String	The ID of the related usage product	94434ff8-8537-4f72-a5df-a45cca271544
quantity*	String	Usage quantity	10
additional_report_data	String	Key-value set for the usage report use. Will added as a new column in the report.	{ "note": "User-specific note" }
validations	String	Validate the usage event match the related document properties: Currency, Entity reference	USD 27db2a0c-a11f-4b2e-bfab-8032d0a5a7a1

Response Schema

Term	Type	Description	Example
event_ref	String	Event reference	d1d3416c-0b33-479e-a42f-dbb74effd290
related_document_ref	String	The ID of the related document (Invoice, Credit, Debit)	fffb529d-e5ad-4d87-b1e5-fa5085a675b5
related_document_numbers	String	Related document numbers	US-INV-1234

Report Formatted Usage

POST https://api.received.ai/api/usage/event/formatted

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

Response

{
  "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"
  }
}

Request Schema

Term	Type	Description	Example
format_name*	String	Look for the relevant format if ref is undefined	Default Format
event*	String	Any key value pair that will be processed by the format

Response Schema

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

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.

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

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

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.

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

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

Response

Updated usage event

Delete Usage Event

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