Service Custom Fields

With service custom fields, you can capture additional information about the product that has been sold or the existing service. Once you have created a Service and One-Time custom field in the original Gotransverse user interface 1.0, you can retrieve available custom field values and related references with the Gotransverse Billing API. Here, you can also associate the existing service custom fields with a product, retrieve and delete the available relations

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

You can also create and update several service custom field values in a single bulk request to reduce the number of requests needed to manage service custom field values.

Note: Before adding a custom field value, you have to associate this service custom field value with the desired product.

Retrieving the configured custom fields and related references

To retrieve existing service custom fields, use the following endpoints:

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

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

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

Managing service custom field relations

With API 2.0, you can associate service custom fields with a product that allows for better product definition. The following actions are available for the existing service custom fields.


Associating a service custom field with a product

To associate an existing service custom field with a product, use the following endpoint. In the request body, indicate the ID and name of the service custom field.POST https://example.gotransverse.com/billing/2/products/id/service-custom-field-relations

Request

{
"custom_field": {
	"id": "19",
	"name": "Service Custom Field#1",
	"custom_field_type": "service"
}
}

Response

{
"id": "1422",
"product": {
	"product_type": "customer-subscription",
	"id": "27314",
	"name": "Sub ss"
},
"custom_field": {
	"custom_field_type": "service",
	"id": "2220",
	"name": "Service Custom Field#1"
}
}

Associating a service custom field with a product during product creation

To associate an existing service custom field with a product when creating a new subscription or one-time product, add the details about the custom field to the payload when creating the product as an object nested within the service_custom_field_relations parameter.
POST https://example.gotransverse.com/billing/2/products

Request

{
"name": "Sub test00",
"taxable": false,
"trial": false,
"product_type": "customer-subscription",
"requires_agreement": false,
"default_quantity": 1,
"product_category": {
	"id": "900"
},
"min_service_resources": 0,
"max_service_resources": 0,
"trial_override": false,
"introduction_date": "2017-05-13T20:11:00+03:00",
"rule_override": true,
"rule_type": "TAPERED",
"consume_prepaid_balance": false,
"service_custom_field_relations": [
{
	"custom_field": {
		"id": "18",
		"name": "Service Custom Field#1",
		"custom_field_type": "service"
	}
},
{
"custom_field": {
	"id": "19",
	"name": "Service Custom Field#2",
	"custom_field_type": "service"
}
}
]
}

Response

{
"product_type": "customer-subscription",
"id": "31360",
"name": "Sub test00",
"serialized": true,
"taxable": false,
"trial": false,
"state": "DRAFT",
"requires_agreement": false,
"default_quantity": 1,
"product_category": {
	"id": "900",
	"name": "Default"
},
"min_service_resources": 0,
"max_service_resources": 0,
"trial_override": false,
"product_tags": [],
"introduction_date": "2018-05-13T12:11:00-05:00",
"custom_field_values": [],
"service_custom_field_relations": [
{
	"id": "1408",
	"product": {
		"product_type": "customer-subscription",
		"id": "31360",
		"name": "Sub test00"
	},
	"custom_field": {
		"custom_field_type": "service",
		"id": "2664",
		"name": "Service Custom Field#2"
	}
},
{
"id": "1410",
"product": {
	"product_type": "customer-subscription",
	"id": "31360",
	"name": "Sub test00"
},
"custom_field": {
	"custom_field_type": "service",
	"id": "2662",
	"name": "Service Custom Field#1"
}
}
],
"rule_override": true,
"rule_type": "TAPERED",
"rule_mode": "ROOT",
"consume_prepaid_balance": false
}

Retrieving associations between products and service custom fields

To retrieve existing service custom fields associations, use the following endpoints:
GET https://example.gotransverse.com/billing/2/products/ {product_id}/service-custom-field-relations
GET https://example.gotransverse.com/billing/2/products/ {product_id}/service-custom-field-relations/{id}


Deleting the association between products and service custom fields

Use the following endpoint to delete the association between the product and the desired service custom field:
DELETE https://example.gotransverse.com/billing/2/products/{product_id}/service-custom-field-relations/{id}

Working with service custom field values

The Gotransverse Billing API provides a way to retrieve the available custom field values and add new ones to the existing custom fields. You can also edit and delete desired custom field values. Service custom field values can be managed in bulk, meaning you can create and update multiple values in a single request.

Retrieving service custom field values

Use the following endpoints to retrieve service custom field values:

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

Creating a new service custom field value

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

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

Request

{
  "custom_field_value_type": "service",
  "value": "service custom field value #2",
  "custom_field": {
      "id": "2336",
	  "name": "service custom field #1",
	  "custom_field_type": "service"
   }
}

Response

{
  "custom_field_value_type": "service",
  "id": "171496",
  "value": "service custom field value #2",
  "custom_field": {
       "custom_field_type": "service",
	   "id": "2336",
	   "name": "service custom field #1"
	}
}

Editing and deleting service 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/services/{service_id}/custom-field-values/{id}

Request

{
  "custom_field_value_type": "service",
  "value": "updated service custom field value #2"
}

Response

{
  "custom_field_value_type": "service",
  "id": "171496",
  "value": "updated service custom field value #2",
  "custom_field": {
       "custom_field_type": "service",
	"id": "2336",
	"name": "service custom field #1"
  }
}

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

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

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

Creating or updating service custom field values in bulk

The Gotransverse Billing API provides a way to create or update multiple service 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 billing account custom field values in bulk.

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

To manage several custom field values in bulk, use the following endpoint: POST /services/{service_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 service 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 unique identifier. For example:


"custom_field_value_type": "service", 
"id": "193440", 
"value": "golden sparkles" 
			
OR

"custom_field_value_type": "service", 
"value": "golden sparkles", 
"custom_field": { 
	"custom_field_type": "service", 
	"id": "2336", 
	"name": "service custom field #1" 
}
OR

"custom_field_value_type": "service", 
"id": "193440", 
"value": "golden sparkles", 
"custom_field": { 
	"custom_field_type": "service", 
	"id": "2336", 
	"name": "service custom field #1" 
} 

If the specified custom field value already exists, the mode property determines whether it can be 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 service custom field value and update the existing one in a single request, use the following endpoint and a sample request body:

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

Request

{
  "mode": "OVERWRITE_ON_EXISTING",
  "custom_field_values": [
  {
  	  "custom_field_value_type": "service",
	  "id": "193440", 
	  "value": "golden sparkles 2021",
	  "custom_field": {
	 	  "custom_field_type": "service",
		  "id": "2336",
		  "name": "service custom field #1"
	   }
	},
	{
	"custom_field_value_type": "service",
	"value": "silver balloons",
	"custom_field": {
	    "custom_field_type": "service",
		"id": "2388",
		"name": "a24"
	}
  }
  ]
}

Response

{
  "custom_field_values": [
  {
      "status_code": 200,
      "custom_field_value": {
	      "custom_field_value_type": "service",
		  "id": "193440",
		  "value": "golden sparkles 2021",
		  "custom_field": {
			  "custom_field_type": "service",
		   	  "id": "2336",
			  "name": "service custom field #1"
		  }
	}
	},
  {
  "status_code": 201,
  "custom_field_value": {
	 "custom_field_value_type": "service",
	 "id": "193442",
	 "value": "silver balloons",
	 "custom_field": {
		"custom_field_type": "service",
		"id": "2388",
		"name": "a24"
	 }
  }
}
]
}

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.