SOS Inventory MCP by usefulapi

List or search inventory items (products, assemblies, services...) with SKU, type, quantities (onhand, available, on sales/purchase orders) and prices. Filter by free text, SKU, category, type, tags, ids or update time; pass location to see quantities at one location. GET /api/v2/item.

{
  "type": "object",
  "properties": {
    "query": {
      "description": "Free-text search over item name, SKU, description and similar fields.",
      "type": "string",
      "minLength": 1,
      "maxLength": 200
    },
    "sku": {
      "description": "Exact SKU.",
      "type": "string",
      "minLength": 1,
      "maxLength": 200
    },
    "category": {
      "description": "Category name.",
      "type": "string",
      "minLength": 1,
      "maxLength": 200
    },
    "type": {
      "description": "Item type: \"Inventory Item\", \"Non-inventory\", \"Category\", \"Expense\", \"Assembly\", \"Kit\", \"Service\", \"Labor\", \"Overhead\" or \"Other\".",
      "type": "string",
      "minLength": 1,
      "maxLength": 50
    },
    "tags": {
      "description": "Comma-separated tags; records matching them are returned.",
      "type": "string",
      "minLength": 1,
      "maxLength": 200
    },
    "ids": {
      "description": "Only these item ids.",
      "minItems": 1,
      "maxItems": 100,
      "type": "array",
      "items": {
        "type": "integer",
        "exclusiveMinimum": 0,
        "maximum": 9007199254740991
      }
    },
    "location": {
      "description": "Location name: quantities then reflect that location.",
      "type": "string",
      "minLength": 1,
      "maxLength": 200
    },
    "updated_since": {
      "description": "Only items created or updated since this local date-time (YYYY-MM-DDTHH:MM:SS).",
      "type": "string",
      "pattern": "^\\d{4}-\\d{2}-\\d{2}T\\d{2}:\\d{2}:\\d{2}$"
    },
    "summary": {
      "description": "true (default) = summary records without line items and long sub-lists; false = full records.",
      "type": "boolean"
    },
    "start": {
      "description": "1-based row number to start at (default 1). Pass next_start from the previous reply to read the next page.",
      "type": "integer",
      "exclusiveMinimum": 0,
      "maximum": 9007199254740991
    },
    "max_results": {
      "description": "Rows per call, 1-200 (default 50).",
      "type": "integer",
      "exclusiveMinimum": 0,
      "maximum": 200
    }
  },
  "$schema": "https://json-schema.org/draft/2020-12/schema"
}

One item by id with all fields: quantities, prices, accounts, vendor, category, units of measure, price tiers, custom fields. GET /api/v2/item/{id}.

{
  "type": "object",
  "properties": {
    "id": {
      "type": "integer",
      "exclusiveMinimum": 0,
      "maximum": 9007199254740991,
      "description": "SOS item id (from sosinventory_list_items)."
    },
    "location": {
      "description": "Location name: quantities then reflect that location.",
      "type": "string",
      "minLength": 1,
      "maxLength": 200
    }
  },
  "required": [
    "id"
  ],
  "$schema": "https://json-schema.org/draft/2020-12/schema"
}

The bill of materials of an assembly item: component items, quantities and costs. GET /api/v2/item/{id}/bom.

{
  "type": "object",
  "properties": {
    "id": {
      "type": "integer",
      "exclusiveMinimum": 0,
      "maximum": 9007199254740991,
      "description": "SOS item id of the assembly."
    }
  },
  "required": [
    "id"
  ],
  "$schema": "https://json-schema.org/draft/2020-12/schema"
}

List or search customers with contact details, billing/shipping addresses, terms, sales rep and credit-hold flag. Filter by name/notes text, name, email or update time. GET /api/v2/customer.

