# Address

## Overview

Addresses represent physical locations associated with parties - where to ship orders, where to send bills, where to send payments. They capture structured address data with proper geographic hierarchy and formatting rules, supporting both domestic and international shipping and billing operations.

Each address belongs to a party and serves a specific purpose. Shipping addresses indicate where goods should be delivered. Billing addresses show where invoices should be sent. Payment addresses specify where payments should be mailed. A party can have multiple addresses of each type, supporting complex organizational structures where different departments or locations handle different functions.

The address structure captures standard components: street address (with up to three lines for complex addresses), city, state/region, postal code, and country. This structure supports international addresses with varying formats while maintaining enough structure for address validation and shipping label generation. The formatted field provides a single-string representation of the complete address for display purposes.

Additional address lines handle edge cases like care-of information, apartment numbers, or building names. Direction lines provide delivery instructions - gate codes, suite numbers, or special handling notes. These additional fields ensure delivery personnel have all the information they need to successfully deliver shipments.

Addresses are versioned and immutable once used on orders or shipments. When a customer updates their address, the old address is retained for historical orders while new orders use the new address. This ensures you can always see where a past shipment was sent, supporting customer service and preventing confusion about historical transactions.

The system can validate addresses through integration with shipping carriers. This validation catches errors before shipment, reducing undeliverable packages and shipping costs. Some carriers require specific address formats or validated addresses for their services, making this validation essential for smooth shipping operations.

Addresses link to the party's contact information, providing a complete picture of how to communicate with and ship to that party. When creating an order, you can select from the party's existing addresses or create a new one. This balance between reuse and flexibility supports both routine orders and special situations.

---

### GraphQL API

The `address` collection provides access to address data via the GraphQL API. All queries use the Relay connection specification with cursor-based pagination.

**Query Name:**`addressViewConnection`

**Available Features:**

- Cursor-based pagination (first/last/after/before)

## Query Examples

### Basic Query

The `address` collection is accessed via the `addressViewConnection` query, which returns a Relay-style connection with pagination support.

```graphql
query {
  addressViewConnection(first: 10) {
    edges {
      node {
        additionalLines
        additionalLinesLine1
        additionalLinesLine2
        additionalLinesLine3
        city
      }
    }
    pageInfo {
      hasNextPage
      endCursor
    }
  }
}
```

### Pagination

Use cursor-based pagination to retrieve large datasets:

```graphql
# First page
query {
  addressViewConnection(first: 50) {
    edges {
      node { additionalLines }
    }
    pageInfo {
      hasNextPage
      endCursor
    }
  }
}

# Subsequent pages
query {
  addressViewConnection(first: 50, after: "cursor-from-previous-page") {
    edges {
      node { additionalLines }
    }
    pageInfo {
      hasNextPage
      endCursor
    }
  }
}
```

## Fields

This collection has 18 fields:

- 16 simple fields
- 2 enum fields (with predefined values)
- 0 parameterized fields (accept query options)

> **Note on Field Formatting:** All scalar fields support the `formatter` argument to control output format. Available options: `