Promote Sign in Sign up

Repository

commerce-checkout-starter-kit

An AppBuilder starter kit that provides the scaffolding for checkout integration patterns with Adobe Commerce.

Adobe
Repository

README

Adobe Commerce checkout starter kit

Welcome to the home of Adobe Commerce checkout starter kit.

This starter kit is designed to help you get started with building custom checkout experiences for Adobe Commerce. Its
goal is to showcase how to use Adobe Commerce Extensibility in combination with Adobe App Builder to build custom
checkout experiences.

For more details, please refer to the Adobe Commerce checkout starter kit documentation.

Template: <project-name>

The following is an example app installation guide. For more details, please refer to the App submission guidelines.

Note that this template could be outdated. Make sure to refer to the latest information in the Adobe Commerce checkout starter kit documentation.

Prerequisites

You must install or have access to the following prerequisites to develop with <project-name>:

  • Adobe Commerce as a Cloud Service (SaaS) or Adobe Commerce version 2.4.5 or higher (PaaS).

  • Node.js version 22. If you have Node Version Manager (nvm) installed, you can run the following command to install and use the required version:

    nvm install 22 && nvm use

  • Adobe I/O CLI:

    npm install -g @adobe/aio-cli

  • Access to the Adobe Developer Console with an App Builder license.

Install Adobe Commerce Modules (PaaS only)

List only necessary modules for the project.

  • Install the required modules for <project-name>:

    composer require magento/module-out-of-process-payment-methods --with-dependencies
composer require magento/module-out-of-process-shipping-methods --with-dependencies
composer require magento/module-out-of-process-tax-management --with-dependencies

  • For Commerce Webhook, refer to the Install Adobe Commerce Webhooks

  • (If using Eventing) Update Commerce Eventing module to version 1.12.1 or higher:

    composer show magento/commerce-eventing
composer update magento/commerce-eventing --with-dependencies

  • (If using Admin UI SDK) Complete the Admin UI SDK installation process and install version 3.0.0 or higher:

    composer require "magento/commerce-backend-sdk": ">=3.0"

Create an App Builder project in Developer Console

  1. Log in to the Adobe Developer Console and select the desired organization from the dropdown menu in the top-right corner.

  2. Click Create new project from template.

  3. Select App Builder. The Set up templated project page displays.

  4. Specify a project title and app name. Mark the Include Runtime with each workspace checkbox.

Initialize App Builder project

  1. Navigate to the downloaded code and run:

    npm install
aio login
aio console org select
aio console project select
aio console workspace select
aio app use --merge

  2. Add required services to your project:

    aio app add service

    Select the following from the list:

    • I/O Management API
    • (If using Eventing) I/O Events
    • (If using Eventing) Adobe I/O Events for Adobe Commerce
    • (If connecting to Adobe Commerce as a Cloud Service) Adobe Commerce as a Cloud Service

  3. Copy the environment variables from the env.dist to a local .env file. We will complete the required variables in the upcoming sections.

  4. Run the following command to populate the relevant .env values:

    npm run sync-oauth-credentials

    This will generate entries:

    OAUTH_CLIENT_ID=
OAUTH_CLIENT_SECRETS=[""]
OAUTH_TECHNICAL_ACCOUNT_ID=
OAUTH_TECHNICAL_ACCOUNT_EMAIL=
OAUTH_SCOPES=[""]
OAUTH_IMS_ORG_ID=

    • This script is also configured as a pre-app-build hook and will auto-sync when a build is triggered.

    • If the credential is empty, make sure you have added the I/O Management API and your .env is synced with the Developer Console Project.

Connect to Adobe Commerce

Update the COMMERCE_BASE_URL value in the .env file and complete the authentication setup:

  • For PaaS (On-Premise/Cloud):
    • The base URL includes your base site URL + /rest/<store_view_code>/
    • Example: https://<commerce_instance_url>/rest/all/
  • For SaaS (Adobe Commerce as a Cloud Service):
    • Go to Commerce Cloud Manager in Adobe Experience Cloud and click info button on the instance > GraphQL endpoint URL.
    • Example: https://na1.api.commerce.adobe.com/<tenant_id>/

Option 1: Authenticate with IMS