{
  "type": "object",
  "properties": {
    "query": {
      "description": "Free-text search over the customer name, full name and notes (use `email` for an email lookup).",
      "type": "string",
      "minLength": 1,
      "maxLength": 200
    },
    "name": {
      "description": "Match on the customer name or full name.",
      "type": "string",
      "minLength": 1,
      "maxLength": 200
    },
    "email": {
      "description": "Match on the customer email.",
      "type": "string",
      "minLength": 1,
      "maxLength": 200
    },
    "updated_since": {
      "description": "Only customers created or updated since this local date-time (YYYY-MM-DDTHH:MM:SS).",
      "type": "string",
      "pattern": "^\\d{4}-\\d{2}-\\d{2}T\\d{2}:\\d{2}:\\d{2}$"
    },
    "summary": {
      "description": "true (default) = summary records without line items and long sub-lists; false = full records.",
      "type": "boolean"
    },
    "start": {
      "description": "1-based row number to start at (default 1). Pass next_start from the previous reply to read the next page.",
      "type": "integer",
      "exclusiveMinimum": 0,
      "maximum": 9007199254740991
    },
    "max_results": {
      "description": "Rows per call, 1-200 (default 50).",
      "type": "integer",
      "exclusiveMinimum": 0,
      "maximum": 200
    }
  },
  "$schema": "https://json-schema.org/draft/2020-12/schema"
}

One customer by id with all fields (addresses, contact, terms, price tier, custom fields). GET /api/v2/customer/{id}.

{
  "type": "object",
  "properties": {
    "id": {
      "type": "integer",
      "exclusiveMinimum": 0,
      "maximum": 9007199254740991,
      "description": "SOS customer id (from sosinventory_list_customers)."
    }
  },
  "required": [
    "id"
  ],
  "$schema": "https://json-schema.org/draft/2020-12/schema"
}

List or search vendors (suppliers) by name or notes, with contact details, address, terms and account number. GET /api/v2/vendor.

{
  "type": "object",
  "properties": {
    "query": {
      "description": "Free-text search over the vendor name and notes (SOS has no email or phone filter for vendors).",
      "type": "string",
      "minLength": 1,
      "maxLength": 200
    },
    "updated_since": {
      "description": "Only vendors created or updated since this local date-time (YYYY-MM-DDTHH:MM:SS).",
      "type": "string",
      "pattern": "^\\d{4}-\\d{2}-\\d{2}T\\d{2}:\\d{2}:\\d{2}$"
    },
    "summary": {
      "description": "true (default) = summary records without line items and long sub-lists; false = full records.",
      "type": "boolean"
    },
    "start": {
      "description": "1-based row number to start at (default 1). Pass next_start from the previous reply to read the next page.",
      "type": "integer",
      "exclusiveMinimum": 0,
      "maximum": 9007199254740991
    },
    "max_results": {
      "description": "Rows per call, 1-200 (default 50).",
      "type": "integer",
      "exclusiveMinimum": 0,
      "maximum": 200
    }
  },
  "$schema": "https://json-schema.org/draft/2020-12/schema"
}

One vendor by id with all fields. GET /api/v2/vendor/{id}.

{
  "type": "object",
  "properties": {
    "id": {
      "type": "integer",
      "exclusiveMinimum": 0,
      "maximum": 9007199254740991,
      "description": "SOS vendor id (from sosinventory_list_vendors)."
    }
  },
  "required": [
    "id"
  ],
  "$schema": "https://json-schema.org/draft/2020-12/schema"
}

List or search sales orders with customer, dates, totals, order stage, channel and (with summary=false) line items with shipped/invoiced quantities. GET /api/v2/salesorder.

