Magento 2 Web API: How to Create One and Why It Matters

A web API in Magento 2, now part of Adobe Commerce, is a custom endpoint that lets your store exchange data with another system, such as an ERP, a CRM or a mobile app, without manual work. Building one takes a small module with five files, a route declared in webapi.xml and an interface that defines what the endpoint accepts and returns.

Every commerce executive has lived some version of the same Monday morning. The sales review begins, the CFO presents revenue from the ERP, the digital director presents orders from the store, and the two numbers do not match. Someone explains that inventory is synchronized overnight, that a batch failed on Friday, that two hundred units sold online were already committed to a distributor. Nobody in the room doubts the people involved. The problem is that two systems that should behave as one are held together by exports, spreadsheets and goodwill. That gap is where margin leaks, where customers receive apologies instead of products, and where the cost to serve quietly climbs.

This article uses a deliberately simple example, a contact form that sends a customer's name and message to a custom endpoint, to explain how Magento web services work and why the decision to build one belongs on an executive agenda. The code is short. The consequences of getting integration right, or leaving it to improvisation, are not.

Why does a web service matter beyond the IT department?

A web service is a mechanism through which two or more systems communicate: information is transferred, procedures are executed or user data is captured. When a customer fills in a form, requests a quote or files a claim, the data travels to a server that processes it. The same principle applies when your store sends an order to an ERP, asks a warehouse system for stock levels or pushes a new customer to a CRM. The quality of those conversations determines whether your company behaves as one organization in front of the customer or as a collection of departments.

Consider a regional retailer that sells through a Magento storefront and twelve physical stores. If the storefront learns about inventory movements every twenty-four hours, it will promise products that the stores have already sold. Each broken promise is a cancellation, a service contact and a customer who is less likely to come back. If the same retailer exposes a secure endpoint that the point-of-sale system calls whenever a unit leaves a shelf, the promise on the website matches the shelf. The investment is a few days of development. The return is fewer cancellations, fewer service tickets and a forecast the CFO can defend.

The pattern repeats across sectors. A distributor selling to business customers needs credit limits from its ERP to appear at the moment a buyer builds an order. A bank or insurer that uses a commerce platform for products and services needs customer data to reach compliance and CRM systems without being re-typed. A manufacturer with an authorized dealer network needs price lists to flow from a pricing engine to the portal that dealers use. In each case the web service is the quiet component that makes the commercial promise true. ICX Consulting approaches these projects from the process outward, mapping which decisions depend on which data before choosing how to connect systems, as described in its process integration with systems practice.

What does Adobe Commerce offer out of the box, and when do you need a custom endpoint?

Adobe Commerce supports three types of web API: GraphQL, REST and SOAP. According to Adobe's developer documentation, authentication varies by use case, with OAuth 1.0a for third-party applications, tokens for mobile apps and login credentials for administrators and customers. For standard operations such as reading a product, creating a customer or placing an order, the platform already ships ready-made endpoints, and the first decision a technical leader should make is whether one of them is enough.

A custom endpoint is justified when the business needs behavior the standard interface does not provide: capturing data from a campaign form, receiving a webhook from a logistics partner, exposing a calculation specific to your pricing or returning a response shaped for a particular mobile application. It is also justified when the standard endpoint would expose more data than the consumer should see. A narrow endpoint that does one thing and returns only what is needed is easier to secure, easier to monitor and easier to hand to a partner.

The trade-off is ownership. Every custom endpoint is code the company must maintain through platform upgrades. Executives who approve integration work should therefore ask three questions before development begins. Which business event triggers the exchange? Who owns the data on each side? What happens, operationally, when the call fails? A company that cannot answer the third question is not ready to automate the process, however simple the code looks.

For readers weighing how deep the integration should go, the related analysis on types of Magento integration with an inventory system compares the usual options, and the article on six key integrations in an eCommerce shows which connections tend to pay back first.

How do you create a simple web API in Magento 2? A working example

