canonical: https://jentic.com/apis/riskified.com/riskified

# Riskified E-Commerce API

Jentic publishes the only available OpenAPI specification for the Riskified E-Commerce API, keeping it validated and agent-ready. The Riskified E-Commerce API screens online orders for fraud and returns an approve or decline decision, either synchronously through the decide call or asynchronously after an order is submitted for review. Merchants keep Riskified in step with the order lifecycle by reporting updates, cancellations, refunds, fulfillments, chargebacks, and their own final decisions. A separate group of Account Action calls reports customer logins, account creation, password resets, verification, wishlist changes, and contact events so account takeover and policy abuse can be scored alongside orders.

## For AI agents

Submit e-commerce orders to Riskified for fraud screening, get approve or decline decisions, and report refunds, fulfillments, chargebacks, and customer account events.

## Scope

Does not process payments, issue refunds to customers, or manage store inventory. Use for fraud screening and reporting order and account events to Riskified only.

## Capabilities

- Screen an order for fraud and get an immediate decision with the synchronous decide call
- Submit an order for asynchronous fraud review and receive the decision afterwards
- Report order updates, cancellations, refunds, and fulfillments so Riskified tracks the order lifecycle
- Notify Riskified of a chargeback and report your own final decision on an order
- Report checkout creation and checkout denials, and ask Riskified to advise on authentication
- Send customer login, account creation, password reset, and verification events for account-level scoring
- Upload historical orders to train fraud models on your past order outcomes

## Use cases

### AI order-review agent with live fraud decisions

An AI agent handling order operations needs a fraud decision before it releases an order to the warehouse. Through Jentic the agent searches for 'screen an order for fraud', loads the Riskified decide operation with its input schema, and posts the order with the HMAC signature and shop-domain header handled at call time. It reads the approve or decline decision from the response and routes the order to fulfillment or manual review.

Example prompt: POST the new order payload to `/api/decide`, read the returned decision, and hold the order for manual review if it is declined

### Keeping fraud review in sync with the order lifecycle

A store that uses asynchronous review creates the order with Riskified, submits it for analysis, and then reports what happens next. Updates, cancellations, partial or full refunds, and fulfillments each have their own call, so Riskified's view of the order matches the store's.

Example prompt: Call POST `/api/create` for a new order, then POST `/api/submit` to send it for review, and POST `/api/fulfill` once the shipment leaves the warehouse

### Chargeback reporting

When a payment processor raises a dispute, the merchant notifies Riskified through the chargeback call so the dispute is tied to the original reviewed order. Reporting the merchant's own decision on an order through the decision call closes the loop for orders that were overridden. Together these record the final outcome of each reviewed order.

Example prompt: When a dispute notice arrives, POST the order id and dispute details to `/api/chargeback`

### Account takeover and policy abuse signals

Fraud is not only at checkout. The Account Action calls let a store report customer logins, new accounts, account updates, password resets, verification attempts, logouts, loyalty redemptions, and wishlist changes. Feeding these events gives Riskified the account history it needs to flag a login or redemption that does not fit the customer's pattern.

Example prompt: POST each successful and failed login to `/customers/login` and each password reset to `/customers/reset_password`

## Key endpoints

| Method | Path | Description |
| --- | --- | --- |
| POST | `/api/decide` | Synchronous fraud decision |
| POST | `/api/create` | Create order |
| POST | `/api/submit` | Submit order for review |
| POST | `/api/refund` | Refund order |
| POST | `/api/fulfill` | Fulfill order |
| POST | `/api/chargeback` | Report chargeback |
| POST | `/customers/login` | Report customer login |

## Key resources

- **Orders** — Orders created, submitted, updated, cancelled, refunded, fulfilled, and decided on through the /api/ order actions
- **Checkouts** — Checkout creation and denial events plus the advise call for authentication guidance
- **Customer account events** — Login, logout, account creation and update, password reset, verification, redeem, wishlist, and contact events under /customers/

## AI readiness

This API is usable in Jentic One now. Its AI-readiness score against Jentic's framework shows where it stands today and where improvements would make it even easier for agents to use.

- **Score:** 61 / 100
- **Maturity:** AI-Aware
- **Dimensions:**
  - Foundational Compliance: 74 / 100
  - Developer Experience & Jentic Compatibility: 63 / 100
  - AI-Readiness & Agent Experience: 48 / 100
  - Agent Usability: 94 / 100
  - Security: 50 / 100
  - AI Discoverability: 57 / 100