{
  "type": "object",
  "properties": {
    "query": {
      "description": "Free-text search over number, customer/vendor name, reference fields and similar.",
      "type": "string",
      "minLength": 1,
      "maxLength": 200
    },
    "from": {
      "description": "Transaction date on or after this (YYYY-MM-DDTHH:MM:SS). `to` is optional.",
      "type": "string",
      "pattern": "^\\d{4}-\\d{2}-\\d{2}T\\d{2}:\\d{2}:\\d{2}$"
    },
    "to": {
      "description": "Transaction date on or before this (YYYY-MM-DDTHH:MM:SS). `from` is optional.",
      "type": "string",
      "pattern": "^\\d{4}-\\d{2}-\\d{2}T\\d{2}:\\d{2}:\\d{2}$"
    },
    "updated_since": {
      "description": "Only transactions created or updated since this local date-time (YYYY-MM-DDTHH:MM:SS).",
      "type": "string",
      "pattern": "^\\d{4}-\\d{2}-\\d{2}T\\d{2}:\\d{2}:\\d{2}$"
    },
    "summary": {
      "description": "true (default) = summary records without line items and long sub-lists; false = full records.",
      "type": "boolean"
    },
    "start": {
      "description": "1-based row number to start at (default 1). Pass next_start from the previous reply to read the next page.",
      "type": "integer",
      "exclusiveMinimum": 0,
      "maximum": 9007199254740991
    },
    "max_results": {
      "description": "Rows per call, 1-200 (default 50).",
      "type": "integer",
      "exclusiveMinimum": 0,
      "maximum": 200
    },
    "status": {
      "description": "Open or closed transactions.",
      "type": "string",
      "enum": [
        "open",
        "closed"
      ]
    },
    "location": {
      "description": "Location name.",
      "type": "string",
      "minLength": 1,
      "maxLength": 200
    },
    "channel": {
      "description": "Channel name.",
      "type": "string",
      "minLength": 1,
      "maxLength": 200
    },
    "order_stage": {
      "description": "Order stage name.",
      "type": "string",
      "minLength": 1,
      "maxLength": 200
    }
  },
  "$schema": "https://json-schema.org/draft/2020-12/schema"
}

One sales order by id with all fields and line items. GET /api/v2/salesorder/{id}.

{
  "type": "object",
  "properties": {
    "id": {
      "type": "integer",
      "exclusiveMinimum": 0,
      "maximum": 9007199254740991,
      "description": "SOS sales order id (from sosinventory_list_sales_orders; not the order number)."
    }
  },
  "required": [
    "id"
  ],
  "$schema": "https://json-schema.org/draft/2020-12/schema"
}

List or search purchase orders with vendor, dates, expected receipt date, totals and (with summary=false) line items with received quantities. GET /api/v2/purchaseorder.

{
  "type": "object",
  "properties": {
    "query": {
      "description": "Free-text search over number, customer/vendor name, reference fields and similar.",
      "type": "string",
      "minLength": 1,
      "maxLength": 200
    },
    "from": {
      "description": "Transaction date on or after this (YYYY-MM-DDTHH:MM:SS). `to` is optional.",
      "type": "string",
      "pattern": "^\\d{4}-\\d{2}-\\d{2}T\\d{2}:\\d{2}:\\d{2}$"
    },
    "to": {
      "description": "Transaction date on or before this (YYYY-MM-DDTHH:MM:SS). `from` is optional.",
      "type": "string",
      "pattern": "^\\d{4}-\\d{2}-\\d{2}T\\d{2}:\\d{2}:\\d{2}$"
    },
    "updated_since": {
      "description": "Only transactions created or updated since this local date-time (YYYY-MM-DDTHH:MM:SS).",
      "type": "string",
      "pattern": "^\\d{4}-\\d{2}-\\d{2}T\\d{2}:\\d{2}:\\d{2}$"
    },
    "summary": {
      "description": "true (default) = summary records without line items and long sub-lists; false = full records.",
      "type": "boolean"
    },
    "start": {
      "description": "1-based row number to start at (default 1). Pass next_start from the previous reply to read the next page.",
      "type": "integer",
      "exclusiveMinimum": 0,
      "maximum": 9007199254740991
    },
    "max_results": {
      "description": "Rows per call, 1-200 (default 50).",
      "type": "integer",
      "exclusiveMinimum": 0,
      "maximum": 200
    },
    "status": {
      "description": "Open or closed transactions.",
      "type": "string",
      "enum": [
        "open",
        "closed"
      ]
    }
  },
  "$schema": "https://json-schema.org/draft/2020-12/schema"
}

