Modeling Commercial Relationships Without Duplicate Masters: The Party Model in Apache OFBiz

Businesses rarely operate in neatly separated roles. A single organization may act as a customer in one transaction, a supplier in another, and even a partner or service provider in a different context. Traditional ERP systems often model these relationships using separate customer and vendor masters, which leads to duplicate records, fragmented history, and ongoing data maintenance challenges. This duplication not only creates operational inefficiencies but also makes it harder to maintain a single, accurate view of the business relationship.

Apache OFBiz solves this problem through its party model, which separates business identity from business function. Instead of creating multiple masters, Apache OFBiz maintains a single party record and dynamically assigns roles based on the commercial context.

In this blog, you will understand how the party model in Apache OFBiz represents complex commercial relationships without creating duplicate master records.

A Simple Business Scenario

Imagine this situation.

A company:

• Buys products from you
• Also sells services to you
• Sometimes ships goods
• Sometimes issues invoices
• Sometimes pays you
• Sometimes you pay it

In many traditional ERP systems, this results in:

• A Customer Master record
• A Vendor Master record
• Possibly duplicate addresses
• Duplicate tax IDs
• Separate credit controls
• Complex reconciliation

But in real life, it is still the same company.

So the real question becomes:

Is it truly a “customer” or a “vendor” — or is it simply a business entity playing different roles depending on the situation?

This is where Apache OFBiz takes a fundamentally different approach.

The Core Philosophy: Identity Over Category

Most ERP systems classify entities into rigid categories:

• Customer
• Vendor

Each “master” record mixes:

• Identity (who the entity is)
• Category (what the entity is)

Apache OFBiz deliberately separates these concerns. It models:

• Identity first
• Capability second
• Transaction third

That architectural decision changes everything.

The Layered Mental Model

In Apache OFBiz, business relationships are modeled in layers:

I. Party → Identity Layer

II. PartyRole → Capability Layer

III. OrderRole / InvoiceRole → Transaction Layer

Understanding these three layers unlocks the system. Let’s break them down.

Party — The Identity Layer

In Apache OFBiz, everything begins with a Party.

A Party represents identity. It may later be assigned one or more roles — such as CUSTOMER, VENDOR, or EMPLOYEE — but those behaviors are defined separately through PartyRole.

Before any roles are assigned, the system only needs to answer a simple question:

Is this identity a person or an organization?

That fundamental distinction is captured using PartyType:

Example:

Notice what is missing:

There is no “Customer” table.
There is no “Vendor” table.

Those are not identities. They are roles applied to a Party.

PartyRole — The Capability Layer

Once identity exists, Apache OFBiz defines what that Party is capable of doing. This is done through PartyRole.

PartyRole answers:

What business role can this Party perform?

Example:

A single Party can have multiple roles. No duplication required.

Why Both SUPPLIER and VENDOR?

One of the most common points of confusion for Business Analysts new to Apache OFBiz is the distinction between SUPPLIER and VENDOR.

At first glance, they appear to mean the same thing.

However, within OFBiz, they are used in different functional contexts and serve different purposes in practice.

Understanding this distinction is essential for correctly modeling procurement, transactions, and accounting behavior.

The SUPPLIER Role — Strategic Sourcing Context

The SUPPLIER role is primarily associated with procurement configuration and sourcing capability.

It represents:

An approved business relationship for purchasing goods or services.

In practical terms, SUPPLIER is commonly used in:

• Supplier-product relationships
• Purchase agreements
• Negotiated pricing and discounts
• Credit or account limits
• Planning and MRP sourcing logic

SUPPLIER answers the question: Who are we authorized to buy from?

This role typically exists before any transaction occurs. It enables purchasing teams to configure commercial relationships independently of specific orders. So SUPPLIER lives in the planning and procurement domain.

The VENDOR Hierarchy — Transactional Context

The VENDOR role functions as the parent in a transactional role hierarchy.

Child roles include:

• BILL_FROM_VENDOR
• SHIP_FROM_VENDOR

These roles appear primarily in order and invoice participation.

They answer questions such as:

• Who is issuing this invoice?
• Who is the legal seller in this transaction?
• Who is physically shipping the goods?

For example, in a Purchase Order:

In accounting terms:

• BILL_FROM_VENDOR determines who is credited in Accounts Payable.
• It also influences GL account resolution and payment processing.

So the VENDOR hierarchy lives in the transactional and accounting domain.

How Do They Work Together in Practice?

In many implementations, a supplier organization will have:

• SUPPLIER (for sourcing configuration)
• VENDOR (to participate in orders and invoices)

This allows Apache OFBiz to separate:

• Strategic commercial setup (who we source from)
• Transactional execution (who is legally issuing and shipping in a specific order)