To create OAuth credentials for App Builder authentication:

  1. Access your IMS credentials via the Adobe Developer Console. Select the project and workspace, then click OAuth Server-to-Server in the side-navigation menu.

    Note: You can find these credentials already in your .env as OAUTH_*.

  2. Add a technical account with server-to-server credentials to Commerce Admin using the Admin User Creation Guide.

  3. When associating the user, use the Technical Account email from the generated IMS credentials (<technical-account>@techacct.adobe.com) in the Email field.

  4. On the User Role tab, assign the necessary API integration permissions and save the user.

Option 2: Authenticate with Commerce Integration (PaaS only)

  1. Create a new Adobe Commerce Integration by following the systems integration guide.

  2. Copy the integration details to the .env file in the root of the project.

    COMMERCE_CONSUMER_KEY=<key>
COMMERCE_CONSUMER_SECRET=<secret>
COMMERCE_ACCESS_TOKEN=<access token>
COMMERCE_ACCESS_TOKEN_SECRET=<access token secret>

Configuration

Configure <project-name>

Describe any credentials required for the app.

Configure Payment Method

Create a payment method defined in payment-methods.yaml:

npm run create-payment-methods

Update the .env with your payment method code, which is used for the payment method validation webhook:

COMMERCE_PAYMENT_METHOD_CODES=["<your-payment-code>"]

Configure Shipping Method

Create a shipping method defined in shipping-carriers.yaml:

npm run create-shipping-carriers

Configure Tax Integration

Create a tax integration defined in tax-integrations.yaml:

npm run create-tax-integrations

Configure Webhooks

Prepare Webhook Signature

  1. In Adobe Commerce, go to Stores > Settings > Configuration > Adobe Services > Webhooks

  2. Enable Digital Signature Configuration and click Regenerate Key Pair

  3. Add the generated Public Key to your .env as the same format:

    COMMERCE_WEBHOOKS_PUBLIC_KEY="-----BEGIN PUBLIC KEY-----
XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX
-----END PUBLIC KEY-----"

Create Webhooks

After deploying your App Builder actions, create the webhooks with the following actions:

List all webhook methods and their corresponding actions required for the application.

  1. collect-taxes: This action collects taxes for the cart.

    • For SaaS, register your action to plugin.magento.out_of_process_tax_management.api.oop_tax_collection.collect_taxes webhook method in System > Webhooks > Webhooks Subscriptions.

    • For PaaS, please refer to webhooks.xml. Replace the app builder URL with your action after deploying the App Builder application.

      <config xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
        xsi:noNamespaceSchemaLocation="urn:magento:module:Magento_AdobeCommerceWebhooks:etc/webhooks.xsd">
    <method name="plugin.magento.out_of_process_tax_management.api.oop_tax_collection.collect_taxes" type="before">
        <hooks>
            <batch name="collect_taxes">
                <hook
                    name="collect_taxes"
                    url="https://<your_app_builder>.runtime.adobe.io/api/v1/web/<your-project>/collect-taxes"
                    method="POST" timeout="10000" softTimeout="2000"
                    priority="300" required="true" fallbackErrorMessage="Tax calculation failed. Please try again later."
                    ttl="0"
                />
            </batch>
        </hooks>
    </method>
</config>

Configure Eventing

Follow the steps below to configure eventing for your application:

Create Event Provider

Configure the event provider defined in events.config.yaml:

npm run configure-events

This scripts populates the AIO_EVENTS_PROVIDERMETADATA_TO_PROVIDER_MAPPING environment variable in your .env file with the provider metadata and the provider id.

Configure Commerce Eventing

To configures the Commerce event provider for your Commerce instance:

  1. Update your .env file with the Commerce event provider metadata in Stores > Configuration > Adobe Services > Adobe I/O Events > Commerce events:

    COMMERCE_ADOBE_IO_EVENTS_MERCHANT_ID=
COMMERCE_ADOBE_IO_EVENTS_ENVIRONMENT_ID=

  2. Run the following script to configure the Commerce Event module to your Commerce. This uses the commerce event provider dx_commerce_events defined in events.config.yaml:

    npm run configure-commerce-events

Once this step is done, deploy the application to register the events to your App Builder application.

Deploy Your Application

Once all configuration steps are complete, deploy the application:

aio app deploy --force-build --force-deploy

Validation

Write your validation steps here

To verify the application:

  1. Check that payment, shipping, and tax methods appear on the Checkout page.
  2. Place an order and confirm that it is successfully created with the expected configurations.

Configure <project-name>

1

  • Describe any credentials required for the app.