OpenAI Agentic Commerce Protocol (ACP) API for Magento 2

Magento 2 REST implementation of the OpenAI Agentic Commerce Protocol (ACP) feed API: Feeds, Products and Promotions resources, so ChatGPT can retrieve and update your catalog data through API-based delivery instead of (or alongside) daily file uploads.

All endpoints are bearer-token authenticated per the ACP specification. Feeds are persisted in the database (they survive cache flushes and restarts), product export is fully paginated with configurable-product variants, and promotions are sourced from Magento Cart Price Rules including coupon codes and free shipping.

Works together with angeo/module-openai-product-feed (CSV file-upload feed): per OpenAI's guidance, provide the full feed daily via file upload and send incremental updates through this API.

Requirements

• PHP >= 8.3
• Magento 2.4.x (Open Source or Adobe Commerce)
• angeo/module-openai-product-feed ^2.0

Installation

composer require angeo/module-openai-product-feed-api
bin/magento setup:upgrade
bin/magento cache:flush

Authentication (required)

Every endpoint requires a bearer token carrying the Angeo_OpenAiProductFeedApi::manage_feeds ACL resource, matching the ACP requirement that requests include Authorization: Bearer <api_key>.

1. In the Magento admin, go to System → Extensions → Integrations → Add New Integration.
2. On the API tab, select the resource Angeo — Manage Product Feed API (under Marketing).
3. Save, then Activate the integration and copy the Access Token.
4. Provide that token to OpenAI as the feed API key; use it in the Authorization: Bearer header for your own calls as well.

Requests without a valid token receive 401 Unauthorized.

Endpoints

Invalid target_country returns 400 Bad Request; unknown feed or store IDs return 404 Not Found, per the ACP error model.

PATCH bridge — web server setup

Magento 2's REST framework does not support HTTP PATCH. The ACP spec defines upserts as PATCH /product_feeds/:id/products. Bridge this with a rewrite before the request reaches Magento:

# nginx — add inside your server {} block
location ~ ^/rest/V1/angeo/product_feeds/[^/]+/products$ {
    if ($request_method = PATCH) {
        rewrite ^(.*)$ $1/upsert last;
    }
}

location ~ ^/rest/V1/angeo/product_feeds/[^/]+/promotions$ {
    if ($request_method = PATCH) {
        rewrite ^(.*)$ $1/upsert last;
    }
}

# Apache — .htaccess in the Magento root
RewriteCond %{REQUEST_METHOD} ^PATCH$
RewriteRule ^rest/V1/angeo/product_feeds/([^/]+)/products$ rest/V1/angeo/product_feeds/$1/products/upsert [L]
RewriteCond %{REQUEST_METHOD} ^PATCH$
RewriteRule ^rest/V1/angeo/product_feeds/([^/]+)/promotions$ rest/V1/angeo/product_feeds/$1/promotions/upsert [L]

Quick start

TOKEN="<integration access token>"

# 1. Create a feed
curl -X POST https://yourstore.com/rest/V1/angeo/product_feeds \
  -H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" \
  -d '{"targetCountry":"US","storeId":1}'
# → {"id":"feed_a1b2c3d4e5f6","target_country":"US","store_id":1,"updated_at":"...","created_at":"..."}

# 2. Get products (page 1, 100 per page)
curl -H "Authorization: Bearer $TOKEN" \
  "https://yourstore.com/rest/V1/angeo/product_feeds/feed_a1b2c3/products?page=1&pageSize=100"

# 3. Upsert products (POST to /upsert; OpenAI's PATCH is rewritten by nginx)
curl -X POST https://yourstore.com/rest/V1/angeo/product_feeds/feed_a1b2c3/products/upsert \
  -H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" \
  -d '{"feedId":"feed_a1b2c3","products":[{"id":"42","variants":[{"id":"43","title":"Black / M"}]}]}'
# → {"id":"feed_a1b2c3","accepted":true,"upserted_count":1,"errors":[]}

# 4. Get promotions (sourced from Magento Cart Price Rules)
curl -H "Authorization: Bearer $TOKEN" \
  https://yourstore.com/rest/V1/angeo/product_feeds/feed_a1b2c3/promotions

# 5. Reset the product cache after catalog changes
curl -X POST -H "Authorization: Bearer $TOKEN" \
  https://yourstore.com/rest/V1/angeo/product_feeds/feed_a1b2c3/products/invalidate

