Skip to main content

Update Supplier

PUT 
/api/suppliers/:supplier

Update an existing supplier. All fields are optional.

Required scope: suppliers:write

Grant this scope to your token under Settings → Developer → Personal Access Tokens.

  • messaging_phone — the supplier's WhatsApp/SMS number in international format (E.164, e.g. +15551234567), used to message them from a purchase order.

  • purchase_order_format — only allowed on PUT.

  • purchase_order_csv_columns — optional array of column keys controlling which columns appear in this supplier's outgoing PO email CSV attachment. Each entry must be one of the keys returned by GET /api/purchase-orders/csv-columns. Set to null (or omit) to fall back to the tenant default. Set to an empty array to fall back to the tenant default. Order of the array determines column order in the CSV. Use the POST /api/suppliers/:supplier/csv-sample endpoint to preview the layout.

  • proportional_apply_deposits — boolean or null. Supplier-level default for proportional deposit application (each automatic deposit application capped at the bill's share of its purchase order). true / false override the payment-term and account defaults for this supplier's deposits; null (the default) inherits — on when the purchase order's payment term has a payment schedule, otherwise the account setting vendor_deposits_proportional_apply_enabled. A deposit's own proportional_apply_enabled still wins over all of these.

Authentication: Requires Bearer token. Requires IsPowerUserAccess middleware.

Requires permission: suppliers.update

Clearing default_incoterm_id (sending it as null/empty) also clears default_incoterm_place — a default named place is never kept without a default term.

Custom fields: custom_field_values (optional array) fully replaces the supplier's stored custom field values when present — entries with an id update that existing value (the id must reference a custom-field value belonging to THIS supplier; a value id from another supplier is rejected with a 422), entries without one create a new value (custom_field_id required, must reference a custom field defined for suppliers), and any stored value row omitted from the array is deleted. Omit the key entirely to leave stored values untouched.

Advanced lead times: warehouse_lead_times (optional array of { warehouse_id, leadtime }) sets supplier-level per-warehouse lead-time overrides. Rows with a warehouse_id and a numeric leadtime are upserted; a warehouse omitted from the array has its override removed. Omit the key to leave overrides untouched.

Dropship vendor labels (all optional):

  • dropship_label_mode (string): vendor_label (default — labels off: the vendor ships on their own account), auto (the store buys the label when the PO is sent) or on_request (the vendor requests it from the supplier portal). On update, auto / on_request require a complete ship-from address on every dropship warehouse of the supplier (422 otherwise).
  • dropship_label_integration_instance_id (integer|null): a connected label-capable shipping integration (see List Dropship Label Providers); null = the account default
  • dropship_label_allowed_services (array of strings|null): service tokens the label may use; empty/null = any
  • dropship_label_handling_days (integer, 0–30)
  • dropship_label_max_relabels (integer, 0–10): how many replacement labels the vendor may request per order
  • dropship_label_default_package (object|null): weight, weight_unit (lb, oz, kg, g), length, width, height, dimension_unit (in, cm) — all required when the object is sent; numbers > 0

direct_destinations (optional array, replaces the list): fulfillment network warehouses this supplier ships to directly — each destination_warehouse_id (required; an Amazon FBA / AWD, Walmart WFS or TikTok FBT warehouse; Faire FBF is rejected with 422 because the Send Planner doesn't plan sends to it), lead_days (0–365, null = the supplier's lead time) and prep_notes (≤500 chars). The Send Planner suggests a supplier-direct PO only for these networks.

Request​

Responses​

OK

Response Headers
    Content-Type