Shopify Agenium App

Turn any Shopify store into an agent:// endpoint via the Agenium protocol (A2A).

Features

Core Shopify APIs

• Products — CRUD products, variants, collections, metafields
• Orders — list, create drafts, fulfill, cancel, refund
• Customers — search, profiles, purchase history, segments
• Cart/Checkout — Storefront API cart management, checkout links
• Discounts — create/manage discount codes and automatic discounts
• Inventory — stock levels, adjustments across locations
• Analytics — sales summaries, top products, order stats
• Webhooks — real-time events → agent notifications

Third-Party Integrations (auto-detected)

• Klaviyo — email/SMS campaigns, flows, segments
• Judge.me / Loox — product reviews management
• ReCharge — subscription management
• ShipStation / Shippo — shipping labels, tracking, rates

Quick Start

# Install
npm install

# Configure
cp .env.example .env
# Edit .env with your Shopify app credentials and Agenium API key

# Development
npm run dev

# Production
npm run build && npm start

Setup

1. Create a Shopify App

1. Go to Shopify Partners
2. Create a new app
3. Set the redirect URL to https://your-domain.com/auth/callback
4. Copy API key and secret to .env

2. Install on a Store

Visit: https://your-domain.com/auth?shop=your-store.myshopify.com

3. Agent Registration

The app auto-registers with Agenium DNS on startup when AGENT_DOMAIN and AGENIUM_API_KEY are set.

Agent Protocol (A2A)

Agent Card

GET /.well-known/agent.json

Send Task

POST /tasks/send
{
  "id": "optional-task-id",
  "message": {
    "role": "user",
    "parts": [
      { "type": "text", "text": "List all products" }
    ]
  }
}

Structured Actions

{
  "message": {
    "role": "user",
    "parts": [
      {
        "type": "data",
        "data": {
          "action": "products.create",
          "input": { "title": "New Widget", "productType": "Gadget" }
        }
      }
    ]
  }
}

Available Actions

| Domain | Actions | |--------|---------| | products | .list .get .create .update .delete .collections | | orders | .list .get .draft.create .fulfill .cancel .refund | | customers | .list .get .create .update .top_spenders | | cart | .create .get .add .update .remove .browse | | discounts | .list .create_code .create_automatic .delete | | inventory | .locations .levels .adjust .check_sku | | analytics | .sales_summary .top_products .order_stats .reports | | metafields | .get .set | | klaviyo | .lists .segments .campaigns .create_campaign .track_event .add_to_list .flows | | reviews | .list .summary .reply | | subscriptions | .list .get .cancel .skip .customers | | shipping | .rates .create_label .track .orders |

Environment Variables

| Variable | Required | Description | |----------|----------|-------------| | SHOPIFY_API_KEY | Yes | Shopify app API key | | SHOPIFY_API_SECRET | Yes | Shopify app secret | | SHOPIFY_SCOPES | Yes | OAuth scopes | | SHOPIFY_HOST | Yes | App public URL | | AGENIUM_API_KEY | Yes | Agenium DNS API key | | AGENT_DOMAIN | Yes | Agent domain (e.g., mystore.shop.agenium.net) | | STOREFRONT_ACCESS_TOKEN | No | For cart/checkout features | | KLAVIYO_API_KEY | No | Klaviyo integration | | RECHARGE_API_TOKEN | No | ReCharge integration | | SHIPSTATION_API_KEY | No | ShipStation integration | | SHIPPO_API_TOKEN | No | Shippo integration |

License

MIT

Bug Reporting

This project includes optional bug reporting to the Agenium monitoring server.

Configuration

Set the following environment variables to enable bug reporting:

BUG_REPORT_URL=http://130.185.123.153:3100
BUG_REPORT_TOKEN=your_token_here

Bug reporting is disabled by default — it only activates when BUG_REPORT_TOKEN is set. Reports are sent asynchronously (fire and forget) and never block the main application.