Connect to Adobe Commerce

This guide explains how a checkout starter kit app connects to Adobe Commerce.

Association

The adobe-commerce.js file provides a set of methods to interact with the Adobe Commerce instance. The client uses the Adobe Commerce HTTP Client, which is a wrapper around the Adobe Commerce REST API.

Each app connects to a specific Commerce instance through App Management's association step: an app manager associates the deployed app with their Commerce instance from Apps > App Management in the Commerce Admin. See manage your app for the association, installation, and other lifecycle steps.

Once associated, getCommerceClient (from @adobe/aio-commerce-lib-app) resolves the Commerce instance's base URL and environment (PaaS or SaaS) from the stored association data, so there's no COMMERCE_BASE_URL to configure manually for actions that go through association:

import { getCommerceClient } from "@adobe/aio-commerce-lib-app";
import { resolveImsAuthParams } from "@adobe/aio-commerce-sdk/auth";

export async function main(params) {
  const commerceClient = await getCommerceClient(resolveImsAuthParams(params));
  const products = await commerceClient.get("products").json();
}

getCommerceClient throws an AppNotAssociatedError if the app isn't associated with a Commerce instance yet. Re-associating the app resolves this error.

Authentication

getCommerceClient only accepts IMS authentication. If you're calling Commerce directly instead of going through App Management association, use resolveCommerceHttpClientParams and AdobeCommerceHttpClient from @adobe/aio-commerce-sdk/api. These support both IMS and Commerce Integration (OAuth1) authentication, picked automatically based on which credentials are present.

Adobe Identity Management Service (IMS)

SaaS Only IMS authentication is used and Commerce Integration authentication is not available.

Use resolveImsAuthParams(params) to resolve the app's own IMS credentials, which are populated automatically at association time. Use forwardImsAuthProvider(params) when you need to forward the caller's own IMS token, such as when an Admin UI action needs to act as the logged-in admin rather than as the app itself.

Create a Commerce integration

PaaS Only Commerce Integration (OAuth1) is a supported alternative to IMS for calling Commerce directly, outside of App Management association.

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

2. Make sure your API integration has the necessary permissions to access the Commerce REST API.

   To confirm that you have access, in the Commerce Admin, navigate to System > Extensions > Integrations. Under the Basic Settings menu, click API to view the Available APIs. Then select All in the Resource Access field.

3. Provide the integration details, along with the Commerce base URL, as action inputs:

   AIO_COMMERCE_API_BASE_URL=<your commerce base url>
   AIO_COMMERCE_AUTH_INTEGRATION_CONSUMER_KEY=<key>
   AIO_COMMERCE_AUTH_INTEGRATION_CONSUMER_SECRET=<secret>
   AIO_COMMERCE_AUTH_INTEGRATION_ACCESS_TOKEN=<access token>
   AIO_COMMERCE_AUTH_INTEGRATION_ACCESS_TOKEN_SECRET=<access token secret>
   

4. Build the client:

   import { AdobeCommerceHttpClient, resolveCommerceHttpClientParams } from "@adobe/aio-commerce-sdk/api";
   
   export async function main(params) {
     const commerceClient = new AdobeCommerceHttpClient(resolveCommerceHttpClientParams(params));
     const products = await commerceClient.get("products").json();
   }
   

Debugging requests

You can debug your application and access customized logs using the LOG_LEVEL environment variable. If this variable is set, logs from different phases of the commerce client display with detailed information.