This layered modeling provides flexibility without duplicating identity.

A Note on Terminology

It is important to note that Apache OFBiz has evolved over many years, and role terminology may not always be used with rigid semantic boundaries across all modules. The explanation above reflects how these roles are typically interpreted in modern implementations and how they function in transactional and accounting contexts.

In other words, while SUPPLIER and VENDOR often serve distinct functional purposes in practice, their usage may vary depending on module configuration and implementation approach.

The key takeaway is not semantic perfection, but understanding how these roles influence procurement setup, order participation, and accounting behavior.

What Is INTERNAL_ORGANIZATIO ?

You may notice the role name INTERNAL_ORGANIZATIO and assume it’s a typo — it’s not. This is an actual role type in Apache OFBiz.

The name appears truncated because the underlying role identifier field in the data model is limited to 20 characters (historically defined as VARCHAR(20)). As a result, longer identifiers such as “INTERNAL_ORGANIZATION” were shortened to fit within that constraint.

This is simply a legacy design decision in the data model and does not affect functionality. Like CUSTOMER or VENDOR, it is a PartyRole assigned to a Party.

But its purpose is different. It identifies:

Which Party represents your own legal company entity inside the system, the entity that owns the General Ledger and financial books.

In multi-party system:

• Multiple Parties exist in the same Apache OFBiz database.
• Only Parties marked with INTERNAL_ORGANIZATIO are treated as internal legal entities.

Without this role:

• Ledger ownership cannot be determined.
• Accounting entries cannot be posted correctly.
• Financial separation between external parties and internal parties is impossible.

It is critical for accounting integrity.

Role Hierarchies — Structured Specialization

Roles are organized into parent–child hierarchies. This allows specialization without duplication.

Customer Role Hierarchy

Parent Role: CUSTOMER

If a Party has the CUSTOMER role, it becomes eligible to participate in transactions using one or more specialized child roles. Below given child roles allow Apache OFBiz to model real-world business relationships with precision.

Child Roles:

• BILL_TO_CUSTOMER
• SHIP_TO_CUSTOMER
• PLACING_CUSTOMER
• END_USER_CUSTOMER

These allow precision in the Order-to-Cash lifecycle.

Description of each child roles:

• BILL_TO_CUSTOMER
  
  Purpose: Identifies the legal billing entity. This is the party that:
• Receives the invoice
• Is financially responsible for payment
• Appears as the debtor in Accounts Receivable

In many scenarios, this is the corporate headquarters or finance entity.

Example: A large enterprise places orders through regional offices, but all invoices are billed to corporate HQ.

• SHIP_TO_CUSTOMER
  
  Purpose: Identifies the physical delivery destination. This is the party or location that:
• Receives the goods
• Is associated with shipment tracking
• May differ from the billing entity

Example: Goods are billed to Corporate HQ but shipped directly to Warehouse #3.

• PLACING_CUSTOMER
  
  Purpose: Identifies who initiated the order. This is the party that:
• Logged into the system or portal
• Submitted the order
• Triggered the purchase process

This role is especially important in:

• B2B portals
• Franchise networks
• Multi-department procurement systems

Example: A regional purchasing office places the order on behalf of the corporate entity.

• END_USER_CUSTOMER
  
  Purpose: Identifies the final consumer or user of the product. This role is used when:
  
  
• The purchaser is not the ultimate user
• The product is delivered to an intermediary
• Usage tracking or warranty registration matters

Example: A distributor buys equipment, but the equipment is installed and used by a specific end customer.

Do We Really Need All These Roles?

At this point, a practical question often arises:

In our business, the same company places the order, receives the goods, and pays the invoice. Do we really need PLACING_CUSTOMER, BILL_TO_CUSTOMER, and SHIP_TO_CUSTOMER separately?

The answer is yes — but they can all reference the same Party.

Apache OFBiz does not require multiple parties per transaction. It supports them. In simple scenarios, all customer roles can point to the same Party without adding complexity.

The roles exist to make responsibility explicit — not to force multiple entities.

Even if your business is simple today, the structure ensures that future complexity — such as multi-branch billing, drop-shipping, intercompany flows, or franchise networks — can be handled without redesigning the data model.

Apache OFBiz favors clarity and scalability over hidden assumptions. Let's look at how these roles work in B2C and B2B scenarios.

In simple B2C:

All collapse into one identity.

But in complex B2B:

No duplicate master records required.

Vendor Role Hierarchy

Parent Role: VENDOR

Child Roles:

• BILL_FROM_VENDOR
• SHIP_FROM_VENDOR

This separates:

• Financial responsibility (who issued invoice)
• Logistics responsibility (who shipped goods)

