← 12Eat for AI Assistants

12Eat tool contracts

This HTML page is readable by general web-based AI assistants. The original Markdown file is available for Skill-compatible clients.

# 12Eat public tool contracts

The anonymous public surface is read-only and requires no login. For browser-based readers that cannot open Markdown, the complete public-use workflow is also available as HTML at `https://mm.12eat.ai/agent`.

Use the sequence **Search → Read → Compare → Present → Act**. Never recommend a merchant based only on a search snippet when merchant detail is available.

## MCP

### Authorized Commerce

SEARCH → READ → QUOTE → APPROVE → CONFIRM → TRACK

`public.merchants.read` returns `fulfilmentOptions`: current published options with `optionId`, `revision`, `mode`, `executor`, `pricing`, `locationRefs`, `lifecycleStatus: published` and `source: merchant_published`. Paused or retired latest revisions do not fall back to earlier published versions. Private policy and credentials are omitted. Read merchant detail before recommending and show its available modes.

The following capabilities are only available through authorized `/mcp` or `/capabilities/{name}` under current permissions. MCP arguments wrap the exact contract in `input`; writes use a stable `requestKey`. Discover schemas before constructing inputs.

| Capability | Permission | Input / purpose |
| --- | --- | --- |
| `merchants.fulfilment-options.put` | `merchants:capabilities:publish` | Own merchant option revision and lifecycle |
| `merchants.platform-payment.put` | `merchants:platform-payment:write` | Publish the next immutable enabled/disabled platform-payment declaration revision |
| `merchants.platform-payment.read` | `merchants:platform-payment:read` | Read the current declaration for the authenticated Merchant Workspace |
| `commerce.orders.draft` | `orders:create` | Exact catalog and published fulfilment revisions |
| `commerce.orders.quote` | `orders:create` | Order ID and expected revision; authoritative linked delivery offer if applicable |
| `commerce.orders.quote.submit` | `orders:quote` | Own merchant's versioned quote, frozen line/option revisions, currency, components, expiry and idempotency key |
| `commerce.orders.quote.read` | `orders:read` | Read the latest exact quote before customer approval |
| `commerce.delivery.destinations.put` | `orders:create` | Requester-scoped resolved address/coordinates with explicit destination disclosure |
| `commerce.delivery.quote` | `orders:create` | Owned draft order ID; pending until an eligible provider offer exists; never dispatches |
| `commerce.delivery.commit` | `orders:confirm` | Approved covered parent order ID only; idempotent one-child commit/reconciliation, no extra Coverage |
| `commerce.orders.confirm` | `orders:confirm` | Exact quote ID/revision and settlement mode after explicit approval |
| `commerce.orders.read` | `orders:read` | Owned order ID |
| `commerce.orders.fulfilment.transition` | `orders:accept` | Own merchant order, expected revision, mode and permitted next status |

Customer confirmation leaves merchant fulfilment pending. The merchant records `accepted` before preparation or a mode-specific subsequent transition. Authoritative child `delivered` evidence completes parent fulfilment independently of payment collection. Provider payment results must retain the original persisted attempt key and authoritative transaction/evidence references; delayed results must never be reassigned to the latest attempt. Post-confirmation failures preserve Coverage for explicit reconciliation/compensation.

Principal, tenant and market are server-bound; request-body IDs cannot replace context. Present the quote and fulfilment terms and require explicit approval before confirmation. `quote_required` has no final payable price. Platform settlement requires the merchant's current declaration to be enabled before Coverage reservation and again atomically at confirmation; the customer's payment choice is not merchant consent. Coverage is not proof of collection; a delivery quote is not dispatch. `direct` settlement omits platform payment fields. Read payment and fulfilment separately. Child delivery commitment is server-only, and DCT/legacy stays `blocked_external` until a parent-funded adapter exists. No transaction tool is added to public MCP. SG and ID follow the same contract.

### Public connection

Connect a Streamable HTTP MCP client to:

`https://one2eat-api-sg.onrender.com/mcp/public`

Available tools:

