Customer Supplier Management Blueprint

Customer and supplier master data management with credit limits, territory and group hierarchies, portal access, lead conversion, internal parties, and supplier hold/block controls.

Feature	customer-supplier-management
Category	Data
Version	1.0.0
Tags	customer, supplier, master-data, credit-limit, territory, customer-group, portal-access, lead-conversion
YAML Source	View on GitHub
JSON API	customer-supplier-management.json

Actors

ID	Name	Type	Description
sales_user	Sales User	human	Creates and manages customer records, converts leads
purchase_user	Purchase User	human	Creates and manages supplier records, controls hold status
accounts_user	Accounts User	human	Manages credit limits, account mappings, and frozen status
portal_user	Portal User	external	Customer or supplier user accessing self-service portal
system	System	system	Validates credit limits, enforces naming rules, manages hierarchies

Fields

Name	Type	Required	Label	Description
customer_name	text	Yes	Customer Name
customer_type	select	Yes	Customer Type
customer_accounts	json	No	Customer Accounts
credit_limits	json	No	Credit Limits
territory	text	No	Territory
customer_group	text	No	Customer Group
default_price_list	text	No	Default Price List
default_currency	text	No	Default Currency
sales_team	json	No	Sales Team
customer_disabled	boolean	No	Disabled
customer_is_frozen	boolean	No	Is Frozen
is_internal_customer	boolean	No	Is Internal Customer
portal_users	json	No	Portal Users
lead_name	text	No	Source Lead
supplier_name	text	Yes	Supplier Name
supplier_type	select	No	Supplier Type
supplier_accounts	json	No	Supplier Accounts
supplier_default_price_list	text	No	Supplier Default Price List
payment_terms	text	No	Payment Terms
supplier_disabled	boolean	No	Disabled
supplier_is_frozen	boolean	No	Is Frozen
on_hold	boolean	No	On Hold
hold_type	select	No	Hold Type
release_date	date	No	Hold Release Date
prevent_rfqs	boolean	No	Prevent RFQs
warn_rfqs	boolean	No	Warn on RFQs
prevent_pos	boolean	No	Prevent Purchase Orders
warn_pos	boolean	No	Warn on Purchase Orders
group_name	text	No	Group Name
parent_group	text	No	Parent Group
is_group	boolean	No	Is Group Node
group_default_accounts	json	No	Group Default Accounts
group_credit_limits	json	No	Group Credit Limits
territory_name	text	No	Territory Name
parent_territory	text	No	Parent Territory
territory_manager	text	No	Territory Manager
targets	json	No	Territory Targets

Rules

• naming_configurable:
  • description: Customer and supplier names can be configured to use the party name directly or follow a naming series pattern. The naming rule is set at the system level and applies to all new records.
• credit_limits_per_company:
  • description: Credit limits are validated per company. When a customer’s outstanding amount plus a new transaction exceeds the credit limit for that company, the transaction is blocked or a warning is shown.
• cannot_assign_group_nodes:
  • description: Group/parent nodes in customer group and territory hierarchies cannot be directly assigned to a customer. Only leaf nodes (is_group = false) are valid for assignment.
• one_internal_party_per_company:
  • description: Only one internal customer and one internal supplier can exist per company. This prevents duplicate inter-company transaction paths.
• primary_contact_auto_created:
  • description: When a customer or supplier is saved with contact details, a primary contact record is automatically created and linked.
• primary_address_auto_created:
  • description: When a customer or supplier is saved with address details, a primary address record is automatically created and linked.
• portal_users_get_roles:
  • description: Portal users added to a customer record are automatically assigned the customer portal role, granting access to orders, invoices, and support tickets for that customer.
• account_currency_must_match:
  • description: The currency of mapped receivable (customer) or payable (supplier) accounts must match the party’s default currency. Mismatched currencies are rejected at save time.
• lead_conversion_links:
  • description: When a lead is converted to a customer, all addresses and contacts from the lead are automatically linked to the new customer record. The lead is marked as converted.

Outcomes

Create_customer (Priority: 1)

Given:

• sales user provides customer name and customer type
• customer name does not already exist (or naming series generates unique name)

Then:

• create_record — Create customer record with default values
• create_record — Auto-create primary contact if contact details provided
• create_record — Auto-create primary address if address details provided
• emit_event event: customer.created

Result: Customer created with linked primary contact and address

Duplicate_name_rejected (Priority: 1) — Error: PARTY_DUPLICATE_NAME

Given:

• user creates a customer or supplier
• a record with the same name already exists

Then:

• notify — Show existing record name and suggest alternatives

Result: Creation blocked due to duplicate name

Group_assignment_rejected (Priority: 1) — Error: PARTY_GROUP_ASSIGNMENT

Given:

• user assigns a customer to a group or territory node
• the selected node has is_group = true

Then:

• notify — Inform that only leaf nodes can be assigned

Result: Assignment blocked, select a non-group node

Credit_exceeded (Priority: 1) — Error: PARTY_CREDIT_EXCEEDED

Given:

• transaction amount plus outstanding exceeds credit limit
• bypass_credit_limit_check is not enabled

Then:

• notify — Show outstanding amount, credit limit, and excess

Result: Transaction blocked until credit limit is increased or outstanding reduced

