How do I partially update a supplier record via the External API?

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
POST	/external/api/v1/suppliers/{id}	Full replace. Any accepted field you omit is written as empty or null. name is required. Use this only when you intend to send the complete supplier representation.
PATCH	/external/api/v1/suppliers/{id}	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
name	Required on full-replace POST; optional on PATCH
description, street_address, city, state, zip, country	Supplier address and description
factory_admin_id	Internal user id for the supplier admin
bank_name, routing_number, account_number, swift_code	Banking details
default_payment_term	Must match a configured payment term label
default_currency_code	ISO 4217 three-letter code (e.g. USD)
contact_ids	Array of existing contact ids to link; replaces the linked set when sent
default_logistic_code	Incoterm: fob, exw, cif, ddp, or fca
default_warehouse_id	Warehouse id from GET /warehouses
default_order_type	INTERNAL_TRANSFER_ORDER or DROP_SHIP_ORDER
default_requested_ship_date_offset_days	Calendar days added to order date → requested ship date
default_arrival_due_date_offset_days	Calendar days added to order date → arrival due date
ship_to_addresses	Array of ship-to address objects; see below
custom_fields	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_code must be one of the values listed in the table above.
• default_warehouse_id must be an id that exists in your tenant's warehouse list.
• contact_ids elements 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).