- **View full report:** https://jentic.com/apis/riskified.com/riskified/scorecard
- **How the score is calculated:** https://docs.jentic.com/reference/api-readiness-framework/overview/
- **More about the dimensions:** https://docs.jentic.com/reference/api-readiness-framework/specification/#dimensional-model-overview

### Score it yourself

Every API in the directory is allowlisted, so you can re-score it with no key required.

- **Score your own API:** https://jentic.com/scorecard.md
- **Scoring CLI agent skill:** https://github.com/jentic/jentic-api-scorecard/blob/main/skills/jentic-api-scorecard/SKILL.md

```sh
npx @jentic/api-scorecard-cli score <openapi-url>
```

## Why Jentic

- **Setup:** Wiring Riskified by hand means computing an HMAC-SHA256 signature of every request body with your auth token, adding the shop-domain header, and choosing between separate order-action and account-action hosts. Through Jentic you install once, import Riskified from the API Directory, store the token once, and your agent calls it.
- **Permission scoping:** Riskified carries the order inside the request body, so rules bound which operations your agent may call, not which order it touches. You choose the operations it may call, so lifecycle changes like cancel, refund, or chargeback reporting are not included unless you add them.
- **Credential handling:** Your Riskified auth token is stored once, encrypted, by your own Jentic One instance and used at execution time. It never enters the agent's prompt, logs, or context.
- **Discovery method:** Agents search Jentic by intent such as 'screen an order for fraud' or 'report a chargeback', and Jentic returns the matching Riskified operation with its input schema so the agent calls the right endpoint without browsing the reference docs.

## Related APIs

- **Sift API** — Digital trust and fraud scoring across payments, accounts, and content events
- **FraudLabs Pro Fraud Detection** — Rule-based order fraud screening with a risk score for each transaction
- **Shopify REST Admin API** — Storefront and order data source whose orders can be sent to Riskified for review
- **Stripe API** — Payment processing and dispute records that feed Riskified's refund and chargeback calls

## FAQ

### Why is there no official OpenAPI spec for the Riskified E-Commerce API?

Riskified does not publish an OpenAPI specification. Jentic generates and maintains this spec so that AI agents and developers can call the Riskified E-Commerce API via structured tooling. It is validated against the live API and kept up to date. To run it on your own infrastructure, install Jentic One from its GitHub repo.

### What authentication does the Riskified E-Commerce API use?

Per its OpenAPI spec, each request carries an HMAC-SHA256 signature of the request body, computed with your Riskified auth token and sent in the `X-RISKIFIED-HMAC-SHA256` header. Requests also identify your store with the `X-RISKIFIED-SHOP-DOMAIN` header. Through Jentic the auth token is held by your own instance and used at call time, so the agent never sees it.

### Can I get a fraud decision on an order immediately with the Riskified E-Commerce API?

Yes. POST `/api/decide` submits an order for synchronous fraud analysis and returns the decision in the same response. If you prefer asynchronous review, create the order with POST `/api/create` and send it for analysis with POST `/api/submit` instead.

### What are the rate limits for the Riskified E-Commerce API?

The OpenAPI spec does not specify rate limits. Check the Riskified API reference at https://apiref.riskified.com/ or your Riskified account team for current limits before sending historical order uploads in bulk.

### Is there a Riskified MCP server?

You do not need an MCP server to give your agent Riskified. Jentic connects it directly from the API Directory: import it, store your auth token once, and your agent calls the order and account operations it needs on demand without loading another server's tool definitions into its context.

### Can I limit what my agent is allowed to do with the Riskified E-Commerce API?

Yes. For an order-review agent, write a rule that allows only POST `/api/decide` and POST `/api/fulfill`, so it can screen orders and mark them shipped but cannot cancel, refund, or report chargebacks. Every call it makes is logged.

### Does the Riskified E-Commerce API use different hosts for order and account actions?

Yes. The spec lists https://wh.riskified.com for production order actions and https://api.riskified.com for production account actions, with https://sandbox.riskified.com and https://api-sandbox.riskified.com as the matching sandbox hosts. Use the sandbox hosts while testing an integration.
