---
feature: Service addresses
slug: addresses
surface: client
consumer: flutter
version: 1.0.1
status: ready
brd_version: "1.3"
brd_ids: [CUST-004]
business_rules: [BR-02, BR-08]
decisions: [DEC-15, DEC-17, TD-01, TD-03, TD-08, TD-09, TD-11, TD-19, TD-22, TD-25, TD-30, TD-56, TD-57, TD-68, TD-69]
schema_tables: [customer_addresses, customers, users, governorates, governorate_translations, regions, region_translations]
screens: [customer--account--04-*]
related_docs: [auth.md, ../API_CONVENTIONS.md, ../admin/service-areas.md]
last_updated: 2026-10-26
---

# Service addresses — Flutter Integration Guide (client)

> **Base URL:** `{HOST}/api/v1/client` · Shared headers, envelope and errors:
> [API_CONVENTIONS.md](../API_CONVENTIONS.md).

## Version history

| Version | Date | Type | Summary | App action required |
|---------|------|------|---------|---------------------|
| 1.0.1 | 2026-10-26 | PATCH | Documentation only: validation 422 examples and rows now show `data.errors` (`{field: [messages]}`, TD-02, API_CONVENTIONS 2.7.0) instead of `data: null`; examples are the captured Postman responses. | None. |
| 1.0.0 | 2026-10-22 | Initial | CUST-004 CRUD, active service-area validation and atomic defaults on customer_addresses. | Integrate the six routes and resource below; replace any legacy address model. |

## Changelog

### 1.0.1 — 2026-10-26

- **Added:** N/A.
- **Changed:** Validation 422 examples and error-table rows show `data.errors`, not `data: null` (TD-02).
- **Fixed:** Documentation only; the server already returned `data.errors`.
- **Removed / Deprecated:** N/A.
- **Breaking:** No.
- **Endpoints affected:** None (documentation).
- **App action required:** None; map `data.errors` onto form fields, fall back to `message`.
- **BRD / decisions:** TD-02.

### 1.0.0 — 2026-10-22

- **Added:** Six customer-app endpoints; UUID ownership, localized label category and geo names, formatted address, paired map coordinates, soft deletion and default promotion.
- **Changed:** TD-30 address unregistration is superseded by TD-68/69. Legacy AddressController/AddressRequest/Address services and the base addresses table remain reference-only.
- **Fixed:** N/A, initial feature release.
- **Removed / Deprecated:** No previously shipped address API; do not integrate the legacy title/address/country_id/governorate_id/region_id payload.
- **Breaking:** No shipped address contract to migrate. New storage/contract replaces the unrouted base implementation.
- **Endpoints affected:** GET/POST `/addresses`, GET/PUT/DELETE `/addresses/{address}`, PATCH `/addresses/{address}/default`.
- **App action required:** Parse UUIDs and the full stable resource; mirror validation; refresh the list after deleting or changing default; handle typed service-area alerts.
- **BRD / decisions:** CUST-004, AC-CUST-004, BR-02/08, TD-30/56/57/68/69.

## 1. Business summary

Customers save, edit and remove their service addresses and select a default. The first saved address becomes default automatically; deleting it promotes the newest remaining address. Saving or explicitly selecting a default requires an active city and, when supplied, an active district belonging to that city.

City means the existing governorates table; district means regions. There is no maximum address count. A saved/default address does not certify provider coverage, booking availability or delivery pricing: those checks belong to booking/discovery and must be rerun there.

## 2. User flow and screens

Only `customer--account--04-addresses.png` was inspected. It shows the saved count, home/work icons, formatted location, default badge, set-default/delete controls, and two add-address entry points. Create/edit fields follow the BRD/schema contract; no additional form screen was opened.

| Step | Screen / widget | Endpoint | Notes (states, empty, loading, errors) |
|------|-----------------|----------|---------------------------------------|
| 1 | Address list | GET `/addresses` | `data` is a plain array; count = its length. Preserve server order. Loading, retry and empty/add states belong in Flutter. |
| 2 | Add (+ / Add a new address) | POST `/addresses` | Send selected geo UUIDs and form fields. Add the returned record or reload; show its is_default badge. |
| 3 | Address editor | GET then PUT `/addresses/{address}` | Prefill from stable keys; omitted PUT fields are preserved. Changing city requires clearing/replacing an incompatible district. |
| 4 | Set default | PATCH `/addresses/{address}/default` | Show success from the response then reload the list to update the previous default and ordering. Repeating is safe. |
| 5 | Delete | DELETE `/addresses/{address}` | Reload after success; the response does not include the promoted address. A stale 404 also means the row should be removed/refetched. |

