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.

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.

Use the following endpoint and sample request body to post a usage event:

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

Request

1
2
3
4
5
6
7
8
9
10
11
12
13
{
    "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": []
}

Parameters

• mode* — the mode of usage events. Possible values are FAIL_ON_EXISTING and OVERWRITE_ON_EXISTING.

• start_time* — the date and time when the usage event starts.

• end_time — the date and time when the usage event ends.

• service_resource_identifier* — the unique identifier associated with a service that is used to show where the service is located in a service hierarchy. For products these usually represent license IDs, GUIDs, or installation keys. It is a unique identifier referencing the end customer within the Gotransverse customers systems. Usage Rules use SRIDs to load usage into the system.

• usage_uom* — defines the usage duration unit of measurement. Usage Duration UOM is used within usage events, usage rules, usage discount schedules, and other areas related to usage. Possible values are the following: MILLISECOND, SECOND, MINUTE, HOUR, DAY, WEEK, EVENT, BYTE, KILOBYTE, MEGABYTE, GIGABYTE, TERABYTE, COUNT, BITS_PER_SECOND, KILOBITS_PER_SECOND, MEGABITS_PER_SECOND, GIGABITS_PER_SECOND, CURRENCY, WATT, KILOWATT, MEGAWATT, GIGAWATT, WATTS_PER_HOUR, KILOWATTS_PER_HOUR, MEGAWATTS_PER_HOUR, GIGAWATTS_PER_HOUR.

• usage_amount* — the number of measured items used by the customer during the billing period for which a calculated charge will be levied.

• reference_id — can be set from an external system and should be a unique value. The combination of reference_id and sequence_id is unique and is used to ensure that duplicate usage events are not posted.

• sequence_id — can be set from an external system and should be a unique value. The combination of reference_id and sequence_id is unique and is used to ensure that duplicate usage events are not posted. For example, if the customer sends an hourly group of usage events, it is common that the reference_id is the name with timestamp of the usage event group, and the sequence_id is a running number within this group (reference_id).