In this topic:

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.

How to post 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. 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": []
}

How to simulate posting a bulk of 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 simulated events won’t be displayed on the billing account balance. 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": []
}

How to void a bulk of usage events

The Billing API provides a way to void up to fifty usage events in a single bulk action. To void specific usage events, indicate ID values of the usage events or associated sequence and reference IDs depending on the selected mode—“BY_ID” or “BY_REF_SEQ”.

Note: You can only void events that haven’t been billed yet.

Use the following endpoint and sample request body:

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

Request

{
  "mode": "BY_ID",
  "void_event_criterias": [
  {
      "id": "1006660724"
  },
  {
      "id": "1006660725"
  }
]
}

Response

{
  "num_voided": 2,
  "voided_event_criterias": [
  {
    "id": "1006660724"
  },
  {
    "id": "1006660725"
  }
  ],
 	"erred_event_criterias": []
  }
Top