The example that follows captures the data of a customer who is filling out a contact form. Imagine that you fill out a form with your personal data, the data is sent to a server and processed, perhaps to participate in a raffle, to request a particular service or to make a claim. The mechanism is the same one a business would use for a lead capture or a service request.

First, the client-side form must be created. A tool such as Bootsnipp generates an HTML form quickly and easily.

Copy the HTML code of the form and paste it where you want to show it to the user. For this exercise, a contact page will be created.

The following JavaScript submits the form when the user presses the Submit button. The example is a basic demonstration, so add validations or a captcha before using it in production.

<script type="text/javascript" defer>
  require(['jquery','jquery/ui'], function($) {
    $('#submit').on('click', function(){
      var formData = new FormData($("#contact-form")[0]);
      formData = JSON.stringify(Object.fromEntries(formData));
      $('body').trigger('processStart');
      $.ajax({
        type: "POST",
        url: "/rest/V1/custom/contact-form/",
        data: formData,
        success: function(){
          $('body').trigger('processStop');
          alert("Success");
        },
        error: function (xhr, ajaxOptions, thrownError) {
          $('body').trigger('processStop');
          alert("Error");
        },
        dataType: 'json',
        contentType: 'application/json',
      });
   });
});
</script>

>> Essential cybersecurity for your store in Adobe Commerce <<

In the JavaScript above, replace "contact-form" with the name you want to give to the route of your web service. With that the form is complete, and the next step is the server side. In the app/code folder of your Magento directory, create a module. In this example it is named ICX_Contact (create the folder app/code/ICX/Contact). Replace "ICX" and "Contact" to match the name of your own module in every file below.

registration.php:

<?php
\Magento\Framework\Component\ComponentRegistrar::register(
    \Magento\Framework\Component\ComponentRegistrar::MODULE,
    'ICX_Contact',
    __DIR__
);

etc/module.xml:

<?xml version="1.0"?>
<config xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:noNamespaceSchemaLocation="urn:magento:framework:Module/etc/module.xsd">
    <module name="ICX_Contact" setup_version="1.0.0" />
</config>

etc/di.xml:

<?xml version="1.0"?>
<config xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:noNamespaceSchemaLocation="urn:magento:framework:ObjectManager/etc/config.xsd">
    <preference for="ICX\Contact\Api\Contact" type="ICX\Contact\Model\Api\Contact"/>
</config>

etc/webapi.xml (replace "contact-form" with the same name you assigned in the JavaScript):

<?xml version="1.0"?>
<routes xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:noNamespaceSchemaLocation="../../../../../app/code/Magento/Webapi/etc/webapi.xsd">
    <route method="POST" url="/V1/custom/contact-form/">
        <service class="ICX\Contact\Api\Contact" method="getPost"/>
        <resources>
            <resource ref="anonymous"/>
        </resources>
    </route>
</routes>

Api/Contact.php defines the parameters the web service receives. In this case there are only two, the name and the contact information. Both are strings, and their names must match the names of the HTML form fields.

<?php
namespace ICX\Contact\Api;
interface Contact
{
    /**
     * GET for Post api
     * @param string $name
     * @param string $info
     * @return string
     */
    public function getPost($name, $info);
}

The docblock matters more than it appears. Adobe's documentation on configuring services as web APIs states that, for REST and SOAP to work, the interface docblock must declare each parameter as @param type $name and the return value as @return type.

Model/Api/Contact.php adds the functionality of the getPost method. It must keep the same parameters and names as the interface defined above.

<?php
namespace ICX\Contact\Model\Api;
 
use Psr\Log\LoggerInterface;
 
class Contact
{
    protected $logger;
 
    public function __construct(
        LoggerInterface $logger
    )
    {
        $this->logger = $logger;
    }
 
    /**
     * @inheritdoc
     */
    public function getPost($name, $info)
    {
        $response = ['success' => false];
        try {
            // Your Code here
            $response = ['success' => true, 'message' => $name . " " . $info];
        } catch (\Exception $e) {
            $response = ['success' => false, 'message' => $e->getMessage()];
            $this->logger->info($e->getMessage());
        }
        return json_encode($response);
    }
}

