> ## Documentation Index
> Fetch the complete documentation index at: https://docs.joinluminous.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Partially update a supplier

> Partially update an existing supplier. Only the fields present in the request body are written; omitted fields are left unchanged, and a nullable field sent as `null` is cleared. At least one recognized supplier field must be supplied.

Use `POST /suppliers/{supplierId}` when you want to replace the whole record instead.




## OpenAPI

````yaml /api-reference/build.yaml patch /suppliers/{supplierId}
openapi: 3.0.0
info:
  title: Luminous API
  version: 1.0.0
  description: API documentation for Luminous
servers:
  - url: https://{companyName}.api.joinluminous.com/external/api/v1
    variables:
      companyName:
        default: companyName
        description: Your company-specific subdomain
security: []
tags:
  - name: Products
    description: Get and manage products
  - name: Pricing
    description: Manage price schedules, levels, and customizations
  - name: BOMs
    description: Manage Bills of Materials (BOMs)
  - name: Labels
    description: Label rendering via Labelary ZPL service
  - name: Companies
    description: Manage business accounts and their associated data
  - name: Contacts
    description: Manage contact information for individuals
  - name: Suppliers
    description: Manage suppliers (factories) — vendors used on purchase orders
  - name: Supplier SKUs
    description: Manage per-supplier SKU and unit-cost overrides for products
  - name: Locations
    description: Manage warehouses and locations
  - name: Inventory
    description: Get and adjust product stock levels
  - name: Lots
    description: Create, update, and delete product lots (batches)
  - name: Transfer Orders
    description: Manage transfer orders
  - name: Fulfillment Orders
    description: Manage fulfillment orders and picklists
  - name: Fulfillment Priority Lists
    description: Configure fulfillment routing priority lists
  - name: Purchase Orders
    description: Get and modify purchase orders
  - name: Supplier Portal
    description: >-
      Read a supplier's response to a purchase order and control the one-click
      portal link
  - name: Receiving Reports
    description: Manage receiving reports
  - name: Payment Obligations
    description: Manage payment obligations for purchase orders
  - name: Sales Orders
    description: Manage sales orders and sales order shipments
  - name: Purgatory
    description: >-
      Inspect and resolve non-posted sales orders in the purgatory staging
      workflow
  - name: PickFlow Shipping
    description: >-
      Provider-agnostic shipping rates, services, packages, and label purchase
      for PickFlow
  - name: Cycle Counts
    description: >-
      Create, drive, and post PickFlow cycle counts — batches, per-warehouse
      sessions, and CSV import/export
  - name: Print Stations
    description: List paired print stations and enqueue print jobs to them
  - name: Invoices
    description: Get and manage invoices
  - name: Work Orders
    description: >-
      Manage work orders — production lifecycle, steps, materials, links,
      shipments, and comments
  - name: Production Batches
    description: Group and manage work orders as production batches
  - name: Bills
    description: >-
      Accounts payable bill management, payments, attachments, allocations, and
      variance
  - name: Prepayments
    description: Manage vendor prepayments and applications
  - name: Vendor Credits
    description: Manage vendor credits and applications
  - name: Vendor Returns
    description: Manage vendor returns and credit generation
  - name: Customer Returns
    description: Manage customer returns (sales returns), receiving, and restock behavior
  - name: Stock Snapshot
    description: Point-in-time stock snapshots with export support
  - name: Consumption
    description: Consumption reports and exports
  - name: Inventory Aging
    description: Cost-layer-based inventory aging reports
  - name: Bills Reports
    description: Accounts payable bills aging reports
  - name: Forecast
    description: Materialized forecast data
  - name: Reports
    description: Close the books, inventory discrepancy, transaction COGS, and EDI reports
  - name: Tags
    description: Add/remove tags across various resources
  - name: Custom Fields
    description: Get and set custom fields across various resources
  - name: Currency
    description: Currency configuration, exchange rates, and conversion
  - name: Integration Mappings
    description: Manage integration mappings for external systems
  - name: Integration Field Mappings
    description: Manage field-level mappings between Luminous and external systems
