How do I partially update a supplier record via the External API?
Last updated: September 3, 2026
Partially updating a supplier — PATCH /suppliers/{id}
The External V1 API now offers a dedicated partial-update endpoint for suppliers. Send only the fields you want to change; everything else is left untouched.
When to use PATCH vs. POST
Method | Path | Behaviour |
|---|---|---|
|
| Full replace. Any accepted field you omit is written as empty or null. |
|
| Partial update. Only the fields you include are written. Omitted fields keep their current values. No field is required. |
Rule of thumb: if you are not sending the entire supplier record, use PATCH.
Quick examples
Change default currency only
PATCH /external/api/v1/suppliers/123
Content-Type: application/json
{
"default_currency_code": "EUR"
}
Address, payment terms, contacts, and every other field are unchanged.
Clear a nullable field
Send null to explicitly erase a nullable value:
PATCH /external/api/v1/suppliers/123
Content-Type: application/json
{
"default_payment_term": null
}
Update PO lead-time defaults
PATCH /external/api/v1/suppliers/123
Content-Type: application/json
{
"default_requested_ship_date_offset_days": 14,
"default_arrival_due_date_offset_days": 21
}
Writable fields
Field | Notes |
|---|---|
| Required on full-replace POST; optional on PATCH |
| Supplier address and description |
| Internal user id for the supplier admin |
| Banking details |
| Must match a configured payment term label |
| ISO 4217 three-letter code (e.g. |
| Array of existing contact ids to link; replaces the linked set when sent |
| Incoterm: |
| Warehouse id from |
|
|
| Calendar days added to order date → requested ship date |
| Calendar days added to order date → arrival due date |
| Array of ship-to address objects; see below |
| Label → value map; see below |
Special-case fields: ship_to_addresses and custom_fields
These two fields behave the same on both PATCH and the full-replace POST:
Omitting the key entirely leaves existing data untouched.
Including the key replaces the data you specify.
ship_to_addresses
Send the full set of addresses you want stored. An empty array [] clears all addresses. The entry with "is_default": true becomes the PO ship-to default.
{
"ship_to_addresses": [
{
"is_default": true,
"ship_to_name": "Receiving Dock A",
"street_address_1": "123 Warehouse Lane",
"city": "Chicago",
"state": "IL",
"zip": "60601",
"country": "US"
}
]
}
custom_fields
Send a label → value map. Only the labels you include are written; other custom field values are left alone.
{
"custom_fields": {
"Lot Prefix": "ACME-",
"Lead Time Override": 30
}
}
To clear a single custom field value, send null for that label:
{
"custom_fields": {
"Lead Time Override": null
}
}
Labels are resolved case-insensitively against your tenant's configured custom field definitions. An unrecognised label returns a 422 with a per-label error message.
For details on reading custom field values back, see How do I read supplier custom fields from the External API?
Validation rules
At least one recognised supplier field must be present — an empty body or a body containing only unknown keys returns 422.
name, if included, must be a non-empty string (max 255 characters).default_currency_code, if included, must be exactly 3 characters.default_logistic_codemust be one of the values listed in the table above.default_warehouse_idmust be an id that exists in your tenant's warehouse list.contact_idselements must be ids of existing contact records.
Response
A successful PATCH returns 200 with the full updated supplier object in the same shape as GET /suppliers/{id} — including all relations (contacts, ship-to addresses, custom fields).