How do I read supplier custom fields from the External API?

Supplier Custom Fields in the External V1 API

The External V1 suppliers endpoint now returns all custom field values alongside standard supplier fields. This lets you sync every piece of supplier metadata — including any fields your team defined under Manage → Custom Fields — in a single API call.

Prerequisite: Custom fields must be defined and scoped to the Supplier object type before they appear here. See Supplier Custom Fields and Purchase Order Defaults for setup instructions.

Endpoints

Action	Request
List suppliers	`GET /external/api/v1/suppliers`
Single supplier	`GET /external/api/v1/suppliers/{id}`

No extra query parameters are required — custom_fields is returned on every response automatically.

Response shape

custom_fields is a JSON object (never an array) whose keys are your custom field labels and whose values are the stored field values.

{
  "data": {
    "id": 42,
    "name": "Acme Supplies",
    "custom_fields": {
      "Lot Prefix": "ACME-LOT",
      "Lot Shelf Days": 180,
      "Lot Audited On": "2026-08-19",
      "Preferred Carriers": ["UPS", "FedEx"]
    }
  }
}
**Type mapping**

| Custom field type | JSON value type |
|---|---|
| Text / String | string |
| Number | number |
| Date | string (ISO 8601) |
| Multi-select dropdown | string (comma-separated) |

**When no values are set**, the field is still present as an empty object — it will never collapse to `null` or `[]`:

```json
"custom_fields": {}

Scoping rules

Only custom fields defined for the Supplier object type appear here. Fields scoped to other record types (SKUs, sales orders, business accounts, etc.) are automatically excluded.

PII-restricted API tokens

If your API token has the PII Restriction setting enabled, custom_fields will be returned as an empty object ({}) regardless of the values stored on the supplier.

Tips

Key by label, not by ID. The object is keyed on your field's human-readable label. If you rename a custom field label in Manage → Custom Fields, update your integration's mapping accordingly.
Check for key existence. A label key will only be present if at least one value has been saved. An absent key and a null value both mean "not set" from the integration's perspective; the empty-object guarantee means you can safely do custom_fields[label] ?? null without a key-existence guard.
List vs. single endpoint. Both the paginated list and the single-record endpoint return the same custom_fields shape, so you don't need separate logic for each.