A reference guide for building AI agents: every method, how to authenticate, and the permissions each one needs.
The Magento API is how an app or AI agent works with an Adobe Commerce store: listing and updating products, reading and creating orders, managing customers, building a cart and placing an order, and adjusting stock. Access is granted through a Bearer token, and what it can reach is set by access control resources like Magento_Catalog::products rather than granular scopes, so a token is limited to the resources its integration or admin role was given. It exposes a single namespace and can call out to an external endpoint while a store action runs.
How an app or AI agent connects to Magento determines what it can reach. There is the REST API for making calls, a webhooks module that calls out to an endpoint while an action runs, and a Commerce MCP server that exposes store tools to agents, and each is governed by the token behind it and the resource permissions that token carries.
The REST API answers under /rest/
The webhooks module calls an external HTTPS endpoint synchronously while a store action runs, so the endpoint's response can let the action continue, modify its payload, or block it. Supported hooks are listed with the GET /V1/webhooks/supportedList method, or with bin/magento webhooks:list:all on self-hosted installs. This is a request-and-wait hook, not an asynchronous event stream.
Adobe ships a Commerce MCP server that exposes store capabilities to AI agents through the Model Context Protocol, covering catalog, cart, pricing, inventory, promotions, checkout, order management, and post-purchase flows. It was introduced at Adobe Summit 2026 as the sanctioned way for agents to read and act on Commerce data.
An integration is defined in the Admin, where an operator selects the access control resources it may use, like Magento_Catalog::products or Magento_Sales::sales. Activating it runs an OAuth 1.0a handshake and yields an access token sent as a Bearer credential. The token reaches exactly the resources the integration was granted and does not expire until revoked.
POST /V1/integration/admin/token exchanges an admin username and password for a Bearer token that acts as that admin user, reaching whatever access control resources the user's role grants. It is valid for 4 hours by default.
POST /V1/integration/customer/token exchanges a customer's email and password for a Bearer token that acts as that customer. It reaches the self resources, like the customer's own cart, addresses, and orders, and is valid for 1 hour by default.
OAuth 1.0a is the handshake behind an integration. Adobe Commerce signs requests with a consumer key and secret plus a token and token secret, rather than the OAuth 2.0 bearer-and-scope model. There are no granular per-call OAuth scopes; what a token can do is set by the integration's selected access control resources and, for admin tokens, the user role.
The Magento API is split into areas an agent can act on, like products, categories, orders, customers, carts, inventory, invoices, and shipments. Each area maps to an access control resource, and writes in some areas change the catalog, move stock, or push an order through fulfilment.
List products with searchCriteria, read a product by SKU, create, update, and delete products.
Read the category tree, read a single category, and create or update categories.
List orders with searchCriteria, read an order, and create an order directly.
List customers with searchCriteria, read a customer, create, and update customers.
Create a cart for the signed-in customer, add items to it, and place an order from it.
Read and write per-source stock levels with Multi-Source Inventory, and read a product's salable quantity.
List invoices, read an invoice, and create an invoice against an order.
Read a shipment and create a shipment against an order to mark it shipped.
Read, create, and update CMS pages and CMS blocks.
Filter by method, access, or permission, or search any path. Select a row for version detail, rate limits, the related webhook event, and the source.
| Method | Endpoint | What it does | Access | Permission | Version | |
|---|---|---|---|---|---|---|
ProductsList products with searchCriteria, read a product by SKU, create, update, and delete products.5 | ||||||
| GET | /V1/products | List products, filtered, sorted, and paged with searchCriteria. | read | Magento_Catalog::products | Current | |
Read-only. Returns the same set an admin sees on the product grid, narrowed by searchCriteria filter_groups. Acts onproduct Permission (capability) Magento_Catalog::productsVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| GET | /V1/products/{sku} | Get a single product by SKU. | read | Magento_Catalog::products | Current | |
Read-only. Acts onproduct Permission (capability) Magento_Catalog::productsVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| POST | /V1/products | Create a product. | write | Magento_Catalog::products | Current | |
A core catalog write. The same resource governs both reading and writing products, so a token that can read products can also create them unless the role is narrowed. Acts onproduct Permission (capability) Magento_Catalog::productsVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| PUT | /V1/products/{sku} | Update a product by SKU. | write | Magento_Catalog::products | Current | |
A core catalog write. Acts onproduct Permission (capability) Magento_Catalog::productsVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| DELETE | /V1/products/{sku} | Delete a product by SKU. | write | Magento_Catalog::products | Current | |
Removes the product from the catalog. Acts onproduct Permission (capability) Magento_Catalog::productsVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
CategoriesRead the category tree, read a single category, and create or update categories.4 | ||||||
| GET | /V1/categories | Get the category tree. | read | Magento_Catalog::categories | Current | |
Read-only. Acts oncategory Permission (capability) Magento_Catalog::categoriesVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| GET | /V1/categories/{categoryId} | Get a single category by id. | read | Magento_Catalog::categories | Current | |
Read-only. Acts oncategory Permission (capability) Magento_Catalog::categoriesVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| POST | /V1/categories | Create a category. | write | Magento_Catalog::categories | Current | |
A catalog structure write. Acts oncategory Permission (capability) Magento_Catalog::categoriesVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| PUT | /V1/categories/{id} | Update a category by id. | write | Magento_Catalog::categories | Current | |
A catalog structure write. Moving a category in the tree uses the separate /V1/categories/{id}/move method. Acts oncategory Permission (capability) Magento_Catalog::categoriesVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
OrdersList orders with searchCriteria, read an order, and create an order directly.3 | ||||||
| GET | /V1/orders | List orders, filtered, sorted, and paged with searchCriteria. | read | Magento_Sales::sales | Current | |
Read-only. Orders carry customer and billing data, so this exposes personal information. Acts onorder Permission (capability) Magento_Sales::salesVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| GET | /V1/orders/{id} | Get a single order by id. | read | Magento_Sales::sales | Current | |
Read-only. Returns billing and shipping addresses and customer name. Acts onorder Permission (capability) Magento_Sales::salesVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| POST | /V1/orders | Create an order directly, bypassing the cart and checkout flow. | write | Magento_Sales::create | Current | |
Writes a sales order without going through a quote. Most storefront flows place orders through the cart instead. Acts onorder Permission (capability) Magento_Sales::createVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
CustomersList customers with searchCriteria, read a customer, create, and update customers.4 | ||||||
| GET | /V1/customers/search | Search customers, filtered, sorted, and paged with searchCriteria. | read | Magento_Customer::manage | Current | |
Read-only. Returns customer names and email addresses, so this exposes personal information. Acts oncustomer Permission (capability) Magento_Customer::manageVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| GET | /V1/customers/{customerId} | Get a single customer by id. | read | Magento_Customer::manage | Current | |
Read-only. Returns the customer's email and addresses. Acts oncustomer Permission (capability) Magento_Customer::manageVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| POST | /V1/customers | Create a customer account. | write | Magento_Customer::manage | Current | |
Creating a customer with an admin or integration token uses Magento_Customer::manage. The unauthenticated self-signup path is a separate anonymous resource. Acts oncustomer Permission (capability) Magento_Customer::manageVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| PUT | /V1/customers/{customerId} | Update a customer by id. | write | Magento_Customer::manage | Current | |
A core customer write. Acts oncustomer Permission (capability) Magento_Customer::manageVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
Carts & quotesCreate a cart for the signed-in customer, add items to it, and place an order from it.3 | ||||||
| POST | /V1/carts/mine | Create a cart for the signed-in customer and return its id. | write | self | Current | |
The /mine routes act as the authenticated customer, governed by the self resource on a customer token rather than an admin role. Acts oncart Permission (capability) selfVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| POST | /V1/carts/mine/items | Add an item to the signed-in customer's cart. | write | self | Current | |
Acts on the authenticated customer's own quote. Acts oncart Permission (capability) selfVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| PUT | /V1/carts/mine/order | Place an order from the signed-in customer's cart. | write | self | Current | |
Converts the quote into a real sales order. Acts as the authenticated customer. Acts oncart Permission (capability) selfVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
Inventory & stockRead and write per-source stock levels with Multi-Source Inventory, and read a product's salable quantity.3 | ||||||
| GET | /V1/inventory/get-product-salable-quantity/{sku}/{stockId} | Get the salable quantity of a product for a given stock. | read | Magento_InventoryApi::source | Current | |
Read-only. Part of Multi-Source Inventory, which models stock per physical source. Acts onstock item Permission (capability) Magento_InventoryApi::sourceVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| GET | /V1/inventory/source-items | List per-source stock items, filtered with searchCriteria. | read | Magento_InventoryApi::source | Current | |
Read-only. Acts onsource item Permission (capability) Magento_InventoryApi::sourceVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| POST | /V1/inventory/source-items | Create or update per-source stock items, setting quantity and status. | write | Magento_InventoryApi::source | Current | |
Changes on-hand stock at a source, which feeds the salable quantity shown on the storefront. Acts onsource item Permission (capability) Magento_InventoryApi::sourceVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
InvoicesList invoices, read an invoice, and create an invoice against an order.3 | ||||||
| GET | /V1/invoices | List invoices, filtered, sorted, and paged with searchCriteria. | read | Magento_Sales::sales_invoice | Current | |
Read-only. Acts oninvoice Permission (capability) Magento_Sales::sales_invoiceVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| GET | /V1/invoices/{id} | Get a single invoice by id. | read | Magento_Sales::sales_invoice | Current | |
Read-only. Acts oninvoice Permission (capability) Magento_Sales::sales_invoiceVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| POST | /V1/order/{orderId}/invoice | Create an invoice against an order, capturing payment for the captured items. | write | Magento_Sales::sales_invoice | Current | |
Invoicing can capture real payment depending on the payment method, and moves the order toward complete. Acts oninvoice Permission (capability) Magento_Sales::sales_invoiceVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
ShipmentsRead a shipment and create a shipment against an order to mark it shipped.2 | ||||||
| GET | /V1/shipment/{id} | Get a single shipment by id. | read | Magento_Sales::shipment | Current | |
Read-only. Acts onshipment Permission (capability) Magento_Sales::shipmentVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| POST | /V1/order/{orderId}/ship | Create a shipment against an order to mark it shipped, with optional tracking. | write | Magento_Sales::ship | Current | |
Marks items as shipped and can notify the customer, progressing fulfilment. Acts onshipment Permission (capability) Magento_Sales::shipVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
CMSRead, create, and update CMS pages and CMS blocks.3 | ||||||
| GET | /V1/cmsPage/search | Search CMS pages with searchCriteria. | read | Magento_Cms::page | Current | |
Read-only. Acts oncms page Permission (capability) Magento_Cms::pageVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| POST | /V1/cmsPage | Create a CMS page. | write | Magento_Cms::page | Current | |
Publishes storefront content. Acts oncms page Permission (capability) Magento_Cms::pageVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| POST | /V1/cmsBlock | Create a CMS block. | write | Magento_Cms::block | Current | |
Publishes a reusable storefront content block. Acts oncms block Permission (capability) Magento_Cms::blockVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
Magento webhooks call out to an external endpoint at the moment a store action runs, like a cart being saved or an order being placed, and the endpoint's response can let the action proceed, change its data, or block it. This is a synchronous hook for validating or enriching an action, not a fire-and-forget event feed.
| Event | What it signals | Triggered by |
|---|
A self-hosted Magento install applies no API rate limit by default, so throughput is bounded by the server. Adobe Commerce on cloud adds limits at its web application firewall, and very large reads are bounded by the page size set on each request.
A self-hosted Magento Open Source or Adobe Commerce install applies no API rate limit by default, so request throughput is bounded by the web server, PHP, and database rather than a quota. Adobe Commerce on cloud infrastructure and as a Cloud Service add protection at the web application firewall and platform edge, which can throttle or block bursts. There is no documented per-method point cost, so the per-row rate fields are empty.
List and search endpoints page through searchCriteria, where pageSize sets how many items a page returns and currentPage selects the page. Omitting pageSize returns every matching record, which can be a very large response on a big catalog, so a pageSize should be set on broad queries. Results are filtered with filter_groups (each group ANDed, filters within a group ORed) and ordered with sortOrders.
There is no single fixed page-size ceiling in the core API, so the practical limit is the pageSize chosen and what the server can return without timing out. Bulk and asynchronous endpoints exist for large writes, accepting batched payloads and returning a status to poll rather than processing inline.
The status codes an agent should handle, and what to do about each.
| Status | Code | Meaning | What to do |
|---|---|---|---|
| 400 | Bad Request | The request data is invalid or a required parameter is missing, including when service input validation fails. The body holds a message, sometimes with %1 style placeholders, and a parameters array that fills them. | Read the message and parameters, correct the request body or query, and resend. |
| 401 | Unauthorized | The caller is not authenticated, for example the Bearer token is missing, invalid, or expired. | Obtain a fresh token and send it in the Authorization header. |
| 403 | Forbidden | The token is valid but its role or integration lacks the access control resource the method needs. | Grant the missing resource to the integration or role, then retry. |
| 404 | Not Found | The endpoint or the requested object does not exist. | Check the path, store code, and object identifier. |
| 405 | Method Not Allowed | The resource does not support the HTTP method used. | Use the method the endpoint defines, such as PUT rather than POST for an update. |
| 500 | Internal Server Error | An error on the server, such as a database or network failure. In developer mode the body can include a trace field with stack detail. | Retry with backoff, and inspect the trace or server logs if it persists. |
Magento exposes a single REST namespace, V1, and ships dated quarterly releases of Adobe Commerce and Magento Open Source that add and deprecate methods over time. A breaking change lands in a new product release rather than a new API version segment.
Magento exposes one REST namespace, V1, on the store's own host, so there is no dated version segment to pin. Methods evolve through dated quarterly product releases rather than a new API version string. The entries below are notable dated releases that changed or extended the API.
Adobe introduced the Commerce MCP server, exposing catalog, cart, pricing, inventory, promotions, checkout, order management, and post-purchase capabilities to AI agents over the Model Context Protocol, and committed to emerging agentic commerce standards.
Multi-Source Inventory introduced per-source stock items and salable-quantity methods under /V1/inventory, letting stock be tracked across multiple physical sources rather than a single global quantity.
Pin to a Magento release and move up on the quarterly upgrade cycle.
Adobe Commerce release notes ↗Bollard AI sits between a team's AI agents and Magento. Grant each agent exactly the access it needs, read or write, resource by resource, and every call is checked and logged.