Service Custom Fields

With service custom fields, you can capture additional information about the product that has been sold. 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 have to populate existing custom fields with the custom field values. You can also edit and delete values that you have added.

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 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 existing list 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 the 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 for 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 association between products and service custom fields

Use the following endpoint to delete the desired service 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.

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.

Retrieving order 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 order 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.