Again — structured precision without duplication.

Transaction Layer — Roles in Action

Party defines identity. PartyRole defines capability. But business happens in transactions. That is where:

• OrderRole
• InvoiceRole

come into play.

They answer:

What is this Party doing right now?

This is where Apache OFBiz becomes powerful. Let's understand this in the Order-to-Cash and Procure-to-Pay lifecycles.

Order-to-Cash (O2C) Example

Northwind Retail Inc places Sales Order SO-10045.

Northwind has roles:

• PartyRole = CUSTOMER

Your Company LLC has roles:

• VENDOR
• INTERNAL_ORGANIZATIO

OrderRole Assignments

Notice something important, even in a Sales Order, your company acts under the VENDOR hierarchy. Because you are issuing the invoice. Perspective changes. Structure remains consistent.

InvoiceRole Assignments

Based on these roles:

• Accounts Receivable gets created
• Revenue gets posted
• Customer owes you

O2C complete.

Procure-to-Pay (P2P) Example

You purchase components from SupplyCo.

SupplyCo has roles:

• SUPPLIER
• VENDOR

OrderRole Assignments

Perspective flips. Supplier acts under the VENDOR hierarchy. You act under CUSTOMER hierarchy.

Invoice Role Assignments

Based on these roles:

• Accounts Payable gets created
• Liability gets recorded
• Cash will flow out

P2P complete.

Why Roles Matter? A Structural Insight

The most important question is:

How does the system decide who owes whom?

In Apache OFBiz, this decision is primarily driven by roles.

Roles determine:

• Whether the transaction results in Accounts Receivable (AR) or Accounts Payable (AP)
• Which party is the debtor
• Which party is the creditor
• Which GL accounts should be used
• Which credit or liability rules apply

For example:

If the invoice shows:

• BILL_FROM_VENDOR = Your Company
• BILL_TO_CUSTOMER = Customer

Then the customer owes you → AR is created.

If instead:

• BILL_FROM_VENDOR = Supplier
• BILL_TO_CUSTOMER = Your Company

Then you owe the supplier → AP is created.

Roles clearly define financial direction.

What About Document Types?

Invoices in Apache OFBiz also have a document type, such as:

• SALES_INVOICE
• PURCHASE_INVOICE

Document types help categorize the invoice and apply certain business rules.

However, document type alone does not fully define who owes whom. That relationship is determined by the roles assigned to the parties.

It is also important to recognize that Apache OFBiz has evolved over many years. In some areas of the application logic, document types are used in legacy logic to guide behavior. In other areas, role context plays the primary determining role.

From a modeling perspective, the principle is clear:

Roles identify the financial relationship.
Document types categorize the document.

Both exist in the system, but roles provide the relational clarity needed to determine AR vs AP and party responsibility.

The Mental Model That Unlocks Apache OFBiz Party Roles

Traditional ERP thinking asks:

Is this entity a customer or a vendor?

Apache OFBiz asks a better question:

What role is this Party playing in this transaction?

Once you separate:

• Identity (Party)
• Capability (PartyRole)
• Transaction Context (OrderRole / InvoiceRole)

The system becomes coherent.

A single Party can:

• Buy
• Sell
• Ship
• Invoice
• Pay
• Receive payment

Without duplication.
Without master fragmentation.
Without accounting ambiguity.

Apache OFBiz does not classify businesses. It models behavior.

And once that mental shift happens, Party Roles stop being confusing — and start being powerful.

Beyond Commercial Transactions

While this guide focused on Customer, Vendor, and Supplier roles in commercial flows, the same Party model extends far beyond buying and selling. Apache OFBiz also uses PartyRoles and PartyRelationship to model employer–employee relationships, organizational hierarchies, subsidiaries, sales representatives, and many other structured connections between entities. This means the Party framework is not just about transactions — it is a foundational model for representing an entire business ecosystem. We’ll explore that relationship layer in a separate guide.

Conclusion

The party model in Apache OFBiz provides a strong architectural foundation for representing real-world commercial relationships without creating duplicate master records. Backed by the Apache Software Foundation and designed for extensibility, Apache OFBiz enables businesses to maintain a single source of truth while supporting multiple roles dynamically as relationships evolve.

HotWax Systems accelerates this journey through its Accelerator layer on top of Apache OFBiz, delivering modern user experiences, real-time visibility, and pre-configured foundational data models. This enables organizations to implement faster, reduce complexity, and build scalable systems aligned with their operational needs.

If you are exploring Apache OFBiz for your ERP or supply chain initiatives, connect with our team. HotWax Systems specializes in implementing Apache OFBiz and developing tailored solutions that align with your business processes and support long-term growth.