How to

Manage company addresses

Add, update, and remove company addresses using Geins Merchant API.

Prerequisites

  • Merchant API key (X-ApiKey)
  • Authenticated user session (JWT bearer token)
  • User associated with a company account

Goals

  • Add new billing and shipping addresses to a company
  • Update existing company address details
  • Remove addresses that are no longer needed

Architecture at a glance

  • Authenticate company user → createCompanyAddress / updateCompanyAddress / deleteCompanyAddress → Verify via getCompany

APIs used

  • Merchant API: https://merchantapi.geins.io/graphql

Step-by-step

Create a company address

Use createCompanyAddress to add a new address. Each address must have an addressType that determines how it can be used during checkout: billing, shipping, or billingandshipping.

Try it out in the GraphQL Playground using the query, headers and variables below.

Request example

mutation createCompanyAddress(
  $address: CreateCompanyAddressInputType!
  $channelId: String
  $languageId: String
  $marketId: String
) {
  createCompanyAddress(
    address: $address
    channelId: $channelId
    languageId: $languageId
    marketId: $marketId
  )
}
Required fields: firstName, lastName, addressLine1, zip, city, country, and addressType. Optional fields include email, phone, company, careOf, addressLine2, addressLine3, and region.

Response example

200 OK
response.json
{
  "data": {
    "createCompanyAddress": true
  }
}

Update an existing address

Use updateCompanyAddress to modify an existing address. Only the fields you provide are updated — omitted fields remain unchanged. You need the addressId from the getCompany query.

Try it out in the GraphQL Playground using the query, headers and variables below.

Request example

mutation updateCompanyAddress(
  $addressId: String!
  $address: UpdateCompanyAddressInputType!
  $channelId: String
  $languageId: String
  $marketId: String
) {
  updateCompanyAddress(
    addressId: $addressId
    address: $address
    channelId: $channelId
    languageId: $languageId
    marketId: $marketId
  )
}
All fields in UpdateCompanyAddressInputType are optional. Only provide the fields you want to change. The country field expects a 2-character ISO 3166-1 alpha-2 code (e.g., SE).

Response example

200 OK
response.json
{
  "data": {
    "updateCompanyAddress": true
  }
}

Delete an address

Use deleteCompanyAddress to remove an address from the company. You need the addressId from the getCompany query.

Try it out in the GraphQL Playground using the query, headers and variables below.

Request example

mutation deleteCompanyAddress(
  $addressId: String!
  $channelId: String
  $languageId: String
  $marketId: String
) {
  deleteCompanyAddress(
    addressId: $addressId
    channelId: $channelId
    languageId: $languageId
    marketId: $marketId
  )
}

Response example

200 OK
response.json
{
  "data": {
    "deleteCompanyAddress": true
  }
}

Options

Multi-market support

All mutations support optional parameters for multi-market functionality:

  • channelId: Target specific sales channels
  • languageId: Set content language
  • marketId: Target specific markets
Read more about channelId, languageId, and marketId in the how-to about using multi-market support.

Authenticated access

Authentication is required for all company address mutations. The API uses the JWT bearer token to identify the user's company membership and scope operations to that company. Without a valid token the request will fail with an authorization error.

Include the token in the Authorization header:

Authorization: Bearer {JWT_TOKEN}
See the authentication flow guide for details on obtaining and refreshing JWT tokens.

Common pitfalls

  • Invalid addressType value — Must be exactly billing, shipping, or billingandshipping. Other values will cause an error.
  • Invalid country format — Use 2-character ISO 3166-1 alpha-2 codes (e.g., SE, NO, DE), not full country names.
  • Addresses affect checkout flow — Company addresses are presented as selectable options during company checkout. Changes here are immediately reflected in the checkout address lists.
Related

Get company infoGet company ordersManage company settingsManage company addressesManage company buyersUse multi-market supportCreateCompanyAddressDeleteCompanyAddressUpdateCompanyAddress

Log out user

Securely log out users and invalidate authentication tokens using Geins Auth Service

Manage company buyers

Add, assign, update, and remove buyers on a company account using Geins Merchant API.