One purchase order by id with all fields and line items. GET /api/v2/purchaseorder/{id}.

{
  "type": "object",
  "properties": {
    "id": {
      "type": "integer",
      "exclusiveMinimum": 0,
      "maximum": 9007199254740991,
      "description": "SOS purchase order id (from sosinventory_list_purchase_orders; not the PO number)."
    }
  },
  "required": [
    "id"
  ],
  "$schema": "https://json-schema.org/draft/2020-12/schema"
}

List any SOS transaction type: invoices, estimates, sales receipts, item receipts, shipments, pick tickets, work orders, builds, adjustments, transfers, RMAs, returns, returns to vendor, rentals, rental returns and processes. Filters: query, date range, updated_since; status (open/closed; invoices voided/notvoided; estimates accepted/pending/closed/rejected; not available for transfers, shipments, builds, returns, item receipts, processes); location (transfers, rentals and rental returns take from_location/to_location instead). GET /api/v2/{type}.

{
  "type": "object",
  "properties": {
    "type": {
      "type": "string",
      "enum": [
        "salesorder",
        "estimate",
        "invoice",
        "salesreceipt",
        "purchaseorder",
        "itemreceipt",
        "shipment",
        "pickticket",
        "workorder",
        "build",
        "adjustment",
        "transfer",
        "rma",
        "return",
        "returntovendor",
        "rental",
        "rentalreturn",
        "process"
      ],
      "description": "Transaction type (the API endpoint name)."
    },
    "query": {
      "description": "Free-text search over number, customer/vendor name, reference fields and similar.",
      "type": "string",
      "minLength": 1,
      "maxLength": 200
    },
    "from": {
      "description": "Transaction date on or after this (YYYY-MM-DDTHH:MM:SS). `to` is optional.",
      "type": "string",
      "pattern": "^\\d{4}-\\d{2}-\\d{2}T\\d{2}:\\d{2}:\\d{2}$"
    },
    "to": {
      "description": "Transaction date on or before this (YYYY-MM-DDTHH:MM:SS). `from` is optional.",
      "type": "string",
      "pattern": "^\\d{4}-\\d{2}-\\d{2}T\\d{2}:\\d{2}:\\d{2}$"
    },
    "updated_since": {
      "description": "Only transactions created or updated since this local date-time (YYYY-MM-DDTHH:MM:SS).",
      "type": "string",
      "pattern": "^\\d{4}-\\d{2}-\\d{2}T\\d{2}:\\d{2}:\\d{2}$"
    },
    "summary": {
      "description": "true (default) = summary records without line items and long sub-lists; false = full records.",
      "type": "boolean"
    },
    "start": {
      "description": "1-based row number to start at (default 1). Pass next_start from the previous reply to read the next page.",
      "type": "integer",
      "exclusiveMinimum": 0,
      "maximum": 9007199254740991
    },
    "max_results": {
      "description": "Rows per call, 1-200 (default 50).",
      "type": "integer",
      "exclusiveMinimum": 0,
      "maximum": 200
    },
    "status": {
      "description": "Status filter; the allowed values depend on the type (see the tool description).",
      "type": "string",
      "enum": [
        "open",
        "closed",
        "voided",
        "notvoided",
        "accepted",
        "pending",
        "rejected"
      ]
    },
    "location": {
      "description": "Location name.",
      "type": "string",
      "minLength": 1,
      "maxLength": 200
    },
    "from_location": {
      "description": "Transfers, rentals, rental returns: the source location name.",
      "type": "string",
      "minLength": 1,
      "maxLength": 200
    },
    "to_location": {
      "description": "Transfers, rentals, rental returns: the destination location name.",
      "type": "string",
      "minLength": 1,
      "maxLength": 200
    }
  },
  "required": [
    "type"
  ],
  "$schema": "https://json-schema.org/draft/2020-12/schema"
}