## 3. Endpoints

### Common authentication, headers and errors

Every route requires `Authorization: Bearer <customer-app JWT>`, its matching customers profile, and the existing active-account check (`auth:api`, `app:customer`, `active`). Guests cannot use this feature; provider/driver tokens are rejected even for the same person with a customer profile. Admin RBAC and approved-provider checks are N/A.

Send `Accept: application/json`, `Accept-Language: ar|en` and `Content-Type: application/json` for bodies. No X-Country/X-City header or Idempotency-Key is required. No route-specific throttle is configured. Successful responses are `Cache-Control: no-store, private`.

All `{address}` path parameters are **UUID strings** for the customer's live saved address. Foreign, deleted, missing, integer and malformed identifiers share `404 ENTITY_NOT_FOUND`; PUT resolves ownership before body validation. There are no list filters, sorting options or pagination/query fields; the list request explicitly returns empty `rules()` and `queryParameters()` (TD-56/69). Query input cannot change the fixed list order.

| HTTP | `data.error_code` | Applies to / when | Flutter action |
|------|-------------------|-------------------|----------------|
| 401 | UNAUTHENTICATED | Every route: missing/invalid token | Sign in with the customer app. |
| 403 | PERMISSION_DENIED | Every route: wrong app claim or missing customer profile | Use customer login; do not retry with a provider/driver token. |
| 403 | ACCOUNT_INACTIVE | Every route: disabled/banned account | Show the account restriction message. |
| 404 | ENTITY_NOT_FOUND | Show/update/delete/set-default: target not reachable | Refresh addresses and discard stale selection. |
| 422 | N/A (`data.errors`) | Create/update: body shape, missing fields, invalid UUID or coordinate pair | Map `data.errors` (`{field: [messages]}`) onto the form fields; fall back to `message` when `data.errors` is absent (TD-02). |
| 422 | SERVICE_AREA_UNAVAILABLE | Create/update/set-default: selected city or district inactive | Alert the customer and ask for another enabled service area. |
| 422 | BUSINESS_RULE_VIOLATED | Create/update/set-default: district does not belong to resulting city | Re-select district or clear it; retain unsaved text for correction. |

Domain responses include `data.error_code` and `data.correlation_id`. Diagnostic `data.context` can be hidden outside debug; never require it for branching. The captured examples below are actual responses from the named MySQL tests; the complete success/error sets are the saved responses of each request in the [Postman collection](../postman-collection.json).

### 3.1 List saved addresses

`GET /api/v1/client/addresses` · route `client.addresses.index`

Auth/headers: common contract above. Path/query/body: N/A. Order is default first, then `created_at DESC, id DESC`; soft-deleted and other customers' rows are excluded. Returns all rows without pagination or a count limit.

**Success — 200 (nonempty)**

```json
{
  "status": "success",
  "message": "",
  "data": [
    {
      "id": "01a162d8-9837-709c-a485-77e399044320",
      "label": "Office",
      "label_type": {
        "value": "work",
        "label": "Work"
      },
      "city": {
        "id": "01a162d8-9802-71de-be97-3d17a77fca54",
        "name": "Riyadh"
      },
      "district": null,
      "address_line": "Building 5",
      "details": null,
      "lat": null,
      "lng": null,
      "is_default": true,
      "formatted": "Riyadh، Building 5"
    }
  ]
}
```

**Success — 200 (empty)**

```json
{
  "status": "success",
  "message": "",
  "data": []
}
```

Errors: common 401 and 403 only.

### 3.2 Create an address

`POST /api/v1/client/addresses` · route `client.addresses.store`

Auth/headers: common contract above. Path/query: N/A. Body is JSON. The fields below also apply to PUT, where omission preserves the existing value. No ownership/default/deletion fields are writable through either payload; use PATCH for an explicit default change.

