Shipping method extension tutorial

Go to pipedream.com and sign up or log in.

Click New workflow (or Add workflow).

For the trigger, select HTTP / Webhook.

In the trigger configuration, set HTTP Response to Return a custom response from your workflow. This allows the Code step to send the mock JSON response.

Pipedream displays a unique HTTP endpoint URL, such as https://123456.m.pipedream.net.

Copy this URL and use it as the Service URL when configuring the extension in the Commerce Admin.

{width="600" modal="regular"}

Click the + icon to add a step.

Choose Run Node.js code (Code step).

Replace the default code with the following JavaScript.

export default defineComponent({
async run({ steps, $ }) {
   const event = steps.trigger.event;
   const body = event.body ?? {};
   const headers = event.headers ?? {};
   const apiKey = headers["api-key"] ?? body.api_key ?? "";

   if (!apiKey || String(apiKey).trim() === "") {
      await $.respond({
      immediate: true,
      status: 401,
      headers: { "Content-Type": "application/json" },
      body: { error: "Missing or invalid API-Key header" },
      });
      return;
   }

   const shipment = body.shipment;
   if (!shipment || typeof shipment !== "object") {
      await $.respond({
      immediate: true,
      status: 400,
      headers: { "Content-Type": "application/json" },
      body: { error: "Missing or invalid shipment" },
      });
      return;
   }

   const rates = [
      {
      service_code: "mock_standard",
      service_name: "Mock Standard",
      carrier_friendly_name: "Mock Carrier",
      shipping_amount: { amount: 5.99 },
      shipment_cost: 5.99,
      cost: 5.99,
      },
      {
      service_code: "mock_express",
      service_name: "Mock Express",
      carrier_friendly_name: "Mock Carrier",
      shipping_amount: { amount: 12.99 },
      shipment_cost: 12.99,
      cost: 12.99,
      },
   ];

   await $.respond({
      immediate: true,
      status: 200,
      headers: { "Content-Type": "application/json" },
      body: { rates },
   });
},
});

Click Deploy.

{width="600" modal="regular"}

Navigate to the MCP settings in your coding agent. For example, in Cursor, go to Cursor > Settings > Cursor Settings > Tools & MCP. Verify that the commerce-extensibility toolset is enabled without errors. If you see errors, toggle the toolset off and on.

{width="600" modal="regular"}

If you have any documentation added to Cursor’s context, disable it. Navigate to Cursor > Settings > Cursor Settings > Indexing & Docs and delete any documentation listed.

{width="600" modal="regular"}

Give the agent access to the mock rates API specification, so it can implement the client correctly. If you have not already done so, download the mock rates API specification file, open it, and add the .md file to your project (for example docs/mock-rates-api-spec.md), then reference that file in your prompt.

Generate the shipping method extension:

• From the agent’s chat window, select Plan mode, if available. This prevents the agent from proceeding without a plan.
• Enter the following prompt:

Build an Adobe Commerce extension that adds a shipping method at checkout. The rates come from an external mock shipping rates service: the merchant configures the service's URL and API key in Admin, and at checkout the extension asks that service for rates and shows the returned options to the customer.

