Usage Events

Usage events are data records which represent usage or consumption by a given account or service ID. For example, a service that supplies 100 calls per bill cycle may log each call as a usage event to be tracked. Usage events can only be posted once the usage rules and service identifiers are set up. These can be added via the API by including the following in the request body: start time, end time, unit of measure, usage amount, reference ID and sequence IDs.

If needed, you can also add the usage_field_names parameter associated with given lookup or rate tables. For example, when creating a usage rule on order item (Formula, operator=Lookup), we added the following usage_field_name: NUMBER05. When you add this parameter to the request payload when posting events, only usage associated with this field will be posted.

You can perform the following actions on usage events:

In UI 2.0, you can also view, edit, and void existing usage events. For more details, refer to Pending Charges.

Posting Usage Events

The Gotransverse API provides a way to post up to fifty usage events in a single call. In the request body, indicate the mode of posting usage events (FAIL_ON_EXISTING, OVERWRITE_ON_EXISTING) and details about the usage event that is to occur.

Note: If you post a usage event in the OVERWRITE_ON_EXISTING mode with the same sequence and reference ID as that of an already posted event, the latter will be automatically voided. Sequence and reference ID values cannot duplicate in posted usage events. If you override the updated posted usage event again by posting a new event with identical sequence and reference IDs, the overridden usage event will also be voided. Later, when you retrieve voided usage events by sequence and reference IDs, two voided usage events with the same sequence and reference ID values will return.

To post a usage event, use the following endpoint and sample request body:

POST https://example.gotransverse.com/billing/2/usage-events/bulk

Request

{
  "mode": "FAIL_ON_EXISTING",
  "usage_events": [
  {
      "start_time": "2018-12-25",
	  "service_resource_identifier": "12345",
	  "usage_uom": "DAY",
	  "usage_amount": 20,
	  "reference_id": "1",
	  "sequence_id": "3"
  }
  ]
}

Response

{
  "rated_events": [
  {
      "id": "1006410042",
	  "total_charge": 2000,
	  "start_time": "2018-12-25T00:00:00-06:00",
	  "end_time": "2018-12-24T06:22:24-06:00",
	  "service_resource_identifier": "12345",
	  "usage_uom": "DAY",
	  "usage_amount": 20,
	  "reference_id": "1",
	  "sequence_id": "3",
	  "request_id": "9b6bc730-e26a-4fa4-a5da-745d498ab4e9",
	  "event_charges": [
	  {
	      "id": "1008000057",
		  "charge": 2000,
		  "usage_rule": {
		      "id": "142866894"
		   },
	     "charge_category": {
		     "charge_category_type": "usage-charge",
			 "id": "4314",
			 "name": "usage charge y"
		 },
		"usage_uom": "DAY",
		"usage_amount": 20
	}
	],
	"service_period": {
    	"id": "637204734"
	},
	"overwrite_counter": 0
	}
	],
  "erred_events": []
}

Simulate Posting Usage Events

You can simulate a process of creating one or more usage events in a bulk process. It provides a way to preview the event charges before posting the actual usage event. The simulate process executes the full rating logic for a usage event, however, it does not persist the event in the GTV platform, meaning simulated events won’t be displayed on the billing account balance.

To simulate posting a usage event, use the following endpoint and sample request body:

POST https://example.gotransverse.com/billing/2/usage-events/simulate/bulk

Request

{
  "mode": "FAIL_ON_EXISTING",
  "usage_events": [
  {
      "start_time": "2018-12-25",
	  "service_resource_identifier": "12345",
	  "usage_uom": "DAY",
	  "usage_amount": 20,
	  "reference_id": "1",
	  "sequence_id": "3"
  },
  {
      "start_time": "2019-01-24",
	  "service_resource_identifier": "12345",
	  "usage_uom": "DAY",
	  "usage_amount": 35,
	  "reference_id": "2",
	  "sequence_id": "4"
  }
  ]
}

Response

{
  "rated_events": [
  {
      "id": "1006660021",
	  "total_charge": 2000,
	  "start_time": "2018-12-25T00:00:00-06:00",
	  "end_time": "2019-01-24T04:34:05-06:00",
	  "service_resource_identifier": "12345",
	  "usage_uom": "DAY",
	  "usage_amount": 20,
	  "reference_id": "1",
	  "sequence_id": "3",
	  "event_charges": [
	  {
	    "id": "1008430023",
		"charge": 2000,
		"usage_rule": {
			"id": "142866894"
		},
		"charge_category": {
		    "charge_category_type": "usage-charge",
		    "id": "4314",
			"name": "usage charge y"
		},
		"usage_uom": "DAY",
		"usage_amount": 20
		}
		],
	"service_period": {
		"id": "637204734"
	},
	"overwrite_counter": 0
   },
   {
	"id": "1006660022",
	"total_charge": 3500,
	"start_time": "2019-01-24T00:00:00-06:00",
	"end_time": "2019-01-24T04:34:05-06:00",
	"service_resource_identifier": "12345",
	"usage_uom": "DAY",
	"usage_amount": 35,
	"reference_id": "2",
	"sequence_id": "4",
	"event_charges": [
	{
		"id": "1008430024",
		"charge": 3500,
		"usage_rule": {
			"id": "143443790"
		},
		"charge_category": {
			"charge_category_type": "usage-charge",
			"id": "4314",
			"name": "usage charge y"
		},
		"usage_uom": "DAY",
		"usage_amount": 35
		}
		],
	"service_period": {
		"id": "637204736"
	},
	"overwrite_counter": 0
	}
    ],
	"erred_events": []
}

Retrieving Posted Usage Events

With API 2.0, you can view existing usage events you previously posted. You can retrieve desired usage events by ID or by using available query parameters. You can also view posted usage events in the Pending Charges tab in UI 2.0.

To retrieve a posted usage event by ID, use the following endpoint:

POST https://example.gotransverse.com/billing/2/usage-events/bulk-void

Note: A usage event ID displays in the response body when you post a usage event.

You can also retrieve a usage event using available query parameters. The endpoint above does not support an empty parameter set; you must use the following required parameters or a combination of them:

service_period_id The ID of the associated service period.
reference_id The associated reference ID entered when posting a usage event.
request_id The unique identifier generated by Gotransverse that displays in the response body when you post a usage event.
account_num
AND
closed
The associated account number to which the usage was posted.
Indicates whether the associated service period is billed. Possible values are true or false.
billing_account_id
AND
closed
The ID of the associated billing account to which the usage was posted.
Indicates whether the associated service period is billed. Possible values are true or false.

For example:

GET https://example.gotransverse.com/billing/2/usage-events?account_num=8883&closed=false GET https://example.gotransverse.com/billing/2/usage-events?service_period_id=1113