One transaction of any type by id, with all fields and line items. GET /api/v2/{type}/{id}.

{
  "type": "object",
  "properties": {
    "type": {
      "type": "string",
      "enum": [
        "salesorder",
        "estimate",
        "invoice",
        "salesreceipt",
        "purchaseorder",
        "itemreceipt",
        "shipment",
        "pickticket",
        "workorder",
        "build",
        "adjustment",
        "transfer",
        "rma",
        "return",
        "returntovendor",
        "rental",
        "rentalreturn",
        "process"
      ],
      "description": "Transaction type (the API endpoint name)."
    },
    "id": {
      "type": "integer",
      "exclusiveMinimum": 0,
      "maximum": 9007199254740991,
      "description": "SOS record id (from sosinventory_list_transactions)."
    }
  },
  "required": [
    "type",
    "id"
  ],
  "$schema": "https://json-schema.org/draft/2020-12/schema"
}

List a configuration or reference table: locations, channels, classes, departments, payment terms, tax codes, sales reps, ship methods, payment methods, priorities, order stages, price tiers, units of measure, users (id, name, email), accounts, custom fields, warranties, bins, workers, work centers, jobs, lots or serial numbers. Use it to find the ids and names that the create tools reference. GET /api/v2/{type}.

{
  "type": "object",
  "properties": {
    "type": {
      "type": "string",
      "enum": [
        "location",
        "channel",
        "class",
        "department",
        "terms",
        "taxcode",
        "salesrep",
        "shipmethod",
        "paymentmethod",
        "priority",
        "orderstage",
        "pricetier",
        "uom",
        "user",
        "account",
        "customfield",
        "warranty",
        "bins",
        "worker",
        "workcenter",
        "job",
        "lot",
        "serial"
      ],
      "description": "Which table to list (the API endpoint name)."
    },
    "query": {
      "description": "Free-text filter (supported by some tables, e.g. job, lot, serial).",
      "type": "string",
      "minLength": 1,
      "maxLength": 200
    },
    "start": {
      "description": "1-based row number to start at (default 1). Pass next_start from the previous reply to read the next page.",
      "type": "integer",
      "exclusiveMinimum": 0,
      "maximum": 9007199254740991
    },
    "max_results": {
      "description": "Rows per call, 1-200 (default 50).",
      "type": "integer",
      "exclusiveMinimum": 0,
      "maximum": 200
    }
  },
  "required": [
    "type"
  ],
  "$schema": "https://json-schema.org/draft/2020-12/schema"
}

WRITE: creates a new customer record in SOS Inventory. Only name is required. Check sosinventory_list_customers first so you do not create a duplicate. POST /api/v2/customer.

