# Breadcrumb: agentpromocode > ACDP protocol
Index: https://agentpromocode.com/llms.txt
Related: https://agentpromocode.com/quickstart.md, https://agentpromocode.com/acdp-alternatives.md, https://agentpromocode.com/acdp-vs-affiliate-networks.md, https://agentpromocode.com/slo.md
---
# Agent Commerce Discount Protocol (ACDP) — v0.1.2

> Mirror notice: canonical public repo is [`github.com/agentpromocode/acdp`](https://github.com/agentpromocode/acdp). This monorepo copy is kept in sync for implementation work.

ACDP is an open, agent-native wire contract for:

1. **Resolve** — given a merchant domain + basket, return ranked promotional offers and an `attribution_token`.
2. **Feedback** — after checkout, the agent MUST report whether the offer worked.

This repository hosts the normative spec. **agentpromocode.com** ships the reference HTTP implementation (`/v1/*`).

## Normative endpoints (HTTP binding)

| Method | Path | Purpose |
|--------|------|-----------|
| POST | `/v1/resolve` | Rank offers and return an attribution token |
| POST | `/v1/feedback` | Close the loop with checkout outcome |
| POST | `/v1/feedback/batch` | Report up to 20 outcomes in one request |
| GET | `/v1/coverage` | Paginated list of covered domains + offer counts |
| POST | `/v1/postback` | Attribution (optional in V1) |
| GET | `/v1/me` | Contract health |

## No coverage

When a merchant is not indexed, resolve MUST return HTTP 200 with:

| Field | Value |
|-------|-------|
| `merchant_found` | `false` |
| `coverage` | `"none"` |
| `coverage_message` | Human-readable explanation |
| `suggest_domain_report` | `true` |
| `offers` | `[]` |

On internal timeout, implementations MAY return `coverage: "unknown"` instead.

## Resolve offer fields

Each offer in a resolve response SHOULD include:

| Field | Type | Meaning |
|-------|------|---------|
| `success_rate` | number | Historical checkout success ratio (0–1) |
| `sample_size` | integer | Feedback attempts in the last 30 days |
| `last_verified_at` | string \| null | ISO-8601 timestamp of last validating feedback |
| `confidence` | enum | `verified` \| `likely` \| `unverified` |
| `confidence_reason` | string | Human-readable explanation of the label |
| `estimated_savings` | number \| null | Basket-adjusted savings if the code applies |
| `success_probability` | number | Same as `success_rate` (explicit for EV math) |
| `expected_value` | number \| null | `estimated_savings * success_probability` |

Resolve requests MAY include `min_expected_value` (number) to filter out offers below an agent-defined EV threshold.

`basket.items` is deprecated — implementations SHOULD strip line-item payloads and MUST NOT use them in ranking.

## Feedback outcomes

| Outcome | Meaning |
|---------|---------|
| `worked` | Code applied successfully |
| `expired` | Code no longer valid |
| `ineligible` | Basket or SKU ineligible |
| `error` | Checkout or application error |
| `unknown` | Agent could not observe the result (counts as 0.5 credit toward feedback ratio) |

`code` and `basket_value` are optional when the agent lacks partial checkout data.

## Contract suspension (keyed access)

Reference implementation policy:

- Evaluate only when `resolve_count_30d >= 20`.
- Weight `unknown` outcomes at **0.5 credit** toward the feedback ratio.
- Suspend after **14 consecutive** daily evaluations below ratio **0.40**.
- Emit `X-Contract-Warning` on resolve when streak reaches **7** days (before suspension).
- `/v1/me` exposes `suspension_reason` and `next_evaluation_at`.

Anonymous demo tier is exempt from suspension.

## Confidence labels

Implementations SHOULD expose confidence/verification state on returned offers:

- `verified` — `verification_status` is `verified` and `last_verified_at` is within the last 30 days.
- `likely` — `success_rate >= 0.7` and `sample_size >= 10` (30-day feedback window).
- `unverified` — all other public candidates.

Implementations MUST NOT imply unverified offers are guaranteed.

## Versioning

- **v0.1** — initial public draft (2026-05-02).
- **v0.1.1** — enriched offer payload (`sample_size`, `last_verified_at`, `expected_value`, `confidence_reason`); backward compatible.
- **v0.1.2** — first-class no coverage, batch feedback, `unknown` outcome, fairer suspend policy, deprecated `basket.items`.

## License

Spec text: CC-BY-4.0. Code examples: MIT.

## Service level objectives

Published targets for the reference implementation: [https://agentpromocode.com/slo.md](https://agentpromocode.com/slo.md) (p95 resolve <500ms, 99.9% uptime).