Suppliers

Manage your suppliers and purchase orders. Track the full procurement lifecycle from draft to delivery.

Supplier Model

class Supplier {
  id: string;              // Unique UUID identifier
  name: string;            // Company name (required)
  contactName: string;     // Primary contact person
  email: string;           // Contact email
  phone: string | null;    // Contact phone number
  street: string;          // Street address
  city: string;            // City
  postalCode: string;      // Postal/ZIP code
  country: string;         // Country code (e.g. "US", "DE")
  isActive: boolean;       // Active status (default: true)
}

PurchaseOrder Model

class PurchaseOrder {
  id: string;                    // Unique UUID identifier
  supplierId: string;            // Associated supplier ID
  items: PurchaseOrderItem[];    // Line items
  status: PurchaseOrderStatus;   // Current PO status
  expectedDelivery: Date | null; // Expected delivery date
  notes: string | null;          // Optional notes
}

class PurchaseOrderItem {
  productId: string;     // Product being ordered
  quantity: number;      // Quantity to order
  unitCost: number;      // Cost per unit in cents
}

enum PurchaseOrderStatus {
  DRAFT        // PO created but not yet submitted
  SUBMITTED    // PO sent to supplier
  CONFIRMED    // Supplier confirmed the order
  SHIPPED      // Supplier has shipped the goods
  RECEIVED     // Goods have been received
  CANCELLED    // PO was cancelled
}

Purchase Order Status Workflow

100%

Loading diagram...

Supplier Operations

Manage Suppliers

Create a supplier:

import { createServices } from "commercio";

const { supplierService } = createServices();

// Create a supplier
const supplier = await supplierService.createSupplier({
  name: "Acme Electronics Ltd",
  contactName: "Jane Smith",
  email: "jane@acme-electronics.com",
  phone: "+1-555-0100",
  street: "100 Industrial Blvd",
  city: "Chicago",
  postalCode: "60601",
  country: "US",
});

console.log(supplier.id);          // UUID
console.log(supplier.name);        // "Acme Electronics Ltd"
console.log(supplier.contactName); // "Jane Smith"
console.log(supplier.isActive);    // true

Get a supplier:

// Get supplier by ID
const supplier = await supplierService.getSupplierById(supplierId);

console.log(supplier.name);
console.log(supplier.email);

Update a supplier:

// Update supplier details
const updated = await supplierService.updateSupplier(supplier.id, {
  contactName: "John Doe",
  email: "john@acme-electronics.com",
  phone: "+1-555-0200",
});

console.log(updated.contactName); // "John Doe"
console.log(updated.email);       // "john@acme-electronics.com"

Deactivate a supplier:

// Deactivate a supplier
const deactivated = await supplierService.deactivateSupplier(supplier.id);

console.log(deactivated.isActive); // false

// Reactivate
const reactivated = await supplierService.activateSupplier(supplier.id);

console.log(reactivated.isActive); // true

Complete Example

import { createServices } from "commercio";

const { supplierService } = createServices();

// 1. Create a supplier
const supplier = await supplierService.createSupplier({
  name: "Acme Electronics Ltd",
  contactName: "Jane Smith",
  email: "jane@acme-electronics.com",
  phone: "+1-555-0100",
  street: "100 Industrial Blvd",
  city: "Chicago",
  postalCode: "60601",
  country: "US",
});

// 2. Create a purchase order with items
const po = await supplierService.createPurchaseOrder({
  supplierId: supplier.id,
  items: [
    { productId: laptop.id, quantity: 50, unitCost: 45000 },
    { productId: mouse.id, quantity: 200, unitCost: 1500 },
  ],
  expectedDelivery: new Date("2026-05-15"),
  notes: "Q2 inventory restock",
});
console.log(po.status); // "DRAFT"

// 3. Submit to supplier
await supplierService.submitPurchaseOrder(po.id);
console.log("Status: SUBMITTED");

// 4. Supplier confirms
await supplierService.confirmPurchaseOrder(po.id);
console.log("Status: CONFIRMED");

// 5. Supplier ships goods
await supplierService.shipPurchaseOrder(po.id);
console.log("Status: SHIPPED");

// 6. Receive goods at warehouse
await supplierService.receivePurchaseOrder(po.id);
console.log("Status: RECEIVED");

// 7. Verify final state
const completed = await supplierService.getPurchaseOrderById(po.id);
console.log(completed.status);       // "RECEIVED"
console.log(completed.items.length);  // 2

// 8. Query all POs for this supplier
const allPOs = await supplierService.getPurchaseOrdersBySupplier(supplier.id);
console.log(`Total POs: ${allPOs.length}`);

Best Practices

1. Keep Supplier Information Updated

Regularly update supplier contact details to ensure smooth communication:

// Update contact information when it changes
await supplierService.updateSupplier(supplier.id, {
  contactName: "New Contact Person",
  email: "new.contact@supplier.com",
});

2. Use Costs in Cents

Store all monetary values in cents to avoid floating-point issues:

// Good: Use cents for unitCost
const po = await supplierService.createPurchaseOrder({
  supplierId: supplier.id,
  items: [
    { productId: product.id, quantity: 100, unitCost: 2599 }, // $25.99
  ],
});

// Calculate total
const total = po.items.reduce((sum, item) => sum + item.quantity * item.unitCost, 0);
console.log(`Total: $${total / 100}`); // "Total: $2599.00"

3. Add Notes to Purchase Orders

Include useful context in purchase order notes for future reference:

const po = await supplierService.createPurchaseOrder({
  supplierId: supplier.id,
  items: [...],
  expectedDelivery: new Date("2026-06-01"),
  notes: "Urgent restock for summer sale campaign. Contact warehouse team on arrival.",
});

4. Deactivate Instead of Delete

Deactivate suppliers rather than deleting them to preserve purchase order history:

// Deactivate supplier, keeping all PO records
await supplierService.deactivateSupplier(supplier.id);

// Use active suppliers for new POs
const activeSuppliers = await supplierService.getActiveSuppliers();