- `public.services.search`: accepts an `input` object with optional `q`, `market` (`SG` or `ID`), `serviceType`, and `limit`.
- `public.merchants.search`: accepts an `input` object with optional `q`, `market`, and `limit`.
- `public.merchants.read`: accepts an `input` object containing a merchant `slug`.

Pass arguments as `{ "input": { ... } }`. MCP search results are currently JSON arrays in text content; merchant detail is a JSON object. Do not assume an output schema or uniform REST-style envelope is advertised by these legacy tools. Use only facts present in the returned projection.

## HTTP alternative

- `GET https://one2eat-api-sg.onrender.com/public/services?q={query}&market={SG|ID}&serviceType={type}`
- `GET https://one2eat-api-sg.onrender.com/public/merchants?q={query}&market={SG|ID}`
- `GET https://one2eat-api-sg.onrender.com/public/merchants/{slug}`

The endpoints allow cross-origin public reads. A merchant detail response is the current canonical projection for its public profile, services, catalog, source attribution and merchant-authorized contact actions.

REST search responses are objects with `schemaVersion` and a `services` or `merchants` array. This differs from the current MCP search result shape. Treat both as discovery candidates and read merchant detail before recommending anyone.

## Structured inquiry HTTP contract

Use only the platform-owned `inquiryEndpoint` returned in a current `contactActions` entry. Do not POST an inquiry to the merchant URL. `requesterRef` and `requestKey` must each be a valid, distinct, client-generated UUID. They are opaque protocol identifiers, not places for an email, phone number, user ID, or other personal data.

Prepare with `POST {inquiryEndpoint}` and JSON:

```json
{"merchantSlug":"current-slug","actionId":"current-action","requesterRef":"5d7ed6c2-2a85-4f63-a47a-2ae15cc91821","message":"What the user needs","replyTo":"user@example.com","requestedService":"optional service","requestKey":"8a79d4cd-cfd4-4cde-8c7b-7408c2f23b69"}
```

The response is `pending_approval` and includes `inquiryId`, `actionRevision`, an expiring `approvalToken`, and an absolute `decisionEndpoint`. This step sends nothing to the merchant and creates neither an order nor a CRM record. Preserve `requesterRef`, `requestKey`, `approvalToken`, and the returned endpoint across retries.

After displaying the exact inquiry to the user, POST to the returned `decisionEndpoint`:

```json
{"requesterRef":"5d7ed6c2-2a85-4f63-a47a-2ae15cc91821","approvalToken":"returned-token","decision":"approve"}
```

Use `decision: decline` when the user declines. Retrying the same decision is idempotent. Only an approved receipt with `crmRecordId` proves capture in the represented Merchant Workspace. It does not prove acceptance and is not an order. If the merchant revoked or replaced the contact action after preparation, approval fails and the client must read current merchant detail again.

## Interpretation rules

- `pricing.mode: fixed` contains a current fixed amount in integer minor currency units.
- `pricing.mode: quote` means the merchant calculates the price from the actual request; it is not free and has no implied amount.
- `contactActions` are merchant-authorized handoff methods. Following one does not itself create a 12Eat order or prove acceptance.
- `geoUrl` is the canonical public 12Eat merchant page.
- Google facts and 12Eat facts retain separate attribution and ratings.
- `promotions` contains only the Merchant's current published, valid offers. Money uses integer minor units. A formal quote confirms whether an offer applies and returns `originalDeliveryCharge`, `merchantSubsidy`, customer `deliveryCharge`, and `appliedPromotion`.
- A request for "nearby", "open now" or "in stock" needs current location, hours or stock evidence. These public tools do not provide a dedicated proximity, live-hours or inventory query; do not infer those claims from a name or search ranking.

## Formal actions

Formal orders, logistics execution, status tracking and optional platform payment use the authenticated MCP endpoint:

`https://one2eat-api-sg.onrender.com/mcp`

Discover OAuth metadata at:

`https://one2eat-api-sg.onrender.com/.well-known/oauth-protected-resource/mcp`

The user's authorization determines the available tools. Never manufacture credentials or reuse another principal's authority.

For `orders.native.confirm`, choose exactly one settlement mode:

