README

Magento 2 REST API for the OpenAI Agentic Commerce Protocol (ACP). Full 7-endpoint feed surface with DB-persisted feeds, paginated product export, and SalesRule → Promotion mapping.

What this module fixes

• DB-persisted feeds — feed IDs survive cache flushes and server restarts (angeo_acp_feed table via Schema Patch)
• Proper pagination — getProducts now iterates the full catalog in batches (v1 silently capped at 100 products)
• PATCH workaround documented — Magento has no native PATCH support; upserts exposed via /upsert POST + nginx rewrite
• Structured validation errors — upsert responses include errors: string[] per field, not a silent false
• Category names resolved — products now return {value: "Tools", taxonomy: "merchant"} instead of {value: "42"}
• ImageUrlBuilder — product images use Magento's proper resized URL builder, not raw file paths
• /invalidate endpoint — bust product cache without a deploy
• Coupon codes in promotion descriptions — auto-appended when rule has a specific coupon
• Multiple benefits per promotion — e.g. 10% off + free shipping in one benefits array
• GET /product_feeds — list all feeds (new endpoint)

Endpoints

PATCH workaround — nginx setup

Magento 2's REST framework does not support HTTP PATCH. OpenAI's ACP crawler sends PATCH /product_feeds/:id/products. Bridge this with an nginx rewrite before the request reaches Magento:

# 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 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]

Installation

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

Configuration

Navigate to Stores → Configuration → Angeo → Product Feed API.

Quick start

# 1. Create a feed
curl -X POST https://yourstore.com/rest/V1/angeo/product_feeds \
  -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 "https://yourstore.com/rest/V1/angeo/product_feeds/feed_a1b2c3/products?page=1&pageSize=100"

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

# 4. Get promotions (sourced from Magento SalesRules)
curl https://yourstore.com/rest/V1/angeo/product_feeds/feed_a1b2c3/promotions

# 5. Invalidate product cache (after catalog changes)
curl -X POST https://yourstore.com/rest/V1/angeo/product_feeds/feed_a1b2c3/products/invalidate \
  -H "Authorization: Bearer <admin_token>"

ACP Product Schema Coverage

Product level

Variant level

ACP Promotion Schema Coverage

Sourced from active Magento SalesRules:

Testing

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

The Angeo AI Suite

License

MIT — see LICENSE