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.

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

Pagination

Use cursor-based pagination to retrieve large datasets:

# 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: "html", "none", "abbreviated", "blank-zero". Some fields have a default formatter (shown below). See the Formatting guide for details.

Note on Sorting: Field sortability may vary depending on the UI context and query parameters used. Some parameter options explicitly disable sorting (marked with ⚠️ not sortable).

Simple Fields

These fields return values directly without additional options.

`additionalLines`

Supplementary address information beyond the street address. This field provides space for additional location details such as suite numbers, building names, or other descriptive information that helps identify the specific delivery point.

Label: Additional lines
Sortable: No

`additionalLinesLine1`

First line of additional address information. This is the first of three separate lines available for supplementary location details beyond the primary street address.

Label: Additional lines line 1
Sortable: No

`additionalLinesLine2`

Second line of additional address information. This is the second of three separate lines available for supplementary location details beyond the primary street address.

Label: Additional lines line 2
Sortable: No

`additionalLinesLine3`

Third line of additional address information. This is the third of three separate lines available for supplementary location details beyond the primary street address.

Label: Additional lines line 3
Sortable: No

`city`

The city or municipality component of the address. This field identifies the incorporated city, town, or other municipal entity where the address is located.

Label: City
Sortable: No

`directions`

Additional instructions for finding or accessing the location. This field provides supplementary guidance beyond the standard address components to help with delivery or navigation.

Label: Directions
Sortable: No

`directionsLine1`

The first line of the directions field when split into individual lines for display or formatting purposes.

Label: Directions line 1
Sortable: No

`directionsLine2`

The second line of the directions field when split into individual lines for display or formatting purposes.

Label: Directions line 2
Sortable: No

`directionsLine3`

The third line of the directions field when split into individual lines for display or formatting purposes.

Label: Directions line 3
Sortable: No

`formatted`

The complete address presented as a single formatted string with all components combined for display or mailing label purposes.

Label: Formatted
Sortable: No

`name`

The name of the person or organization receiving mail at this address. This field is used when the recipient's name differs from the primary party name, such as "Attention to" information on shipping labels.

Label: Name
Sortable: No

`postalCode`

The postal or ZIP code for the address. This field is used for mail delivery and can be used with other address fields to validate and format complete mailing addresses.

Label: Postal code
Sortable: No

`streetAddress`

The primary street address line containing the building number and street name. This is the main address field used for shipping, billing, and facility locations.

Label: Street address
Sortable: No

`streetAddressLine1`

The first line of the street address when the full street address is split across multiple lines. This allows for more granular control when importing or exporting address data line by line.

Label: Street address line 1
Sortable: No

`streetAddressLine2`

The second line of the street address when the full street address is split across multiple lines. This allows for more granular control when importing or exporting address data line by line.

Label: Street address line 2
Sortable: No

`streetAddressLine3`

The third line of the street address when the full street address is split across multiple lines. This allows for more granular control when importing or exporting address data line by line.

Label: Street address line 3
Sortable: No

Enum Fields

These fields return one of a predefined set of values.

`country`

The country where the address is located. This field uses standardized geographic codes and can be formatted as country names or ISO 3166 alpha-2 codes for international address compatibility.

Label: Country
Sortable: No

Possible Values: See Country Codes (ISO 3166-1 alpha-3)

`stateRegion`

The state, province, or region component of the address. This field stores geographic identifiers and provides options for state/province selection based on the country.

Label: State / region
Sortable: No

Possible Values: See State and Region Codes

Relations

No relations available.

Filters

No filters available.