Managing addresses

Retrieve, create, update and delete addresses for customers and companies using Propeller's GraphQL API.

Retrieving addresses for the logged-in user

Use the viewer query to retrieve addresses for the currently authenticated user. Contacts access addresses through their company. Customers have addresses directly on their account.

query {
  viewer {
    __typename
    ... on Contact {
      contactId
      company {
        companyId
        name
        addresses {
          id
          firstName
          lastName
          company
          street
          number
          numberExtension
          postalCode
          city
          country
          phone
          email
          type
          isDefault
          icp
          notes
        }
      }
    }
    ... on Customer {
      customerId
      addresses {
        id
        firstName
        lastName
        street
        number
        numberExtension
        postalCode
        city
        country
        phone
        email
        type
        isDefault
        notes
      }
    }
  }
}

Expected response (for a contact):

{
  "data": {
    "viewer": {
      "__typename": "Contact",
      "contactId": 312,
      "company": {
        "companyId": 456,
        "name": "Brouwer Industrie",
        "addresses": [
          {
            "id": 101,
            "firstName": "Lisa",
            "lastName": "de Vries",
            "company": "Brouwer Industrie",
            "street": "Herengracht",
            "number": "42",
            "numberExtension": null,
            "postalCode": "1015 BN",
            "city": "Amsterdam",
            "country": "NL",
            "phone": "020-5551234",
            "email": "info@brouwerindustrie.nl",
            "type": "delivery",
            "isDefault": "Y",
            "icp": "N",
            "notes": null
          },
          {
            "id": 102,
            "firstName": "Lisa",
            "lastName": "de Vries",
            "company": "Brouwer Industrie",
            "street": "Industrieweg",
            "number": "88",
            "numberExtension": null,
            "postalCode": "5651 GK",
            "city": "Eindhoven",
            "country": "NL",
            "phone": "040-5559876",
            "email": "eindhoven@brouwerindustrie.nl",
            "type": "delivery",
            "isDefault": "N",
            "icp": "N",
            "notes": "Use entrance B at the back of the building"
          },
          {
            "id": 103,
            "firstName": "Lisa",
            "lastName": "de Vries",
            "company": "Brouwer Industrie",
            "street": "Herengracht",
            "number": "42",
            "numberExtension": null,
            "postalCode": "1015 BN",
            "city": "Amsterdam",
            "country": "NL",
            "phone": "020-5551234",
            "email": "finance@brouwerindustrie.nl",
            "type": "invoice",
            "isDefault": "Y",
            "icp": "N",
            "notes": null
          }
        ]
      }
    }
  }
}

The addresses field on both Company and Customer accepts two optional filters:

Filter	Description
type	Filter by address type: delivery, invoice or home. Omit to return all types.
isDefault	Filter by default status: Y or N.

For example, to retrieve only the default delivery address:

addresses(type: delivery, isDefault: Y) {
  id
  street
  number
  city
  postalCode
  country
}

Querying addresses directly

Use addressesByCompanyId or addressesByCustomerId to query addresses without going through the viewer. The optional type parameter filters by address type.

query {
  addressesByCompanyId(companyId: 456, type: delivery) {
    id
    firstName
    lastName
    company
    street
    number
    numberExtension
    postalCode
    city
    country
    phone
    email
    type
    isDefault
    icp
  }
}

Expected response:

{
  "data": {
    "addressesByCompanyId": [
      {
        "id": 101,
        "firstName": "Lisa",
        "lastName": "de Vries",
        "company": "Brouwer Industrie",
        "street": "Herengracht",
        "number": "42",
        "numberExtension": null,
        "postalCode": "1015 BN",
        "city": "Amsterdam",
        "country": "NL",
        "phone": "020-5551234",
        "email": "info@brouwerindustrie.nl",
        "type": "delivery",
        "isDefault": "Y",
        "icp": "N"
      },
      {
        "id": 102,
        "firstName": "Lisa",
        "lastName": "de Vries",
        "company": "Brouwer Industrie",
        "street": "Industrieweg",
        "number": "88",
        "numberExtension": null,
        "postalCode": "5651 GK",
        "city": "Eindhoven",
        "country": "NL",
        "phone": "040-5559876",
        "email": "eindhoven@brouwerindustrie.nl",
        "type": "delivery",
        "isDefault": "N",
        "icp": "N"
      }
    ]
  }
}

Omit the type parameter to return all addresses regardless of type.

addressesByCustomerId works the same way, with customerId instead of companyId.

Creating a company address

Use companyAddressCreate to add an address to a company:

