Vendors — Reference
The Vendors surface is the supplier-records plane for SGEN commerce. It owns the catalog of vendor records — business contact information, vendor-catalog product bindings, purchase-order history, payment terms, and the per-vendor enabled-for-purchasing flag. Anything that issues a purchase order, tracks a supplier balance, or attributes a product to a source traces back to a record managed here.
This page is a reference for platform engineers and integrators who need to understand the surface before extending it, scripting against it, or scoping a supplier-management model. Customer-facing how-tos live in the customer docs set; this page describes the shape of the surface, not the steps to drive it.
This surface is B2B-oriented — vendors are the operators' suppliers, not the storefront customers. The Customers surface owns the customer-facing records; this page covers the upstream supply side.
Overview
Vendors lives under the Commerce module in SG-Admin, in the procurement group. The module renders four primary views — the vendor list, the vendor detail / edit form, the purchase-order ledger per vendor, and the vendor-catalog binding view — and exposes a small set of write operations for create, edit, archive, restore, issue purchase order, record receipt, and update payment terms.
The module is paired by convention: one half renders the views and prepares the vendor and purchase-order data, the other half handles writes and returns AJAX responses. Engineers reading the SG-Admin source will see this split across two controller files; the reference below describes the combined surface as it appears to a calling integration.
A vendor catalog is the subset of products the vendor supplies. A product can be sourced from more than one vendor; each binding carries its own cost basis and lead time. The cart-side product catalog is unaffected by the vendor catalog — vendors are a procurement concern, not a storefront concern.
Where it lives in SG-Admin:
- Sidebar: SG-Admin → Commerce → Procurement → Vendors
- URL prefix:
/sg-admin/vendors/ - View templates:
application/views/Admin/Commerce/Vendors/
┌──────────────────────────────────────────────────────────────────────┐│ SG-Admin → Commerce → Procurement → Vendors [ + Add vendor ] │├──────────────────────────────────────────────────────────────────────┤│ Vendor name Contact Open POs Balance State ││ ───────────────────── ───────────────── ───────── ──────── ────││ Apex Wholesale Maria Reyes 3 ₱42,580 ✔ ││ Northern Supplies Jonas Tan 1 ₱8,400 ✔ ││ Pacific Trading Co Anna Cruz 0 — ✔ ││ Sunrise Imports Reggie de Leon 2 ₱18,200 ✔ ││ Legacy Supplies (archived) 0 — — ││ ││ Active: 4 · Archived: 1 · Open POs: 6 · Owed: ₱69,180 ││ [ Edit ] [ Issue PO ] [ View ledger ] [ Catalog ] │└──────────────────────────────────────────────────────────────────────┘Actions
The Vendors surface exposes the following operations. Each is described by what it does to the data, not by its internal method name.
List and filter
Returns the vendor catalog paginated, with vendor name, primary contact, open-purchase-order count, current balance owed, payment-terms summary, and active flag. Supports filter by active state, by payment-terms type, by balance threshold, and by free-text on name. The default view excludes archived vendors — they remain queryable via the explicit filter.
View vendor
Returns the full record for a single vendor — business name, primary contact, secondary contacts, billing address, shipping address, tax identifier, payment terms, currency preference, vendor catalog (product bindings with cost basis and lead time), purchase-order ledger summary, and the active flag. The purchase-order ledger and the vendor catalog are paginated within the detail view.
Create vendor
Opens an empty vendor form. Required fields at minimum: business name, primary contact name, primary contact email, billing address. Optional fields cover secondary contacts, shipping address, tax identifier, payment terms, currency preference, and the initial product catalog. On submit, the surface validates the email format, validates that no existing vendor uses the same business name plus tax identifier combination, persists the record, and returns the new identifier.
Edit vendor
Loads an existing vendor record into the same form shape used for create, pre-populated. Submit replaces the stored vendor profile with the posted values. Fields left blank do not clear server-side values (the form is partial-update by default).
Edit payment terms
Dedicated path for the payment-terms subset. Editable fields cover terms type (net-N, due-on-receipt, prepay, end-of-month), terms value (the N in net-N), discount-for-early-payment, and late-payment-penalty. Changes apply to purchase orders issued after the edit — open purchase orders retain the terms they were issued under.
Edit vendor catalog
Opens the binding editor between the vendor and the product catalog. Each binding records the vendor's product identifier (their SKU, often different from ours), the cost basis, the lead time in days, the minimum order quantity, and the active flag. Bindings are per-vendor-per-product — a product sourced from three vendors has three rows here.
Issue purchase order
Creates a new purchase-order record against the vendor. Required fields: line items (product, quantity, agreed cost), expected delivery date, payment terms (defaults to the vendor's standard terms). The surface validates that every line item is bound in the vendor's catalog, computes the total, persists the purchase order, and returns the new identifier. Issued purchase orders are immutable from this surface — adjustments require the cancel-and-reissue path.
Record receipt
Marks a purchase-order line item as received. Required fields: line item identifier, quantity received, receipt date, optional condition notes. Supports partial receipts — a line item with a multi-shipment expected delivery can record each shipment separately. Receiving the full quantity closes the line item; closing all line items closes the purchase order.
Cancel purchase order
Marks an open purchase order as cancelled. Cancellation does not delete the record — the cancelled purchase order remains in the ledger with a cancelled marker. Required fields: cancellation reason. Cancelled purchase orders are excluded from balance computation but remain queryable.
Archive and restore vendor
Archive marks the vendor inactive without removing it from the database. Archived vendors disappear from the default list view but remain queryable via the archived filter. Their purchase-order history remains attached for audit; the vendor itself is excluded from new purchase-order issuance. Restore reverses the archive.
Engineering note. The archive path validates that the vendor has zero open purchase orders. A vendor with an open purchase order cannot be archived until the purchase order is closed or cancelled. The surface returns a structured rejection naming the blocking purchase-order identifiers.
Data model
A vendor record carries the following fields. Field names below are the conceptual shape — the on-disk column names match closely but are not contractually stable across releases.
| Field | Type | Notes |
|---|---|---|
id | integer | Primary key. Stable across edits. |
business_name | string | Vendor display name. Not unique on its own. |
tax_identifier | string | Tax identifier. Unique paired with business name. |
primary_contact_name | string | Primary contact display name. |
primary_contact_email | string | Primary contact email. Used for purchase-order delivery. |
primary_contact_phone | string | Optional. |
secondary_contacts | json | Array of secondary contact records (name, email, role). |
billing_address | json | Structured address. Format follows the address-template catalog. |
shipping_address | json | Optional. Defaults to billing address. |
payment_terms_type | enum | net_n, due_on_receipt, prepay, end_of_month. |
payment_terms_value | integer | The N in net-N. Optional for other types. |
currency_id | integer | Foreign key into Currencies. Defaults to base currency. |
early_payment_discount_percent | decimal | Optional. |
late_payment_penalty_percent | decimal | Optional. |
is_active | boolean | Whether the vendor accepts new purchase orders. |
archived_at | timestamp | Set when archived. Null when active. |
created_at | timestamp | Set on create, immutable. |
updated_at | timestamp | Touched on any edit. |
vendor_id, product_id, vendor_sku, cost_basis, lead_time_days, min_order_qty, is_active. A product sourced from multiple vendors has one row per vendor.Purchase-order record: each purchase order carries id, vendor_id, issued_at, expected_delivery_at, payment_terms_snapshot (terms captured at issuance), line_items (json array), total, currency_id, status (open, partial, closed, cancelled), cancelled_at, cancelled_reason.
Balance computation: the current balance owed is computed from closed and partial purchase orders that have not yet been settled. Settlement is recorded against the Accounting surface; the Vendors surface displays the rolling balance for operator convenience.
VENDOR RECORD│▼┌───────────────────────────────────────────┐│ ISSUE PURCHASE ORDER ││ ▶ pick line items from vendor catalog ││ ▶ confirm payment terms snapshot ││ ▶ confirm expected delivery date ││ ▶ purchase order = OPEN │└───────────────────────┬───────────────────┘│▼ receipt arrives┌───────────────────────────────────────────┐│ RECORD RECEIPT (per line item) ││ ▶ full receipt → line item CLOSED ││ ▶ partial receipt → line item PARTIAL ││ ▶ all line items CLOSED → PO CLOSED │└───────────────────────┬───────────────────┘│▼ settlement┌─────────┴─────────┐▼ ▼Accounting Balanceledger entry owed reducedPermissions
Access to the Vendors surface is gated at two layers.
Layer 1 — admin gate. Every action under SG-Admin passes through the platform's standard admin access check at request entry. An unauthenticated request never reaches the Vendors surface.
Layer 2 — per-action capability. Within SG-Admin, each Vendors action checks a capability associated with the calling operator's role. The default role configuration ships with three roles — Administrator, Editor, Viewer — and the capability map is:
| Capability | Administrator | Editor | Viewer |
|---|---|---|---|
| List vendors | ✔ | ✔ | ✔ |
| View vendor detail | ✔ | ✔ | ✔ |
| View purchase-order ledger | ✔ | ✔ | ✔ |
| Create vendor | ✔ | ✔ | — |
| Edit vendor profile | ✔ | ✔ | — |
| Edit vendor catalog | ✔ | ✔ | — |
| Issue purchase order | ✔ | ✔ | — |
| Record receipt | ✔ | ✔ | — |
| Cancel purchase order | ✔ | — | — |
| Edit payment terms | ✔ | — | — |
| Archive vendor | ✔ | — | — |
| Restore vendor | ✔ | — | — |
Self-protection rules. A vendor with open purchase orders cannot be archived. A purchase order that has any receipt activity cannot be cancelled — issue a return-to-vendor record instead. A vendor catalog binding that is referenced by any open purchase-order line item cannot be removed — close or cancel the purchase order first. The surface returns a structured rejection in each case.
Audit. Every write — create, edit, payment-terms edit, catalog edit, purchase-order issue, receipt, cancellation, archive, restore — emits an Activity Log entry. The log records the acting operator, the vendor identifier (and purchase-order identifier where applicable), and the change shape (field-level diff for edits). Purchase-order issuance and cancellation write dedicated event types for audit clarity.
REQUEST│▼┌───────────────────────────┐│ Admin gate │ unauth → reject│ (every /sg-admin/* call) │└─────────────┬─────────────┘│ authed▼┌───────────────────────────┐│ Capability check │ role lacks cap → reject│ (per-action) │ (custom roles override defaults)└─────────────┬─────────────┘│ allowed▼┌───────────────────────────┐│ Self-protection rules │ open-PO archive / receipt-cancel /│ │ bound-product unbind → reject└─────────────┬─────────────┘│ passes▼action executes│▼Activity Log + PO ledgerRelated references
- Products — Reference. Vendor-catalog bindings reference product identifiers. A product can be bound to multiple vendors; each binding carries its own cost basis and lead time.
- Inventory — Reference. Receipts recorded here update inventory levels there. Stock-level alerts trigger purchase-order suggestions against the vendor catalog.
- Accounting — Reference. Vendor balances reconcile against settlement entries recorded there. The rolling balance shown on the vendor detail is informational; the source of truth is the accounting ledger.
- Currencies — Reference. Each vendor carries a currency preference. Purchase-order totals are captured in the vendor's currency; settlement converts to base currency at settlement time.
- Countries — Reference. Vendor addresses follow the address-template catalog, which is anchored against the country record.
- Activity Log — Reference. Purchase-order issuance, receipt, and cancellation all surface here with dedicated event types for audit.
- Settings — Reference. Owns the payment-terms-type catalog, the default-currency rule for new vendors, and the receipt-tolerance rule (how much under-receipt counts as partial vs cancelled). Changes there reshape the Vendors workflow.
/docs/vendors.