Address Block

Display and manage saved shipping and billing addresses for the currently logged-in customer.

What It Does

The Address block shows a customer’s saved addresses from BigCommerce, allowing them to view, edit, add, and delete addresses. This is typically used in account dashboards for customer self-service address management.

Use cases:

• Account dashboard address management
• Checkout address selection
• Customer profile address book
• Shipping/billing address display

How to Add It

Requirements: Must be used inside the Account parent block.

1. Add an Account block to your page (or open the account page template)
2. Click + inside the Account block
3. Search for “Address”
4. Click to insert

The Address block will automatically display addresses for the currently logged-in customer.

Block Settings

Attributes

• settingsId (string) - Settings configuration identifier
  • Default: ""

Block Support

• HTML editing: Not supported
• Alignment: Inherits from parent
• Nested blocks: Not applicable (self-contained)

Customization

Styling with CSS

/* Address card container */
.wpe-mustang-address {
  display: grid;
  gap: 1.5rem;
  margin-bottom: 2rem;
}

/* Individual address card */
.wpe-mustang-address__card {
  border: 1px solid #ddd;
  border-radius: 8px;
  padding: 1.5rem;
  background: #fff;
}

/* Address type badge (Shipping/Billing) */
.wpe-mustang-address__type {
  display: inline-block;
  padding: 0.25rem 0.75rem;
  background: #f0f0f0;
  border-radius: 4px;
  font-size: 0.875rem;
  font-weight: 600;
  margin-bottom: 0.75rem;
}

/* Default address indicator */
.wpe-mustang-address__default {
  color: #2271b1;
  font-weight: 600;
}

/* Address details */
.wpe-mustang-address__details {
  margin-bottom: 1rem;
  line-height: 1.6;
}

/* Action buttons (Edit/Delete) */
.wpe-mustang-address__actions {
  display: flex;
  gap: 0.75rem;
  margin-top: 1rem;
}

.wpe-mustang-address__edit,
.wpe-mustang-address__delete {
  padding: 0.5rem 1rem;
  border: 1px solid #2271b1;
  background: #fff;
  color: #2271b1;
  border-radius: 4px;
  cursor: pointer;
  transition: all 0.2s;
}

.wpe-mustang-address__edit:hover {
  background: #2271b1;
  color: #fff;
}

.wpe-mustang-address__delete {
  border-color: #d63638;
  color: #d63638;
}

.wpe-mustang-address__delete:hover {
  background: #d63638;
  color: #fff;
}

/* Add new address button */
.wpe-mustang-address__add {
  display: inline-flex;
  align-items: center;
  gap: 0.5rem;
  padding: 0.75rem 1.5rem;
  background: #2271b1;
  color: #fff;
  border: none;
  border-radius: 4px;
  font-weight: 600;
  cursor: pointer;
  transition: background 0.2s;
}

.wpe-mustang-address__add:hover {
  background: #135e96;
}

Custom Layout

Two-column grid:

.wpe-mustang-address {
  display: grid;
  grid-template-columns: repeat(2, 1fr);
  gap: 2rem;
}

@media (max-width: 768px) {
  .wpe-mustang-address {
    grid-template-columns: 1fr;
  }
}

Compact card style:

.wpe-mustang-address__card {
  padding: 1rem;
  border-radius: 4px;
  box-shadow: 0 2px 4px rgba(0, 0, 0, 0.1);
}

.wpe-mustang-address__details {
  font-size: 0.875rem;
}

Common Patterns

Account Dashboard Address Management

[Account Block]
  Account Menu (navigation tabs)
  → Address Block ← (address management)
    [Shipping Address Card]
      Type: Shipping (Default)
      John Doe
      123 Main Street
      Austin, TX 78701
      [Edit] [Delete]

    [Billing Address Card]
      Type: Billing
      John Doe
      456 Oak Avenue
      Austin, TX 78702
      [Edit] [Delete]

    [+ Add New Address]
  Account Orders
  Account Details

Checkout Address Selection

When used in checkout context, the Address block allows customers to:

• Select from saved addresses
• Edit existing addresses inline
• Add new address during checkout
• Set default shipping/billing addresses

Empty State

When customer has no saved addresses:

[Address Block]
  No addresses saved yet.

  [+ Add Your First Address]

Login Requirement

Authentication required: The Address block only displays for logged-in customers.

Unauthenticated behavior:

• Block shows “Please sign in to view addresses” message
• Or redirects to login page (configurable)
• No address data is exposed to non-authenticated visitors

Security: Address data is scoped to the authenticated customer. Customer A can never see Customer B’s addresses.

Block Context

Must be used inside:

• Account parent block

Receives context from:

• Customer authentication session
• Customer ID from BigCommerce

Does not work:

• Standalone (requires Account parent block)
• Outside authenticated customer context
• In public pages without login

Technical Details

Block Name

wpe-mustang/address

View Script

This block includes interactive JavaScript (viewScript) for:

• Add/Edit/Delete address actions
• Form validation
• AJAX calls to BigCommerce API
• Real-time address updates without page reload

Data Source

