EventCatalog | Entities

Overview

The Address entity stores shipping and billing addresses for customers, orders, and payments. It supports address validation, geocoding, and delivery instructions to ensure accurate order fulfillment.

Entity Properties

Name	Type	Required	Description
`addressId`	`UUID`	Required	Unique identifier for the address
`customerId`	`UUID`	Optional	Customer this address belongs to
`type`	`string`	Required	Type of address
`firstName`	`string`	Required	First name of the recipient
`lastName`	`string`	Required	Last name of the recipient
`company`	`string`	Optional	Company name if applicable
`addressLine1`	`string`	Required	Primary address line (street address)
`addressLine2`	`string`	Optional	Secondary address line (apartment, suite, etc.)
`city`	`string`	Required	City name
`state`	`string`	Required	State or province
`postalCode`	`string`	Required	Postal or ZIP code
`country`	`string`	Required	Country code (ISO 3166-1 alpha-2)
`phone`	`string`	Optional	Phone number for delivery contact
`isDefault`	`boolean`	Required	Whether this is the default address for the customer
`isValidated`	`boolean`	Required	Whether the address has been validated
`validationDetails`	`object`	Optional	Address validation details
`geocoordinates`	`object`	Optional	Geographic coordinates for the address
`deliveryInstructions`	`string`	Optional	Special delivery instructions
`orders`	`array`	Optional	Orders using this address
`payments`	`array`	Optional	Payments using this as billing address
`createdAt`	`DateTime`	Required	Date and time when the address was created
`updatedAt`	`DateTime`	Optional	Date and time when the address was last updated

Relationships

Customer: An address can belong to one Customer (identified by customerId).
Order: An address can be used by multiple Order entities for shipping.
Payment: An address can be used by multiple Payment entities for billing.

Address Types

Billing: Used for payment processing and invoicing
Shipping: Used for order delivery
Both: Can be used for both billing and shipping

Examples

Address #1: John Doe’s home address - default shipping and billing address.
Address #2: Corporate office address - billing only, validated with high confidence.
Address #3: Gift recipient address - shipping only, with special delivery instructions.

Business Rules

Each customer can have only one default address per type
Addresses must be validated before being marked as default
International addresses require country-specific validation
Geocoordinates are automatically populated when available
Address changes should create new versions for audit trail
PO Box addresses may have shipping restrictions
Address validation improves delivery success rates

Address (v1.0.0)