Object Definitions and API Calls

This topic sets out in detail the objects that feature in the Events and Notifications framework. The relevant API calls you can use with each object are noted together with examples of object JSON schemas.

Tip: API Calls? Please see the Events, Notifications, and Integrations sections of our API Reference Docs for relevant API calls.

Event Types

Events Types cover many of the common configuration and billing objects. For each object there are three Event Types - for when the configuration or billing object is created, updated, or deleted.

API Call

To obtain a list of the Event Types currently available for configuring Notifications, you can use the List Notification Events API call:

GET https://api.m3ter.com/organizations/{orgId}/events/types

The return lists the available Event Types:

1
{
2
"events": [
3
"configuration.commitment.created",
4
"configuration.commitment.deleted",
5
"configuration.commitment.updated",
6
"configuration.account.created",
7
"configuration.account.deleted",
8
"configuration.account.updated",
9
"configuration.aggregation.created",
10
"configuration.aggregation.deleted",
11
"configuration.aggregation.updated",
12
"configuration.compoundaggregation.created",
13
"configuration.compoundaggregation.deleted",
14
"configuration.compoundaggregation.updated",
15
"configuration.meter.created",
16
"configuration.meter.deleted",
17
"configuration.meter.updated",
18
"configuration.metergroup.created",
19
"configuration.metergroup.deleted",
20
"configuration.metergroup.updated",
21
"configuration.plan.created",
22
"configuration.plan.deleted",
23
"configuration.plan.updated",
24
"configuration.plantemplate.created",
25
"configuration.plantemplate.deleted",
26
"configuration.plantemplate.updated",
27
"configuration.plangroup.created",
28
"configuration.plangroup.deleted",
29
"configuration.plangroup.updated",
30
"configuration.plangrouplink.created",
31
"configuration.plangrouplink.deleted",
32
"configuration.plangrouplink.updated",
33
"configuration.pricing.created",
34
"configuration.pricing.deleted",
35
"configuration.pricing.updated",
36
"configuration.product.created",
37
"configuration.product.deleted",
38
"configuration.product.updated",
39
"configuration.accountplan.created",
40
"configuration.accountplan.deleted",
41
"configuration.accountplan.updated",
42
"configuration.pricingband.created",
43
"configuration.pricingband.deleted",
44
"configuration.pricingband.updated",
45
"configuration.organization.created",
46
"configuration.organization.deleted",
47
"configuration.organization.updated",
48
"configuration.customfield.created",
49
"configuration.customfield.deleted",
50
"configuration.customfield.updated",
51
"configuration.organizationconfig.created",
52
"configuration.organizationconfig.deleted",
53
"configuration.organizationconfig.updated",
54
"configuration.contract.created",
55
"configuration.contract.deleted",
56
"configuration.contract.updated",
57
"configuration.creditreason.created",
58
"configuration.creditreason.deleted",
59
"configuration.creditreason.updated",
60
"configuration.transactiontype.created",
61
"configuration.transactiontype.deleted",
62
"configuration.transactiontype.updated",
63
"billing.bill.created",
64
"billing.bill.deleted",
65
"billing.bill.updated",
66
"billing.billconfig.created",
67
"billing.billconfig.deleted",
68
"billing.billconfig.updated",
69
"billing.billjob.created",
70
"billing.billjob.deleted",
71
"billing.billjob.updated",
72
"billing.balance.created",
73
"billing.balance.deleted",
74
"billing.balance.updated"
75
]
76
}

Event Fields

Fields are available for each Event Type to make any calculations on the schema dynamic and forward compatible.

API Call

To obtain a list of the fields for an Event Type, you can use the List Events call:

GET https://api.m3ter.com/organizations/{orgId}/events/fields

Query Parameters

eventName (String) - the name of the Event Type to filter by.

Here we've queried to get the field for the configuration.commitment.created Event Type - new represents the attributes the new object has:

