Get Customer Addresses

Retrieve all saved addresses for the authenticated customer. Addresses are used for billing and shipping during checkout, and can be managed from the customer's account dashboard.

Query

query getCustomerAddresses($first: Int, $after: String) {
  getCustomerAddresses(first: $first, after: $after) {
    edges {
      cursor
      node {
        id
        _id
        addressType
        companyName
        name
        firstName
        lastName
        email
        address
        city
        state
        country
        postcode
        phone
        vatId
        defaultAddress
        useForShipping
        additional
        createdAt
        updatedAt
      }
    }
    pageInfo {
      hasNextPage
      hasPreviousPage
      startCursor
      endCursor
    }
    totalCount
  }
}

Authentication

This query requires a valid customer authentication token in the Authorization header. Use the Customer Login API to retrieve the token.

Request Headers

Header	Value	Required	Description
Content-Type	application/json	Yes	Request content type
X-STOREFRONT-KEY	pk_storefront_xxx	Yes	Storefront API key
Authorization	Bearer {token}	Yes	Customer authentication token

Arguments

Argument	Type	Required	Description
first	Int	No	Number of addresses to fetch (default: 10, max: 100)
after	String	No	Cursor for forward pagination
last	Int	No	Number of addresses to fetch backward
before	String	No	Cursor for backward pagination

Response Fields

Field	Type	Description
id	String	IRI identifier (e.g., /api/shop/customer-addresses/2829)
_id	Int	Numeric database ID
addressType	String	Address type (e.g., customer)
companyName	String	Company name (nullable)
name	String	Full name (computed from first + last name)
firstName	String	First name
lastName	String	Last name
email	String	Email address
address	String	Street address
city	String	City
state	String	State/Province code
country	String	Country code (ISO 3166-1 alpha-2)
postcode	String	Postal/Zip code
phone	String	Phone number
vatId	String	VAT identification number (nullable)
defaultAddress	Boolean	Whether this is the default address
useForShipping	Boolean	Whether this address is used for shipping
additional	JSON	Additional address data (nullable)
createdAt	DateTime	Creation timestamp
updatedAt	DateTime	Last update timestamp

cURL Example

curl -X POST "http://localhost:8000/api/graphql" \
  -H "X-STOREFRONT-KEY: pk_storefront_your_key_here" \
  -H "Authorization: Bearer YOUR_CUSTOMER_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "query": "query { getCustomerAddresses(first: 10) { edges { cursor node { _id firstName lastName address city state country postcode phone defaultAddress } } pageInfo { hasNextPage endCursor } totalCount } }"
  }'

Pagination

Uses cursor-based pagination:

• Forward: first + after — use endCursor from pageInfo as the next after value
• Backward: last + before — use startCursor from pageInfo as the next before value
• Check for more: read pageInfo.hasNextPage or pageInfo.hasPreviousPage

Empty Response

When the customer has no saved addresses:

{
  "data": {
    "getCustomerAddresses": {
      "edges": [],
      "pageInfo": {
        "hasNextPage": false,
        "hasPreviousPage": false,
        "startCursor": null,
        "endCursor": null
      },
      "totalCount": 0
    }
  }
}

Use Cases

Use Case	Approach
Address book	Fetch all addresses with first: 50 for account dashboard
Checkout selector	Fetch minimal fields (_id, name, address, city, defaultAddress) for an address dropdown
Default address	Look for the entry with defaultAddress: true
Business addresses	Include companyName and vatId fields for B2B customers
Pre-fill checkout	Use defaultAddress: true entry to pre-populate shipping/billing forms

Error Responses

Unauthenticated

{
  "errors": [
    {
      "message": "Unauthenticated. Please login to perform this action",
      "locations": [{ "line": 2, "column": 3 }],
      "path": ["getCustomerAddresses"]
    }
  ]
}

Related Documentation

• Create Customer Address
• Update Customer Address
• Delete Customer Address