In this topic:

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.

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

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

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

Note: You can add order item custom field values only when the associated order is in the Draft status.

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

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

Note: You can edit or delete an order item custom field only when the associated order is in the Draft status.

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}

Top