Order Item Custom Fields

The Gotransverse Billing API allows you to create custom fields for storing additional information about order items. To use order item custom fields, you have to add Service and One-Time custom fields in the original Gotransverse user interface 1.0.

Note: Order item custom field values populate custom fields of the service type.

Order item custom field values can be added to the specified order items in the Draft status OR in a single request with creating an order or a billing account with an order.

You can add order item custom fields for one-time, subscription, or add-on products that have been added to the cart. Before adding a customer field value, you must fist associate this service custom field with the desired product.

Note: You can add, edit, or delete custom fields on one-time order items before and after the order is invoiced.

Retrieving the configured custom fields

To view the available custom fields that you can populate with order item custom field values, retrieve service custom fields.

Adding order item custom field values

You can add order item custom field values in the following ways:

Adding order item custom field value to the order item

Depending on whether the custom field is added on a recurring or one-time product, you can manage custom fields values on different stages of order processing. You can add custom field values:

  • On recurring products—Only when the associated order is in Draft status.
  • On one-time products—Regardless of the order status, even after the order is invoiced.

Use the following endpoint and sample request body to create a new custom field value for the existing custom field:

POST https://example.gotransverse.com/billing/2/order-items/{order_item_id}/custom-field-values

Request

{
  "custom_field_value_type": "order-item",
  "value": "value #7",
  "custom_field": {
      "id": "2336",
	  "custom_field_type": "service"
  }
}

Response

{
  "custom_field_value_type": "order-item",
  "id": "171962",
  "value": "value #7",
  "custom_field": {
      "custom_field_type": "service",
	  "id": "2336",
	  "name": "service custom field #1"
  }
}

Adding a custom field value to order item when creating an order

Use the following endpoint and sample request body to add a new custom field value when creating an order:

POST https://example.gotransverse.com/billing/2/billing-accounts/{billing_account_id}/orders

Request

{
  "initial_status": "CONFIRMED",
  "email_receipt": false,
  "order_items": [
  {
      "order_item_type": "product",
	  "product": {
	       "object_type": "product",
		   "default_quantity": 1,
		   "id": "27452",
		   "product_type": "general"
      },
	 "quantity": 1,
	 "custom_field_values": [
	 {
		"custom_field_value_type": "order-item",
		"value": "value #1",
		"custom_field": {
			"custom_field_type": "service",
			"id": "2336"
		}
    }
	]
}
]
}

Response

{
  "order_type": "sales",
  "id": "2165226",
  "order_num": "223451316",
  "order_items": [
  {
      "order_item_type": "product",
	  "id": "2660388",
	  "quantity": 1,
	  "sequence": 1,
	  "product": {
	      "product_type": "customer-subscription",
		  "id": "27452",
		  "name": "Sample subscription for CA"
	  },
	 "order_items": [],
	 "status": "COMPLETED",
	 "extended_price": 10,
	 "awaiting_approval": false,
	 "price_list": {
	     "id": "696",
		 "name": "Default Price List"
	 },
	"service_resources": [],
	"requested_effective_date": "2019-05-08T09:21:53-05:00",
	"operation_run_attributes": [],
	"custom_field_values": [
	{
		"custom_field_value_type": "order-item",
		"id": "171604",
		"value": "value #1",
		"custom_field": {
			"custom_field_type": "service",
			"id": "2336",
			"name": "service custom field #1"
		}
  }
  ],
  "addresses": [],
  "consume_prepaid_balance": false,
  "order_item_prices": [
  {
     "order_item_price_type": "recurring",
	 "id": "2674794",
	 "tapered": false,
	 "currency_code": "USD",
	 "category": {
		"charge_category_type": "price",
		"id": "2884",
		"name": "Default"
	 },
	"price_override": true,
	"amount": 10,
	"taxable_amount": 0,
	"product_price": {
		"product_price_type": "recurring",
		"id": "46640",
		"tapered": false,
		"currency_code": "USD",
		"category": {
			"charge_category_type": "price",
			"id": "2884",
			"name": "Default"
		},
		"valid_from": "2019-01-01T00:00:00-06:00",
		"price_override": true,
		"price_ranges": [
		{
			"price_range_type": "product",
			"id": "50686",
			"price": 10,
			"level": 1,
			"quantity_begin_range": 0,
			"currency_code": "USD"
		}
		],
		"payment_on_purchase_required": false,
		"price_group": null,
		"recurring_payment_required": false,
		"recurrence_period": "BILL_CYCLE",
		"prorated_on_order": false,
		"prorated_on_cancel": false,
		"prorated_on_order_no_charge": false,
		"bill_in_advance": false,
		"usage_rules": []
  },
  "price_ranges": [
  {
      "price_range_type": "order-item",
	  "id": "755818",
	  "price": 10,
	  "level": 1,
	  "quantity_begin_range": 0,
	  "currency_code": "USD"
  }
  ],
      "price_group": null,
      "prorated_on_order": false,
      "prorated_on_cancel": false,
      "prorated_on_order_no_charge": false,
      "bill_in_advance": false
  }
  ],
  "service": {
     "id": "2186136"
  },
  "order_item_counters": [],
  "charges": [
  {
      "order_item_charge_type": "product-one-time",
	  "id": "3921750",
	  "amount": 10,
	  "price_category": {
	       "charge_category_type": "price",
		   "id": "2884",
		   "name": "Default"
     },
	"overridden": false,
	"scheduled_charges": []
    }
    ]
   }
   ],
  "billing_account": {
      "id": "1494678",
	  "account_num": "Dpref2043",
	  "external_account_num": null
   },
  "email_receipt": false,
  "order_date": "2019-05-08T09:21:53-05:00",
  "total_amount": 10,
  "custom_field_values": [],
  "status": "COMPLETED",
  "sub_total": 10,
  "tax_total": 0,
  "due_now_total": 0,
  "due_now_tax_total": 0
}