The Address block communicates with BigCommerce’s Customers API to:

• Retrieve all saved addresses for the authenticated customer
• Display shipping and billing addresses
• Submit new addresses to BigCommerce
• Update existing addresses
• Delete addresses from customer account

Data flow:

1. Customer authentication is verified
2. API request fetches all addresses for customer ID
3. Addresses returned with full details (name, street, city, state, postal code, country)
4. Addresses displayed in WordPress® UI with BigCommerce data
5. Customer actions (add/edit/delete) sent to BigCommerce API
6. UI updates dynamically after successful API response

Storage: Address data is NOT stored in WordPress®. All addresses are managed in BigCommerce as the source of truth.

Address Fields

Typical address fields displayed:

• Full name - First + Last name
• Company (optional)
• Street address - Address line 1 and 2
• City
• State/Province
• Postal/ZIP code
• Country
• Phone number (optional)

Address Types

• Shipping address - Default delivery location
• Billing address - Default payment location
• Default indicators - Shows which addresses are set as defaults
• Multiple addresses - Customers can save multiple shipping/billing addresses

Supports

• Typography controls: No (uses theme defaults)
• Color settings: No (styled via CSS)
• Spacing (margin): Yes
• Custom CSS classes: Yes

Does Not Support

• Static content mode (always dynamic)
• Preview in editor without authentication
• Bulk address import

Troubleshooting

Addresses not displaying

Check:

1. Customer is logged in (check authentication session)
2. Block is inside Account parent block
3. Customer has saved addresses in BigCommerce
4. BigCommerce API connection is active

Fix:

• Verify customer authentication token
• Check that Account parent block is configured correctly
• Review browser console for API errors
• Test address retrieval in BigCommerce admin for that customer

Unable to add new address

Common causes:

• Required fields not completed (street, city, state, postal code, country)
• Invalid postal code format for selected country
• API permissions missing for address write access
• BigCommerce API rate limiting

Fix:

# Check browser console for validation errors
# Verify all required fields are filled
# Ensure postal code matches country format (e.g., 5 digits for US ZIP)
# Check BigCommerce API logs for rejected requests

Unable to edit existing address

Check:

1. Customer owns the address (can’t edit another customer’s address)
2. API permissions include address update access
3. Required fields remain valid after edit
4. No conflicting default address rules

Fix:

• Verify customer ID match between session and address owner
• Check API response for validation errors
• Ensure at least one default shipping and billing address exists

Unable to delete address

Common causes:

• Address is set as default (must change default before deleting)
• Address is associated with pending/active orders
• API permissions missing for address delete access

Fix:

1. Set a different address as default first
2. Complete or cancel any pending orders using this address
3. Verify API permissions include address deletion
4. Check BigCommerce admin for address dependencies

Changes saved but not reflecting

Check:

1. Clear WordPress® and CDN caching
2. Refresh page to reload addresses from BigCommerce
3. Verify changes persisted in BigCommerce admin
4. Check for AJAX errors in browser console

Fix:

# Clear page cache
# Hard refresh browser (Cmd+Shift+R or Ctrl+Shift+F5)
# Verify address data in BigCommerce admin matches what should display
# Check network tab for successful API response

Customer sees other customers’ addresses

CRITICAL SECURITY ISSUE - Report immediately to development team

Investigation steps:

1. Verify authentication token is being validated correctly
2. Check that customer ID is properly scoped to authenticated user
3. Review API request parameters for customer filtering
4. Audit session handling for cross-customer data leakage
5. Test with multiple customer accounts to reproduce

This should NEVER happen and indicates a serious authentication/authorization bug.

Default address indicators not showing

Check:

1. At least one shipping and one billing address are set as default in BigCommerce
2. Default address flags are being returned by API
3. CSS for default indicator is not overridden by theme

Fix:

• Set default addresses in BigCommerce admin
• Check API response includes is_default_shipping and is_default_billing flags
• Inspect element to verify CSS class is applied

Address form validation errors

Common issues:

• Postal code mismatch - US requires 5-digit ZIP or 9-digit ZIP+4, Canada requires A1A 1A1 format
• State/Province required - Some countries require state selection
• Phone format - Some systems require specific phone number formats
• Country restrictions - BigCommerce may have country restrictions configured

Fix:

• Display clear validation messages to customer
• Use country-specific format hints (e.g., “Format: 12345 or 12345-6789”)
• Validate on client-side before API submission
• Show inline error messages near invalid fields

Performance with many addresses

If a customer has 20+ saved addresses, consider:

• Pagination or “show more” functionality
• Search/filter addresses by type or location
• Collapse/expand address cards
• Virtual scrolling for large lists

Optimization:

/* Lazy load address cards */
.wpe-mustang-address__card {
  content-visibility: auto;
}

/* Limit initial display */
.wpe-mustang-address__card:nth-child(n + 6) {
  display: none;
}

.wpe-mustang-address.show-all .wpe-mustang-address__card {
  display: block;
}

Related Blocks

• Account - Parent container for customer account features
• Account Details - Customer profile management
• Account Orders - Order history display
• User Profile Tabs - Navigation for account sections