External service (mock shipping rates API):
- The service endpoint URL is configurable by the merchant (for example https://123456.m.pipedream.net).
- The API is specified in ./docs/mock-rates-api-spec.md.

The merchant must be able to configure the following in the Adobe Commerce Admin UI. Use the Adobe Commerce Admin UI SDK (or equivalent App Builder extensibility options for the Admin) to add a configuration screen where the merchant can set:
- The service URL (where the extension sends rate requests).
- An API key the service expects (any non-empty value for the mock). The API key is sensitive data: it must be stored securely and must never appear in logs, error messages, or in the UI in full (e.g. mask in the UI).
- The warehouse (ship-from) address: name, phone, street, city, state, postal code, country. This is the origin used when requesting rates.

{width="600" modal="regular"}

Answer the agent’s questions precisely to help it generate the best code. If the agent asks which kit or template to use, direct it to the checkout starter kit with the shipping domain and Admin UI SDK extension so that both the shipping webhook and the merchant configuration screen are implemented.

The agent may create a requirements.md (or equivalent) file that serves as the source of truth for the implementation.

Review the requirements.md (or equivalent) file and verify the plan. If everything looks correct, instruct the agent to move to architecture planning (or Phase 2). Confirm that:

• A shipping-methods action (or equivalent) handles the Commerce webhook and calls the external rates API.
• A shipping-config (or equivalent) action supports GET (read config, API key masked) and SET (save service URL, API key, warehouse address), with config stored securely, for example in Runtime State.
• The Admin UI includes a Mock Shipping (or similar) tab with fields for Service URL, API key (password/masked), and warehouse address.

{width="600" modal="regular"}

Review the architecture plan when the agent provides it.

{width="600" modal="regular"}

Instruct the agent to proceed with code generation. The agent should add a mock carrier to the shipping carriers configuration allowing Commerce to accept the returned methods, and use the webhook method plugin.magento.out_of_process_shipping_methods.api.shipping_rate_repository.get_rates (webhook type after, required Optional).

The agent generates the necessary code and provides a detailed summary with your next steps (including installing dependencies, registering the mock carrier, configuring the Commerce webhook, and deploying).

{width="600" modal="regular"} {width="600" modal="regular"}

After verifying the generated code, deploy the extension using the following prompt:

Deploy the app.

The agent performs a pre-deployment readiness assessment (for example checking .env for COMMERCE_WEBHOOKS_PUBLIC_KEY, COMMERCE_BASE_URL, and OAuth/IMS variables if the Admin UI or Commerce API is used).

{width="600" modal="regular"}

When you are confident with the assessment results, instruct the agent to proceed with deployment. The agent uses the MCP toolkit to verify, build, and deploy automatically.

{width="600" modal="regular"}

Register the mock carrier in Commerce (run once after deploy):

npm run create-shipping-carriers

Ensure your .env has COMMERCE_BASE_URL and a valid OAuth/IMS credentials, so the script can register the carrier.

Configure the shipping webhook in Commerce Admin:

• Go to Stores > Settings > Configuration > Adobe Services > Commerce Webhooks.

• Add a webhook:

  • Webhook method: plugin.magento.out_of_process_shipping_methods.api.shipping_rate_repository.get_rates
  • Webhook type: after
  • URL: the deployed shipping-methods web action URL (from the deploy output or the Adobe Developer Console).
  • Required: Optional - This allows checkout to still work if the external API returns no rates.

{width="600" modal="regular"}

Configure the Admin UI SDK extension:

• In Commerce Admin, go to Stores > Settings > Configuration.
• Open Adobe Services > Admin UI SDK.
• Set Enable Admin UI SDK to Yes and click Save Config if it is not already enabled.
• Click Configure extensions, choose the workspace your app is deployed to, then click Apply. You can also select the Custom option and enter the workspace name.
• Select your App Builder app in the list and save. If the app does not appear, click Refresh registrations and try again.

{width="600" modal="regular"}

Configure the Mock Shipping method in the Adobe Commerce Admin UI:

• Open Apps and select your app.

• Open the Mock Shipping tab (or equivalent).

• Enter the following details:

  • Service URL: the Pipedream workflow URL you copied (for example https://123456.m.pipedream.net).
  • API key: any non-empty value for the mock, for example tutorial-key.
  • Warehouse (ship-from) address: name, phone, street, city, state, postal code, country.

• Click Save. The configuration is stored in the Runtime State and is used by the shipping-methods action.

{width="600" modal="regular"}

Verify at checkout: Add a product to the cart, go to checkout, and enter a shipping address. You should see the mock shipping options, for example Mock Standard and Mock Express.

{width="600" modal="regular"}