How to

Manage company buyers

Add, assign, update, and remove buyers on a company account 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 buyers to a company (create or assign existing users)
  • Update buyer details such as name, phone, and active status
  • Remove buyers from the company

Architecture at a glance

  • Authenticate company user → createCompanyBuyer / assignCompanyBuyer / updateCompanyBuyer / deleteCompanyBuyer → Verify via getCompany

APIs used

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

Step-by-step

Create a new buyer

Use createCompanyBuyer to add a completely new buyer to the company. The buyer's id is their email address, which also serves as their login identifier.

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

Request example

mutation createCompanyBuyer(
  $buyer: CreateCompanyBuyerInputType!
  $channelId: String
  $languageId: String
  $marketId: String
) {
  createCompanyBuyer(
    buyer: $buyer
    channelId: $channelId
    languageId: $languageId
    marketId: $marketId
  )
}
The id field (email) is required. Fields firstName, lastName, phone, and active are optional. If active is omitted it defaults to true.

Response example

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

Assign an existing user as buyer

Use assignCompanyBuyer to link an already-registered user to the company as a buyer. This is useful when the user already has an account but needs to be added to a company.

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

Request example

mutation assignCompanyBuyer(
  $id: String!
  $channelId: String
  $languageId: String
  $marketId: String
) {
  assignCompanyBuyer(
    id: $id
    channelId: $channelId
    languageId: $languageId
    marketId: $marketId
  )
}
The id parameter is the email address of the existing user to assign. Use createCompanyBuyer instead if the user does not already have an account.

Response example

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

Update a buyer

Use updateCompanyBuyer to modify buyer details. Only provided fields are updated. Changing the id field reassigns the buyer to a new email/identifier.

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

Request example

mutation updateCompanyBuyer(
  $id: String!
  $buyer: UpdateCompanyBuyerInputType!
  $channelId: String
  $languageId: String
  $marketId: String
) {
  updateCompanyBuyer(
    id: $id
    buyer: $buyer
    channelId: $channelId
    languageId: $languageId
    marketId: $marketId
  )
}
All fields in UpdateCompanyBuyerInputType are optional. Setting active to false deactivates the buyer without removing them. To change the buyer's email, pass a new value in the id field inside the buyer input — this reassigns the buyer to the new email.

Response example

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

Remove a buyer

Use deleteCompanyBuyer to remove a buyer from the company. The id parameter is the buyer's email address.

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

Request example

mutation deleteCompanyBuyer(
  $id: String!
  $channelId: String
  $languageId: String
  $marketId: String
) {
  deleteCompanyBuyer(
    id: $id
    channelId: $channelId
    languageId: $languageId
    marketId: $marketId
  )
}

Response example

200 OK
response.json
{
  "data": {
    "deleteCompanyBuyer": 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 buyer 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

  • A buyer cannot remove themselves — The deleteCompanyBuyer mutation prevents users from deleting their own account. Another company member must perform the removal.
  • createCompanyBuyer vs assignCompanyBuyer — Use createCompanyBuyer when the person does not yet have an account. Use assignCompanyBuyer when you want to link an already-registered user to the company.
  • Changing buyer email via updateCompanyBuyer — Passing a new id in the buyer input reassigns the buyer to that email. This changes their login identifier.
  • Deactivating vs removing — Setting active: false via updateCompanyBuyer disables the buyer without deleting them, preserving their order history association. Use deleteCompanyBuyer only for permanent removal.
Related

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

Manage company addresses

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

Manage company settings

Update company properties for the authenticated user's company using Geins Merchant API.