> ## Documentation Index
> Fetch the complete documentation index at: https://docs.digifist.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Addresses

> Customer address book management template for adding, editing, and deleting shipping addresses

The Main Addresses template creates the address book management page where logged-in customers can view, add, edit, and delete their saved shipping and billing addresses. This interface accessible from the account dashboard automatically handles address CRUD operations through Shopify's customer address API. Use this template to provide customers with convenient address management that streamlines future checkouts and improves order accuracy through saved, validated addresses.

***

## Template Purpose

The address book allows customers to manage multiple shipping destinations:

<CardGroup cols={2}>
  <Card title="View All Addresses" icon="list">
    Displays all saved addresses in an organized list with default address highlighted
  </Card>

  <Card title="Add New Address" icon="plus">
    Provides form to create new shipping/billing addresses with full validation
  </Card>

  <Card title="Edit Addresses" icon="pen-to-square">
    Allows modification of existing address details including marking as default
  </Card>

  <Card title="Delete Addresses" icon="trash">
    Enables removal of unused addresses (except default address)
  </Card>
</CardGroup>

***

## Template Settings

The Main Addresses template provides minimal customization, focusing on section-level styling:

<AccordionGroup>
  <Accordion title="Section Width" icon="left-right">
    * **Page Width** (default) - Contained within page margins
    * **Fluid Width** - Extends to container edges

    <Note>
      Full width is not available for address pages to maintain comfortable form width and readability.
    </Note>
  </Accordion>

  <Accordion title="Color Scheme" icon="palette">
    * Select from available theme color schemes
    * **Default:** scheme-1

    <Tip>
      Use the same color scheme across all account templates (account, addresses, order) for consistent customer experience.
    </Tip>
  </Accordion>

  <Accordion title="Spacing" icon="arrows-up-down">
    * **Top Spacing**: 0, 1, 2 (default), 4, or 6
    * **Bottom Spacing**: 0, 1, 2 (default), 4, or 6
  </Accordion>

  <Accordion title="Borders" icon="border-top-left">
    * **None** (default)
    * **Top Border**
    * **Bottom Border**
    * **Both Borders**
  </Accordion>
</AccordionGroup>

***

## Address Management Features

While template settings are minimal, the address book provides robust functionality:

### Address Display

<AccordionGroup>
  <Accordion title="Address Cards" icon="address-card">
    Each saved address displays:

    * Full name
    * Street address (line 1 and line 2)
    * City, State/Province, ZIP/Postal code
    * Country
    * Phone number (if provided)
    * **Default** badge for default address
  </Accordion>

  <Accordion title="Default Address" icon="star">
    The default address is:

    * Highlighted with visual indicator (badge or styling)
    * Pre-selected during checkout
    * Cannot be deleted (must set another as default first)
    * Used for subscription deliveries and auto-orders
  </Accordion>

  <Accordion title="Address Limits" icon="hashtag">
    Shopify allows customers to save:

    * Up to **100 addresses** per customer account
    * 1 default address (must always exist)
    * Unlimited billing addresses (stored same way)
  </Accordion>
</AccordionGroup>

### Address Actions

<AccordionGroup>
  <Accordion title="Add New Address" icon="square-plus">
    **Form Fields:**

    * First name and Last name (required)
    * Company (optional)
    * Address line 1 (required)
    * Address line 2 (optional)
    * City (required)
    * Country/region (dropdown, required)
    * State/Province (dropdown, conditional based on country)
    * ZIP/Postal code (required, format validated by country)
    * Phone (optional, recommended for shipping)
    * "Set as default address" checkbox

    <Note>
      Form fields and validation rules automatically adjust based on country selection (e.g., US shows "State" and "ZIP", UK shows "County" and "Postcode").
    </Note>
  </Accordion>

  <Accordion title="Edit Address" icon="pencil">
    * Click "Edit" on any saved address
    * Form pre-fills with current address data
    * Update any field and save
    * Option to change default status
    * Validation ensures required fields are complete
  </Accordion>

  <Accordion title="Delete Address" icon="x">
    * Click "Delete" on any non-default address
    * Confirmation prompt before deletion ("Are you sure?")
    * Default address cannot be deleted directly
    * To delete current default: set another as default first, then delete
  </Accordion>
</AccordionGroup>

***

## Customer Access Requirements

<Warning>
  The Main Addresses template is only accessible to **logged-in customers**. Visitors not logged in are redirected to the login page.
</Warning>

**Access Control:**

| Customer State | Access  | Result                         |
| -------------- | ------- | ------------------------------ |
| Logged In      | Granted | Manage address book            |
| Not Logged In  | Denied  | Redirected to `/account/login` |
| Guest Checkout | Denied  | No account = no address book   |

***

## Address Book Workflow

### First-Time User Flow

1. Customer creates account (Main Register template)
2. During checkout, enters shipping address
3. Option to save address to account (checkbox)
4. First saved address automatically becomes default
5. Navigate to Addresses page from account dashboard
6. View, edit, or add more addresses

### Returning Customer Flow

1. Customer logs in (Main Login template)
2. Navigates to account dashboard (Main Account template)
3. Clicks "View addresses" or "Manage addresses"
4. Lands on Addresses page
5. Performs address management tasks
6. Returns to account or continues shopping

***

## Best practices

