Skip to main content

Create Supplier

POST 
/api/suppliers

Create a new supplier. Automatically creates a default warehouse for the supplier and attaches default pricing tiers.

Required scope: suppliers:write

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

proportional_apply_deposits (boolean or null) is the supplier's default for proportional deposit application — each automatic application of a deposit capped at the bill's share of its purchase order. true / false apply to every deposit for this supplier that has no explicit proportional_apply_enabled of its own; null defers to the purchase order's payment term (on when the term has a payment schedule) and then the account setting vendor_deposits_proportional_apply_enabled. Optional on create.

Authentication: Requires Bearer token. Requires IsPowerUserAccess middleware.

Notes:

  • email and purchase_order_email accept comma-separated multiple email addresses
  • messaging_phone: the supplier's WhatsApp/SMS number in international format (E.164, e.g. +15551234567), used to message them from a purchase order
  • name must be unique
  • po_processing_method: email, ftp, direct
  • po_batch_schedule.days: monday, tuesday, wednesday, thursday, friday, saturday, sunday
  • default_stock_level: normal, low, critical

Requires permission: suppliers.create

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) sets values for supplier custom fields. Each entry takes custom_field_id (required — must reference a custom field defined for suppliers) and value (nullable); id is prohibited on create (value ids only exist once the supplier does). The response echoes each value with its field metadata: name, slug, field_type (text | long_text | number | decimal | date | datetime | checkbox | dropdown), options, description, and is_visible_in_details.

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

Request​

Responses​

Created

Response Headers
    Content-Type