Custom Data

Overview

custom_data is a metadata structure that allows you to connect key-value pairs of data to enrich objects with additional information.

Many of Shipwell's objects—including Users, Customers, Locations, Carriers, Purchase Orders, Shipments, Loads, and Products allow adding custom_data to the underlying objects.

custom_data is useful for storing additional structured information on an object such as for cross-referencing and cross-linking structured data between systems or adding extra metadata for your particular use cases.

You may also ingest custom_data for use with your own search and analytics infrastructures as the custom_data is a dictionary of key-value pair strings or text. A few highlights of custom_data functionality are that:

• Custom data is searchable in the Shipwell user interface, in the global search toolbar to quickly find the key-values.
• Custom data may also be used in the Shipwell analytics infrastructure to create custom reports.
• Custom data and the associated values will not be seen by your users unless you choose to show it to them

As an example of a use case for custom_data, you can save a custom customer reference or identifier and call it anything as a name or key, like custom_field1, and set the value for this to the corresponding unique id from your system on a shipment.

The custom_data property in an API request or response body looks like the following:

"custom_data": {
    "custom_field1": "custom_value1",
    "custom_field2": "custom_value2"
}

Below is an example of setting the custom_data property on a mock object:

{
	"name": "My Shipment",
  	"custom_data": {
		"custom_field1": "custom_value1",
		"custom_field2": "custom_value2"
	},
	"stops": [{
		"location": {
			"address": {
				"city": "Austin",
				"state_province": "TX",
				"country": "US"
			},
			"location_name": "Loc 1",
			"location_type": {
				"id": 1,
				"name": "Business (with dock or forklift)"
			}
		},
		"ordinal_index": 0,
		"carrier_specified_eta": {
			"running_window_start": "2020-02-13T14:49:40.902847Z"
		}
	}, {
		"location": {
			"address": {
				"city": "Bloomington",
				"state_province": "IN",
				"country": "US"
			},
			"location_name": "Loc 2"
		},
		"ordinal_index": 1
	}],
	"line_items": [{}],
	"est_trip_miles": 500,
	"final_trip_miles": 505,
	"weight_lbs": 1000,
	"description": "Acorns",
	"temperature_upper_limit": 100.5,
	"temperature_lower_limit": -32,
	"equipment_type": {
		"id": 2
	},
	"mode": {
		"id": 1
	},
	"service_level": {
		"id": 1
	},
	"accessorials": [{
		"id": 1
	}],
	"total_declared_value": "3.00"
}

Restrictions on custom data

Custom data fields have the following restrictions:

• You may only specify up to 50 keys
• Key names cannot exceed 40 characters in length
• Maximum length of the value of custom data field is 500 characters in length

Types of custom data

There are two types of custom data:

1. API custom data key-value pairs that is typically for backend and system-to-system integration needs (i.e. custom named metadata ) without user-facing UI needs. This is represented here .
2. UI custom (data) fields are user-facing custom fields for data entry that are managed in the Shipwell admin user interface.

Both types of custom data are string values, but the use cases and setting the values are slightly different.

API custom data key-value pairs

API custom data key-value pairs are the most common use case for custom_data as they allow both power and flexibility in attaching custom data to records as metadata. Prefer using this type of custom_data in API integrations when you have metadata that does not need to be user accessible in the Shipwell platform, is internal metadata, or is data that you typically do not wish to share with most users associated with your account.

UI custom data fields

These UI custom (data) fields, custom data fields, or custom fields are custom form fields with associated data that are generally created and managed in the Shipwell admin UI. These fields are user-facing and visible in the Shipwell UI. The fields are typically created to enable consistent user data entry into the platform for shipments and other entities or objects. For certain types of integrations and advanced use cases, like an ERP or NetSuite integration, these fields may also be utilized if both systems allow data entry. Learn how to create these fields in the Shipwell web app admin here.

For example, you may have a special code that needs to be entered in data entry by users that has a friendly name like Sales Order #.

When a user in the Shipwell admin sees a custom field that is text, they will see a form field that is similar to the following:

The fields may also be set to render a single-select dropdown to allow users to select from a predefined list of options or selections.

When a user sees a single-select list field, i.e. in a shipment data entry screen, they will see a single-select dropdown list that is similar to the following: