What are usage lookup tables?

Usage lookup tables are used to simplify usage rule specifications by moving commonly referenced information into a table accessible by the rule. A lookup table consists of lookup entries used for grouping the charge information. Once you have added the desired table entries, activate the table so that it can be used.

Creating lookup tables

To create a new lookup table, use the sample request body and endpoint below:

POST https://example.gotransverse.com/billing/2/usage-lookup-tables

Request

{
  "name": "lookup table #1",
  "description": "sample lookup table for usage rules"
}

Response

{
  "id": "380",
  "name": "lookup table #1",
  "status": "DRAFT",
  "description": "sample lookup table for usage rules"
}

Activating lookup tables

To use your lookup table, you must activate it:

POST https://example.gotransverse.com/billing/2/usage-lookup-tables/{id}/activate

Note: You can activate a rate table only is it has at least one lookup table entry.

Retrieving available lookup tables

To retrieve the specified lookup table by ID:

GET https://example.gotransverse.com/billing/2/usage-lookup-tables/{id}

To retrieve a list of available lookup tables:

GET https://example.gotransverse.com/billing/2/usage-lookup-tables

Updating lookup tables

To update the usage lookup table, specify new values in the request body as detailed below:

PUT https://example.gotransverse.com/billing/2/usage-lookup-tables/{id}

Request

{   
  "name": "updated lookup table #1"
}

Response

{
  "id": "380",
  "name": "updated lookup table #1",
  "status": "ACTIVE",
  "description": "sample lookup table for usage rules"
}

Suspending lookup tables

To suspend the usage lookup table, use the following endpoint:

POST https://example.gotransverse.com/billing/2/usage-lookup-tables/{id}/suspend

Once you have moved the lookup table to the Suspended status, it won’t be available for use, but you activate it when needed.

Deleting lookup tables

To delete the lookup table that you no longer need, use the following endpoint:

DELETE https://example.gotransverse.com/billing/2/usage-lookup-tables/{id}

Note: Once deleted, you cannot recover this lookup table.

Creating lookup table entries

Lookup table entries are key-value pairs associated with a certain lookup table. Use lookup entries to configure usage rules of the following type: specification=Formula, operator=lookup. Add as many lookup table entries as you need with either single or multiple values.

You can manage either one or several lookup table entry values in one API request. The Lookup Table Processing Mode system setting controls how lookup table entry values are processed:

Note: You cannot edit the configuration of the Lookup Table Processing Mode system setting. If you need to change it, please contact GTV support.

  • If the system setting is set to MULTI, the standard GET API call will return both the value and the multi_value fields.
  • If the system setting is set to SINGLE, by default, only one value for the lookup table entry is returned from the standard GET API call. However, you can still return multiple entry values by using the expand query parameter: POST /usage-lookup-tables/{id}/entries?expand=multi_value The request can include either value or multi_value field.

    Note: This option is deprecated and is available for backwards compatibility only. We recommend switching to the MULTI option. Contact GTV Support for details.

Adding a single lookup table entry value

To add a single value to the lookup table entry with the Lookup Table Processing Mode system setting set to SINGLE, in the response body, enter the entry key, value that you want to add, date when the entry becomes valid, and run the following endpoint.

POST https://example.gotransverse.com/billing/2/usage-lookup-tables/{id}/entries

Request

{
  "key": "Office Furniture Color",
  "value": "White",
  "valid_from": "2020-12-07T13:34:58.698Z"
}

Response

{
  "id": "26522",
  "key": "Office Furniture Color",
  "value": "White",
  "valid_from": "2020-12-07T07:34:58-06:00",
  "valid_to": null
}

To add a single value with the Lookup Table Processing Mode system setting set to MULTI, add a value within the multi_value object:

{
    "key": "Available Colors",
    "multi_value": {
        "value": "Ivory"
    },
    "valid_from": "2018-01-01T01:00:00-05:00"
}

Adding multiple lookup table entry values

You can manage up to 20 values for a single entry in a usage lookup table. This can help reduce the number of lookup tables used by rules needed for usage rating processing. You can also rename the labels of all entry values to provide the context of the data column for configuring usage rules.

To add multiple values to the lookup table entry, use the following endpoint:POST /usage-lookup-tables/{id}/entries.

In the request body, enter the desired values within the multi_value object.

The following example adds a new lookup table entry with three associated values: POST https://example.gotransverse.com/billing/2/usage-lookup-tables/{id}/entries

Request

{
  "key": "Office Furniture Color",
  "valid_from": "2020-12-07T13:34:58.698Z",
  "valid_to": "2020-12-07T13:34:58.698Z",
  "multi_value": {
      "Value": "Blue",
      "Value 2": "Yellow",
      "Value 3": "Ivory"
   }
}

Response

{
  "id": "26534",
  "key": "Office Furniture Color",
  "valid_from": "2020-12-07T07:34:58-06:00",
  "valid_to": "2020-12-07T07:34:58-06:00",
  "multi_value": {
       "Value 3": "Ivory",
       "Value 2": "Yellow",
        "Value": "Blue"
  }
}

Retrieving lookup table entries

To retrieve the specified lookup entry by ID:

GET https://example.gotransverse.com/billing/2/usage-lookup-tables/{usage_lookup_table_id}/entries/{id}

To retrieve a list of available lookup entries:

GET https://example.gotransverse.com/billing/2/usage-lookup-tables/{usage_lookup_table_id}/entries

