Custom Field PATCH

URI

https://{DATACENTER}.brightpearl.com/public-api/{ACCOUNT}
/order-service/order/{ID}/custom-field

Refer to our documentation on URI syntax for more information on how to construct URIs.

Description

Order custom field PATCH allows you to update fields on an individual basis, leaving all other fields as they were. Please refer to the HTTP PATCH documentation for a more detailed explanation of the operations and syntax of, and reasons behind, HTTP PATCH.

You cannot use this endpoint to add a new type of custom field to orders - only to provide or change the value of an existing custom field type.

Note that fields of the type select-list do not hold simple values - they are maps containing an ID & value. When adding a select-list custom field value to an order you only need to supply the ID but the ID must be inside a map. When changing an existing select-list value again only the ID needs to change but you must remember to include the path to the ID in the patch operation. Example of both of these are included below for clarity.

Use the custom field metadata GET endpoint to find out about the available custom fields (including the IDs applicable to a select-list).

If successful this endpoint returns the new state of the order's custom fields as if you had performed an order custom fields GET.

Example 1

These examples form a sequence to demonstrate some of the more common PATCH operations. In the example we have one of each type of custom field available to an order and order 1 has some data in each custom field already.

Updating the value of 'PCF_FREEFORM' (freeform text type) for order 1 to "I have changed".

Request URI

/order/1/custom-field

Request body

[
	{
		"op": "replace",
		"path": "/PCF_FREEFORM",
		"value": "I have changed"
	}
]

Response

{
	"response": {
		"PCF_FREEFORM": "I have changed",
		"PCF_TEXTAREA": "This text\r\nis written across\r\nseveral lines",
		"PCF_DATE": "2015-06-19T00:00:00.000+01:00",
		"PCF_YESNO": true,
		"PCF_SELECTLI": {
			"id": 9,
			"value": "Ringo"
		},
		"PCF_NUMERIC": 456
	}
}

Example 2

Adding a select-list value to order 3 which currently has no custom field values

Request URI

/order/3/custom-field

Request body

[
	{
		"op": "add",
		"path": "/PCF_COLOUR",
		"value": {
			"id": 5
		}
	}
]

Response

{
	"response": {
		"PCF_COLOUR": {
			"id": 5,
			"value": "Red"
		}
	}
}

Example 3

Updating the value of 'PCF_SELECTLI' (select-list type) for order 1 to George (which has an ID of 8). Note that the path to the ID is '/PCF_SELECTLI/id' and we don't need to supply the value, just the ID.

Request URI

/order/1/custom-field

Request body

[
	{
		"op": "replace",
		"path": "/PCF_SELECTLI/id",
		"value": 8
	}
]

Response

{
	"response": {
		"PCF_FREEFORM": "I have changed",
		"PCF_TEXTAREA": "This text\r\nis written across\r\nseveral lines",
		"PCF_DATE": "2015-06-19T00:00:00.000+01:00",
		"PCF_YESNO": true,
		"PCF_SELECTLI": {
			"id": 8,
			"value": "George"
		},
		"PCF_NUMERIC": 456
	}
}

Example 4

Remove the current value from 'PCF_DATE'.

Request URI

/order/1/custom-field

Request body

[
	{
		"op": "remove",
		"path": "/PCF_DATE"
	}
]

Response

{
	"response": {
		"PCF_FREEFORM": "I have changed",
		"PCF_TEXTAREA": "This text\r\nis written across\r\nseveral lines",
		"PCF_YESNO": true,
		"PCF_SELECTLI": {
			"id": 8,
			"value": "George"
		},
		"PCF_NUMERIC": 456
	}
}

Example 5

Add a new value to 'PCF_DATE' (date type).

Request URI

/order/1/custom-field

Request body

[
	{
		"op": "add",
		"path": "/PCF_DATE",
		"value": "2000-01-01"
	}
]

Response

{
	"response": {
		"PCF_FREEFORM": "I have changed",
		"PCF_TEXTAREA": "This text\nis written across\nseveral lines",
		"PCF_DATE": "2000-01-01T00:00:00.000Z",
		"PCF_YESNO": true,
		"PCF_SELECTLI": {
			"id": 8,
			"value": "George"
		},
		"PCF_NUMERIC": 456
	}
}