paths:
  /suppliers/{supplierId}:
    patch:
      tags:
        - Suppliers
      summary: Partially update a supplier
      description: >
        Partially update an existing supplier. Only the fields present in the
        request body are written; omitted fields are left unchanged, and a
        nullable field sent as `null` is cleared. At least one recognized
        supplier field must be supplied.


        Use `POST /suppliers/{supplierId}` when you want to replace the whole
        record instead.
      operationId: patchSupplier
      parameters:
        - name: supplierId
          in: path
          required: true
          schema:
            type: integer
          description: The unique identifier of the supplier
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              description: >
                Partial update. Only the fields you send are written; omitted
                fields are left unchanged. Send a nullable field as `null` to
                clear it. At least one recognized supplier field must be
                supplied.


                For a full replace of the supplier record, use `POST
                /suppliers/{supplierId}` instead.
              properties:
                name:
                  type: string
                  maxLength: 255
                  description: Supplier name. If supplied it must be a non-empty string.
                  example: Acme Manufacturing
                description:
                  type: string
                  nullable: true
                  description: Supplier description
                  example: Primary overseas supplier for apparel
                street_address:
                  type: string
                  maxLength: 255
                  nullable: true
                  example: 123 Industrial Way
                city:
                  type: string
                  maxLength: 255
                  nullable: true
                  example: Shenzhen
                state:
                  type: string
                  maxLength: 255
                  nullable: true
                  example: Guangdong
                zip:
                  type: string
                  maxLength: 255
                  nullable: true
                  example: '518000'
                country:
                  type: string
                  maxLength: 255
                  nullable: true
                  example: China
                factory_admin_id:
                  type: integer
                  nullable: true
                  description: >-
                    ID of the internal user to set as the primary admin for this
                    supplier
                  example: 100
                bank_name:
                  type: string
                  maxLength: 255
                  nullable: true
                  example: Bank of China
                routing_number:
                  type: string
                  maxLength: 255
                  nullable: true
                  example: '021000021'
                account_number:
                  type: string
                  maxLength: 255
                  nullable: true
                  example: '1234567890'
                swift_code:
                  type: string
                  maxLength: 255
                  nullable: true
                  example: BKCHCNBJ
                default_payment_term:
                  type: string
                  nullable: true
                  description: >-
                    Default payment term name. Must match one of the payment
                    term names configured in Luminous.
                  example: Net 30
                default_currency_code:
                  type: string
                  nullable: true
                  minLength: 3
                  maxLength: 3
                  description: >-
                    Default ISO 4217 currency code for this supplier (3
                    letters). Auto-applied to new purchase orders created for
                    the supplier.
                  example: USD
                contact_ids:
                  type: array
                  nullable: true
                  description: IDs of existing contacts to link to this supplier
                  items:
                    type: integer
                  example:
                    - 501
                    - 502
                default_logistic_code:
                  type: string
                  nullable: true
                  enum:
                    - fob
                    - exw
                    - cif
                    - ddp
                    - fca
                  description: >-
                    Incoterm applied to a purchase order raised for this
                    supplier when the order does not name one itself.
                  example: fob
                default_warehouse_id:
                  type: integer
                  nullable: true
                  description: >-
                    Warehouse a purchase order raised for this supplier defaults
                    to when the order does not name one. A warehouse id, as
                    returned by GET /warehouses.
                  example: 7
                default_order_type:
                  type: string
                  nullable: true
                  enum:
                    - INTERNAL_TRANSFER_ORDER
                    - DROP_SHIP_ORDER
                  description: >-
                    Order type a purchase order raised for this supplier
                    defaults to when the order does not name one.
                  example: DROP_SHIP_ORDER
                default_requested_ship_date_offset_days:
                  type: integer
                  nullable: true
                  description: >-
                    Whole calendar days (not business days) added to a purchase
                    order's order date to produce its requested ship date, when
                    the order does not carry one.
                  example: 14
                default_arrival_due_date_offset_days:
                  type: integer
                  nullable: true
                  description: >-
                    Whole calendar days (not business days) added to a purchase
                    order's order date to produce its arrival due date, when the
                    order does not carry one.
                  example: 30
                ship_to_addresses:
                  type: array
                  nullable: true
                  description: >
                    The supplier's saved ship-to address set. There is no
                    separate "default ship to" field — the default is the entry
                    flagged `is_default`, and the set is normalized so exactly
                    one carries the flag whenever it is non-empty.


                    Sending `ship_to_addresses` replaces rather than merges the
                    set (even an empty array writes it); omitting it leaves the
                    existing set untouched.
                  items:
                    type: object
                    properties:
                      is_default:
                        type: boolean
                        nullable: true
                        example: true
                      ship_to_name:
                        type: string
                        maxLength: 255
                        nullable: true
                        example: Main Warehouse
                      ship_to_company:
                        type: string
                        maxLength: 255
                        nullable: true
                        example: Acme Distribution
                      ship_to_phone:
                        type: string
                        maxLength: 255
                        nullable: true
                        example: +1 555 123 4567
                      ship_to_email:
                        type: string
                        maxLength: 255
                        nullable: true
                        example: receiving@acme.example
                      street_address_1:
                        type: string
                        maxLength: 255
                        nullable: true
                        example: 500 Distribution Blvd
                      street_address_2:
                        type: string
                        maxLength: 255
                        nullable: true
                        example: Suite 200
                      street_address_3:
                        type: string
                        maxLength: 255
                        nullable: true
                      city:
                        type: string
                        maxLength: 255
                        nullable: true
                        example: Dallas
                      state:
                        type: string
                        maxLength: 255
                        nullable: true
                        example: TX
                      zip:
                        type: string
                        maxLength: 255
                        nullable: true
                        example: '75201'
                      country:
                        type: string
                        maxLength: 255
                        nullable: true
                        example: USA
                custom_fields:
                  type: object
                  nullable: true
                  description: >
                    Custom field values as a `label => value` map, matching the
                    shape GET returns. Only fields defined for the supplier
                    object type are accepted; a label that is unknown, scoped to
                    another object type, or a case-variant duplicate is rejected
                    with a 422. Set a value to `null` to clear that field.


                    Sending `custom_fields` replaces rather than merges;
                    omitting it leaves the existing values untouched.
                  example:
                    Region: Southwest
                    Preferred Carrier: UPS
      responses:
        '200':
          description: Supplier successfully updated
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: object
                    properties:
                      id:
                        type: integer
                        description: Unique identifier for the supplier
                        example: 42
                      status:
                        type: integer
                        description: Numeric status flag (1 = active)
                        example: 1
                      created_at:
                        type: string
                        format: date-time
                        description: When the supplier was created
                        example: '2026-04-20T14:30:00Z'
                      updated_at:
                        type: string
                        format: date-time
                        description: When the supplier was last updated
                        example: '2026-04-20T14:30:00Z'
                      created_by:
                        type: integer
                        nullable: true
                        description: ID of the user that created this supplier
                        example: 100
                      updated_by:
                        type: integer
                        nullable: true
                        description: ID of the user that last updated this supplier
                        example: 100
                      name:
                        type: string
                        description: Supplier name
                        example: Acme Manufacturing
                      description:
                        type: string
                        nullable: true
                        description: Supplier description
                        example: Primary overseas supplier for apparel
                      street_address:
                        type: string
                        nullable: true
                        example: 123 Industrial Way
                      city:
                        type: string
                        nullable: true
                        example: Shenzhen
                      state:
                        type: string
                        nullable: true
                        example: Guangdong
                      zip:
                        type: string
                        nullable: true
                        example: '518000'
                      country:
                        type: string
                        nullable: true
                        example: China
                      factory_admin_id:
                        type: integer
                        nullable: true
                        description: >-
                          ID of the internal user acting as the primary admin
                          for this supplier
                        example: 100
                      supplier_admin_id:
                        type: integer
                        nullable: true
                        description: Alias of `factory_admin_id`
                        example: 100
                      contact_name:
                        type: string
                        nullable: true
                        description: >-
                          Legacy single-contact name (use `contacts` for the
                          full list)
                        example: Jane Doe
                      contact_email:
                        type: string
                        format: email
                        nullable: true
                        description: >-
                          Legacy single-contact email (use `contacts` for the
                          full list)
                        example: jane@acme.example
                      contact_phone:
                        type: string
                        nullable: true
                        description: >-
                          Legacy single-contact phone (use `contacts` for the
                          full list)
                        example: +86 755 1234 5678
                      bank_name:
                        type: string
                        nullable: true
                        example: Bank of China
                      routing_number:
                        type: string
                        nullable: true
                        example: '021000021'
                      account_number:
                        type: string
                        nullable: true
                        example: '1234567890'
                      swift_code:
                        type: string
                        nullable: true
                        example: BKCHCNBJ
                      default_payment_term:
                        type: string
                        nullable: true
                        description: >-
                          Default payment term name, matches the set available
                          to companies
                        example: Net 30
                      default_currency_code:
                        type: string
                        nullable: true
                        description: >-
                          Default ISO 4217 currency code for this supplier.
                          Auto-applied to new purchase orders created for the
                          supplier.
                        example: USD
                      default_logistic_code:
                        type: string
                        nullable: true
                        description: >-
                          Incoterm applied to a purchase order raised for this
                          supplier when the order does not name one itself. One
                          of "fob", "exw", "cif", "ddp" or "fca". Null when the
                          supplier has no Incoterm default.
                        example: fob
                      default_warehouse_id:
                        type: integer
                        nullable: true
                        description: >-
                          Warehouse a purchase order raised for this supplier
                          defaults to when the order does not name one. A
                          warehouse id, as returned by GET /warehouses. Null
                          when the supplier has no warehouse default.
                        example: 7
                      default_order_type:
                        type: string
                        nullable: true
                        description: >-
                          Order type a purchase order raised for this supplier
                          defaults to when the order does not name one. Either
                          "INTERNAL_TRANSFER_ORDER" or "DROP_SHIP_ORDER". Null
                          when the supplier has no order type default.
                        example: DROP_SHIP_ORDER
                      default_requested_ship_date_offset_days:
                        type: integer
                        nullable: true
                        description: >-
                          Whole calendar days (not business days) added to a
                          purchase order's order date to produce its requested
                          ship date, when the order does not carry one. Null
                          when the supplier has no requested ship date default.
                        example: 14
                      default_arrival_due_date_offset_days:
                        type: integer
                        nullable: true
                        description: >-
                          Whole calendar days (not business days) added to a
                          purchase order's order date to produce its arrival due
                          date, when the order does not carry one. Null when the
                          supplier has no arrival due date default.
                        example: 30
                      custom_fields:
                        type: object
                        description: >-
                          Map of the supplier's custom field values as label =>
                          value pairs. Only fields defined for the supplier
                          object type appear. Always a JSON object; empty when
                          no custom fields are set. Field definitions are
                          available via GET /custom-fields?object_type=supplier.
                          Writable via POST — see the create/update request
                          body.
                        example:
                          Region: Southwest
                          Preferred Carrier: UPS
                          Onboarded On: '2025-03-14'
                      ship_to_addresses:
                        type: array
                        nullable: true
                        description: >-
                          Addresses saved against this supplier for shipping
                          purchase orders to (only present when the relation is
                          loaded). The one entry with `is_default` true is the
                          address a purchase order raised for this supplier
                          ships to when the order does not carry its own;
                          exactly one entry carries the flag whenever the set is
                          non-empty.
                        items:
                          type: object
                          properties:
                            id:
                              type: integer
                              example: 88
                            is_default:
                              type: boolean
                              example: true
                            ship_to_name:
                              type: string
                              nullable: true
                              example: Main Warehouse
                            ship_to_company:
                              type: string
                              nullable: true
                              example: Acme Distribution
                            ship_to_phone:
                              type: string
                              nullable: true
                              example: +1 555 123 4567
                            ship_to_email:
                              type: string
                              nullable: true
                              example: receiving@acme.example
                            street_address_1:
                              type: string
                              nullable: true
                              example: 500 Distribution Blvd
                            street_address_2:
                              type: string
                              nullable: true
                              example: Suite 200
                            street_address_3:
                              type: string
                              nullable: true
                            city:
                              type: string
                              nullable: true
                              example: Dallas
                            state:
                              type: string
                              nullable: true
                              example: TX
                            zip:
                              type: string
                              nullable: true
                              example: '75201'
                            country:
                              type: string
                              nullable: true
                              example: USA
                      contacts:
                        type: array
                        nullable: true
                        description: >-
                          Linked contacts (only present when the relation is
                          loaded)
                        items:
                          type: object
                          properties:
                            id:
                              type: integer
                              example: 501
                            name:
                              type: string
                              nullable: true
                              example: Jane Doe
                            email:
                              type: string
                              format: email
                              nullable: true
                              example: jane@acme.example
                            phone:
                              type: string
                              nullable: true
                              example: +86 755 1234 5678
                    required:
                      - id
                      - name
                      - status
        '401':
          description: Authentication credentials were missing or invalid
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: string
                    example: Unauthorized
                  message:
                    type: string
                    example: Authentication credentials are missing or invalid
                  status_code:
                    type: integer
                    example: 401
        '403':
          description: You do not have permission to perform this action
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: string
                    example: Forbidden
                  message:
                    type: string
                    example: You do not have permission to access this resource
                  status_code:
                    type: integer
                    example: 403
        '404':
          description: The requested resource was not found
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: string
                    example: Not Found
                  message:
                    type: string
                    example: The requested resource could not be found
                  status_code:
                    type: integer
                    example: 404
        '422':
          description: Validation error
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
                  errors:
                    type: object
                    additionalProperties:
                      type: array
                      items:
                        type: string
      security:
        - BearerAuth: []
components:
  securitySchemes:
    BearerAuth:
      type: http
      scheme: bearer
      description: >-
        Authenticate using a bearer token. To create a token, navigate to
        /settings/api-tokens and click Create API Token.

````