- `settlementMode: direct`: the merchant and customer settle outside 12Eat. Omit settlement account, Coverage and payment references. 12Eat may track merchant and delivery fulfilment but does not create a platform settlement record.
- `settlementMode: platform` (or the legacy platform-payment shape): provide the authorized settlement account, Coverage type/reference and validity. 12Eat verifies Coverage before confirming the order.

Never describe a direct order as paid, collected, refunded or platform-settled merely because fulfilment was reported.

## Built-in LiveXpress logistics

LiveXpress delivery is provided as a built-in platform capability and is intentionally not required to appear as a merchant service SKU in public search.

### Guest direct-prepayment HTTP flow

This flow requires no 12Eat login, OAuth client ID, customer identity or Partner credential. Create a client-generated UUID v4 `requestId`; it is an opaque protocol identifier and must contain no personal data.

Request a quote with `POST https://one2eat-api-sg.onrender.com/public/logistics/quotes`:

```json
{"schemaVersion":"12eat.guest-logistics-quote.v1","requestId":"10000000-0000-4000-8000-000000000002","market":"SG","currency":"SGD","serviceMode":"immediate","pickup":{"address":"Pickup address","lat":1.3001,"lng":103.8001},"dropoff":{"address":"Destination address","lat":1.3101,"lng":103.8101},"subject":{"drivingType":"Car","city":"Singapore","pickupLocalTime":"2026-10-07 12:00"},"requestedWindow":{"start":"2026-10-07T04:00:00.000Z","end":"2026-10-07T05:00:00.000Z"}}
```

For Indonesia use `market: ID` and `currency: IDR`; the flow and three service modes (`errand`, `immediate`, `next_day`) are otherwise the same. Quote input deliberately contains no contact name, phone number, parcel description, `principalId`, OAuth client ID or Partner credential.

The `202 Accepted` response contains `statusToken`, an absolute `statusUrl`, and `expiresAt`. Treat the token as a secret scoped only to that quote. Read status with `GET {statusUrl}` and header `x-12eat-guest-token: {statusToken}`. Poll with bounded backoff until a current LiveXpress offer is returned or the token expires. Do not invent a provider quote ID or provider expiry when absent; use only the returned amount/currency and stated local offer validity.

Show the exact current offer to the user, then collect the order-only contact names, mobile numbers and parcel description. Generate distinct UUID v4 values for `orderId` and `requestKey`. Show the complete immutable submission—offer, contacts and description—and obtain explicit transaction approval for that exact body. Only then `POST {statusUrl}/approve` with the same token header:

```json
{"schemaVersion":"12eat.guest-logistics-approval.v1","orderId":"40000000-0000-4000-8000-000000000002","requestKey":"60000000-0000-4000-8000-000000000002","decision":"approve","offerId":"exact-returned-offer-id","offerRevision":1,"pickupContact":{"mobile":"+6591111111","contactName":"Sender"},"dropoffContact":{"mobile":"+6592222222","contactName":"Receiver"},"description":"Sealed parcel"}
```

Keep the same approval body for an exact retry. A changed body under the same order ID is a conflict. Approval creates a direct-settlement order only; it is not payment or dispatch. Continue reading `{statusUrl}` with the token until checkout is `payment_instruction_ready` and `paymentMethod` is `paynow`, then show the returned order-specific instruction and stop. Never call a payment confirmation, wallet payment, dispatch or fulfilment transition from this guest flow.

If status becomes `outcome_unknown` or `payment_instruction_outcome_unknown`, preserve the original request and order identifiers and stop. Do not resubmit approval, retry the Partner write, or create another order. Tell the user that authorized LiveExpress operations must reconcile the preserved result with the provider. Exact approval replay is only for transport uncertainty before a terminal ambiguous status; it never authorizes retry after one.

### Authorized tools

After OAuth, list the tools authorized for the current identity rather than assuming a role:

- Requester identities use the discovered `logistics.delivery.*` request, status, match and commitment tools.
- Merchant Workspace identities use `orders.external-delivery.requests.create` for an external order and the returned external-delivery status, match and commitment tools.

The Business Agent, not the customer, holds the Partner connector credentials. An order-specific `paynow` or `one_two_eat_account` checkout response is a payment instruction only. Do not report payment, acceptance or dispatch until a later authoritative status confirms it.