BusinessEntity now exposes legalEntityId in the GraphQL Admin API

As of API version 2026-07, the BusinessEntity type in the GraphQL Admin API includes a new legalEntityId field. This field returns the stable Central Legal Entity ID from Shopify's Organizations Platform, giving Partners a consistent identifier for the same legal entity across multiple shops, markets, and sales channels.

What's new

The BusinessEntity type now includes:

• legalEntityId (BigInt, nullable): The stable organization-level legal entity identifier. This ID is consistent across all shops belonging to the same legal entity, enabling partners to recognize the same underlying company regardless of how many shops or markets it operates.

This field returns null when the business entity has no backing Central Legal Entity or when the legal entity does not have a stable external ID.

Example query

query {
  businessEntity(id: "gid://shopify/BusinessEntity/123456") {
    id
    legalEntityId
    companyName
    displayName
  }
}

Example response

{
  "data": {
    "businessEntity": {
      "id": "gid://shopify/BusinessEntity/123456",
      "legalEntityId": "223432432",
      "companyName": "Acme Corporation",
      "displayName": "Acme US"
    }
  }
}

Why this matters

Previously, BusinessEntity.id was scoped to individual shops, meaning the same company operating multiple shops would appear with different IDs. The new legalEntityId provides a single, stable identifier at the organization level that Partners can use to:

• Map a merchant's legal entity to a company code in their own systems
• Consistently identify the same company across multiple shops and markets
• Correlate legal entity data between the GraphQL Admin API and tax webhook payloads (where the same identifier appears as merchant_business_entity.legal_entity_id)

API version

This field is available starting in API version 2026-07 and in unstable.