# Ap2 Merchant Agent

> Build an AP2 Merchant Agent — the seller-side agent that receives intent mandates, searches product catalogs, creates signed cart mandates, and represents the merchant in agentic transactions. Use when implementing the Merchant Endpoint role.

- **Type:** Skill
- **Install:** `agentstack add skill-orcaqubits-agentic-commerce-skills-plugins-ap2-merchant-agent`
- **Verified:** Yes — security-reviewed for prompt injection and unsafe behavior
- **Seller:** [OrcaQubits](https://agentstack.voostack.com/s/orcaqubits)
- **Installs:** 0
- **Category:** [Finance & Payments](https://agentstack.voostack.com/c/finance-and-payments)
- **Latest version:** 0.1.0
- **License:** MIT
- **Upstream author:** [OrcaQubits](https://github.com/OrcaQubits)
- **Source:** https://github.com/OrcaQubits/agentic-commerce-skills-plugins/tree/main/ap2-agentic-payments/skills/ap2-merchant-agent

## Install

```sh
agentstack add skill-orcaqubits-agentic-commerce-skills-plugins-ap2-merchant-agent
```

Requires the [AgentStack CLI](https://agentstack.voostack.com/docs/cli). Works with Claude Code, Cursor, and any MCP-compatible agent.

## About

# AP2 Merchant Agent Implementation

## Before writing code

**Fetch live docs**:
1. Fetch `https://ap2-protocol.org/specification/` for Merchant Endpoint responsibilities
2. Web-search `site:github.com google-agentic-commerce AP2 samples roles merchant_agent` for reference implementation
3. Web-search `site:github.com google-agentic-commerce AP2 merchant cart mandate` for Cart Mandate creation
4. Fetch SDK docs for merchant-side agent patterns

## Conceptual Architecture

### What the Merchant Agent Does

The Merchant Agent (ME) **represents the seller** in AP2 transactions:

1. **Receives Intent Mandates** from Shopping Agents
2. **Searches product catalog** for matching items
3. **Creates Cart Mandates** with specific product offers, prices, and totals
4. **Signs Cart Mandates** with the merchant entity's signature
5. **Handles clarification requests** when intent is ambiguous
6. **Supports the payment flow** by forwarding to Payment Processor

### Agent Card

The Merchant Agent's Agent Card advertises:
- AP2 extension support with supported payment methods
- Skills related to product search, cart creation, order management
- Product categories and capabilities
- Authentication requirements for Shopping Agents

### Key Responsibilities

#### Intent Processing
- Parse incoming Intent Mandates from Shopping Agents
- Match intent against product catalog
- Determine if the intent can be fulfilled within constraints
- Decide whether to proceed, request clarification, or reject

#### Cart Mandate Creation
- Select matching products from catalog
- Calculate prices, taxes, shipping, and totals
- Build the Cart Mandate with W3C Payment Request API structure
- Include all line items with individual pricing
- Sign the Cart Mandate with the merchant entity's key

#### Merchant Signature
The merchant signature is critical:
- It's an **entity-level** signature (the merchant organization, not the AI agent)
- It guarantees product availability at the stated prices
- It commits the merchant to fulfillment
- Key management must be handled at the organization level

#### Escalation Decisions
When facing ambiguous intent, the merchant can:
- **Offer choices** — Present multiple matching products for user selection
- **Ask clarifications** — Request more specific requirements
- **Force human-present** — Require the user to confirm directly
- **Reject** — Decline the intent if it can't be fulfilled

### Catalog Integration

The Merchant Agent needs access to:
- **Product catalog** — Names, descriptions, SKUs, images
- **Inventory** — Real-time stock availability
- **Pricing** — Current prices, discounts, taxes
- **Shipping** — Available shipping methods, costs, timeframes
- **Policies** — Return policy, refund period, terms

### Payment Method Advertisement

Cart Mandates include supported payment methods:
```json
"method_data": [
  {
    "supportedMethods": "https://processor.example.com/pay",
    "data": { "merchant_id": "..." }
  }
]
```

### Multi-Merchant Scenarios

A Shopping Agent may contact multiple merchants:
- Each merchant independently evaluates the Intent Mandate
- Each returns their own Cart Mandate
- The Shopping Agent compares offers on behalf of the user
- The merchant should respond quickly to be competitive

### Best Practices

- Sign Cart Mandates at the entity level, not the agent level
- Include all items with clear descriptions and prices
- Respond to Intent Mandates promptly — the Shopping Agent may be comparing merchants
- Handle out-of-stock gracefully with alternatives or clear messaging
- Implement proper key management for merchant signing keys
- Validate incoming Intent Mandates for authenticity
- Keep catalog data fresh — stale prices cause disputes
- Log all Cart Mandate creation for audit trail

Fetch the specification for exact Merchant Agent requirements, Cart Mandate creation process, and signing formats before implementing.

## Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

- **Author:** [OrcaQubits](https://github.com/OrcaQubits)
- **Source:** [OrcaQubits/agentic-commerce-skills-plugins](https://github.com/OrcaQubits/agentic-commerce-skills-plugins)
- **License:** MIT

Install and usage instructions live in the source repository linked above.

## Pricing

- **Free** — Free

## Security capabilities

Automated source analysis of v0.1.0 — what this tool can access:

- **Network access:** no
- **Filesystem access:** no
- **Shell / process execution:** no
- **Environment & secrets:** no
- **Dynamic code execution:** no

*"Yes" means the capability is present in the source — more access means more to trust, not that it is unsafe.*


## Versions

- **0.1.0** — security scan: passed — Imported from the upstream source.

## Links

- Listing page: https://agentstack.voostack.com/l/skill-orcaqubits-agentic-commerce-skills-plugins-ap2-merchant-agent
- Seller: https://agentstack.voostack.com/s/orcaqubits
- Browse the marketplace: https://agentstack.voostack.com/browse

---
Listed on AgentStack — the marketplace for AI agent skills and MCP servers. Every listing is security-reviewed. Creators keep 70%.