mutation {
  companyAddressCreate(
    input: {
      companyId: 456
      type: delivery
      firstName: "Tom"
      lastName: "Hendriks"
      company: "Brouwer Industrie"
      street: "Prinsengracht"
      number: "200"
      postalCode: "1016 HC"
      city: "Amsterdam"
      country: "NL"
      phone: "020-5554567"
      email: "amsterdam-west@brouwerindustrie.nl"
      isDefault: N
      notes: "Ring bell twice"
    }
  ) {
    id
    firstName
    lastName
    company
    street
    number
    postalCode
    city
    country
    phone
    email
    type
    isDefault
  }
}

Expected response:

{
  "data": {
    "companyAddressCreate": {
      "id": 104,
      "firstName": "Tom",
      "lastName": "Hendriks",
      "company": "Brouwer Industrie",
      "street": "Prinsengracht",
      "number": "200",
      "postalCode": "1016 HC",
      "city": "Amsterdam",
      "country": "NL",
      "phone": "020-5554567",
      "email": "amsterdam-west@brouwerindustrie.nl",
      "type": "delivery",
      "isDefault": "N"
    }
  }
}

The required fields are:

Field	Description
companyId	The company to add the address to
type	Address type: delivery, invoice or home. In practice, most implementations use delivery and invoice. The home type exists but is rarely used.
street	Street name
postalCode	Postal code
city	City
country	Country code (e.g. NL, DE, BE)

All other fields are optional. When isDefault is omitted, the address is not set as default. Setting isDefault to Y makes this the default address for its type within the company.

The icp field controls whether tax is applied when this address is selected as a delivery address. Set it to Y for intra-community B2B shipments within the EU where the reverse charge mechanism applies.

Creating a customer address

Use customerAddressCreate to add an address to a customer account:

mutation {
  customerAddressCreate(
    input: {
      customerId: 789
      type: delivery
      firstName: "Sophie"
      lastName: "van Dijk"
      street: "Vondelstraat"
      number: "15"
      numberExtension: "A"
      postalCode: "1054 GD"
      city: "Amsterdam"
      country: "NL"
      phone: "020-5557890"
      email: "sophie@example.com"
    }
  ) {
    id
    firstName
    lastName
    street
    number
    numberExtension
    postalCode
    city
    country
    phone
    email
    type
    isDefault
  }
}

Expected response:

{
  "data": {
    "customerAddressCreate": {
      "id": 201,
      "firstName": "Sophie",
      "lastName": "van Dijk",
      "street": "Vondelstraat",
      "number": "15",
      "numberExtension": "A",
      "postalCode": "1054 GD",
      "city": "Amsterdam",
      "country": "NL",
      "phone": "020-5557890",
      "email": "sophie@example.com",
      "type": "delivery",
      "isDefault": "N"
    }
  }
}

The required fields are the same as for company addresses: customerId, type, street, postalCode, city and country.

Updating an address

Use companyAddressUpdate to modify an existing company address. Only send the fields you want to change. Fields you omit keep their current values.

mutation {
  companyAddressUpdate(
    input: {
      id: 102
      companyId: 456
      street: "Kanaaldijk"
      number: "12"
      postalCode: "5683 CR"
      city: "Best"
    }
  ) {
    id
    street
    number
    postalCode
    city
    country
    type
    isDefault
  }
}

Expected response:

{
  "data": {
    "companyAddressUpdate": {
      "id": 102,
      "street": "Kanaaldijk",
      "number": "12",
      "postalCode": "5683 CR",
      "city": "Best",
      "country": "NL",
      "type": "delivery",
      "isDefault": "N"
    }
  }
}

The id and companyId fields are required. All other fields are optional.

The type field cannot be changed after creation. To change an address from delivery to invoice, delete it and create a new one with the correct type.

customerAddressUpdate works the same way, using customerId instead of companyId.

Deleting an address

Use companyAddressDelete to remove a company address:

mutation {
  companyAddressDelete(
    input: {
      id: 104
      companyId: 456
    }
  )
}

{
  "data": {
    "companyAddressDelete": true
  }
}

customerAddressDelete works the same way, using customerId instead of companyId.

Handling both user types

Your frontend needs to handle both contacts (B2B) and customers (B2C). Use the __typename from the viewer query to determine which mutations to call:

User type	__typename	Mutations	Identifier
Contact (B2B)	Contact	companyAddressCreate, companyAddressUpdate, companyAddressDelete	companyId from viewer.company
Customer (B2C)	Customer	customerAddressCreate, customerAddressUpdate, customerAddressDelete	customerId from viewer

Contacts manage addresses at the company level. Any changes to company addresses are visible to all contacts within that company.

Next steps

• Understanding companies, contacts and customers for how companies, contacts and customers relate
• Authentication and authorization for registration, login and token management
• Checkout flow to use stored addresses during checkout