Skip to content
Visit ShipperHQ.com
  • There are no suggestions because the search field is empty.

How to install ShipperHQ on Adobe Commerce with Adobe App Builder

ShipperHQ Integration using Adobe App Builder

The ShipperHQ Adobe Commerce App available via Adobe App Builder provides a cloud-compatible means to install ShipperHQ to calculate and return shipping rates. This App provides an alternative means of connecting ShipperHQ to Adobe Commerce when using the ShipperHQ Extension is not feasible.

Table of Contents

Prerequisites

Before you start, ensure you have:

  • Adobe Developer Console project & workspace with App Builder enabled.

  • Adobe I/O CLI (aio) installed.

  • Node.js 22.x installed.

  • Access to an Adobe Commerce instance with Webhooks enabled.

  • A ShipperHQ Enterprise plan.

Supported Functionality

The ShipperHQ Adobe Commerce app via App Builder supports all baseline ShipperHQ functionality including:

  • Real-time, live shipping rates
  • Custom and table rate shipping options
  • LTL Freight rating
  • Dimensional packing
  • Delivery dates
  • Basic in-store pickup and ship to store
  • Multi-origin rating
  • Shipping rules

However, it does not support functionality which requires checkout UI components such as:

  • Delivery calendar and/or timeslots
  • In-store pickup with map and store info
  • Split shipments
  • LTL freight accessorial UI components

If you need these capabilities, you are able to do so using either the standard ShipperHQ Adobe Commerce extension or ShipperHQ Enhanced Checkout for Adobe Commerce. If you're unsure, please contact us and we'll be happy to help.

1. Installation

  1. Install dependencies:

    npm ci

  2. Select your Adobe App Builder workspace:

    aio app use

    This generates .aio and .env files.

  3. Copy environment variables:

    cp env.dist .env

    Then update .env with your values.

  4. Run locally for testing: 

    aio app dev

    Local actions/web will run on http://localhost:9080.

2. Configuration

Update your .env file with required values:

ShipperHQ credentials:

SHIPPERHQ_API_KEY=your_api_key
SHIPPERHQ_PASSWORD=auth_code
SHIPPERHQ_ENVIRONMENT_SCOPE=LIVE   # or TEST/DEVELOPMENT
SHIPPERHQ_WEBSITE_URL=https://example.com
MAGENTO_VERSION=2.4.8

Your API Key (`api_key`) and

Adobe Commerce connectivity: 

COMMERCE_BASE_URL=https://example.com/rest/default/
COMMERCE_WEBHOOKS_PUBLIC_KEY="-----BEGIN PUBLIC KEY-----\n...\n-----END PUBLIC KEY-----"

3. Authentication

Choose one authentication method:

Option A (Recommended, SaaS): IMS OAuth Server-to-Server

  • Configure IMS credentials in Developer Console.

  • Sync credentials into .env:

    npm run sync-oauth-credentials 

Option B (PaaS/On-Prem): Adobe Commerce Integration (OAuth 1.0a)

  • In Adobe Commerce: System → Extensions → Integrations → Add New Integration.

  • Copy credentials into .env:

    COMMERCE_CONSUMER_KEY=
    COMMERCE_CONSUMER_SECRET=
    COMMERCE_ACCESS_TOKEN=
    COMMERCE_ACCESS_TOKEN_SECRET=

4. Create Shipping Carriers

Define carriers in shipping-carriers.yaml, then run:

npm run create-shipping-carriers
For a custom path:
npm run create-shipping-carriers -- ./path/to/shipping-carriers.yaml

5. Webhook Configuration

Add this snippet to webhooks.xml in Adobe Commerce:

<method name="plugin.magento.out_of_process_shipping_methods.api.shipping_rate_repository.get_rates" type="after">
    <hooks>
        <batch name="get_shipperhq_rates">
            <hook name="add_shipperhq_shipping_rates"
                  url="https://localhost:9080/api/v1/web/shipperhq/get-rates"
                  method="POST"
                  timeout="10000"
                  softTimeout="5000"
                  priority="100"
                  required="true"
                  sslVerification="false">
                <fields>
                    <field name="rateRequest" />
                </fields>
            </hook>
        </batch>
    </hooks>
</method>

Replace https://localhost:9080/... with your deployed action URL in production.

Set sslVerification="true" for production environments.

6. Deployment

Deploy to Adobe App Builder:

aio app deploy

7. Security Requirements

  • Add require-adobe-auth: true to all runtime actions in app.config.yaml.

  • Protect webhooks via signature verification or IMS token validation.

  • Use .env for all credentials — never hardcode secrets.

Testing & Quality Checks

The app supports various testing and quality checks that may be used as desired once installed.

  • Type check:

    npm run check-types 

  • Lint:

    npm run lint 

  • Audit:

    npm audit --omit=dev

Conclusion

Once complete, your ShipperHQ App Builder integration will be able to return real-time shipping rates to Adobe Commerce through Out-of-Process (OOP) shipping methods.