1
{
2
"events": {
3
"configuration.commitment.created": {
4
"new.accountCode": "string",
5
"new.accountId": "string",
6
"new.accountingProductId": "string",
7
"new.amount": "double",
8
"new.amountFirstBill": "double",
9
"new.amountPrePaid": "double",
10
"new.amountSpent": "double",
11
"new.billEpoch": "string",
12
"new.billingInterval": "int",
13
"new.billingOffset": "int",
14
"new.billingPlanId": "string",
15
"new.commitmentFeeBillInAdvance": "boolean",
16
"new.commitmentFeeDescription": "string",
17
"new.commitmentUsageDescription": "string",
18
"new.contractId": "string",
19
"new.currency": "string",
20
"new.customFields": "map",
21
"new.endDate": "string",
22
"new.feeDates": "array",
23
"new.id": "string",
24
"new.overageDescription": "string",
25
"new.overageSurchargePercent": "double",
26
"new.productIds": "array",
27
"new.startDate": "string"
28
}
29
}
30
}

Here we’ve queried to get the fields for the configuration.commitment.updated Event Type, where new is the updated object and old is the previous state of the object:

1
{
2
"events": {
3
"configuration.commitment.updated": {
4
"new.accountCode": "string",
5
"new.accountId": "string",
6
"new.accountingProductId": "string",
7
"new.amount": "double",
8
"new.amountFirstBill": "double",
9
"new.amountPrePaid": "double",
10
"new.amountSpent": "double",
11
"new.billEpoch": "string",
12
"new.billingInterval": "int",
13
"new.billingOffset": "int",
14
"new.billingPlanId": "string",
15
"new.commitmentFeeBillInAdvance": "boolean",
16
"new.commitmentFeeDescription": "string",
17
"new.commitmentUsageDescription": "string",
18
"new.contractId": "string",
19
"new.currency": "string",
20
"new.customFields": "map",
21
"new.endDate": "string",
22
"new.feeDates": "array",
23
"new.id": "string",
24
"new.overageDescription": "string",
25
"new.overageSurchargePercent": "double",
26
"new.productIds": "array",
27
"new.startDate": "string",
28
"old.accountCode": "string",
29
"old.accountId": "string",
30
"old.accountingProductId": "string",
31
"old.amount": "double",
32
"old.amountFirstBill": "double",
33
"old.amountPrePaid": "double",
34
"old.amountSpent": "double",
35
"old.billEpoch": "string",
36
"old.billingInterval": "int",
37
"old.billingOffset": "int",
38
"old.billingPlanId": "string",
39
"old.commitmentFeeBillInAdvance": "boolean",
40
"old.commitmentFeeDescription": "string",
41
"old.commitmentUsageDescription": "string",
42
"old.contractId": "string",
43
"old.currency": "string",
44
"old.customFields": "map",
45
"old.endDate": "string",
46
"old.feeDates": "array",
47
"old.id": "string",
48
"old.overageDescription": "string",
49
"old.overageSurchargePercent": "double",
50
"old.productIds": "array",
51
"old.startDate": "string"
52
}
53
}
54
}

Note that in contrast to a new Event, an updated Event contains fields for both new and old values, where the old field values are those from the previous version and new are the updated version values.

Correspondingly, if you query for configuration.commitment.deleted Event, the response will show only old field values, which are the values at point of deletion.

Events

Events are instances of available Event Types. They describe a state change in the system.

API Call

You can use the List Event Response call to obtain a list of all Events and apply a filter or GET by id.

Query Parameters

  • eventName (String) -  the name of the event to filter by.

  • notificationId (String) -  the notification id to filter by.

  • accountId (String) -  the account Id that generated the event to filter by.

  • eventType (String) -  the name of the event to filter by.

  • notificationCode (String) -  the code of the notification to filter by.

  • resourceId (String) -  the id of the resource that triggered the event  to filter by.

  • ids(String) -  List of ids to filter by. NOTE: cannot be used with other filters.

  • nextToken (String) -  next page token.

  • pageSize (int) - page size.

For example, if we query by eventName:

GET https://api.m3ter.com/organizations/{orgId}/events?eventName=configuration.commitment.created

In this example, we see that there is a single configuration.commitment.created Event for the Organization:

