Voided Usage Events

You can void posted usage events with API 2.0, UI 2.0, or by voiding a Usage File in UI 1.0. Voiding a usage event removes a usage event record from the list of posted usage events. After you void a usage event, associated charges will not be billed to the billing account. Usage events cannot be reinstated after being voided.

Gotransverse API provides a way to void up to fifty usage events in a single bulk action. You can only void events that haven’t been billed yet.

Note: Usage that has been processed by SVS cannot be voided.

Voided usage events are only retained in the platform if the Enable Retention of Voided Usage Event system setting is set to True prior to voiding usage events. With the system setting set to True, via API 2.0, a user can retrieve voided usage events from the platform.

Voiding Usage Events

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.

To void a usage event, use the following endpoint and sample request bodies:

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

Retrieving Voided Usage Events

After you void a usage event, you can retrieve associated records and charges by voided event ID or a combination of sequence and reference IDs. It provides a way to track the audit history of voided usage events. For example, the records include who voided the usage and the date it was voided. It also may be valuable for troubleshooting billing issues that involve complex usage scenarios.

Note: Voided usage events are only retained in the platform if the Enable Retention of Voided Usage Event system setting is set to True prior to voiding usage events.

To retrieve records of the voided usage events:

  • Retrieve the voided usage events by ID or sequence and reference IDs:
    • Add sequence_id and reference_id query parameter values that you entered when posting a usage event:
      GET https://example.gotransverse.com/billing/2/usage-events/voided?sequence_id={seq_id}&reference_id={ref_id}
    • Add the ID of the voided usage event as a path or query parameter. You can find the voided usage event ID in the database or in the response after you retrieved a voided usage event by sequence and reference IDs.
      GET https://example.gotransverse.com/billing/2/usage-events/voided?id={voided_usage_event_id}
      GET https://example.gotransverse.com/billing/2/usage-events/voided/{id}

No matter what parameters you use to retrieve information about voided usage records such as reference and sequence IDs, or, ID of the voided usage event as a query or path parameter, the response always includes the same set of fields.

Every usage event is associated with a unique combination of sequence and reference ID values. However, if you post a usage event with the OVERWRITE_ON_EXISTING mode with the same sequence and reference IDs as ones of already posted event, the latter will be automatically voided. If you override the updated posted usage event again by posting a new one with identical sequence and reference IDs, the overridden usage event will also be voided and when you retrieve a voided usage event by sequence and reference IDs, two voided usage events with the same sequence and reference ID values will return. For more details and payloads, refer to an example.

Example

In this example, we post and void a usage event with the same reference and sequence IDs three times, then retrieve all voided usage event records.

Note: Although, the sequence and reference values of these voided events are identical, each voided event gets its own ID value once voided.

The usage event is sent in the FAIL_ON_EXISTING mode, so you have to void a usage event before sending the one with identical sequence and reference IDs. Otherwise, sending an event with the same sequence and reference ID values will fail. If the usage event with already existing sequence and reference IDs is posted in the OVERWRITE_ON_EXISTING mode, the older usage event will be automatically voided. The voided record will be stored if the Enable Retention of Voided Usage Event system setting is set to True prior to voiding.

  1. Post a usage event with the following endpoint:
    POST https://example.gotransverse.com/billing/2/usage-events/bulk

    Request

    {
      "mode": "FAIL_ON_EXISTING",
      "usage_events": [
      {
         "start_time": "2019-09-01",
    	 "service_resource_identifier": "sample#1",
    	 "usage_uom": "DAY",
    	 "usage_amount": 20,
    	 "reference_id": "void-usage1",
    	 "sequence_id": "14"
      }
    ]
    }

    Response

    {
      "rated_events": [
      {
    	"id": "1019910006",
    	"total_charge": 36000.00000000000000000000,
    	"start_time": "2019-09-01T00:00:00-05:00",
    	"end_time": "2020-08-31T05:40:06-05:00",
    	"service_resource_identifier": "sample#1",
    	"usage_uom": "DAY",
    	"usage_amount": 20,
    	"reference_id": "void-usage1",
    	"sequence_id": "14",
    	"request_id": "466e0386-6213-4b8c-ac83-9901b7771145",
    	"service_period": {
    		"id": "658554946"
    	},
    	"overwrite_counter": 0,
    	"event_charges": [
    	{
    		"id": "1020010006",
    		"charge": 36000.00000000000000000000,
    		"usage_rule": {
    			"id": "160696860"
    		},
    		"charge_category": {
    			"charge_category_type": "usage-charge",
    			"id": "3182",
    			"name": "def charge cat"
    		},
    		"usage_uom": "HOUR",
    		"usage_amount": 480,
    		"consume_prepaid_balance": false
    	}
        ]
      }
      ],
      "erred_events": []
    }
  2. Void the event we’ve just posted:
    POST https://example.gotransverse.com/billing/2/usage-events/bulk-void

    Request

    {
      "mode": "BY_REF_SEQ",
      "void_event_criterias": [
      {
    	"reference_id": "void-usage1",
    	"sequence_id": "14"
      }
    ]
    }

    Response

    {
      "num_voided": 1,
      "voided_event_criterias": [
      {
    	"reference_id": "void-usage1",
    	"sequence_id": "14"
      }
      ],
      "erred_event_criterias": []
    }
  3. Then, post and void usage events with the same sequence and reference IDs two more times.
  4. Now, retrieve all usage events with this combination of sequence and reference ID values stored in Gotransverse.

The response body includes all three voided usage events, each with its own ID and parameters but with the same combination of reference and sequence IDs.
GET https://example.gotransverse.com/billing/2/usage-events/voided?sequence_id=14&reference_id=void-usage1

Note: If you try to retrieve voided usage events by invalid or nonexistent values, the response will return as empty.