What we do
Tools
Industries
Department
How we workLet's talk →
Home/Magento/Which Magento API, Which Token, Which Scope
Magento Open Source and Adobe Commerce

The Magento API for Back-Office Work: Picking the Interface, the Credential and the Scope

If you're about to write code against a Magento store, three choices come before the first request: REST or GraphQL, which kind of credential, and which store scope each call runs in. Orders, stock and prices belong on REST. GraphQL is for storefronts. SOAP is still around, mostly for integrations written years ago. Scope is the choice that catches people out later.

The Magento API in four lines

Back office (orders, products, stock, customers): REST, under /rest/{store_code}/V1/. Large imports go to /rest/{store_code}/async/bulk/V1/ instead.

Storefront or headless frontend: GraphQL, at the store's /graphql endpoint.

A permanent system-to-system link: an integration registered in the Admin, signed with OAuth 1.0a. Admin and customer tokens suit short jobs tied to one person.

Adobe Commerce as a Cloud Service: integration and admin tokens aren't available there. Calls authenticate through Adobe IMS with OAuth 2, using server-to-server credentials for automated jobs.

REST or GraphQL for a Magento integration

Back office

REST

  • A fixed endpoint per resource, such as /V1/orders or /V1/products/{sku}.
  • Filtering and paging through searchCriteria, so a sync can ask only for orders updated since its last run.
  • Async and bulk variants for jobs too big for one request: Magento replies with a bulk_uuid and you check its status later.
  • Every call is scoped by the store code in its URL.
Storefront

GraphQL

  • One query returns exactly the fields a page needs: product, price, stock status, cart.
  • Shaped around what a shopper does: browse, add to cart, check out, view their own account.
  • Admin-side jobs like order export or stock writes aren't what it's built for.
  • Some B2B storefront features, such as requisition lists, are reachable here but not through REST. The Magento B2B page lists which.

If the other end is an ERP, a warehouse system or accounting software, write it on REST. If the other end is a frontend shoppers use, write it on GraphQL. A store with both gets one integration on each.

Magento API credentials, matched to the job

Credential Good for Watch for
Integration (System › Extensions › Integrations) A standing link from an ERP, WMS or CRM. It only reaches the resources you tick when you create it. From 2.4.4 its access token can't be sent as a plain bearer token unless an admin allows it. Signing each request with OAuth 1.0a is the route Adobe prefers.
Admin token A script someone runs by hand, or a quick test against staging. It acts as that admin user, with that user's permissions, and expires after four hours by default. With admin two-factor authentication on, a plain username-and-password request won't get one; the 2FA module has its own token endpoints.
Customer token Calls made as one shopper: their orders, cart and addresses. GraphQL's generateCustomerToken mutation issues one too. It only reaches resources marked self or anonymous, and lasts an hour by default.
No token (guest) Public catalog reads and guest carts. Only resources marked anonymous. Anything naming a customer or an order needs a credential.
Adobe IMS (Cloud Service only) Stores on Adobe Commerce as a Cloud Service, where the older token types aren't supported. Credentials come from an Adobe Developer Console project, not the Commerce Admin, and an admin's access follows their Commerce role.

Four Magento API snags that surface after the first request works

Product updates that create store-view overrides

How you'll know: You changed a price or name through /rest/default/V1/products, and now editing it at default scope in the Admin no longer changes the storefront.

Fix: A call to /rest/default/ saves values at that store view's level. Write global values through /rest/all/V1/, and only use a store code when you really mean that one store view.

A list request with no page size

How you'll know: GET /V1/orders or /V1/products times out, or hands the other system far more than it can take in one go.

Fix: Always send searchCriteria[pageSize] and searchCriteria[currentPage], and filter on updated_at so each run pulls only what changed.

Stock written past Multi-Source Inventory

How you'll know: The API accepts a new quantity but the storefront's salable quantity doesn't move.

Fix: On stores running MSI, write per-source quantities through /V1/inventory/source-items. How salable quantity gets worked out is on the Magento inventory management page.

The Admin action with no endpoint

How you'll know: Staff do it on an Admin screen, perhaps a setting an extension added, and it's nowhere in the REST reference.

Fix: Magento lets a module declare its own REST routes in webapi.xml, pointing at a service class and guarded by its own ACL resource. A small custom module can expose that one action, and the integration calls it like any core endpoint.

Magento API questions, with the edition caveats

What's the difference between the Magento REST and GraphQL APIs?

REST gives each resource its own endpoint, and it's what back-office integrations call: orders out to an ERP, stock and prices in. GraphQL lets one query ask for exactly the fields a storefront page needs, which is why headless and PWA frontends use it. A store with an ERP link and a headless frontend runs both.

Does Magento have webhooks, or does an integration have to poll?

Adobe's webhooks module and Adobe I/O Events are both built for Adobe Commerce, and I/O Events needs 2.4.4 or later. Adobe's webhooks are synchronous: Commerce waits for the outside system's reply, which can change the data or stop the action. Open Source has no built-in equivalent, so changes reach other systems through a Marketplace webhook extension, a custom module that publishes events, or polling on updated_at.

How do I authenticate with the Magento API from another system?

Register an integration under System, Extensions, Integrations, grant it only the resources it needs, activate it, and sign requests with the four OAuth values it issues. Tokens from the admin or customer token service work as well, but they belong to one person and expire. Adobe Commerce as a Cloud Service is the exception, with authentication through Adobe IMS.

Is Magento's SOAP API still supported for new builds?

Adobe still documents SOAP for self-hosted installs, so older integrations written on it keep working. It isn't where new work should begin. REST sits on the same service contracts, adds the async and bulk endpoints, and is what Adobe's newer guides and examples use.

Can the Magento API trigger an admin-only action, like a pricing rule change?

Partly. Cart price rules have REST endpoints under salesRules, for one. A truly Admin-only action, such as a setting an extension shows only on its own configuration screen, needs an endpoint added by a custom module. n-frames writes that module with an ACL resource of its own, so only the integration's credential can call it.

Who builds a Magento API integration to an ERP?

n-frames builds them on Magento's REST and async bulk endpoints: orders posted to the ERP as they're placed, stock and prices written back at the right scope, and anything the ERP rejects sent to a person with the reason. The record-by-record detail is on Magento ERP integration.

Let's talk

Tell us the one thing your team does manually that eats up time. We read every message and reply within a day.