# Partner Address Management

## Overview

Partner Address Management allows each business partner to maintain multiple addresses, each classified by purpose (BILLING, SHIPPING, REGISTERED, or OTHER). Addresses are child entities — they cannot exist without a parent partner record — and they carry the same structured format used by the organization module's Site entity: line1, line2, city, state/province, postalCode, and country (ISO 3166-1 alpha-2). While a Site models a company-owned physical facility, a partner address models an external party's location and is owned entirely by the business-partner module.

One address per partner may be designated as the default for each address type, eliminating ambiguity when downstream modules (accounts payable, order management, shipping) need to resolve where to send an invoice, a shipment, or a legal notice. When no explicit override is provided on a transaction, the relevant default address is used automatically.

## Business Purpose

Partners routinely operate out of more than one location and require different addresses for different purposes. This feature enables:

- Separate billing and shipping addresses so that invoices reach the accounts-payable office while goods arrive at the warehouse
- A registered address that captures the legal domicile of a corporate partner for compliance, contract, and regulatory correspondence
- An OTHER classification for secondary or informal locations not covered by the primary types
- A default-per-type designation that downstream modules can resolve without bespoke selection logic
- Structured, country-aware address fields that support postal validation and country-specific formatting rules
- Independent address lifecycle — addresses can be added, updated, or removed without altering the partner's own record or status. Adding new addresses requires the partner to be in DRAFT or ACTIVE state; INACTIVE partners may only have their existing addresses read or updated, not extended with new entries
- Preservation of address history: removing an address that has been referenced on historical transactions is prevented to maintain referential integrity

## Process Flow

The following diagram shows the end-to-end flow for managing addresses on a partner:

```mermaid
flowchart TD
    A[Partner exists in system] --> B[Add address to partner]
    B --> C[Provide structured address fields\nline1, city, postalCode, country, addressType]
    C --> D{Mark as default\nfor this type?}
    D -->|Yes| E[Set isDefault = true\nfor this addressType]
    D -->|No| F[Address saved as non-default]
    E --> G[Previous default of same type\nautomatically unset]
    G --> H[Address available for\ndownstream resolution]
    F --> H
    H --> I{Update needed?}
    I -->|Yes| J[Update address fields]
    J --> H
    I -->|No| K{Remove address?}
    K -->|Yes| L{Address referenced\non transactions?}
    L -->|Yes| M[Reject removal —\npreserve referential integrity]
    L -->|No| N[Delete address]
    K -->|No| H
```

The default-resolution flow used by downstream modules:

```mermaid
flowchart TD
    A[Downstream module needs address] --> B[Specify partner + addressType]
    B --> C{Default address\nexists for this type?}
    C -->|Yes| D[Return default address]
    C -->|No| E{Any address\nof this type exists?}
    E -->|Yes| F[Return error —\ncaller must select explicitly]
    E -->|No| G[Return error —\nno address of this type exists]
```

## Scenario Patterns

- **Separate billing and shipping**: A distributor's finance department is located at the head office, but deliveries go to a regional warehouse. Two addresses are added to the partner: one with type BILLING marked as default, one with type SHIPPING marked as default. Purchase orders automatically route the invoice to the head office and the shipment to the warehouse
- **Legal registered address**: A corporate partner is registered with a government authority at a different location from its operational offices. A REGISTERED address is added to hold the statutory address used for compliance filings and contract headers
- **Multiple shipping sites**: A large retail chain partner has three distribution centers. Three SHIPPING addresses are maintained; one is marked as the default and the others are available for explicit selection on individual orders
- **Address correction**: A partner's postal code changes after a municipal rezoning. The affected address record is updated in place without creating a new address or touching the partner's master record
- **Expanding to a new country**: A partner opens a new subsidiary in another country. A second BILLING address is added with the appropriate country code and regional postal format, and the default BILLING designation is moved to the new address
- **Removing an obsolete address**: A partner closes one of its warehouses. The corresponding SHIPPING address is removed, provided no open or historical transactions reference it
- **OTHER address for informal site**: A partner uses a forwarding agent at a location that does not fit BILLING, SHIPPING, or REGISTERED. An OTHER address is recorded to capture the forwarding address for ad hoc use

## Test Cases

- An address cannot be created without a valid, existing parent partner
- address fields line1, city, postalCode, country, and addressType are required at creation
- line2 is optional
- country must be a valid ISO 3166-1 alpha-2 code
- addressType must be one of BILLING, SHIPPING, REGISTERED, OTHER
- A partner may hold multiple addresses of the same type
- Setting isDefault = true for an addressType automatically unsets isDefault on any previous default of the same type for the same partner
- Only one address per partner per addressType may be marked as default at any time
- Retrieving the default address for a partner and type returns exactly the address with isDefault = true for that type
- A partner can have independent defaults for BILLING, SHIPPING, REGISTERED, and OTHER simultaneously
- Updating address fields (line1, line2, city, state, postalCode, country) on an existing address record is permitted
- addressType is immutable after creation; changing type requires deleting the old address and creating a new one
- Deleting an address that is referenced on a historical or open transaction is rejected to preserve referential integrity
- Deleting the default address of a type does not automatically promote another address of the same type to default; no default exists until one is explicitly set
- Querying addresses by partner returns all addresses for that partner
- Querying addresses by partner and addressType returns only addresses of the requested type
- A partner with no addresses returns an empty list, not an error
- Reading and updating existing addresses is permitted regardless of partner status (DRAFT, ACTIVE, or INACTIVE)
- Adding new addresses to a partner requires the partner to be in DRAFT or ACTIVE state; adding to an INACTIVE partner is rejected
- When no default address exists for a requested type, the system returns an error rather than silently picking an arbitrary address; the caller must either set a default or select an address explicitly

## Reference Links

- [SAP Business Partner Address Management (BP)](https://help.sap.com/docs/SAP_S4HANA_ON-PREMISE/f76052846e404ea8811eb06534b6e099/5e13e82b8ca111d1a6090000e8353423.html)
- [Odoo Contact Addresses (child records under res.partner)](https://www.odoo.com/documentation/19.0/applications/inventory_and_mrp/inventory/shipping_receiving/setup_configuration/delivery_countries.html)
- [Dynamics 365 Party postal addresses](https://learn.microsoft.com/en-us/dynamics365/finance/accounts-payable/vendor-posting-profiles)
- [Oracle Supplier Sites and Addresses](https://docs.oracle.com/en/cloud/saas/procurement/24d/faaps/supplier-addresses.html)
- [ISO 3166-1 alpha-2 Country Codes](https://www.iso.org/iso-3166-country-codes.html)