How caching works

• Catalog snapshot — built from the Magento catalog on the first GET, persisted until invalidated. Store-scoped feeds are built under frontend store emulation, so URLs, currency and locale match the store view.
• Upsert overlay — products received via PATCH/upsert are stored separately and merged over the snapshot at read time (overlay wins). Catalog rebuilds never discard upserted products.
• Page slices — formatted responses are cached for 30 minutes with their own tag; any upsert invalidates them immediately.
• /invalidate — full reset for the feed: snapshot, overlay and pages.

Configuration

Stores → Configuration → Angeo → Product Feed API

ACP Product schema coverage

ACP Promotion schema coverage

Sourced from active Magento Cart Price Rules (SalesRules):

Testing

vendor/bin/phpunit -c app/code/Angeo/OpenAiProductFeedApi/phpunit.xml

The PromotionMapper suite (14 tests) covers benefit mapping, free-shipping detection, coupon-code resolution and status transitions.

The Angeo agentic commerce suite

Need help with agentic commerce for Magento? Professional support, AEO audits and implementation at angeo.dev. Check how your store looks to AI agents with the free scanner at api.angeo.dev.

Questions? Contact me at [email protected]

License

MIT — see LICENSE

Changelog

All notable changes to this module are documented in this file.

[2.0.0] - 2026-07-05

Security

• All REST routes now require bearer-token authentication via the
  Angeo_OpenAiProductFeedApi::manage_feeds ACL resource. Previous releases
  exposed every endpoint anonymously, which allowed anyone to dump the full
  catalog with prices and stock, create unlimited feed records in the
  database, poison the feed payload served to OpenAI through unauthenticated
  upserts, and flush the feed caches. This also aligns the module with the
  ACP API specification, which requires Authorization: Bearer <api_key> on
  every request. See the README for the Magento Integration setup that
  produces the token to hand to OpenAI.
• target_country input is validated as ISO 3166-1 alpha-2 (returns
  400 Bad Request on invalid input instead of failing at the database
  layer), and storeId is validated against existing stores (returns
  404 Not Found for unknown stores).

Breaking changes

• Authentication is now required on every endpoint (see Security). Update any
  callers to send a bearer token.
• Requires angeo/module-openai-product-feed ^2.0 and PHP >= 8.3.
• Cache key layout changed (v3 prefix, split snapshot / upsert overlay /
  page slices). Caches are rebuilt automatically on first request.

Fixed

• Free-shipping promotions were never detected. Free shipping lives in the
  simple_free_shipping rule field, not simple_action; the mapper now reads
  getSimpleFreeShipping() against the RuleInterface::FREE_SHIPPING_*
  constants (legacy integer values tolerated). The previous fallback on
  apply_to_shipping was also removed — that flag means "apply the discount
  to shipping cost", not "free shipping".
• Coupon codes were never appended to promotion descriptions. The rule
  repository data model returns coupon_type as the string constant
  SPECIFIC_COUPON (the old == 2 check could never match) and does not
  expose getPrimaryCoupon(). Codes are now resolved through
  CouponRepositoryInterface.
• Stale reads after upsert. PATCH-upserted products are now stored in a
  dedicated overlay cache and served page slices carry their own cache tag,
  so an upsert invalidates the pages immediately without discarding the
  catalog snapshot.
• Catalog rebuilds no longer discard PATCH-upserted products. The upsert
  overlay is merged over the catalog snapshot at read time and survives
  snapshot rebuilds; /invalidate performs the full reset (snapshot +
  overlay + pages).
• Product builds for store-scoped feeds now run under frontend store
  emulation, so product URLs, currency and locale match the feed's store view
  instead of the REST default scope.
• updated_at touch now writes UTC, consistent with the database defaults.
• Unit tests are now runnable: the previous suite mocked
  getCurrentCurrencyCode() on StoreInterface, where the method does not
  exist, and stubbed getSimpleAction() twice in the same mock. The
  PromotionMapper suite (14 tests) passes against the rewritten mapper.

Changed

• /invalidate now performs a scoped reset for the requested feed (snapshot
  and overlay keys) plus the shared page-slice tag, instead of flushing every
  feed's payload cache.

[1.0.0]

• Initial release: ACP feed/products/promotions REST surface, DB-persisted
  feeds, paginated product export, SalesRule → Promotion mapping,
  PATCH-as-POST bridge.