Magento 2.4.9 GraphQL Bug: Telephone Field Requirement Ignores Optional Configuration

Unmasking a Critical GraphQL Glitch in Magento 2.4.9: The 'Optional' Telephone Field Demands Attention

As e-commerce platforms evolve, the consistency between backend configurations and API behavior becomes paramount. A recent GitHub issue (#41034) has brought to light a significant inconsistency within Magento Open Source and Adobe Commerce 2.4.9 concerning its GraphQL API. Developers and merchants leveraging GraphQL for their checkout processes might encounter a frustrating roadblock: the telephone field in shipping addresses, despite being configured as optional in the Magento admin, is still enforced as a required field by GraphQL.

The Core Problem: GraphQL's Strictness vs. Magento's Flexibility

The essence of the bug lies in a mismatch. Magento provides a flexible configuration option under Stores → Configuration → Customers → Customer Configuration → Name and Address Options → Show Telephone, allowing merchants to set the telephone field as 'Optional'. However, when attempting to use the setShippingAddressesOnCart GraphQL mutation, the API's schema (input CartAddressInput { ... telephone: String! }) explicitly defines the telephone field as a non-nullable String!. This means GraphQL strictly requires the field, regardless of the store's configuration.

Reproducing the Issue

The issue is easily reproducible, highlighting a clear regression from earlier Magento versions where this field could indeed be omitted. Here are the steps and the GraphQL query involved:

1. Ensure your Magento Open Source / Adobe Commerce 2.4.9 environment has the telephone field configured as Optional.
2. Create an empty cart.
3. Attempt to call the setShippingAddressesOnCart mutation without including the telephone field in the address input.

GraphQL Mutation:

mutation SetShippingAddress($cartId: String!, $address: CartAddressInput!) {
  setShippingAddressesOnCart(
    input: {
      cart_id: $cartId
      shipping_addresses: [
        {
          address: $address
        }
      ]
    }
  ) {
    cart {
      shipping_addresses {
        firstname
        lastname
      }
    }
  }
}

Variables (without telephone):

{
  "cartId": "",
  "address": {
    "firstname": "John",
    "lastname": "Doe",
    "street": ["Main Street 1"],
    "city": "Hamburg",
    "postcode": "20095",
    "country_code": "DE"
  }
}

Expected Result: The mutation should succeed, respecting the 'Optional' configuration for the telephone field.

Actual Result: The request fails with a validation error:

Field "telephone" of required type "String!" was not provided.

The Flawed Workaround and Its Impact

To bypass the GraphQL validation, one might be tempted to pass an empty string for the telephone field:

{
  "telephone": ""
}

While this satisfies the GraphQL schema and allows the mutation to succeed, it introduces a new, critical problem. Querying the cart afterward reveals an empty shipping_addresses array, rendering the shipping address effectively unusable. Consequently, no shipping methods are returned, leading to a broken checkout experience. This makes the workaround impractical for a live e-commerce environment.

Severity and Implications for Magento Development

The issue has been triaged with a Severity S1, indicating it affects critical functionality and forces users to employ a workaround, albeit a flawed one. For developers building custom checkouts, headless commerce solutions, or integrating third-party systems via GraphQL, this bug presents a significant hurdle. It forces them to either modify their GraphQL queries to include a dummy telephone number (which might not be desired or accurate) or face a non-functional shipping address process.

This regression underscores the importance of rigorous testing and maintaining consistency across all layers of the Magento platform. While no official fix or alternative solution was provided within the issue comments (as of the last update), the community's vigilance in reporting such discrepancies is crucial. We encourage developers and merchants to monitor this GitHub issue for updates and official patches from the Magento core team.

At Shopping Mover, we understand the complexities of Magento migrations and ongoing maintenance. Issues like this highlight the need for robust development practices and staying informed about platform updates and potential pitfalls. Addressing these inconsistencies is vital for a seamless and efficient e-commerce operation.