The Agentic Mercantile Protocol Spec — the unified shape every connector normalizes responses into.

AMPS is the protocol the gateway speaks. Every connector reshapes its native platform response into AMPS before returning it. Agents always see the same shape regardless of underlying platform.

The typed AMPS definitions ship with the gateway and the client SDKs.

Core types

Product

type AmpsProduct = {
  product_id: string;       // connector-prefixed unique id
  site_id: string;          // gateway's UUID for the site
  title: string;
  description?: string;
  price: number;            // in minor units of `currency`
  currency: string;         // ISO 4217
  in_stock: boolean;
  image_urls: string[];
  variants?: AmpsVariant[];
  source_platform: 'shopify' | 'woocommerce' | 'rest_generic' | string;
};

Cart

type AmpsCart = {
  cart_id: string;
  site_id: string;
  line_items: AmpsLineItem[];
  subtotal: number;
  shipping?: number;
  taxes?: number;
  total: number;
  currency: string;
  state: 'open' | 'awaiting_signature' | 'completed' | 'expired';
};

Order

type AmpsOrder = {
  order_id: string;
  site_id: string;
  buyer_email?: string;
  line_items: AmpsLineItem[];
  total: number;
  currency: string;
  status: 'placed' | 'fulfilled' | 'cancelled' | 'refunded';
  placed_at: string;        // ISO 8601
  agent_id: string;
  delegation_token_id?: string;
};

A product may carry an optional addons array — customer-selectable options (size, engraving, gift wrap, …) that are additive to native variants, not a replacement. On WooCommerce these are sourced from ACF fields.

type AmpsProductAddon = {
  addon_id: string;
  label: string;
  type: 'select' | 'radio' | 'checkbox' | 'boolean' | 'text' | 'number';
  required: boolean;
  multiple: boolean;
  options?: { value: string; label: string; price_modifier?: MonetaryAmount }[];
  min?: number;
  max?: number;
  help?: string;
};

When adding to cart, add_to_cart accepts an optional addons map of addon_id → value | value[] | boolean | number (single value for select/radio/boolean, array for checkbox, raw for text/number). The client never sends a price — the connector resolves each modifier from trusted sources and folds it into the cart line's price. Choice values must come from the add-on's options[].value. Invalid selections return 422 (ADDON_REQUIRED, ADDON_INVALID_OPTION, ADDON_OUT_OF_RANGE, ADDON_UNKNOWN).

Why a custom protocol

Three reasons we don't just proxy Shopify/Woo natively:

Agent training data is uniform. A model that learns the AMPS shape doesn't need per-platform retraining.
Audit consistency. Every cart change is recorded with the same field names, regardless of source.
Platform additions are isolated. Adding a new platform = a new connector that reshapes to AMPS. Agents continue working unchanged.

Discoverability

Each site's connector publishes a capability manifest. The gateway exposes the merged view at:

GET /v1/sites/:site_id/manifest

Example:

{
  "site_id": "...",
  "platform": "shopify",
  "capabilities": [
    "read_products",
    "manage_cart",
    "execute_checkout",
    "apply_coupon"
  ],
  "shipping_zones": ["US", "CA"],
  "currencies": ["USD", "CAD"]
}

Agents query this before suggesting an action — apply_coupon isn't offered if the connector doesn't support it.

AMPS Protocol