Extending the checkout drop-in component

The checkout drop-in component follows the Adobe Commerce out-of-process extensibility (OOPE) pattern, which requires components to be flexible and extensible. When the checkout drop-in component lacks a specific feature, it provides mechanisms that allow developers to easily expand and customize its functionality.

GraphQL API

To extend the data payload of the drop-in, developers must use the GraphQL Extensibility API. This API allows developers to extend existing GraphQL operations to meet additional data requirements without increasing code complexity or negatively impacting performance. The API provides a flexible and efficient way to customize GraphQL fragments by integrating build-time modifications into the storefront’s development pipeline.

GraphQL fragments are reusable pieces of GraphQL that developers can use to extend or customize the API for a drop-in component. Drop-in components expose the list of fragments that can be extended in the fragments.ts file. If the drop-in component does not expose these fragments, the build process fails when you install the application because it cannot locate the fragment you want to extend.

The checkout drop-in component exposes the following fragments:

export {
  BILLING_CART_ADDRESS_FRAGMENT,
  SHIPPING_CART_ADDRESS_FRAGMENT,
} from '@/checkout/api/graphql/CartAddressFragment.graphql';
export {
  AVAILABLE_PAYMENT_METHOD_FRAGMENT,
  SELECTED_PAYMENT_METHOD_FRAGMENT,
} from '@/checkout/api/graphql/CartPaymentMethodFragment.graphql';
export { CHECKOUT_DATA_FRAGMENT } from '@/checkout/api/graphql/CheckoutDataFragment.graphql';
export { CUSTOMER_FRAGMENT } from '@/checkout/api/graphql/CustomerFragment.graphql';

Extend or customize a fragment

To make GraphQL fragments extensible in the drop-in component, you must first update the GraphQL fragment that the drop-in uses to request the additional field. You accomplish this by modifying the build.mjs script located at the root of your storefront project.

The build.mjs script automatically generates a new GraphQL query for the checkout drop-in component when you run the install command. This generated query includes the additional data that you specified in your fragment extensions.

Example 1: Adding new information

The merchant wants to extend the customer information by adding the gender and date of birth data.

/* eslint-disable import/no-extraneous-dependencies */
import { overrideGQLOperations } from '@dropins/build-tools/gql-extend.js';

overrideGQLOperations([
  {
    npm: '@dropins/storefront-checkout',
    operations: [
      `
      fragment CUSTOMER_FRAGMENT on Customer {
        gender
        date_of_birth
      }
      `,
    ],
  },
]);

After extending the API, you must extend the models and transformers during the initialization phase if data transformation is required. You accomplish this by modifying the /scripts/initializers/checkout.js script.

// Initialize checkout
await initializeDropin(async () => {
  // Register the checkout component with models extensibility
  const models = {
    CustomerModel: {
      transformer: (data) => ({
        gender: ((gender) => {
          switch (gender) {
            case 1:
              return "Male";
            case 2:
              return "Female";
            case 3:
              return "Not Specified";
            default:
              return "";
          }
        })(data?.gender),
        dateOfBirth: data?.date_of_birth,
      }),
    },
  };

  // Register initializers
  return initializers.mountImmediately(initialize, {
    models
  });
})();

Example 2: Removing information

The merchant wants to remove the selected payment method data.

/* eslint-disable import/no-extraneous-dependencies */
import { overrideGQLOperations } from '@dropins/build-tools/gql-extend.js';

overrideGQLOperations([
  {
    npm: '@dropins/storefront-checkout',
    skipFragments: ['SELECTED_PAYMENT_METHOD_FRAGMENT'],
    operations: [],
  },
]);