Custom fields

Custom fields are a useful resource for extending out the Onport data model with data unique to your business. For example, you may want to add a custom tax field to the dropship provider model. Or, capture additional data on the purchase order.

While there is a setup area in Onport to manage custom fields (Setup > Custom fields), they can also be created through the API. Conceptually, there is a cusotm-fields.json resource, which contains the details on the type of custom field (e.g. the help text, label, type of field etc). Then, there is a joining resource which contains the custom field value. This takes the convention custom-field-{resource}.json. For example, custom-field-sales.json, custom-field-dropshipments.json. You can view our API technical reference for the full list of resources you can attach custom fields to, as the list is being expanded on request.

Getting a list of custom fields for an object

Based on the above contention, you'll be able to get a list of custom fields associated with an object using the following GET request. Note the query param for specifying the saleId (this will be the Onport internal ID). Also, the include param to side load the custom field data (so you know what custom field the value is associated with).

curl --request GET \
  --url 'https://api.jetti.io/api/custom-field-sales.json?where[saleId]=1234&include[0][model]=CustomField' \
  --header 'Authorization: Bearer {{token}}'

Upserting values

As a developer, you'll want a convenient way to update these custom fields. This will avoid the patter of a GET (to get the ID), then a subsequent PUT or POST on the resource, depending on whetehr the cusotm field value exists. To assist with this, we have an endpoint to bulk update custom fields values against a given resource.

curl --request PUT \
  --url https://api.jetti.io/api/sales/{saleId}/sync-custom-fields.json \
  --header 'Authorization: Bearer eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.NDAtam9uK2RldjJAamV0dGkuaW8tYXBp.coAgH8Rv6zP22YtcL4S_Xqu48Nn1BhcHl5sKwm-tUnI' \
  --header 'Content-Type: application/json' \
  --data '{
    "customFields": [{
        "key": "my-key",
        "value": "my-value"
    }]
}'

This pattern can be repeated for any resource supporting custom fields. For example, https://api.jetti.io/api/dropshipments/{dropshipmentId}/sync-custom-fields.json etc. The endpoint will create up to 20 custom fields in bulk synchronously. It will return a payload of the custom field values and their associated custom field. A useful feature of this, is that if the custom field is not yet created under Setup > Custom fields, it will be automatically created.

[
    {
        "instance": {
            "id": 20,
            "value": "my-value",
            "companyId": 40,
            "customFieldId": 82,
            "saleId": 1598,
            "updatedAt": "2021-08-19T10:46:02.632Z",
            "createdAt": "2021-08-19T10:46:02.632Z",
            "values": null
        },
        "customField": {
            "displayName": "my-key",
            "fieldType": "string",
            "showInVendorPortal": false,
            "showInReturnPortal": false,
            "fieldScope": "all",
            "id": 82,
            "companyId": 40,
            "name": "my-key",
            "resource": "sale",
            "updatedAt": "2021-08-19T10:46:01.825Z",
            "createdAt": "2021-08-19T10:46:01.825Z",
            "options": null,
            "namespace": null,
            "showInResellerPortal": null,
            "helpText": null,
            "icon": null,
            "label": null
        },
        "created": true
    }
]

Custom Fields Sales Scope

In order to fetch Sales Orders along with their respective custom Fields, it is possible to make a GET call to https://api.jetti.io/api/sales.json?scope=customFields.

The scope querystring parameter makes sure Onport's API returns the custom_field_sales property, along with field name and value.

The same parameter can be applied to other collections that can carry custom fields. Below are some example endpoints:

https://api.jetti.io/api/sales.json?scope=customFields

https://api.jetti.io/api/sale-items.json?scope=customFields

https://api.jetti.io/api/dropshipments.json?scope=customFields

https://api.jetti.io/api/dropshipment-items.json?scope=customFields

https://api.jetti.io/api/purchases.json?scope=customFields

https://api.jetti.io/api/purchase-items.json?scope=customFields