| Field | Type | Required on POST | Validation / behavior |
|-------|------|------------------|-----------------------|
| label | string | yes | Nonempty, max 60; customer-visible name. |
| label_type | string enum | no | home / work / other; schema default other. Cannot be null when supplied. |
| city_id | UUID string | yes | Existing governorates.uuid; active service area. |
| district_id | UUID string or null | no | Existing regions.uuid, active and belonging to city. Omitted/null on POST means no district. |
| address_line | string | yes | Nonempty, max 255; street/building. |
| details | string or null | no | Max 255; floor/unit/arrival instructions. |
| lat | number or null | paired | -90 through 90 inclusive. Send both keys together: two numbers or two nulls. |
| lng | number or null | paired | -180 through 180 inclusive. Stored to six decimal places under the existing schema. |

Empty nullable text is normalized to null by the shared request middleware. Coordinates are optional; both omitted is valid. First live address becomes default; later creates do not replace it.

**Request captured with the success below**

```json
{
  "label": "Home",
  "label_type": "home",
  "city_id": "01a162d8-9802-71de-be97-3d17a77fca54",
  "district_id": "01a162d8-980b-71e7-8d31-03a3b39e92d2",
  "address_line": "Prince Sultan Street, Villa 12",
  "details": "First floor",
  "lat": 24.713552,
  "lng": 46.675296
}
```

**Success — 201**

```json
{
  "status": "success",
  "message": "",
  "data": {
    "id": "01a162d8-9837-709c-a485-77e399044320",
    "label": "Home",
    "label_type": {
      "value": "home",
      "label": "Home"
    },
    "city": {
      "id": "01a162d8-9802-71de-be97-3d17a77fca54",
      "name": "Riyadh"
    },
    "district": {
      "id": "01a162d8-980b-71e7-8d31-03a3b39e92d2",
      "name": "Al Yasmin"
    },
    "address_line": "Prince Sultan Street, Villa 12",
    "details": "First floor",
    "lat": 24.713552,
    "lng": 46.675296,
    "is_default": true,
    "formatted": "Riyadh، Al Yasmin، Prince Sultan Street, Villa 12، First floor"
  }
}
```

Errors: common 401/403; 422 validation, SERVICE_AREA_UNAVAILABLE or BUSINESS_RULE_VIOLATED. No count-limit error.

### 3.3 Show an address

`GET /api/v1/client/addresses/{address}` · route `client.addresses.show`

Auth/headers: common contract. Path: owned live address UUID. Query/body: N/A. Saved addresses remain readable if the city/district has since been disabled.

**Success — 200**

```json
{
  "status": "success",
  "message": "",
  "data": {
    "id": "01a162d8-9837-709c-a485-77e399044320",
    "label": "Home",
    "label_type": {
      "value": "home",
      "label": "Home"
    },
    "city": {
      "id": "01a162d8-9802-71de-be97-3d17a77fca54",
      "name": "Riyadh"
    },
    "district": {
      "id": "01a162d8-980b-71e7-8d31-03a3b39e92d2",
      "name": "Al Yasmin"
    },
    "address_line": "Prince Sultan Street, Villa 12",
    "details": "First floor",
    "lat": 24.713552,
    "lng": 46.675296,
    "is_default": true,
    "formatted": "Riyadh، Al Yasmin، Prince Sultan Street, Villa 12، First floor"
  }
}
```

Errors: common 401/403/404. No availability error on reads.

### 3.4 Update an address

`PUT /api/v1/client/addresses/{address}` · route `client.addresses.update`

Auth/headers: common contract. Path: owned live address UUID. Query: N/A. Body fields/limits are in §3.2. All fields may be omitted; supplied label, label_type, city_id and address_line cannot be null/empty. Omitted fields retain their saved values; explicit null clears district_id/details. Clear coordinates with both `lat: null` and `lng: null`; supply both numeric keys to change them.

The Domain checks the resulting city/district even when only label/details were changed. If city changes and the old district is retained, an incompatible district returns BUSINESS_RULE_VIOLATED. Send a compatible replacement or `district_id: null` with the city change. The saved default flag is preserved.

**Real request — optional fields cleared**

```json
{
  "label": "Office",
  "label_type": "work",
  "address_line": "Building 5",
  "district_id": null,
  "details": null,
  "lat": null,
  "lng": null
}
```

**Success — 200**

```json
{
  "status": "success",
  "message": "",
  "data": {
    "id": "01a162d8-9837-709c-a485-77e399044320",
    "label": "Office",
    "label_type": {
      "value": "work",
      "label": "Work"
    },
    "city": {
      "id": "01a162d8-9802-71de-be97-3d17a77fca54",
      "name": "Riyadh"
    },
    "district": null,
    "address_line": "Building 5",
    "details": null,
    "lat": null,
    "lng": null,
    "is_default": true,
    "formatted": "Riyadh، Building 5"
  }
}
```

