B2B Organizations GraphQL

GraphQL backend for B2B Organizations.

This app exposes admin and storefront GraphQL APIs to create and manage B2B organizations, cost centers, users, and related settings.

Creating organizations with cost centers

Two mutations can create an organization together with one or more cost centers. They share DefaultCostCenterInput, but behave differently regarding custom IDs and admin user setup.

Mutation	Input type	Organization ID	Cost center ID	Admin user
createOrganization	OrganizationInput	Auto-generated by Master Data	Auto-generated by Master Data	Not attached automatically
createOrganizationAndCostCentersWithId	NormalizedOrganizationInput	Custom (input.id)	Custom (costCenters[].id / defaultCostCenter.id)	Attached to each cost center

When to use each mutation

Use createOrganizationAndCostCentersWithId when the integration needs fixed organization and cost center identifiers (for example, syncing with an external ERP or CRM).

Use createOrganization when identifiers should be generated by Master Data. In this flow, do not send id on the organization or on cost centers. Use the costCenterId returned by the mutation when querying or updating the created cost center.

Sending a custom cost center id to createOrganization may cause a 400 response if that identifier already exists in Master Data (The document already exist with id or alternate key.).

Organization status on create

OrganizationInput and NormalizedOrganizationInput accept an optional status field when creating an organization.

Value	Meaning
(omitted)	Defaults to active (backward compatible)
active	Organization is active
inactive	Organization is inactive
on-hold	Organization is on hold

Canonical values match updateOrganization. Omitting status keeps the historical create behavior. Creating with a non-active status does not send the organization status-changed email (that email only applies when status changes via updateOrganization).

Cost center addresses

DefaultCostCenterInput supports two ways to send addresses when creating an organization:

Field	Type	Description
address	AddressInput	Single address (backward compatible)
addresses	[AddressInput]	Multiple addresses (optional)

Both fields can coexist in the same input. Resolution order:

1. If addresses is provided and non-empty, it is used.
2. Otherwise, if address is provided, it is stored as a one-item array.
3. Otherwise, an empty array is stored.

This matches the behavior already available on createCostCenterWithId, which uses CostCenterInput.addresses.

Optional address fields (such as complement) may be omitted in GraphQL. They are normalized to empty strings before persistence when created through organization mutations.

Example: multiple addresses with custom IDs

Use createOrganizationAndCostCentersWithId:

mutation CreateOrganizationAndCostCenters($input: NormalizedOrganizationInput!) {
  createOrganizationAndCostCentersWithId(input: $input) {
    id
    href
    status
  }
}

{
  "input": {
    "id": "org-example-001",
    "name": "Example Organization",
    "tradeName": "Example Trade Name",
    "b2bCustomerAdmin": {
      "firstName": "Admin",
      "lastName": "User",
      "email": "admin@example.com"
    },
    "costCenters": [
      {
        "id": "cc-example-001",
        "name": "Main Cost Center",
        "addresses": [
          {
            "addressType": "BillingAddress",
            "street": "100 Main Street",
            "city": "Chicago",
            "state": "IL",
            "country": "USA",
            "postalCode": "60601",
            "complement": ""
          },
          {
            "addressType": "ShippingAddress",
            "street": "200 Warehouse Ave",
            "city": "Chicago",
            "state": "IL",
            "country": "USA",
            "postalCode": "60602",
            "complement": ""
          }
        ]
      }
    ]
  }
}

Example: single address (legacy field)

The singular address field remains supported:

{
  "input": {
    "id": "org-example-002",
    "name": "Legacy Organization",
    "b2bCustomerAdmin": {
      "firstName": "Admin",
      "lastName": "User",
      "email": "admin.legacy@example.com"
    },
    "costCenters": [
      {
        "id": "cc-example-002",
        "name": "Main Cost Center",
        "address": {
          "addressType": "BillingAddress",
          "street": "5th Avenue",
          "city": "New York",
          "state": "NY",
          "country": "USA",
          "postalCode": "10001",
          "complement": ""
        }
      }
    ]
  }
}

Example: multiple addresses without custom IDs

Use createOrganization and omit all id fields:

mutation CreateOrganization($input: OrganizationInput!, $notifyUsers: Boolean) {
  createOrganization(input: $input, notifyUsers: $notifyUsers) {
    id
    costCenterId
    href
    status
  }
}

{
  "notifyUsers": false,
  "input": {
    "name": "Auto ID Organization",
    "b2bCustomerAdmin": {
      "firstName": "Admin",
      "lastName": "User",
      "email": "admin.auto@example.com"
    },
    "costCenters": [
      {
        "name": "Main Cost Center",
        "addresses": [
          {
            "addressType": "BillingAddress",
            "street": "Rodeo Drive",
            "city": "Beverly Hills",
            "state": "CA",
            "country": "USA",
            "postalCode": "90210",
            "complement": ""
          },
          {
            "addressType": "ShippingAddress",
            "street": "Sunset Blvd",
            "city": "Los Angeles",
            "state": "CA",
            "country": "USA",
            "postalCode": "90211",
            "complement": ""
          }
        ]
      }
    ]
  }
}

Use the returned costCenterId to query the created cost center:

query GetCostCenter($id: ID!) {
  getCostCenterById(id: $id) {
    id
    name
    addresses {
      addressType
      street
      city
      state
    }
  }
}

Related mutations

• createCostCenterWithId — create a cost center with a custom ID and addresses on an existing organization.
• updateCostCenter — update cost center fields, including addresses.