Adding an order item custom field when creating a billing account

Use the following endpoint and sample request body to add an order item custom field value when creating a billing account with an order:

POST https://example.gotransverse.com/billing/2/billing-accounts

Request

{
  "start_date": "2019-04-21",
  "automatic_recurring_payment": false,
  "bill_cycle": {
      "bill_cycle_type": "monthly",
	  "id": "19100"
  },
  "bill_type": "EMAIL",
  "billing_account_category": {
      "id": "938"
  },
  "responsible_party": {
  "party_type": "person",
  "addresses": [
  {
      "purpose": "BILLING",
	  "city": "Austin",
	  "line1": "97 Meadow Ave",
	  "line2": "412 Green",
	  "postal_code": "78701",
	  "region_or_state": "TX",
	  "address_type": "postal"
  }, 
  {
      "purpose": "PRIMARY",
	  "email": "sam@company.com",
	  "address_type": "email"
  }
  ],
  "first_name": "Sam",
  "last_name": "Baker"
  },
  "sales_order": {
       "order_date": "2019-04-21",
       "email_receipt": false,
	   "order_items": [
	  {
	       "order_item_type": "product",
		   "product": {
		       "object_type": "product",
		        "default_quantity": 1.0,
   		        "id": "27452",
                "product_type": "customer-subscription"
			},
			"quantity": 1,
			"custom_field_values": [
			{
				"custom_field_value_type": "order-item",
				"value": "value #5",
				"custom_field": {
					"custom_field_type": "service",
					"id": "2336"
				}
				}
		  ]
		  }
		]
		}
}

Response


{
  "id": "1496130",
  "account_num": "Dpref2168",
  "external_account_num": null,
  "bill_type": "EMAIL",
  "bill_cycle": {
	  "bill_cycle_type": "monthly",
	  "id": "19100",
	  "status": "ACTIVE",
	  "name": "bill-cycle-sample",
	  "start_date": "2019-04-21T00:00:00-05:00",
	  "end_date": "2019-05-21T00:00:00-05:00",
	  "internal_render": true,
	  "auto_bill": true,
	  "use_payment_term": true,
	  "currency_code": "USD",
	  "billing_account_category": {
		  "id": "938",
		  "name": "All Accounts"
	  },
	  "auto_bill_delay_in_days": 0,
	  "current_bill_cycle_run": {
	        "bill_run_type": "cycle",
	        "id": "1711908"
	   },
	  "day_of_month": 21
	},
	"responsible_party": {
		"party_type": "person",
		"id": "1503006",
		"addresses": [
		{
	    	"address_type": "postal",
			"id": "3130362",
		 	"purpose": "BILLING",
			"country": "USA",
			"city": "Austin",
			"line1": "97 Meadow Ave",
			"line2": "412 Green",
			"region_or_state": "TX",
			"postal_code": "78701"
		},
		{
		    "address_type": "email",
			"id": "3130364",
			"purpose": "PRIMARY",
			"email": "sam@company.com"
		}
		],
		"first_name": "Sam",
		"last_name": "Baker"
	},
	"recurring_payments": [],
	"billing_account_category": {
	"id": "938",
	"description": "Default billing account category",
	"status": "ACTIVE",
	"name": "All Accounts",
	"payment_term": {
		"id": "1060",
		"name": "Immediate"
	},
  "auto_pay_offset": 0,
  "preferred_language_code": null
},
  "auto_payment_authorized": false,
  "status": "ACTIVE",
  "pending_charges_total": 0,
  "balance": 0,
  "start_date": "2019-04-21T00:00:00-05:00",
  "custom_field_values": [],
  "contacts": [],
  "tax_exempt": false,
  "currency_code": "USD",
  "next_invoice_date": "2019-04-21T00:00:00-05:00",
  "responsible_account": {
      "id": "1496130",
	  "account_num": "Dpref2168",
	  "external_account_num": null
  },
  "background_allocation": true,
  "preferred_language_code": null
}

Note: The following response body contains the information about newly created billing account. To see details about the order with order item custom field values, retrieve orders associated with this billing account: GET /billing-accounts/{billing_account_id}/orders

Editing and deleting order item custom field values

Depending on whether the custom field is added on a recurring or one-time product, you can manage custom field values on different stages of order processing. You can edit or delete custom field values:

  • On recurring products—Only when the associated order is in Draft status.
  • On one-time products—Regardless the order status, even after the order has been invoiced.

Use the following endpoint and sample request body to edit the existing custom field value:

PUT https://example.gotransverse.com/billing/2/order-items/{order-item-id}/custom-field-values/{id}

Request

{
  "custom_field_value_type": "order-item",
  "value": "updated value #7"
}

Response

{
  "custom_field_value_type": "order-item",
  "id": "171962",
  "value": "updated value #7",
  "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/order-items/{order_item_id}/custom-field-values/{id}