Errors: common 401/403/404 and the three 422 cases from create. Failed updates leave saved data unchanged.

### 3.5 Soft-delete an address

`DELETE /api/v1/client/addresses/{address}` · route `client.addresses.destroy`

Auth/headers: common contract. Path: owned live address UUID. Query/body: N/A. Deleting a non-default preserves the existing default. Deleting the default promotes the newest remaining live address, using creation time then internal ID as a deterministic tie-breaker. Deleting the final row leaves an empty list; the next create becomes default.

Automatic promotion can choose an area that was disabled after saving. This preserves the specified newest-address rule; explicit selection or later booking must still check availability. Delete itself remains allowed for inactive areas. Reload the list after success.

**Success — 200**

```json
{
  "status": "success",
  "message": "Deleted",
  "data": null
}
```

Errors: common 401/403/404. Repeating deletion returns 404. The row is retained with deleted_at; historical foreign keys are preserved.

### 3.6 Set the default address

`PATCH /api/v1/client/addresses/{address}/default` · route `client.addresses.default`

Auth/headers: common contract. Path: owned live address UUID. Query/body: N/A (send `{}` if the HTTP client requires JSON). Clears the previous live default and sets the target in one transaction; repeating the same active selection leaves it default. Neither create nor PUT accepts a caller-controlled is_default flag.

**Success — 200**

```json
{
  "status": "success",
  "message": "",
  "data": {
    "id": "01a162d8-98a2-7271-9b05-cee48ae8a4a5",
    "label": "Work",
    "label_type": {
      "value": "home",
      "label": "Home"
    },
    "city": {
      "id": "01a162d8-9893-7139-a9fe-b18b8d49474c",
      "name": "Riyadh"
    },
    "district": {
      "id": "01a162d8-9898-70fc-82dd-7594ebc22fde",
      "name": "Al Yasmin"
    },
    "address_line": "Prince Sultan Street, Villa 12",
    "details": "First floor",
    "lat": 24.713552,
    "lng": 46.675296,
    "is_default": true,
    "formatted": "Riyadh، Al Yasmin، Prince Sultan Street, Villa 12، First floor"
  }
}
```

Errors: common 401/403/404; 422 SERVICE_AREA_UNAVAILABLE or BUSINESS_RULE_VIOLATED. Failure preserves the old default. Reload the list after success.

### Response fields (every list item and create/show/update/default result)

| Field | Type | Nullable | Meaning |
|-------|------|----------|---------|
| id | UUID string | no | Public saved-address identifier. |
| label | string | no | User-entered display name. |
| label_type | `{value, label}` | no | Stable icon category and localized label. |
| city | `{id: UUID, name: string}` | no | Governorate with localized name, Arabic fallback. |
| district | `{id: UUID, name: string}` | yes | Region; null when no district. |
| address_line | string | no | Street/building. |
| details | string | yes | Floor/unit/arrival text. |
| lat / lng | JSON number | yes | Numeric coordinates; both null when omitted/cleared. Dart should accept num, not assume an integer or decimal string. |
| is_default | boolean | no | Show the default badge. |
| formatted | string | no | Nonempty city, district, address_line and details joined with Arabic comma + space (`، `). No dangling separators. |

No internal customer/geo integer IDs, generated default_key, timestamps, translations map or ownership data are returned. Action flags are N/A for this resource; actions use the explicit endpoints and their enforced errors.

### Captured failure examples

**422 — unavailable service area**

```json
{
  "status": "fail",
  "message": "Service is unavailable in this city or district. Please choose another service area.",
  "data": {
    "error_code": "SERVICE_AREA_UNAVAILABLE",
    "correlation_id": "af3911dd-badf-4eb1-b8f2-1a321e84883e"
  }
}
```

**422 — incompatible district**

```json
{
  "status": "fail",
  "message": "The selected district does not belong to this city.",
  "data": {
    "error_code": "BUSINESS_RULE_VIOLATED",
    "context": {
      "violations": [
        "The selected district does not belong to this city."
      ]
    },
    "correlation_id": "116908f9-fb56-4da7-a53c-9358f321db42"
  }
}
```