Inside the getPost function you can add the behavior you need, such as saving the information to a database, sending an email or forwarding the data to another system. In every case, run security validations on both the client and the server side, to avoid code injection attacks and to clean up invalid data formats.

Once the files are in place, install and compile the Magento 2 instance by running these commands, in order.

1. bin/magento setup:upgrade
2. bin/magento setup:di:compile
3. bin/magento cache:flush

Now enter data in the form. It helps to open the browser's inspection console (in Chrome, press F12 or right click and choose Inspect) and watch the Network tab when you press Submit.

You should see a 200 code with the response message. If the error code is 400, check the syntax of your JavaScript. If it is a 500 error, check the log files located at var/log/system.log, var/log/exception.log, /var/log/apache2/error.log (if you use Apache) or /var/log/nginx/nginx_error.log (if you use Nginx).

If you want to download the code used in this guide, use the following link:

>> Magento in the financial industry <<

Is it safe to expose an endpoint to anonymous users?

The example declares resource ref="anonymous", which is appropriate for a public contact form and nothing more. Adobe's documentation on resource accessibility explains that anonymous resources require no authentication and are open to guests and customers alike, that they are not defined in acl.xml and that they do not appear in the Admin permissions tree. In practice that means an anonymous endpoint cannot tell the company who is calling it.

The same documentation describes the alternatives. A self resource lets an authenticated customer reach data they own, and an ACL resource restricts an endpoint to administrators or integrations that were granted that permission in the Admin. An endpoint that receives orders from a logistics partner, or exposes customer-specific prices, should use an ACL resource and an integration with its own credentials. Adobe has also moved the platform toward a stricter default, since, according to its page on anonymous API security, Commerce now prevents anonymous users from accessing APIs that could reveal sensitive information, which can break third-party integrations that were built on the old assumption.

For a financial institution, an insurer or any company that handles personal data, the question is not whether the endpoint works but whether the company can prove who called it and what they saw. This is where a development exercise becomes a governance topic, and where the broader practices in ICX's cybersecurity work apply. Rate limiting, logging, input validation and a rotation policy for credentials belong in the design before the first line of code, not in the audit that follows an incident.

What happens when the integration is more than a form?

The contact form is a teaching device. The real value appears when the endpoint becomes a link in an operating process. Take a distributor of industrial supplies that sells through a business portal. When a buyer opens the cart, the portal needs the buyer's negotiated price, the credit available and the stock in the nearest warehouse. Three systems own that information. If each answer arrives through a custom, well-governed service, the buyer completes the order in minutes and the sales representative spends the afternoon on accounts that need a conversation. If each answer requires a phone call to the back office, the portal becomes an expensive catalog.

A similar logic applies to a consumer-goods company that opens a direct channel. Orders arrive in the store, but fulfilment depends on a third-party logistics provider, and customers expect to see tracking and returns in the same place they bought. Each of those expectations is an integration, and each integration is a point at which customer experience can succeed or fail. The article on why AI does not make up for poor integrations makes the point from another angle, that no analytical layer rescues a business whose systems disagree about the facts.

The lesson for the executive is to treat integration as a product with an owner, a service level and a roadmap. The companies that do so can add a channel, a partner or an automation in weeks. The companies that treat each connection as a one-off project accumulate a web of fragile scripts that only one developer understands, and every upgrade of the platform becomes a negotiation with the risk.

What this means for the C-level

For the chief executive and the commercial leadership, the first implication concerns conversion and retention. A customer who sees accurate stock, a correct price and a reliable delivery promise buys more often and complains less, and those effects show up in repeat purchase rates long before they show up in an IT report. The second concerns service. When order status, returns and customer history are available through a clean interface, service teams resolve questions in one contact and the cost to serve falls without reducing quality.

