Customer Address

First-Pass Node Dossier

This page is an evidence-backed node dossier generated from the domain hierarchy and node questionnaire.

What It Is

Customer Address is the customer-owned address flow in Pyle. In the packaged product, these records are implemented on the generic Address model and surfaced through the customer-address controllers and resources. The separate CustomerAddress model exists in the codebase, but it should not be treated as the primary packaged surface for this workflow.

Parent hierarchy:

• Customer Management
• Customer-Owned Records
• Customer Address

Primary implementation paths:

• packages/framework/src/Models/Address.php
• packages/framework/src/Http/Controllers/Api/Admin/CustomerAddressesController.php
• packages/framework/src/Http/Controllers/Api/Storefront/CustomerAddressesController.php
• packages/framework/src/Http/Resources/Admin/CustomerAddressResource.php
• packages/framework/src/Http/Resources/Storefront/CustomerAddressResource.php

What Users Can Do With It

Direct capabilities

Admin users can:

• list customer addresses from a customer record
• create a new address for a customer
• edit an existing address
• delete an address
• set a default shipping or billing address

Storefront users can:

• create their own saved addresses
• edit their own saved addresses
• delete their own saved addresses
• mark an address as the default shipping address
• mark an address as the default billing address

Indirect capabilities

Other workflows use customer addresses without exposing a separate address-admin screen:

• order checkout and account profile flows reuse saved addresses
• shipping and billing selection in cart depends on saved customer addresses
• default-address changes affect what is preselected later
• address updates can affect shipping-postal and territory behavior downstream

Where It Is Managed

Channel	Role	Notes
Admin customer page	Direct	Address management lives on the customer detail page
Admin customer-address API	Direct	Customer address list, create, show, update, delete, and default-address flows are exposed here
Storefront my-account addresses	Direct	Customers manage their own saved addresses
Storefront customer-address API	Direct	Authenticated address CRUD and default-address flows are exposed here
Customer model defaults	Direct system-owned	default_address_id and default_billing_address_id control the active addresses

Sources:

• packages/admin/src/Livewire/Admin/Customer/Page.php
• packages/admin/src/Livewire/Admin/Customer/AddressTable/Block.php
• packages/framework/src/Http/Controllers/Api/Admin/CustomerAddressesController.php
• packages/framework/src/Http/Controllers/Api/Storefront/CustomerAddressesController.php
• packages/storefront/src/Livewire/Storefront/MyAccount/Addresses/Page.php

Channel-Level Field Coverage

Admin and storefront create/edit flows

The packaged create and edit flows expose the same core address fields:

• company
• first_name
• last_name
• address1
• address2
• city
• phone
• country_id
• state_id
• zip

The storefront create flow also resolves the country and state list dynamically.

Sources:

• packages/admin/src/Livewire/Admin/Customer/CreateAddressDialog.php
• packages/admin/src/Livewire/Admin/Customer/EditAddressDialog.php
• packages/storefront/src/Livewire/Storefront/Address/CreateDialog.php
• packages/storefront/src/Livewire/Storefront/Address/EditDialog.php
• packages/storefront/src/Livewire/Storefront/MyAccount/Addresses/ActionDropdown.php

Admin and storefront list shaping

The address APIs expose and filter by:

• id
• addressable_id
• customer_id on storefront responses
• company
• first_name
• last_name
• address1
• address2
• city
• phone
• province_code
• country_code
• state_id
• country_id
• zip

Sources:

• packages/framework/src/Http/Controllers/Api/Admin/CustomerAddressesController.php
• packages/framework/src/Http/Controllers/Api/Storefront/CustomerAddressesController.php
• packages/framework/src/Http/Resources/Admin/CustomerAddressResource.php
• packages/framework/src/Http/Resources/Storefront/CustomerAddressResource.php

Customer defaults

The customer record itself carries the default address pointers:

• default_address_id
• default_billing_address_id

Sources:

• packages/framework/src/Models/Customer.php
• packages/framework/src/Actions/Customer/UpdateDefaultShippingAddress.php
• packages/framework/src/Actions/Customer/UpdateDefaultBillingAddress.php

Configuration And Data Model

Key model characteristics:

• customer-owned through the Address model
• soft-deletable
• geo-aware
• ERP-syncable
• searchable

Important field groups:

Field Group	Purpose
identity	uuid, external_id
contact	company, first_name, last_name, phone
location	address1, address2, city, state_id, country_id, zip
routing	addressable_id, addressable_type, shipping_postal_code_id

Important rules:

• storefront address updates are restricted to the signed-in customer
• admin address records are also validated against the parent customer
• creating a first address can set it as the default shipping address

Sources:

• packages/framework/src/Models/Address.php
• packages/framework/src/Http/Controllers/Api/Admin/CustomerAddressesController.php
• packages/framework/src/Http/Controllers/Api/Storefront/CustomerAddressesController.php
• packages/framework/src/Actions/Customer/UpdateDefaultAddress.php

Relationships

Customer Address directly relates to:

• customer
• state
• country
• shippingPostalCode

Source:

• packages/framework/src/Models/Address.php

Rules And Downstream Effects

Important rules and effects:

• storefront users can only view and manage addresses that belong to their own customer
• admin update flows rewrite the address record through the generic address action path
• setting a new default address affects future customer and checkout behavior
• address changes can flow into territory and shipping logic through the shared address model

Sources:

• packages/framework/src/Http/Controllers/Api/Storefront/CustomerAddressesController.php
• packages/framework/src/Actions/Address/CreateAddress.php
• packages/framework/src/Actions/Address/UpdateAddress.php
• packages/framework/src/Actions/Customer/UpdateDefaultAddress.php

Integrations And Automation

ERP bridge

The underlying address model is ERP-syncable.

Source:

• packages/framework/src/Services/ErpBridge/Address/AddressErpSyncService.php

Search and activity

Address records participate in activity logging and search indexing through the shared model infrastructure.

Sources:

• packages/framework/src/Models/Address.php
• packages/framework/src/Actions/ActivityLog/Address/AddressCreatedParser.php
• packages/framework/src/Actions/ActivityLog/Address/AddressUpdatedParser.php

Where It Appears To End Users

Customer Address appears in:

• the admin customer detail page
• the storefront my-account addresses page
• checkout and billing/shipping selection flows

Sources:

• packages/admin/src/Livewire/Admin/Customer/Page.php
• packages/storefront/src/Livewire/Storefront/MyAccount/Addresses/Page.php
• packages/storefront/src/Livewire/Storefront/Cart/ShippingAddressBlock.php
• packages/storefront/src/Livewire/Storefront/Cart/BillingAddressBlock.php

Current Documentation Takeaways

• The packaged customer-address workflow is centered on the generic Address model, not the older CustomerAddress model name.
• Admin and storefront both expose the same core address behavior with different permissions and ownership checks.
• Default-address selection is part of the customer record, not a separate address entity.

Open Questions

• The separate CustomerAddress model exists in the repository, but this sprint did not find it as the primary packaged authoring surface.
• Some downstream shipping and tax effects are indirect and depend on how the host app consumes the shared address model.

Sources

• packages/framework/src/Models/Address.php
• packages/framework/src/Models/Customer.php
• packages/framework/src/Models/CustomerAddress.php
• packages/framework/src/Http/Controllers/Api/Admin/CustomerAddressesController.php
• packages/framework/src/Http/Controllers/Api/Storefront/CustomerAddressesController.php