Billing Account Custom Fields

With billing account custom fields, you can pass additional information about the customer or billing account. Once you have added the needed account custom fields in Gotransverse user interface 1.0, you can retrieve available custom fields and related references with the Gotransverse Billing API.

To use the Custom Fields functionality, you must populate existing billing account custom fields with custom field values. You can also edit and delete values that you have added.

We also provide a way to create or update multiple billing account custom field values in a single bulk request. This helps to reduce the number of requests needed to manage billing account custom field values.

Retrieving the configured custom fields and related references

To retrieve existing custom fields, use the following endpoints:

GET https://example.gotransverse.com/billing/2/billing-account-custom-fields
GET https://example.gotransverse.com/billing/2/billing-account-custom-fields/{id}

To retrieve existing list values for a billing account custom field with the specified ID, use the following endpoint:

GET https://example.gotransverse.com/billing/2/billing-account-custom-fields/
{custom_field_id}/references

Working with billing account custom field values

Billing API provides a way to retrieve the available custom field values and add new ones to the billing account's existing custom field values. When needed, you can also edit and delete desired custom field values.

Retrieving billing account custom field values

Use the following endpoints to retrieve billing account custom field values:

GET https://example.gotransverse.com/billing/2/billing-accounts/{id}/custom-field-values
GET https://example.gotransverse.com/billing/2/billing-accounts/
{billing_account_id}/custom-field-values/{id}


Creating a new billing account custom field value

Use the following endpoints to create a new billing account custom field value:

POST https://example.gotransverse.com/billing/2/billing-accounts/{billing_account_id}/
custom-field-values

Request

{
  "custom_field_value_type": "billing-account",
  "value": "value #2",
  "custom_field": {	
      "id": "2328",
	  "name": "sample custom field #2",
	  "custom_field_type": "billing-account"
   }
}

Response

{
  "custom_field_value_type": "billing-account",
  "id": "171304",
  "value": "value #2",
  "custom_field": {
      "custom_field_type": "billing-account",
	  "id": "2328",
	  "name": "sample custom field #2"
  }
}

Editing and deleting billing account custom field values

Use the following endpoint to edit the existing custom field value. In the request body, specify the desired custom field value and its type:

PUT https://example.gotransverse.com/billing/2/products/{product_id}/custom-field-values/{id}

Request

{
  "custom_field_value_type": "billing-account",
  "value": "updated value #2"
}

Response

{
  "custom_field_value_type": "billing-account",
  "id": "171304",
  "value": "updated value #2",
  "custom_field": {
      "custom_field_type": "billing-account",
	  "id": "2328",
	  "name": "sample custom field #2"
  }
}

Use the following endpoint to delete the desired custom field value:

DELETE https://example.gotransverse.com/billing/2/billing-accounts/{billing_account_id}/
custom-field-values/{id}

Note: You cannot delete a custom field value that is in use.

Creating or updating billing account custom field values in bulk

The Gotransverse Billing API provides a way to create or update multiple custom field values in one API request. The number of custom field values that can be processed in a bulk is managed by the Max Bulk Size of API NG Request system setting.

Note: You can also manage service custom field values in bulk.

In a single request, you can both add values for non-populated billing account custom fields and update existing billing account custom field values.

To manage several billing account custom field values in bulk, use the following endpoint:POST billing-accounts/{billing_account_id}/custom-field-values/bulk. In the request body, enter details about the custom field value that you want to create or update such as the custom field value type, a reference to the associated custom field, and the value that you want to create or update.

Note: For updating billing account custom field values, in the request body, you can specify the ID of the custom field value, a reference to the custom field, or both. If both values are passed, unique identifiers are evaluated in the following order: custom field value ID, then custom field reference. If the specified custom field value ID doesn’t exist, the custom field reference is used as the key for the custom field value. For example:


"custom_field_value_type": "billing-account",
"id": "193462",
"value": "true"
OR

"custom_field_value_type": "billing-account", 
"value": "false", 
"custom_field": { 
	"custom_field_type": "billing-account", 
	"id": "2326", 
    "name": "sample custom field #1" 
} 
OR

"custom_field_value_type": "billing-account", 
"value": "true", 
"id": "193462", 
"custom_field": { 
	"custom_field_type": "billing-account", 
	"name": "sample custom field #1" 
} 

If the specified custom field value already exists, the mode property determines whether it can be created or updated in a bulk collection:

  • OVERWRITE_ON_EXISTING—An update is performed on an existing custom field value.
  • FAIL_ON_EXISTINGDefault. An update is not performed and an error is returned in the response. In addition, the request is terminated and rolled back.

To create a new billing account custom field value and update an existing one in a single request, use the following endpoint and sample request body:

POST https://example.gotransverse.com/billing/2/billing-accounts/{billing_account_id}/
custom-field-values/bulk

Request

{
  "mode": "OVERWRITE_ON_EXISTING",
  "custom_field_values": [
  {
 	 "custom_field_value_type": "billing-account",
	 "value": "false",
	 "custom_field": {
		"id": "2326",
		"name": "sample custom field #1",
		"custom_field_type": "billing-account"
	 }
  },
{
  "custom_field_value_type": "billing-account",
  "id": "193464",
  "value": "TX Home Decor",
  "custom_field": {
	  "id": "2328",
	  "name": "sample custom field #2",
	  "custom_field_type": "billing-account"
  }
}
]
}

Response

{
 "custom_field_values": [
 {
     "status_code": 200,
	 "custom_field_value": {
	 	 "custom_field_value_type": "billing-account",
	 	 "id": "193462",
		 "value": "false",
		 "custom_field": {
			"custom_field_type": "billing-account",
			"id": "2326",
			"name": "sample custom field #1"
		}
	 }
 },
 {
  "status_code": 200,
  "custom_field_value": {
	 "custom_field_value_type": "billing-account",
	 "id": "193464",
	 "value": "TX Home Decor",
	 "custom_field": {
		"custom_field_type": "billing-account",
		"id": "2328",
	    "name": "sample custom field #2"
	 }
  }
}
]
}

Note: If any of the specified elements in the request payload are not valid, the request will fail. The response message will contain a pointer to the index of the invalid element.