Internal_duplicate_rejected (Priority: 1) — Error: PARTY_INTERNAL_DUPLICATE

Given:

• user creates an internal customer or supplier for a company
• an internal party of the same type already exists for that company

Then:

• notify — Show existing internal party for the company

Result: Only one internal customer/supplier allowed per company

Account_currency_mismatch (Priority: 1) — Error: PARTY_ACCOUNT_CURRENCY_MISMATCH

Given:

• user maps a receivable or payable account to a party
• account currency does not match the party’s default currency

Then:

• notify — Show expected currency vs account currency

Result: Account mapping rejected due to currency mismatch

Create_supplier (Priority: 2)

Given:

• purchase user provides supplier name
• supplier name does not already exist (or naming series generates unique name)

Then:

• create_record — Create supplier record with default values
• create_record — Auto-create primary contact if contact details provided
• create_record — Auto-create primary address if address details provided
• emit_event event: supplier.created

Result: Supplier created with linked primary contact and address

Convert_lead_to_customer (Priority: 3)

Given:

• a qualified lead exists in the system
• sales user initiates lead conversion

Then:

• create_record — Create customer from lead data
• set_field target: lead_name — Link back to original lead record
• call_service target: link_service — Transfer all addresses and contacts from lead to customer
• emit_event event: lead.converted

Result: Lead converted to customer with all contacts and addresses transferred

Apply_credit_limit (Priority: 4)

Given:

• a transaction is being created or submitted for a customer
• customer has credit limits configured for the company
• grand_total (computed) gt 0

Then:

• notify — Display credit limit warning with outstanding amount and limit
• emit_event event: customer.credit_exceeded

Result: Transaction blocked or warning shown based on credit limit configuration

Manage_portal_access (Priority: 5)

Given:

• portal users are added to or removed from a customer record

Then:

• call_service target: role_service — Assign or revoke customer portal roles for affected users

Result: Portal user roles updated to match customer portal user list

Freeze_party (Priority: 6)

Given:

• accounts user freezes a customer or supplier

Then:

• set_field target: customer_is_frozen value: true — Set frozen flag (applies to customer or supplier as appropriate)

Result: Party frozen, no new transactions can be created

Put_supplier_on_hold (Priority: 7)

Given:

• purchase user places a supplier on hold
• hold type and optional release date are specified

Then:

• set_field target: on_hold value: true
• set_field target: hold_type — Set to All, Invoices, or Payments
• emit_event event: supplier.on_hold

Result: Supplier placed on hold, transactions restricted per hold type

Errors

Code	Status	Message	Retry
PARTY_DUPLICATE_NAME	409	A customer or supplier with this name already exists.	No
PARTY_GROUP_ASSIGNMENT	422	Cannot assign a group node. Select a non-group (leaf) node.	No
PARTY_CREDIT_EXCEEDED	403	Customer credit limit exceeded. Outstanding plus this transaction exceeds the allowed limit.	No
PARTY_INTERNAL_DUPLICATE	409	Only one internal customer/supplier is allowed per company.	No
PARTY_ACCOUNT_CURRENCY_MISMATCH	422	Account currency must match the party’s default currency.	No

Events

Event	Description	Payload
customer.created	New customer record created	customer_id, customer_name, customer_type
customer.credit_exceeded	Customer credit limit exceeded during a transaction	customer_id, company, outstanding, credit_limit, transaction_amount
supplier.created	New supplier record created	supplier_id, supplier_name, supplier_type
supplier.on_hold	Supplier placed on hold with transaction restrictions	supplier_id, hold_type, release_date
lead.converted	Lead converted to a customer record	lead_id, customer_id

Related Blueprints

Feature	Relationship	Reason
sales-order-lifecycle	recommended	Sales order lifecycle uses customer credit limits and defaults
purchase-order-lifecycle	recommended	Purchase order lifecycle uses supplier hold status and defaults
lead-opportunity-pipeline	optional	Lead management and conversion to customer records

AGI Readiness

Goals

Reliable Customer Supplier Management

Customer and supplier master data management with credit limits, territory and group hierarchies, portal access, lead conversion, internal parties, and supplier hold/block controls.

Success Metrics:

Metric	Target	Measurement
data_accuracy	100%	Records matching source of truth
duplicate_rate	0%	Duplicate records detected post-creation

Constraints:

• performance (non-negotiable): Data consistency must be maintained across concurrent operations

Autonomy

Level: supervised

Human Checkpoints:

• before making irreversible changes

Escalation Triggers:

• error_rate > 5

Tradeoffs

Prefer	Over	Reason
data_integrity	performance	data consistency must be maintained across all operations

Safety

Action	Permission	Cooldown	Max Auto
create_customer	supervised	-	-
create_supplier	supervised	-	-
convert_lead_to_customer	autonomous	-	-
apply_credit_limit	autonomous	-	-
manage_portal_access	autonomous	-	-
freeze_party	autonomous	-	-
put_supplier_on_hold	autonomous	-	-
duplicate_name_rejected	supervised	-	-
group_assignment_rejected	supervised	-	-
credit_exceeded	autonomous	-	-
internal_duplicate_rejected	supervised	-	-
account_currency_mismatch	autonomous	-	-

Extensions (framework-specific hints)

```yaml source: https://github.com/frappe/erpnext ```