You can now read, update and filter custom field values on purchase order shipments and on purchase orders through the External API.

Read values

  • PO shipments: GET /purchase-order-shipments, GET /purchase-order-shipments/{id} and the nested GET /purchase-orders/{id}/shipments responses include a custom_fields object keyed by field label.
  • Purchase orders: PO responses include custom_fields in the same shape.
  • One record, every defined field: GET /purchase-order-shipments/{id}/custom-fields or GET /purchase-orders/{id}/custom-fields returns every field defined for that record type, keyed by label. Fields with no value on the record show null. The result is always a JSON object.

Update values

PUT /purchase-order-shipments/{id}/custom-fields or PUT /purchase-orders/{id}/custom-fields

{ "Cargo Ready Date": "2026-11-12" }
  • The body can be a {label: value} map or a list of {custom_field: <id>, value: ...} entries.
  • Fields you don't name keep their current value.
  • Sending an empty value (null, "" or []) clears that field. Clearing a required field is refused.
  • Labels are matched against fields defined for that record type. An unknown label, or one defined only for another record type, returns a 422. It is not created automatically.
  • Values are checked against the field type (date, number, dropdown and so on). If any entry is invalid, nothing is saved and the 422 names each rejected entry.
  • Sending no fields at all also returns a 422.

Filter shipments by custom field

Every custom field defined for PO shipments can be used as custom_fields.{Label} on GET /purchase-order-shipments and GET /purchase-orders/{id}/shipments. URL-encode labels that contain spaces.

GET /purchase-order-shipments?custom_fields.Cargo%20Ready%20Date[gte]=2026-11-01&custom_fields.Cargo%20Ready%20Date[lte]=2026-11-30
GET /purchase-order-shipments?custom_fields.Cargo%20Ready%20Date[notset]=true

Fields defined only for other record types are not available as filters here.

To create the fields themselves, see the article on using custom fields on PO shipments in Luminous.