Note: To retrieve lookup table entries with multiple values, the Lookup Table Processing Mode system setting must be set to MULTI. However, you can still retrieve multiple values with the system setting set to SINGLE by using the expand query parameter:GET /usage-lookup-tables/{id}/entries?expand=multi_value

Updating lookup table entries

You can update lookup table entries with both single and multiple values, depending on the configuration of the Lookup Table Processing Mode system setting.

Note: You cannot edit the configuration of the Lookup Table Processing Mode system setting. If you need to change it, please contact GTV support.

  • MULTI—Allows updating only multiple values in the lookup table entry.
  • SINGLE—By default, allows updating one value in the lookup table entry. You can still update multiple entry values by using the expand query parameter: PUT /usage-lookup-tables/{usage_lookup_table_id}/entries/{id}?expand=multi_value.The request can include either value or multi_value field.

    Note: This option is deprecated and is available for backwards compatibility only. We recommend switching to the MULTI option. Contact the GTV Support for details.

Updating a single lookup table entry value

To update a single lookup table entry value, the Lookup Table Processing Mode system setting must be set to SINGLE. Use the following endpoint and, in the response body, enter a new value for the lookup table entry:

PUT https://example.gotransverse.com/billing/2/usage-lookup-tables/{usage_lookup_table_id}/entries/{id}

Request

{
  "value": "White"
}

Response

{
  "id": "26550",
  "key": "Office Furniture Color",
  "value": "White",
  "valid_from": "2020-12-07T07:34:58-06:00",
  "valid_to": "2020-12-07T07:34:58-06:00"
}

Updating multiple lookup table entry values

With the Billing API, you can update multiple lookup table entry values in a single request. This request also allows you to delete entry values by setting them to null.

To update usage lookup table entry values, use the following endpoint and, in the response body, enter new values for the lookup table entry: PUT /usage-lookup-tables/{usage_lookup_table_id}/entries/{id}

Note: If the Lookup Table Processing Mode system setting is set to SINGLE, you can still update multiple entry values by using the expand query parameter:POST /usage-lookup-tables/{id}/entries?expand=multi_value

In the following example, lookup table entry values Value and Value 2 are updated and Value 3 is deleted: PUT https://example.gotransverse.com/billing/2/usage-lookup-tables/{usage_lookup_table_id}/entries/{id}

Request

{
  "multi_value": {
      "Value": "Blue",
      "Value 2": "Marsala",
      "Value 3": null
   }
}

Response

{
  "id": "26534",
  "key": "Office Furniture Color",
  "valid_from": "2020-12-07T07:34:58-06:00",
  "valid_to": "2020-12-07T07:34:58-06:00",
  "multi_value": {
      "Value 2": "Marsala",
      "Value": "Blue"
   }
}

Deleting lookup table entries

You can delete lookup table entries with both single and multiple values. To delete the lookup entry that you no longer need:

DELETE https://example.gotransverse.com/billing/2/usage-lookup-tables/{usage_lookup_table_id}/entries/{id}

Note: Once deleted, you cannot recover this lookup table entry.

Managing labels in usage lookup table entry values

The Billing API allows you to customize labels in usage lookup table entries with multiple values. Default labels for entry values include a sequence of 20 fields named Value, Value 2, Value 3 to Value 20.

To provide more flexibility in leveraging usage lookup tables, we allow you to change the names of default labels for table entry values to custom ones such as “Color” or “Country.” Configuring labels in lookup table entry values helps to provide the context of the data column for configuring usage rules.

To update a label in the usage lookup table entry, first, you must retrieve its meta data information: ID or sequence number. For example:

{ 
  "id": "10042",
  "sequence": 1, 
  "label": "Value" 
}

Then, you can update the desired label for the lookup table entry value.

Retrieving usage lookup table meta data

You can retrieve meta data about all entries in the usage lookup table or the specified entry by ID:

  • To retrieve the meta data information about all usage lookup table entries:
    GET /usage-lookup-tables/{usage_lookup_table_id}/entry-values-metadata
  • To retrieve the meta data information about the specified usage lookup table entry by ID:GET /usage-lookup-tables/{usage_lookup_table_id}/entry-values-metadata/{id}

After you retrieve details about the usage lookup table entry, you can update the desired labels.

Updating usage lookup table meta data

The Billing API allows you to update the labels of usage lookup table entry values to meet your business needs. To update the labels of usage lookup table entry values, use the following endpoint POST /usage-lookup-tables/{id}/entry-values-metadata/bulk

In the request body, enter the ID or sequence number of the lookup table entry value and a new label, for example: POST https://example.gotransverse.com/billing/2/usage-lookup-tables/{id}/entry-values-metadata/bulk

Request

{
 "entry_values_metadata": [
  {
     "id": "10042",
     "label": "Kitchen furniture color"
  }
  ]
}

Response

{
"entry_values_metadata": [
{
	"status_code": 200,
	"entry_value_metadata": {
		"id": "10042",
		"sequence": 1,
		"label": "Kitchen furniture color"
	}
}
]
}

You can update labels before or after associating them with lookup table entry values. The label will update regardless of an existing entry value. For example, if we retrieve the lookup table entry whose label we updated above, it will contain values added previously. GET https://example.gotransverse.com/billing/2/usage-lookup-tables/{usage_lookup_table_id}/entries/{id}

Response

{
  "id": "26574",
  "key": "Office Furniture Color",
  "valid_from": "2020-12-07T07:34:58-06:00",
  "valid_to": "2020-12-07T07:34:58-06:00",
  "multi_value": {
       "Value 2": "Blue",
       "Kitchen furniture color": "White"
  }
}