{
  "type": "object",
  "properties": {
    "name": {
      "type": "string",
      "minLength": 1,
      "maxLength": 300,
      "description": "Customer name (how it is looked up in SOS)."
    },
    "company_name": {
      "type": "string",
      "minLength": 1,
      "maxLength": 300
    },
    "email": {
      "type": "string",
      "minLength": 1,
      "maxLength": 300
    },
    "phone": {
      "type": "string",
      "minLength": 1,
      "maxLength": 100
    },
    "notes": {
      "description": "Internal notes (not shown to the customer).",
      "type": "string",
      "maxLength": 4000
    },
    "terms": {
      "description": "Payment terms, e.g. {name: 'Net 30'} (see sosinventory_list_reference_data type=terms).",
      "type": "object",
      "properties": {
        "id": {
          "type": "integer",
          "exclusiveMinimum": 0,
          "maximum": 9007199254740991
        },
        "name": {
          "type": "string",
          "minLength": 1,
          "maxLength": 300
        }
      }
    },
    "sales_rep": {
      "description": "Sales rep (type=salesrep).",
      "type": "object",
      "properties": {
        "id": {
          "type": "integer",
          "exclusiveMinimum": 0,
          "maximum": 9007199254740991
        },
        "name": {
          "type": "string",
          "minLength": 1,
          "maxLength": 300
        }
      }
    },
    "billing": {
      "description": "Billing address.",
      "type": "object",
      "properties": {
        "line1": {
          "type": "string",
          "minLength": 1,
          "maxLength": 300
        },
        "line2": {
          "type": "string",
          "minLength": 1,
          "maxLength": 300
        },
        "city": {
          "type": "string",
          "minLength": 1,
          "maxLength": 100
        },
        "stateProvince": {
          "type": "string",
          "minLength": 1,
          "maxLength": 100
        },
        "postalCode": {
          "type": "string",
          "minLength": 1,
          "maxLength": 30
        },
        "country": {
          "type": "string",
          "minLength": 1,
          "maxLength": 100
        }
      }
    }
  },
  "required": [
    "name"
  ],
  "$schema": "https://json-schema.org/draft/2020-12/schema"
}

WRITE: creates a new vendor (supplier) record in SOS Inventory. Only name is required. Check sosinventory_list_vendors first to avoid a duplicate. POST /api/v2/vendor.

{
  "type": "object",
  "properties": {
    "name": {
      "type": "string",
      "minLength": 1,
      "maxLength": 300,
      "description": "Vendor name (how it is looked up in SOS)."
    },
    "company_name": {
      "type": "string",
      "minLength": 1,
      "maxLength": 300
    },
    "email": {
      "type": "string",
      "minLength": 1,
      "maxLength": 300
    },
    "phone": {
      "type": "string",
      "minLength": 1,
      "maxLength": 100
    },
    "account_number": {
      "description": "Your account number with this vendor.",
      "type": "string",
      "minLength": 1,
      "maxLength": 100
    },
    "notes": {
      "description": "Internal notes.",
      "type": "string",
      "maxLength": 4000
    },
    "terms": {
      "description": "Payment terms (type=terms).",
      "type": "object",
      "properties": {
        "id": {
          "type": "integer",
          "exclusiveMinimum": 0,
          "maximum": 9007199254740991
        },
        "name": {
          "type": "string",
          "minLength": 1,
          "maxLength": 300
        }
      }
    },
    "address": {
      "description": "Vendor address.",
      "type": "object",
      "properties": {
        "line1": {
          "type": "string",
          "minLength": 1,
          "maxLength": 300
        },
        "line2": {
          "type": "string",
          "minLength": 1,
          "maxLength": 300
        },
        "city": {
          "type": "string",
          "minLength": 1,
          "maxLength": 100
        },
        "stateProvince": {
          "type": "string",
          "minLength": 1,
          "maxLength": 100
        },
        "postalCode": {
          "type": "string",
          "minLength": 1,
          "maxLength": 30
        },
        "country": {
          "type": "string",
          "minLength": 1,
          "maxLength": 100
        }
      }
    }
  },
  "required": [
    "name"
  ],
  "$schema": "https://json-schema.org/draft/2020-12/schema"
}

WRITE: creates a new inventory item. Optionally books initial stock: SOS then creates an inventory adjustment for the quantity at the given location. Item names must be unique within their category: check sosinventory_list_items first. POST /api/v2/item.