**422 — shape validation**

```json
{
  "status": "fail",
  "message": "The label field is required. (and 2 more errors)",
  "data": {
    "errors": {
      "label": [
        "The label field is required."
      ],
      "city_id": [
        "The city id field is required."
      ],
      "address_line": [
        "The address line field is required."
      ]
    }
  }
}
```

**404 — missing, deleted or foreign address**

```json
{
  "status": "fail",
  "message": "Address not found.",
  "data": {
    "error_code": "ENTITY_NOT_FOUND",
    "correlation_id": "c4eb5b9a-1e5d-4caa-bcfe-72af80daac6d"
  }
}
```

## 4. Statuses and enums

| Enum | value | Meaning | Allowed actions |
|------|-------|---------|-----------------|
| label_type | home | Home icon/category | All owned-address actions. |
| label_type | work | Work icon/category | All owned-address actions. |
| label_type | other | Custom/other address (schema default) | All owned-address actions. |

N/A: address workflow status, status transitions, money and can_* flags. is_default is a boolean, not an enum/status.

## Data model

| Table (`db-schema.sql`) | Read / write | Notes |
|-------------------------|--------------|-------|
| customer_addresses | Read + write | Existing schema/model reused; soft delete. customer_id references customers.user_id, not customers.id. default_key unique index restricts live defaults. |
| customers | Read + row lock | Customer profile supplies stable serialization lock for concurrent first creates, switch/update/delete. No new profile fields. |
| users | Read | JWT identity and active-account boundary. |
| governorates / regions | Read + shared row locks on selection | BRD city/district; active flag and district parent govern writes/default action. |
| governorate_translations / region_translations | Read | Eager-loaded localized names; Arabic fallback. Translation rows have no public UUID (TD-22). |

No migration/schema changes or legacy address data conversion are required by this delivery. Existing populated base addresses are not migrated automatically; only customer_addresses is exposed.

## 5. Dart models

```dart
class AddressLabelType {
  final String value;
  final String label;
  AddressLabelType.fromJson(Map<String, dynamic> j)
      : value = j['value'] as String, label = j['label'] as String;
}

class AddressArea {
  final String id;
  final String name;
  AddressArea.fromJson(Map<String, dynamic> j)
      : id = j['id'] as String, name = j['name'] as String;
}

class ServiceAddress {
  final String id, label, addressLine, formatted;
  final AddressLabelType labelType;
  final AddressArea city;
  final AddressArea? district;
  final String? details;
  final double? lat, lng;
  final bool isDefault;

  ServiceAddress.fromJson(Map<String, dynamic> j)
      : id = j['id'] as String,
        label = j['label'] as String,
        labelType = AddressLabelType.fromJson(j['label_type'] as Map<String, dynamic>),
        city = AddressArea.fromJson(j['city'] as Map<String, dynamic>),
        district = j['district'] == null ? null
            : AddressArea.fromJson(j['district'] as Map<String, dynamic>),
        addressLine = j['address_line'] as String,
        details = j['details'] as String?,
        lat = (j['lat'] as num?)?.toDouble(),
        lng = (j['lng'] as num?)?.toDouble(),
        isDefault = j['is_default'] as bool,
        formatted = j['formatted'] as String;
}
```

The list parses `response['data']` as `List<dynamic>`, with no pagination wrapper. Do not send the parsed enum object back as label_type; send its value string. On PUT, distinguish omitted fields from explicit null clears.

## 6. Business rules enforced by the backend

| Rule | Backend behavior | User-visible result |
|------|------------------|---------------------|
| CUST-004 / BR-02 / TD-25 | Customer-app token, matching profile and ownership required. | Login/denial or indistinguishable missing-address response. |
| CUST-004 / BR-08 | Active city/district required when saving or explicitly setting default. | SERVICE_AREA_UNAVAILABLE alert. |
| TD-69 | District must belong to resulting city; both coordinate keys travel together. | Typed domain error or ordinary shape validation. |
| TD-68 | First address auto-default; default switch and delete/promotion are transactional under the customer lock. | One live default; newest promoted after deleting it. |
| TD-19/22/30 | UUID-only new address contract on schema storage. | Stable Flutter keys; no raw base Address model. |

Provider coverage, availability, selection during booking and delivery-fee calculation are CUST-004 consumers in their own features; this API does not implement or certify them.