<CardGroup cols={2}>
  <Card title="Form design" icon="input-text">
    Keep address forms clean and well-organized with clear field labels that avoid abbreviations. Group related fields together, show validation errors inline, and provide helpful error messages beyond just "Invalid format".
  </Card>

  <Card title="User guidance" icon="circle-info">
    Explain what "default address" means and indicate required vs optional fields clearly. Show country-specific format hints and provide example formats for phone numbers, then confirm successful actions like address saved or deleted.
  </Card>

  <Card title="Design consistency" icon="palette">
    Match form styling across account templates and use consistent button styles for Save, Cancel, and Delete actions. Maintain the same spacing and color scheme as Main Account with consistent navigation elements.
  </Card>

  <Card title="Mobile optimization" icon="mobile-screen">
    Test address forms thoroughly on mobile devices to ensure dropdown selectors are touch-friendly and keyboards open correctly. Verify validation errors are visible without scrolling and make Edit/Delete buttons adequately sized for touch.
  </Card>

  <Card title="International support" icon="globe">
    Address forms auto-adapt to country selection with State/Province dropdowns appearing only for applicable countries. Postal code format validation matches country rules, phone fields accept international formats, and forms should be tested with various countries.
  </Card>
</CardGroup>

***

## Common Use Cases

<CardGroup cols={2}>
  <Card title="Multi-Location Shipping" icon="truck-fast">
    Customers with multiple delivery addresses (home, office, vacation property)
  </Card>

  <Card title="Gift Shipping" icon="gift">
    Save recipient addresses for easy future gift sending
  </Card>

  <Card title="Business Accounts" icon="building">
    B2B customers with multiple warehouse or store locations
  </Card>

  <Card title="Seasonal Addresses" icon="calendar">
    Customers with seasonal residences (snowbirds, students)
  </Card>
</CardGroup>

***

## Extending the Address Page

While the core template is functional, you can enhance it:

<CardGroup cols={2}>
  <Card title="Help Text" icon="circle-question">
    Add Rich Text section above with address management tips or FAQs
  </Card>

  <Card title="Shipping Info" icon="truck">
    Include Trust Indicators section mentioning shipping policies and delivery times
  </Card>

  <Card title="International Notice" icon="earth-americas">
    Add Callout Banner for international shipping information or restrictions
  </Card>
</CardGroup>

<Tip>
  Add sections to the addresses template in Theme Customizer: **Online Store → Themes → Customize → Customers → Addresses**
</Tip>

***

## Related Templates

<CardGroup cols={2}>
  <Card title="Main Account" icon="user-circle">
    Account dashboard showing order history and quick link to address management
  </Card>

  <Card title="Main Order" icon="receipt">
    Order details page displaying shipping address used for specific order
  </Card>

  <Card title="Main Login" icon="right-to-bracket">
    Login page required before accessing address management
  </Card>
</CardGroup>

***

## Troubleshooting

<AccordionGroup>
  <Accordion title="Can't Delete Default Address" icon="shield-exclamation">
    **Expected Behavior:**
    Default address cannot be deleted to ensure customer always has at least one address.

    **Solution:**

    1. Add or select another address
    2. Mark that address as default
    3. Then delete the former default address
  </Accordion>

  <Accordion title="Address Not Saving" icon="floppy-disk-circle-xmark">
    **Possible Causes:**

    * Required fields missing
    * Invalid postal code format
    * Phone number format issue
    * JavaScript errors preventing form submission

    **Solutions:**

    1. Check all required fields are filled
    2. Verify postal code matches country format
    3. Check browser console for errors
    4. Try in incognito mode (rule out cache/extension issues)
  </Accordion>

  <Accordion title="State/Province Not Showing" icon="map-location-dot">
    **Reason:**
    State/Province dropdown only appears for countries that use provinces/states (US, Canada, Australia, etc.).

    **Not a bug:**
    Countries like UK, France, Germany don't have this field in Shopify's address system.
  </Accordion>

  <Accordion title="Validation Errors" icon="triangle-exclamation">
    **Common Issues:**

    * ZIP code format (US: 5 digits or 5+4; UK: alphanumeric postcode)
    * Phone number requirements vary by merchant settings
    * Address line too long (Shopify has character limits)

    **Fix:**
    Follow format hints shown in form, or abbreviate long street names/building names.
  </Accordion>
</AccordionGroup>

***

## Developer Notes

### Address Object Structure

Shopify customer addresses contain:

* `id` - Unique address identifier
* `first_name`, `last_name`
* `company` (optional)
* `address1`, `address2`
* `city`, `province`, `zip`
* `country`, `country_code`
* `phone` (optional)
* `default` - Boolean flag

### Form Handling

The address form automatically:

* Submits to `/account/addresses` endpoint
* Validates fields client-side and server-side
* Returns to address list on success
* Shows inline errors on failure
* Handles CSRF token security

<Warning>
  Address management forms are Shopify-native. Custom validation or fields require theme development and may break Shopify's address API integration.
</Warning>

***

## Quick Summary

* **Purpose:** Customer address book management interface
* **Access:** Logged-in customers only
* **Core Features:** Add, edit, delete, set default address
* **Configuration:** Minimal (section width, color scheme, spacing, borders)
* **Address Limit:** 100 addresses per customer
* **Default Address:** Required (cannot delete the only/default address)
* **Related Pages:** Account dashboard, Order details, Checkout

<Note>
  Address management is handled automatically by Shopify. The template provides the UI, while Shopify manages data storage, validation, and checkout integration.
</Note>