1
{
2
"data": [
3
{
4
"id": "9cb46d85-7cb6-4637-80a1-d4ec38e4ab30",
5
"eventName": "configuration.commitment.created",
6
"eventTime": "2022-10-28T13:54:49.557Z",
7
"m3terEvent": {
8
"eventData": {
9
"newDto": {
10
"commitmentFeeDescription": "",
11
"endDate": "2024-12-31",
12
"billingInterval": 1,
13
"orgId": "396d788d-5174-XXXX-9d69-YYYY4671fc33",
14
"overageSurchargePercent": 5.0,
15
"overageDescription": "",
16
"currency": "USD",
17
"id": "480d317e-2030-416b-b64b-c07577c418b4",
18
"amountSpent": 0.0,
19
"accountCode": "doetech_premium",
20
"amount": 15000.0,
21
"billingOffset": 0,
22
"lastModifiedBy": "USER_810e3a43-XXXX-4dab-YYYY-470977405b58",
23
"billingPlanId": "0409e75a-8a87-43de-aa58-fc6ec823ce37",
24
"version": 1,
25
"accountId": "1cf2a754-476c-498c-b05a-7d41abfc404d",
26
"dtCreated": "2022-10-28T13:54:48.081781Z",
27
"amountPrePaid": 0.0,
28
"productIds": [
29
"bec371ef-dbad-4e73-a56a-dadecff2287c"
30
],
31
"createdBy": "USER_810e3a43-XXXX-4dab-YYYY-470977405b58",
32
"contractId": "68595d6d-261f-496b-bf88-51fc7d2b5ccc",
33
"commitmentUsageDescription": "",
34
"startDate": "2023-01-01",
35
"dtLastModified": "2022-10-28T13:54:48.081781Z"
36
}
37
},
38
"eventTime": "2022-10-28T13:54:48.087Z",
39
"eventName": "configuration.commitment.created"
40
}
41
}
42
],
43
"nextToken": "MTY2MDMxNTYyNjQ1NCNERUxJTSNhNTIxMDQ0Zi0zMzA0LTQ0ZjEtYTBkYy05YzQyMjIzZGFhMWE="
44
}

Notification Configuration

Enables you to set up the rules for when a Notification gets triggered on the basis of an Event.

API Calls

You can use the API calls documented in the Notifications section of our API Reference Docs - supports POST, PUT, DELETE, GET by id, or GET list verbs.

Here's an example Notification Configuration schema:

1
{
2
"id": "uuid",
3
"version": 1,
4
"name": "Commitment has under 10% remaining",
5
"description": "Commitment amount fell below 10%",
6
"eventName": "configuration.commitment.updated",
7
"calculation": "(new.amountSpent >= ((new.amount*100)/90)) AND
8
((old.amountSpent <= ((old.amount*100)/90)) OR (old.amountSpent == null))",
9
"code" : "under_10_percent",
10
"active": true
11
}

Some points to note for the Notification Configuration schema:

  • calculation - is the key part, determining whether or not an Event will trigger a Notification. Please see the Creating Calculations section for more details on working with calculations for Notifications.

  • active - allows you to temporarily disable a Notification Configuration.

  • eventName - the calculation will be applied only on these specific events. To apply the same calculation over multiple events, multiple notification configurations need to be created.

Integration Destination and Credentials

You can specify the endpoint as destination for the Notification Integration, which is a webhook.

NOTE: Currently only Webhooks are supported as Notification destinations. More destination types for Notifications are planned for the near future.

You can also specify credentials to be used with the Integration destination. Currently, only the M3TER_SIGNED_REQUEST credential format is supported:

  • apiKey - secret that will always be passed in “X-m3ter-apikey” header when the webhook is called.

  • Secret - secret that never leaves m3ter servers. Used as key to compute a SHA256 hash over: url + "|" + queryString + "|" + apiKey + "|"  + timestamp + "|" + body.

  • The timestamp will be passed in the request at “X-m3ter-timestamp”.

API Calls

You can use the webhooks Destination calls documented in the Integrations section of our API Reference Docs - supports all POST, PUT, DELETE, GET by id or GET list verbs. For example Create Webhook Destination:

POST https://api.m3ter.com/organizations/{orgId}/integrationdestinations/webhooks

Here's an example of the Destination schema:

1
{
2
"version": null,
3
"url":"https://someurl.io",
4
"credentials": {
5
"version": null,
6
"type": "M3TER_SIGNED_REQUEST",
7
"apiKey": "apiKey",
8
"secret": "a secret" // Only visible in first call
9
}
10
}

Important! As a security safeguard, you won’t be able to retrieve the secret once you’ve saved the credential.

Integration Configuration

You can set up an Integration Configuration which connects the Notification Configuration of entityType (=’Notification’) to the corresponding destination (only Webhooks are currently supported).

API Calls

You can use the IntegrationConfig calls documented in the Integrations section of our API Reference Docs - supports all POST, PUT, DELETE, GET by id or GET list verbs.

Next: Example - Commitment Updated Event