## 7. Notifications and real-time events

N/A: this feature emits no push/inbox event. The unavailable-service-area alert is the synchronous localized 422 response. Refresh local list state after mutations.

## 8. Localization and UI notes

- Accept-Language selects API enum labels and translated geo names; the stable values stay home/work/other. label, address_line and details remain user-entered text.
- formatted follows the requested Arabic-comma composition in both languages; null/empty optional parts are skipped. A literal `0` detail is retained.
- Use label_type.value for the home/work/other icon and is_default for the badge. Preserve server ordering and derive the saved-address count from array length.
- Coordinates are optional. A missing map location does not block a textual address. Map/geocoding provider selection is outside this feature.
- Default selection and delete should refresh the list. Handle loading/empty/retry states; do not silently turn a failed write into a successful local change.

## 9. Integration checklist

- [ ] Parse all stable fields, UUIDs, nullable district/details/coordinates and enum objects.
- [ ] Use a customer token and implement every error branch in §3.
- [ ] Mirror string limits and paired coordinate validation.
- [ ] Reload after switching or deleting default; keep the server's order.
- [ ] Implement empty, loading, submit-in-progress and recoverable error states.
- [ ] Test Arabic RTL and English; use localized API labels and formatted address.
- [ ] Use generated Postman address_id and client_token chaining (TD-57); city_id/district_id carry the saved governorate/region UUID variables.
- [ ] Recheck address availability and provider coverage in the later booking flow.

## 10. Acceptance scenarios

All backend scenarios are covered by `tests/Feature/Api/V1/Client/CustomerAddressControllerTest.php` with `test_ac_cust_004_*` names on MySQL joshen_testing. PostmanVariablesTest additionally checks the empty query contract, field descriptions and saved address UUID chaining; AccountRoutesTest verifies the formerly removed route is now live.

| AC ID | Scenario | Expected |
|-------|----------|----------|
| AC-CUST-004 | Create/list/show/edit/delete address | Persisted customer_addresses data, public UUIDs, stable keys, soft-delete exclusion; legacy addresses table untouched. |
| AC-CUST-004 | First/later create, default switching/repeating | First default only; exactly one live default after switch; another customer's default unchanged. |
| AC-CUST-004 | Delete default/non-default/last, tied creation times | Newest live remaining row promoted; creation time then internal ID; next first create becomes default. |
| AC-CUST-004 | Inactive city/district on create/update/default | 422 SERVICE_AREA_UNAVAILABLE, unchanged persisted/default state; saved record still readable/deletable. |
| AC-CUST-004 | District from another city or changing city while retaining district | 422 BUSINESS_RULE_VIOLATED; explicit compatible replacement succeeds. |
| AC-CUST-004 | Missing required/oversized fields, invalid UUIDs, coordinate ranges/pair | 422 standard validation; no create or partial update. |
| AC-CUST-004 | Foreign/deleted/missing/malformed/integer address | Same 404 ENTITY_NOT_FOUND on show/update/delete/default; no foreign mutation or list disclosure. |
| AC-CUST-004 | Provider/driver token, missing customer profile, guest, disabled account | 403/401 as documented on all six endpoints. |
| AC-CUST-004 | Failure while saving new default or promotion | Entire default switch or deletion rolls back. |
| AC-CUST-004 | Arabic/fallback formatting, nullable fields, partial PUT, protected fields, >12 addresses | Exact resource contract and no application address-count limit. |

The BRD's booking-completion acceptance case still requires the booking feature: unavailable addresses must also be refused there. These are local backend acceptance results, not deployed or Flutter end-to-end acceptance. Simultaneous multi-connection race execution was not tested; the parent-row lock and unique generated key implement that boundary.

## 11. Open decisions and known limitations

| ID | Impact | Current behavior |
|----|--------|------------------|
| TD-68 | BRD is silent on deleting the default. | Owner-supplied newest-live promotion is recorded and implemented. |
| TD-69 | Request/response, unavailable saved areas, district validation, ownership, empty query contract. | Recorded implementation choices; no unresolved decision blocks this API. |
| CUST-004 downstream scope | Booking selection/coverage/delivery pricing. | Remain with booking/discovery/provider features; CRUD/default alone is not booking eligibility. |
| Legacy base storage | Existing addresses records, if any. | No automatic import or reinterpretation; classes remain reference-only under TD-30/69. |
