---
updatedAt: 2026-05-26T22:53:01.000Z
agentTools:
  projectIndex: https://developer.vinoshipper.com/llms.txt
---

# List Addresses

# OpenAPI definition

```json
{
  "openapi": "3.0.1",
  "info": {
    "title": "Vinoshipper API Docs",
    "version": "3.0",
    "x-logo": {
      "url": "/static/img/brand/vinoshipper-logo.svg"
    }
  },
  "servers": [
    {
      "url": "https://vinoshipper.com"
    }
  ],
  "tags": [
    {
      "name": "Customer Addresses",
      "description": "Retrieve and modify customer addresses"
    }
  ],
  "paths": {
    "/api/v3/p/customers/{customerId}/addresses": {
      "get": {
        "tags": [
          "Customer Addresses"
        ],
        "summary": "List Addresses",
        "operationId": "listAddresses",
        "parameters": [
          {
            "name": "customerId",
            "in": "path",
            "description": "Customer's ID",
            "required": true,
            "schema": {
              "type": "integer"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Operation successful",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/AddressListResponse"
                }
              }
            }
          },
          "400": {
            "description": "Request has failed validation",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          },
          "401": {
            "description": "Authentication failed"
          },
          "403": {
            "description": "Insufficient permission",
            "content": {}
          },
          "404": {
            "description": "Not Found"
          },
          "500": {
            "description": "Internal server error",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          }
        },
        "security": [
          {
            "BasicAuth": []
          }
        ]
      }
    }
  },
  "components": {
    "schemas": {
      "ShippingAddressSchema": {
        "required": [
          "city",
          "country",
          "fullName",
          "poBox",
          "postalCode",
          "stateCode",
          "street1",
          "suspectedPOBox",
          "verifiedNotPOBox"
        ],
        "type": "object",
        "properties": {
          "id": {
            "type": "integer",
            "format": "int32",
            "nullable": true,
            "readOnly": true
          },
          "salutation": {
            "type": "string",
            "description": "Formal greeting or title of the customer"
          },
          "firstName": {
            "type": "string",
            "nullable": true
          },
          "lastName": {
            "type": "string",
            "nullable": true
          },
          "businessName": {
            "type": "string",
            "nullable": true
          },
          "fullName": {
            "type": "string",
            "description": "Use firstName and lastName instead.",
            "nullable": true,
            "deprecated": true
          },
          "street1": {
            "type": "string"
          },
          "street2": {
            "type": "string",
            "nullable": true
          },
          "city": {
            "type": "string"
          },
          "postalCode": {
            "type": "string",
            "description": "ZIP Code"
          },
          "stateCode": {
            "type": "string"
          },
          "country": {
            "type": "string",
            "description": "Two letter country code",
            "default": "US"
          },
          "phoneNumber": {
            "type": "string",
            "description": "Use phone instead.",
            "nullable": true,
            "deprecated": true
          },
          "phone": {
            "$ref": "#/components/schemas/InternationalPhoneNumber"
          },
          "accessPoint": {
            "$ref": "#/components/schemas/AccessPoint"
          },
          "description": {
            "type": "string",
            "description": "A description for the address, e.g. Home, Work",
            "nullable": true
          },
          "suspectedPOBox": {
            "type": "boolean",
            "description": "True if the address is suspected of being a PO Box",
            "readOnly": true
          },
          "poBox": {
            "type": "boolean",
            "description": "True if this address is confirmed as a PO Box",
            "readOnly": true
          },
          "verifiedNotPOBox": {
            "type": "boolean",
            "description": "True if someone has confirmed this address is not a PO Box. Club processing skips its PO Box check for such an address even when the text still reads like one.",
            "readOnly": true
          },
          "linkedAddress": {
            "$ref": "#/components/schemas/LinkedAddress"
          }
        },
        "description": "The person's shipping address"
      },
      "MailingAddressSchema": {
        "required": [
          "city",
          "country",
          "fullName",
          "poBox",
          "postalCode",
          "stateCode",
          "street1",
          "suspectedPOBox",
          "verifiedNotPOBox"
        ],
        "type": "object",
        "properties": {
          "id": {
            "type": "integer",
            "format": "int32",
            "nullable": true,
            "readOnly": true
          },
          "salutation": {
            "type": "string",
            "description": "Formal greeting or title of the customer"
          },
          "firstName": {
            "type": "string",
            "nullable": true
          },
          "lastName": {
            "type": "string",
            "nullable": true
          },
          "businessName": {
            "type": "string",
            "nullable": true
          },
          "fullName": {
            "type": "string",
            "description": "Use firstName and lastName instead.",
            "nullable": true,
            "deprecated": true
          },
          "street1": {
            "type": "string"
          },
          "street2": {
            "type": "string",
            "nullable": true
          },
          "city": {
            "type": "string"
          },
          "postalCode": {
            "type": "string",
            "description": "ZIP Code"
          },
          "stateCode": {
            "type": "string"
          },
          "country": {
            "type": "string",
            "description": "Two letter country code",
            "default": "US"
          },
          "phoneNumber": {
            "type": "string",
            "description": "Use phone instead.",
            "nullable": true,
            "deprecated": true
          },
          "phone": {
            "$ref": "#/components/schemas/InternationalPhoneNumber"
          },
          "accessPoint": {
            "$ref": "#/components/schemas/AccessPoint"
          },
          "description": {
            "type": "string",
            "description": "A description for the address, e.g. Home, Work",
            "nullable": true
          },
          "suspectedPOBox": {
            "type": "boolean",
            "description": "True if the address is suspected of being a PO Box",
            "readOnly": true
          },
          "poBox": {
            "type": "boolean",
            "description": "True if this address is confirmed as a PO Box",
            "readOnly": true
          },
          "verifiedNotPOBox": {
            "type": "boolean",
            "description": "True if someone has confirmed this address is not a PO Box. Club processing skips its PO Box check for such an address even when the text still reads like one.",
            "readOnly": true
          },
          "linkedAddress": {
            "$ref": "#/components/schemas/LinkedAddress"
          }
        },
        "description": "The person's mailing address"
      },
      "Error": {
        "required": [
          "code",
          "description"
        ],
        "type": "object",
        "properties": {
          "description": {
            "type": "string"
          },
          "code": {
            "type": "string"
          },
          "field": {
            "type": "string"
          },
          "shortDescription": {
            "type": "string"
          }
        }
      },
      "ErrorDetails": {
        "required": [
          "status",
          "type"
        ],
        "type": "object",
        "properties": {
          "status": {
            "type": "integer",
            "format": "int32"
          },
          "type": {
            "type": "string",
            "enum": [
              "VALIDATION",
              "COMPLIANCE",
              "PAYMENT_FAILURE",
              "SERVER_ERROR",
              "ACCESS_DENIED",
              "CONFLICT"
            ]
          },
          "errors": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/Error"
            }
          }
        }
      },
      "ErrorResponse": {
        "required": [
          "error"
        ],
        "type": "object",
        "properties": {
          "error": {
            "$ref": "#/components/schemas/ErrorDetails"
          }
        }
      },
      "AccessPoint": {
        "required": [
          "businessName",
          "city",
          "country",
          "lat",
          "lng",
          "locationId",
          "postalCode",
          "stateCode",
          "street1"
        ],
        "type": "object",
        "properties": {
          "id": {
            "type": "integer",
            "format": "int32"
          },
          "locationId": {
            "type": "string",
            "description": "UPS Location ID"
          },
          "lat": {
            "type": "number",
            "readOnly": true
          },
          "lng": {
            "type": "number",
            "readOnly": true
          },
          "imageUrl": {
            "type": "string",
            "description": "A full URL to an image associated with the Access Point",
            "nullable": true,
            "readOnly": true
          },
          "hours": {
            "type": "string",
            "description": "Text describing open hours",
            "nullable": true,
            "readOnly": true
          },
          "note": {
            "type": "string",
            "description": "Optional note from access point",
            "nullable": true,
            "readOnly": true
          },
          "businessName": {
            "type": "string",
            "readOnly": true
          },
          "street1": {
            "type": "string",
            "readOnly": true
          },
          "street2": {
            "type": "string",
            "nullable": true,
            "readOnly": true
          },
          "city": {
            "type": "string",
            "readOnly": true
          },
          "postalCode": {
            "type": "string",
            "readOnly": true
          },
          "stateCode": {
            "type": "string",
            "readOnly": true
          },
          "country": {
            "type": "string",
            "description": "Two letter country code",
            "readOnly": true
          },
          "phoneNumber": {
            "type": "string",
            "nullable": true,
            "readOnly": true
          }
        },
        "description": "UPS access point",
        "nullable": true
      },
      "Address": {
        "required": [
          "city",
          "country",
          "fullName",
          "poBox",
          "postalCode",
          "stateCode",
          "street1",
          "suspectedPOBox",
          "verifiedNotPOBox"
        ],
        "type": "object",
        "properties": {
          "id": {
            "type": "integer",
            "format": "int32",
            "nullable": true,
            "readOnly": true
          },
          "salutation": {
            "type": "string",
            "description": "Formal greeting or title of the customer"
          },
          "firstName": {
            "type": "string",
            "nullable": true
          },
          "lastName": {
            "type": "string",
            "nullable": true
          },
          "businessName": {
            "type": "string",
            "nullable": true
          },
          "fullName": {
            "type": "string",
            "description": "Use firstName and lastName instead.",
            "nullable": true,
            "deprecated": true
          },
          "street1": {
            "type": "string"
          },
          "street2": {
            "type": "string",
            "nullable": true
          },
          "city": {
            "type": "string"
          },
          "postalCode": {
            "type": "string",
            "description": "ZIP Code"
          },
          "stateCode": {
            "type": "string"
          },
          "country": {
            "type": "string",
            "description": "Two letter country code",
            "default": "US"
          },
          "phoneNumber": {
            "type": "string",
            "description": "Use phone instead.",
            "nullable": true,
            "deprecated": true
          },
          "phone": {
            "$ref": "#/components/schemas/InternationalPhoneNumber"
          },
          "accessPoint": {
            "$ref": "#/components/schemas/AccessPoint"
          },
          "description": {
            "type": "string",
            "description": "A description for the address, e.g. Home, Work",
            "nullable": true
          },
          "suspectedPOBox": {
            "type": "boolean",
            "description": "True if the address is suspected of being a PO Box",
            "readOnly": true
          },
          "poBox": {
            "type": "boolean",
            "description": "True if this address is confirmed as a PO Box",
            "readOnly": true
          },
          "verifiedNotPOBox": {
            "type": "boolean",
            "description": "True if someone has confirmed this address is not a PO Box. Club processing skips its PO Box check for such an address even when the text still reads like one.",
            "readOnly": true
          },
          "linkedAddress": {
            "$ref": "#/components/schemas/LinkedAddress"
          }
        },
        "description": "The address of the location where the sale is made",
        "nullable": true
      },
      "InternationalPhoneNumber": {
        "type": "object",
        "properties": {
          "number": {
            "type": "string"
          },
          "country": {
            "type": "integer",
            "format": "int32"
          },
          "extension": {
            "type": "string"
          }
        },
        "nullable": true
      },
      "LinkedAddress": {
        "required": [
          "city",
          "country",
          "fullName",
          "postalCode",
          "stateCode",
          "street1"
        ],
        "type": "object",
        "properties": {
          "id": {
            "type": "integer",
            "format": "int32",
            "nullable": true,
            "readOnly": true
          },
          "salutation": {
            "type": "string",
            "description": "Formal greeting or title of the customer"
          },
          "firstName": {
            "type": "string",
            "nullable": true
          },
          "lastName": {
            "type": "string",
            "nullable": true
          },
          "businessName": {
            "type": "string",
            "nullable": true
          },
          "fullName": {
            "type": "string",
            "description": "Use firstName and lastName instead.",
            "nullable": true,
            "deprecated": true
          },
          "street1": {
            "type": "string"
          },
          "street2": {
            "type": "string",
            "nullable": true
          },
          "city": {
            "type": "string"
          },
          "postalCode": {
            "type": "string",
            "description": "ZIP Code"
          },
          "stateCode": {
            "type": "string"
          },
          "country": {
            "type": "string",
            "description": "Two letter country code",
            "default": "US"
          },
          "phoneNumber": {
            "type": "string",
            "description": "Use phone instead.",
            "nullable": true,
            "deprecated": true
          },
          "phone": {
            "$ref": "#/components/schemas/InternationalPhoneNumber"
          },
          "description": {
            "type": "string",
            "description": "A description for the address, e.g. Home, Work",
            "nullable": true
          },
          "accessPoint": {
            "$ref": "#/components/schemas/AccessPoint"
          }
        }
      },
      "AddressListResponse": {
        "type": "object",
        "properties": {
          "shipping": {
            "$ref": "#/components/schemas/ShippingAddressSchema"
          },
          "mailing": {
            "$ref": "#/components/schemas/MailingAddressSchema"
          },
          "clubs": {
            "type": "array",
            "description": "The person's wine club membership shipping addresses",
            "items": {
              "$ref": "#/components/schemas/WineClubAddress"
            }
          },
          "addresses": {
            "type": "array",
            "description": "All addresses associated with the person and the usage flags",
            "items": {
              "$ref": "#/components/schemas/AddressWithUsage"
            }
          }
        }
      },
      "AddressUsage": {
        "required": [
          "accessPoint",
          "club",
          "mailing",
          "shipping"
        ],
        "type": "object",
        "properties": {
          "mailing": {
            "type": "boolean",
            "description": "True if this address is the customer's mailing address"
          },
          "shipping": {
            "type": "boolean",
            "description": "True if this address is the customer's shipping address"
          },
          "club": {
            "type": "boolean",
            "description": "True if this address is the shipping address for one or more clubs"
          },
          "accessPoint": {
            "type": "boolean",
            "description": "True if this address is the base address of an access point"
          }
        }
      },
      "AddressWithUsage": {
        "required": [
          "city",
          "country",
          "fullName",
          "postalCode",
          "stateCode",
          "street1",
          "usage"
        ],
        "type": "object",
        "properties": {
          "address": {
            "$ref": "#/components/schemas/Address"
          },
          "usage": {
            "$ref": "#/components/schemas/AddressUsage"
          },
          "accessPoint": {
            "$ref": "#/components/schemas/AccessPoint"
          },
          "stateCode": {
            "type": "string"
          },
          "businessName": {
            "type": "string",
            "nullable": true
          },
          "description": {
            "type": "string",
            "description": "A description for the address, e.g. Home, Work",
            "nullable": true
          },
          "id": {
            "type": "integer",
            "format": "int32",
            "nullable": true,
            "readOnly": true
          },
          "country": {
            "type": "string",
            "description": "Two letter country code",
            "default": "US"
          },
          "fullName": {
            "type": "string",
            "description": "Use firstName and lastName instead.",
            "nullable": true,
            "deprecated": true
          },
          "salutation": {
            "type": "string",
            "description": "Formal greeting or title of the customer"
          },
          "phoneNumber": {
            "type": "string",
            "description": "Use phone instead.",
            "nullable": true,
            "deprecated": true
          },
          "postalCode": {
            "type": "string",
            "description": "ZIP Code"
          },
          "city": {
            "type": "string"
          },
          "firstName": {
            "type": "string",
            "nullable": true
          },
          "lastName": {
            "type": "string",
            "nullable": true
          },
          "street1": {
            "type": "string"
          },
          "phone": {
            "$ref": "#/components/schemas/InternationalPhoneNumber"
          },
          "street2": {
            "type": "string",
            "nullable": true
          }
        },
        "description": "All addresses associated with the person and the usage flags"
      },
      "WineClubAddress": {
        "required": [
          "clubId",
          "clubName",
          "membershipId",
          "pickup"
        ],
        "type": "object",
        "properties": {
          "clubId": {
            "type": "integer",
            "format": "int32"
          },
          "clubName": {
            "type": "string"
          },
          "membershipId": {
            "type": "integer",
            "format": "int32"
          },
          "pickup": {
            "type": "boolean",
            "description": "True if this membership is for pick up"
          },
          "address": {
            "$ref": "#/components/schemas/Address"
          }
        },
        "description": "The person's wine club membership shipping addresses"
      }
    },
    "securitySchemes": {
      "BasicAuth": {
        "type": "http",
        "scheme": "basic"
      }
    }
  }
}
```