For the chief financial officer, the implication is efficiency and control. Every manual re-keying step is a labor cost, an error rate and an audit exposure. Integrations that remove those steps can be evaluated like any other investment, comparing the hours and reconciliations eliminated against the cost to build and maintain. For the chief information and security officers, the discipline is to approve a small number of well-governed integration patterns instead of dozens of improvised ones. For the chief marketing officer, the opportunity is that leads, behavior and purchases finally travel together, which makes segmentation and loyalty programs credible rather than aspirational.

None of this requires the company to build everything itself. It does require leadership to decide which integrations are strategic enough to own, which can be bought as connectors and which should wait. That is a commercial decision before it is a technical one, and it is easier to make with a clear picture of the processes the integrations serve. The comparison of effective integrations connecting CRM, ERP and automation systems offers a useful frame for that conversation.

How to start on Monday morning

A seasoned consultant would begin by asking the team for a single page. On the left, the five commercial events that matter most to the business, for example a customer places an order, a payment is confirmed, stock changes, a price changes and a shipment leaves the warehouse. On the right, which system is the source of truth for each, and how the other systems learn about it today. In most companies this page takes an afternoon to draw and reveals more than a month of status reports, because it shows where the information travels by spreadsheet, where it travels by overnight batch and where it does not travel at all.

From that page, choose one integration where the business pain is visible and the scope is small, ideally one that a customer or a sales representative would notice. Build it with the discipline described above: a narrow endpoint, the right access level, logging from the first day and a defined response when the call fails. Measure what changes, whether cancellations, tickets, hours of reconciliation or days to launch a new channel, and use that evidence to decide the next one. Resist the temptation to start with a platform-wide integration program, because the first successful connection teaches the organization more than a roadmap can.

Finally, give the integration an owner on the business side. Technical teams can build the endpoint, but only a business owner can decide what the data means, who may see it and what a failure costs. When that role is missing, integrations are built quickly and abandoned slowly.

How ICX helps

ICX Consulting helps commercial and technology leaders decide what to connect, in what order and under which governance, before any code is written. The work usually starts with process integration with systems, where the key commercial events are mapped to the data and decisions that depend on them, and continues with the architecture and the selection of the right platform capabilities. For companies that run their digital channel on Adobe Commerce, ICX also supports the implementation, so that the strategy and the technical design remain one conversation. Request a diagnostic with an ICX consultant if your forecast meetings still depend on reconciling two versions of the truth.

The ICX Technology Selection Toolkit includes an assessment checklist, an evaluation matrix and a process diagram that help leadership teams compare platforms and integration capabilities on the same criteria. Use it before approving the next integration project.

Frequently asked questions

What is the difference between REST and SOAP in Magento 2?

Both are supported by the same web API framework, and the same service interface can be exposed through either. REST is the more common choice for web and mobile applications because it exchanges lightweight JSON over standard HTTP routes, while SOAP remains in use where a partner's system expects a formal XML contract. Adobe Commerce also supports GraphQL for storefront queries.

Do I need a custom web service for every integration?

No. Standard endpoints cover products, customers, orders and many other entities. Build a custom service when the business needs a behavior the standard interface lacks, or when exposing a narrower, safer interface is preferable to exposing a broad one. Before building, confirm that no existing endpoint or approved connector already solves the need.

How long does a simple custom endpoint take to build?

The module in this article is a matter of hours for an experienced developer. The calendar time is usually determined by everything around it: defining the data contract with the other system, security review, testing under failure conditions and agreeing who owns monitoring. Companies that decide those items early move far faster than those that discover them during testing.

Which access level should a new endpoint use?

Use anonymous only for genuinely public actions such as a contact form, and add validation and abuse controls. Use a self resource when an authenticated customer should reach their own data, and an ACL resource when the caller is an administrator or a partner integration with its own credentials.

Integration rarely appears on a board agenda until something fails in front of a customer. The companies that avoid that moment are those that treat every connection between systems as part of the commercial promise. If you are weighing where to begin, talk to an ICX consultant about which of your systems should already be speaking to each other.