{
  "type": "object",
  "properties": {
    "name": {
      "type": "string",
      "minLength": 1,
      "maxLength": 300,
      "description": "Item name."
    },
    "type": {
      "description": "Item type (SOS's default applies when omitted).",
      "type": "string",
      "enum": [
        "Inventory Item",
        "Non-inventory",
        "Expense",
        "Assembly",
        "Kit",
        "Service",
        "Labor",
        "Overhead",
        "Other"
      ]
    },
    "sku": {
      "type": "string",
      "minLength": 1,
      "maxLength": 100
    },
    "description": {
      "type": "string",
      "maxLength": 2000
    },
    "barcode": {
      "type": "string",
      "minLength": 1,
      "maxLength": 100
    },
    "category": {
      "description": "Existing category (a category cannot be created here).",
      "type": "object",
      "properties": {
        "id": {
          "type": "integer",
          "exclusiveMinimum": 0,
          "maximum": 9007199254740991
        },
        "name": {
          "type": "string",
          "minLength": 1,
          "maxLength": 300
        }
      }
    },
    "vendor": {
      "description": "Default vendor.",
      "type": "object",
      "properties": {
        "id": {
          "type": "integer",
          "exclusiveMinimum": 0,
          "maximum": 9007199254740991
        },
        "name": {
          "type": "string",
          "minLength": 1,
          "maxLength": 300
        }
      }
    },
    "base_sales_price": {
      "description": "Sales price per unit.",
      "type": "number",
      "minimum": 0
    },
    "purchase_cost": {
      "description": "Purchase cost per unit.",
      "type": "number",
      "minimum": 0
    },
    "reorder_point": {
      "type": "number",
      "minimum": 0
    },
    "taxable": {
      "type": "boolean"
    },
    "initial_quantity": {
      "description": "Opening stock. Needs initial_location; SOS books an adjustment for it.",
      "type": "number",
      "exclusiveMinimum": 0
    },
    "initial_value": {
      "description": "Total value of the opening stock.",
      "type": "number",
      "minimum": 0
    },
    "initial_quantity_date": {
      "description": "Date of the opening stock (YYYY-MM-DDTHH:MM:SS).",
      "type": "string",
      "pattern": "^\\d{4}-\\d{2}-\\d{2}T\\d{2}:\\d{2}:\\d{2}$"
    },
    "initial_location": {
      "description": "Location name that receives the opening stock (type=location).",
      "type": "string",
      "minLength": 1,
      "maxLength": 300
    }
  },
  "required": [
    "name"
  ],
  "$schema": "https://json-schema.org/draft/2020-12/schema"
}

WRITE: creates a new sales order for an EXISTING customer with line items for existing items (a customer or item cannot be created inside an order: use the create tools first). The order number is assigned automatically (SOS auto-numbering) unless you pass one. Confirm the customer, items, quantities and prices with the user before calling. POST /api/v2/salesorder.

{
  "type": "object",
  "properties": {
    "customer": {
      "type": "object",
      "properties": {
        "id": {
          "type": "integer",
          "exclusiveMinimum": 0,
          "maximum": 9007199254740991
        },
        "name": {
          "type": "string",
          "minLength": 1,
          "maxLength": 300
        }
      },
      "description": "Existing customer (sosinventory_list_customers)."
    },
    "lines": {
      "minItems": 1,
      "maxItems": 100,
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "item": {
            "type": "object",
            "properties": {
              "id": {
                "type": "integer",
                "exclusiveMinimum": 0,
                "maximum": 9007199254740991
              },
              "name": {
                "type": "string",
                "minLength": 1,
                "maxLength": 300
              }
            },
            "description": "Item (by id or name; see sosinventory_list_items)."
          },
          "quantity": {
            "type": "number",
            "exclusiveMinimum": 0,
            "description": "Quantity."
          },
          "unit_price": {
            "description": "Price per unit (sales: must not be below the item's minimum price).",
            "type": "number",
            "minimum": 0
          },
          "description": {
            "type": "string",
            "maxLength": 2000
          }
        },
        "required": [
          "item",
          "quantity"
        ]
      },
      "description": "Order lines."
    },
    "date": {
      "description": "Order date (YYYY-MM-DDTHH:MM:SS); defaults to now in SOS.",
      "type": "string",
      "pattern": "^\\d{4}-\\d{2}-\\d{2}T\\d{2}:\\d{2}:\\d{2}$"
    },
    "number": {
      "description": "Order number; leave out for SOS's automatic numbering.",
      "type": "string",
      "minLength": 1,
      "maxLength": 50
    },
    "location": {
      "description": "Location (type=location).",
      "type": "object",
      "properties": {
        "id": {
          "type": "integer",
          "exclusiveMinimum": 0,
          "maximum": 9007199254740991
        },
        "name": {
          "type": "string",
          "minLength": 1,
          "maxLength": 300
        }
      }
    },
    "customer_po": {
      "description": "Customer purchase order reference.",
      "type": "string",
      "minLength": 1,
      "maxLength": 100
    },
    "comment": {
      "description": "Internal comment (not shown to the customer).",
      "type": "string",
      "maxLength": 4000
    },
    "customer_message": {
      "description": "Message shown to the customer.",
      "type": "string",
      "maxLength": 2000
    }
  },
  "required": [
    "customer",
    "lines"
  ],
  "$schema": "https://json-schema.org/draft/2020-12/schema"
}

