Partners & Suppliers

Understanding the multi-model approach to external business relationships.

The SCM application has a multi-model approach to represent external business relationships:

Party

Transaction Entity Low-level entity for POs, Invoices, Shipments. OpenBoxes-style.

Partner

Operational Management SCM-native partner with addresses, contacts, and locations.

Partnership

Cross-Organization Formal B2B relationships between separate Organizations.

OrganizationRelation

Hierarchy Structural relationships (Subsidiary, Division, Partner).

1. Party Model (Transaction Entities)

Purpose: Low-level transactional entity for Purchase Orders, Invoices, Shipments.

model Party {
  id              String
  organizationId  String
  partyTypeId     String    // Links to PartyType (Supplier, Customer, etc.)
  class           String    // ORGANIZATION or PERSON
  name            String
  roles           PartyRole[]    // Used in transactions
  supplierPurchaseOrders  PurchaseOrder[]  @relation("POSupplier")
  invoicesFrom            Invoice[]
  invoicesTo              Invoice[]
}

Key Usage

• PurchaseOrder.supplierPartyId → references a Party
• ProductSupplier.supplierId → links products to their suppliers
• Invoice.partyId → billing party

Party Roles

Role	Description
SUPPLIER	Vendor you buy from
CUSTOMER	Organization you sell to
MANUFACTURER	Product manufacturer
DISTRIBUTOR	Distribution partner
THIRD_PARTY_LOGISTICS	3PL provider

2. Partner Model (Operational Management)

Purpose: SCM-native partner management with addresses, contacts, locations.

model Partner {
  id              String
  organizationId  String    // Your org owns this partner record
  name            String
  type            PartnerType   // SUPPLIER, CUSTOMER, CARRIER, etc.
  status          PartnerStatus // ACTIVE, INACTIVE, SUSPENDED
  
  // Operational settings
  taxId           String?
  paymentTerms    String?
  incoterm        String?
  centralPurchasing Boolean
  poPrefix        String?       // For PO numbering
  
  // Related data
  addresses       PartnerAddress[]
  contacts        PartnerContact[]
  locations       PartnerLocation[]   // Links to shared locations
}

Partner Types

• SUPPLIER: Vendors you purchase from
• CUSTOMER: Organizations you sell to
• CARRIER: Shipping/logistics providers
• MANUFACTURER: Product manufacturers
• DISTRIBUTOR: Distribution partners
• INTERNAL: Internal divisions
• OTHER: Misc partners

Key Features

• Addresses: Billing, shipping, returns addresses per partner
• Contacts: Named contacts with roles (Sales, Support, Accounting)
• Locations: Link partners to shared Location records (warehouses, stores)
• Central Purchasing: Allow parent to purchase on behalf of children

3. Partnership Model (Cross-Organization)

Purpose: Formal B2B relationships between separate Organizations.

model Partnership {
  id                    String
  organizationId        String    // Requesting org
  partnerOrganizationId String    // Partner org
  status                PartnershipStatus  // REQUESTED, ACCEPTED, DENIED
  partyRole             PartyRoleType      // Role they play for you
  relationshipType      RelationshipType   // BUYER_SELLER, LOGISTICS, etc.
  
  // Invitation workflow
  invitationToken       String?
  invitationEmail       String?
  invitationSentAt      DateTime?
  invitationAcceptedAt  DateTime?
}

Partnership Workflow

Relationship Types

• BUYER_SELLER: Standard procurement relationship
• LOGISTICS: 3PL/shipping partnership
• MANUFACTURING: Contract manufacturing
• DISTRIBUTION: Distribution agreement
• FRANCHISE: Franchise relationship

4. OrganizationRelation (Org Hierarchy)

Purpose: Define structural relationships between organizations (including PARTNER role).

model OrganizationRelation {
  parentOrgId  String
  childOrgId   String
  role         String    // SUBSIDIARY, DIVISION, PARTNER, AFFILIATE
  isActive     Boolean
}

Relation Roles

Role	Description	Billing Included
SUBSIDIARY	Owned subsidiary	✅ Yes
DIVISION	Business division	✅ Yes
BRANCH	Branch office	✅ Yes
PARTNER	External partner	❌ No
AFFILIATE	Affiliate org	❌ No
FRANCHISE	Franchise	❌ No

How They Work Together

Scenario: Creating a Purchase Order

1. User selects Supplier → Party record (type: SUPPLIER)
2. System loads → Partner record (for payment terms, addresses)
3. PO is created → supplierPartyId = Party.id
4. Supplier org may have → Partnership (if cross-org visibility needed)

API Flow (/api/partners)

The partners API aggregates from 3 sources:

// 1. Partner model (owned by your org)
const partnersFromModel = await database.partner.findMany({
  where: { organizationId, type: 'SUPPLIER' }
});

// 2. OrganizationRelation (PARTNER role)
const partnersFromRelations = await database.organizationRelation.findMany({
  where: { parentOrgId: organizationId, role: 'PARTNER' }
});

// 3. Partnership model (accepted partnerships)
const partnersFromPartnerships = await database.partnership.findMany({
  where: { organizationId, status: 'ACCEPTED' }
});

Key Flags on Organization

model Organization {
  isCustomer       Boolean   // Can be sold to
  isSupplier       Boolean   // Can be purchased from
  partnershipTier  PartnershipTier?  // PARTNER_ONLY, BASIC, FULL
}

These flags determine:

• isSupplier=true → Appears in supplier dropdowns for POs
• isCustomer=true → Appears in customer dropdowns for Sales Orders
• partnershipTier → Controls what partnership features are available

Summary Table

Model	Purpose	Scope	Used For
Party	Transaction entity	Per-org	POs, Invoices, Shipments
Partner	Operational config	Per-org	Addresses, contacts, terms
Partnership	Cross-org link	Multi-org	Visibility, collaboration
OrganizationRelation	Org hierarchy	Multi-org	Subsidiaries, partners, billing