Configure Commerce

This section provides an overview of configuring out-of-process extensibility on Adobe Commerce for developing an app using the checkout starter kit.

All the configurations in your app must align with the App Builder Configuration file guidelines. In addition, the starter kit provides a set of scripts to help you get started with your project.

Configure Payment, Shipping, or Tax modules

Select one of the following modules to learn about the available scripts:

Configure OAuth Server-to-Server Credential

The OAuth credentials are available after completing the initial configuration.

The sync-oauth-credentials script ensures that the OAuth credentials are available for interacting with AIO, such as creating an event provider. This script synchronizes the OAuth credentials from Adobe Developer Console with your local App Builder project configuration, located in .env:

OAUTH_CLIENT_ID=<client id>
OAUTH_CLIENT_SECRETS=<client secret>
OAUTH_TECHNICAL_ACCOUNT_ID=<technical account id>
OAUTH_TECHNICAL_ACCOUNT_EMAIL=<technical account email>
OAUTH_SCOPES=<scope>
OAUTH_IMS_ORG_ID=<img org>
Copied to your clipboard
OAUTH_CLIENT_ID=<client id>
OAUTH_CLIENT_SECRETS=<client secret>
OAUTH_TECHNICAL_ACCOUNT_ID=<technical account id>
OAUTH_TECHNICAL_ACCOUNT_EMAIL=<technical account email>
OAUTH_SCOPES=<scope>
OAUTH_IMS_ORG_ID=<img org>

This script is included as part of the pre-app-build hook in app.config.yaml. When the app build is triggered, the script runs automatically to synchronize the OAuth credentials with the Commerce instance.

application:
  hooks:
    pre-app-build: ./hooks/pre-app-build.js
Copied to your clipboard
application:
  hooks:
    pre-app-build: ./hooks/pre-app-build.js

If OAuth credentials are still missing, review Verify your application is initialized.

Configure Eventing

The following configuration is required if you want to use the Eventing feature. Skip this process if you do not plan to use the Eventing feature. For third-party events processing, refer to Third-party events processing

To configure eventing, follow these steps:

Install the Commerce eventing module in your Commerce instance.
Set up the Adobe Commerce HTTP Client to authenticate the Commerce instance.
Configure your events.config.yaml and .env files with the commerce event provider specification.
- Create the event provider in advance, by running the configure-events script.
- If you already have a Commerce event provider, ensure that:
  - The events.config.yaml file matches the existing provider metadata.
  - The environment variable AIO_EVENTS_PROVIDERMETADATA_TO_PROVIDER_MAPPING contains the Commerce event provider ID.
- Update <your_application_name> as a prefix in both events.config.yaml and app.config.yaml to isolate event providers per application.
The script requires the following environment variables, which update the values in Stores > Configuration > Adobe Services > Adobe I/O Events > Commerce events:
- COMMERCE_ADOBE_IO_EVENTS_MERCHANT_ID: The merchant ID of the Commerce instance.
- COMMERCE_ADOBE_IO_EVENTS_ENVIRONMENT_ID: The environment ID of the Commerce instance.
Configure your app.config.yaml file to register the events for the app to consume.
- Update the events_of_interest field with the events that your app requires.
- Update the runtime_action field with the action that will consume the events.

This process must be completed before deploying the application for event registration.

events.config.yaml

The events.config.yaml file defines the event providers and their metadata.

Field	Description
`label`	Label of the event provider.
`provider_metadata`	Metadata of the event provider (For example, `dx_commerce_events` for the Commerce event provider).
`description`	Description of the event provider.
`docs_url`	Documentation URL for the event provider.
`events_metadata`	List of event metadata to register. (This is not required for the Commerce event provider, since it uses event subscriptions.)
`subscription`	Only required for the Commerce event provider. List of Commerce events to subscribe to. For payload specifications, refer to Subscribe to events.

app.config.yaml

The app.config.yaml file defines the events of interest for your app. The events will be registered during app deployment.

  events:
    registrations:
      Commerce events consumer:
        description: Consumes events from Adobe Commerce
        events_of_interest:
          - provider_metadata: dx_commerce_events
            event_codes:
               # Set the prefix to your application name (lowercase, alphanumeric, underscores allowed).
               #com.adobe.commerce.<your-application-name>.<commerce-event-code>
              - com.adobe.commerce.checkout_starter_kit.observer.sales_order_creditmemo_save_after
        runtime_action: commerce-checkout-starter-kit/consume
Copied to your clipboard
  events:
    registrations:
      Commerce events consumer:
        description: Consumes events from Adobe Commerce
        events_of_interest:
          - provider_metadata: dx_commerce_events
            event_codes:
               # Set the prefix to your application name (lowercase, alphanumeric, underscores allowed).
               #com.adobe.commerce.<your-application-name>.<commerce-event-code>
              - com.adobe.commerce.checkout_starter_kit.observer.sales_order_creditmemo_save_after
        runtime_action: commerce-checkout-starter-kit/consume

Refer to the App Builder with I/O events guide for more information on how to register events in the app.

configure-events

This script requires OAuth Server-to-Server credential to create the event provider.

The configure-events script configures the Adobe I/O Events integration for your project with a single command.

The script performs the following actions:

It reads the event providers specification from the events.config.yaml file and synchronizes the event providers and their metadata.
- The labels of the event providers defined in the specification are suffixed with the Adobe I/O Runtime namespace to ensure uniqueness across the projects of the organization.
The script updates the AIO_EVENTS_PROVIDERMETADATA_TO_PROVIDER_MAPPING environment variable with the latest provider metadata.

To run the configure-events script, ensure that your project configuration (.aio file) includes the following:

Organization ID: project.org.id
IMS Organization ID: project.org.ims_org_id
Project ID: project.id
Workspace ID: project.workspace.id

The script uses the following environment variables:

AIO_runtime_namespace: The Adobe I/O Runtime namespace is used as the suffix for the Adobe I/O Events provider label.
AIO_EVENTS_PROVIDERMETADATA_TO_PROVIDER_MAPPING: (Optional) Existing provider metadata to provider mapping.

To run this script, use the following command:

npm run configure-events
Copied to your clipboard
npm run configure-events

The script does not support deleting event providers. If you need to delete an event provider, you can do it through AIO CLI with the following command:

aio event provider delete <provider-id>
Copied to your clipboard
aio event provider delete <provider-id>