WRITE: creates a new purchase order to an EXISTING vendor with line items for existing items. The PO number is assigned automatically unless you pass one. Confirm the vendor, items, quantities and costs with the user before calling. POST /api/v2/purchaseorder.

{
  "type": "object",
  "properties": {
    "vendor": {
      "type": "object",
      "properties": {
        "id": {
          "type": "integer",
          "exclusiveMinimum": 0,
          "maximum": 9007199254740991
        },
        "name": {
          "type": "string",
          "minLength": 1,
          "maxLength": 300
        }
      },
      "description": "Existing vendor (sosinventory_list_vendors)."
    },
    "lines": {
      "minItems": 1,
      "maxItems": 100,
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "item": {
            "type": "object",
            "properties": {
              "id": {
                "type": "integer",
                "exclusiveMinimum": 0,
                "maximum": 9007199254740991
              },
              "name": {
                "type": "string",
                "minLength": 1,
                "maxLength": 300
              }
            },
            "description": "Item (by id or name; see sosinventory_list_items)."
          },
          "quantity": {
            "type": "number",
            "exclusiveMinimum": 0,
            "description": "Quantity."
          },
          "unit_price": {
            "description": "Price per unit (sales: must not be below the item's minimum price).",
            "type": "number",
            "minimum": 0
          },
          "description": {
            "type": "string",
            "maxLength": 2000
          }
        },
        "required": [
          "item",
          "quantity"
        ]
      },
      "description": "PO lines (unit_price = purchase cost per unit)."
    },
    "date": {
      "description": "Order date (YYYY-MM-DDTHH:MM:SS); defaults to now in SOS.",
      "type": "string",
      "pattern": "^\\d{4}-\\d{2}-\\d{2}T\\d{2}:\\d{2}:\\d{2}$"
    },
    "number": {
      "description": "PO number; leave out for automatic numbering.",
      "type": "string",
      "minLength": 1,
      "maxLength": 50
    },
    "location": {
      "description": "Location that receives the goods (type=location).",
      "type": "object",
      "properties": {
        "id": {
          "type": "integer",
          "exclusiveMinimum": 0,
          "maximum": 9007199254740991
        },
        "name": {
          "type": "string",
          "minLength": 1,
          "maxLength": 300
        }
      }
    },
    "expected_date": {
      "description": "Expected receipt date (YYYY-MM-DDTHH:MM:SS).",
      "type": "string",
      "pattern": "^\\d{4}-\\d{2}-\\d{2}T\\d{2}:\\d{2}:\\d{2}$"
    },
    "comment": {
      "description": "Internal comment.",
      "type": "string",
      "maxLength": 4000
    },
    "vendor_message": {
      "description": "Message to the vendor.",
      "type": "string",
      "maxLength": 2000
    }
  },
  "required": [
    "vendor",
    "lines"
  ],
  "$schema": "https://json-schema.org/draft/2020-12/schema"
}