> For the complete documentation index, see [llms.txt](https://docs.robotmoney.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.robotmoney.com/govern/purchase-decisions-api.md).

# Purchase Decisions

Record policy-gated purchase decisions and administer purchase budgets.

Purchase decisions let an authenticated agent ask whether a merchant purchase is allowed without changing the existing payment execution path. An approved decision selects a rail and creates or draws down a bounded budget grant. It does not issue a card or settle a payment.

## Record A Purchase Decision

```http
POST /v1/decisions
Authorization: Bearer <agent token>
Idempotency-Key: purchase-demo-001
Content-Type: application/json
```

The agent token needs `payment_intent:propose`.

```json
{
  "type": "purchase",
  "merchant_name": "Example Merchant LLC",
  "merchant_country": "US",
  "merchant_category": "software",
  "description": "Monthly API usage",
  "amount": "25.00",
  "currency": "USD",
  "rail_hint": "x402",
  "session_id": "session-2026-10"
}
```

`merchant_country` and `session_id` are optional. A session id labels the original grant, but it is not a security boundary. Grant lookup is always bound to the authenticated agent, normalized merchant, and currency, so rotating a caller-selected session id cannot create another budget.

The response is terminal: `approved` or `blocked`.

```json
{
  "id": "purchase_...",
  "type": "purchase",
  "decision": "approved",
  "reason_code": "approved",
  "merchant_name": "Example Merchant LLC",
  "merchant_category": "software",
  "description": "Monthly API usage",
  "amount": "25.00",
  "currency": "USD",
  "rail": "x402",
  "budget_grant_id": "grant_...",
  "budget_scope": "session",
  "budget_remaining": "75.00",
  "billed_decision": true,
  "billed_decision_id": "purchase_...",
  "vendor_risk": {
    "merchant_sanctions": "pass",
    "merchant_category": "pass",
    "merchant_allowlist": "pass",
    "per_purchase_cap": "pass"
  },
  "card": null,
  "created_at": "2026-10-25T10:00:00.000Z"
}
```

An `x402` hint selects x402 for per-call API purchases. A `card` hint selects the issuer-neutral `virtual_card` rail. The card adapter is a non-issuing stub until an issuer is selected.

## Policy And Budget Grants

Vendor Risk checks agent lifecycle state, merchant sanctions, merchant category, merchant allowlist, the per-purchase cap, and the aggregate per-agent UTC daily spend cap. A halted, quarantined, or revoked agent cannot purchase.

The first approved request creates a grant with the rule's `budget_amount` and `grant_ttl_seconds`. Later approved requests for the same agent, merchant, and currency draw down the active grant. Deactivating the applicable rule blocks new purchases and drawdowns, even when a grant has budget remaining.

The per-agent daily cap aggregates approved spend across merchants, sessions, and replacement grants in the same currency. A new session id does not reset the cap or create an independent grant.

## Opt-In Grant Replacement

Grant replacement is disabled by default. When an active rule sets `allow_grant_replacement` to `true`, a purchase that exceeds an exhausted, unexpired grant may atomically revoke and replace it. The replacement stays bound to the same agent, normalized merchant, currency, and original scope. The daily per-agent cap is checked before replacement, and concurrent drawdown or replacement requests are serialized.

A replacement creates one new billed decision and emits a purchase audit and Activity event. It does not reopen the session-id rotation path.

## Billing Semantics

* The first approved grant decision is billed once.
* Approved drawdowns reuse the original `billed_decision_id` and do not add a billing decision.
* An approved grant replacement is one new billed decision.
* Every persisted blocked purchase decision is billed, including an exhausted grant drawdown.
* Requests rejected before persistence are not billed.
* Replaying an idempotency key returns the original result and does not bill twice.

`GET /v1/usage/authorizations` is the public usage view for both recorded authorization decisions and purchase billing records.

## Purchase Policy Rule CRUD

Purchase policy rules are tenant scoped and unique by currency.

| Method  | Path                                   | Purpose                        |
| ------- | -------------------------------------- | ------------------------------ |
| `GET`   | `/v1/purchase-policy-rules`            | List active and inactive rules |
| `POST`  | `/v1/purchase-policy-rules`            | Create a currency rule         |
| `GET`   | `/v1/purchase-policy-rules/{currency}` | Read one currency rule         |
| `PATCH` | `/v1/purchase-policy-rules/{currency}` | Update or deactivate a rule    |

Every route requires `execution:admin` and an active tenant admin member. POST and PATCH also require `Idempotency-Key`. PATCH requires the current `expected_updated_at` value for optimistic concurrency.

```json
{
  "currency": "USD",
  "allowed_merchant_categories": ["software", "cloud services"],
  "merchant_allowlist": ["Example Merchant LLC"],
  "per_purchase_cap": "50.00",
  "per_agent_daily_spend_cap": "250.00",
  "budget_amount": "100.00",
  "grant_ttl_seconds": 3600,
  "allow_grant_replacement": false,
  "active": true
}
```

The budget and daily cap must each cover the per-purchase cap. Currency uses an uppercase three or four character code. Grant lifetime is 60 to 604800 seconds. Merchant categories and names are normalized before storage. PATCH with `active: false` deactivates a rule without deleting it.

## Merchant Screening

Hosted merchant screening is fail closed. `clear` is the only allowing outcome. `matched`, `inconclusive`, `unavailable`, and `malformed` each block with a distinct reason code. The match request has a 2,000 ms deadline.

The sanctions dataset version is fetched separately and cached in process. A clear match requires a valid cached version. Audit evidence retains only bounded screening metadata, including the provider, dataset version, query hash, candidate ids, score, threshold, outcome, and timing. Raw provider payloads are never retained.

Merchant screening is controlled by a feature flag that defaults off. It is on in staging and remains off in production until after the pilots. When screening is enabled but unavailable for an unresolved merchant, the decision blocks.

## Related APIs

* [Usage API](https://docs.robotmoney.com/govern/usage-api.md)
* [Authorizations API](https://docs.robotmoney.com/govern/authorizations-api.md)
* [Policy API](https://docs.robotmoney.com/api-reference/policy-api.md)
