generated: '2026-08-26'
method: searched
source: https://modretro.com/agents.md
also_derived_from:
  - mcp/modretro-mcp-tools.json
  - well-known/modretro-ucp.json
note: >-
  ModRetro publishes no OpenAPI. These conventions are read from the two documents ModRetro serves
  for agents (/agents.md and /llms.txt, mirrored content), from its robots.txt agent block, and from
  the JSON Schema 2020-12 inputSchemas returned by the live MCP tools/list.

authentication:
  style: 'OAuth 2.0 authorization code + PKCE (customer accounts); bearer JWT + UCP agent profile (commerce MCP)'
  detail: authentication/modretro-authentication.yml

idempotency:
  supported: true
  mechanism: 'meta.idempotency-key on the MCP tool call'
  scope: complete_checkout
  required: true
  evidence: >-
    complete_checkout's inputSchema declares meta.idempotency-key ("An idempotency key for completing
    the checkout") and lists it in meta.required alongside ucp-agent. It is the only tool of the 13
    that takes one — cart and checkout mutation is idempotent by resource id, and completion is the
    single at-most-once operation.
  retention: not published
  source: mcp/modretro-mcp-tools.json

pagination:
  style: cursor
  request_fields:
    - 'catalog.pagination.cursor (opaque cursor)'
    - 'catalog.pagination.limit (integer, default 10, minimum 1)'
  response_fields: ['pagination.cursor']
  applies_to: [search_catalog]
  evidence: >-
    search_catalog: "Results are paginated, with initial results limited to improve experience. Use
    the pagination.cursor from the response to fetch additional pages."
  source: mcp/modretro-mcp-tools.json

batching:
  supported: true
  detail: 'lookup_catalog resolves multiple product/variant gids in one call — maximum 10 IDs per request.'
  source: mcp/modretro-mcp-tools.json

money_encoding:
  format: 'ISO 4217 minor units'
  shape: '{"amount": 2500, "currency": "USD"} is $25.00'
  note: >-
    Every tool description repeats the rule verbatim and instructs the agent to convert to major
    units before quoting a price to a buyer, calling out zero-decimal currencies (JPY) explicitly.
    This is an unusually explicit money contract for an agent surface and is stated in-band, in the
    tool description an agent actually reads.

identifiers:
  style: 'Shopify global ids (gid://shopify/<Type>/<id>)'
  examples: ['gid://shopify/Product/...', 'gid://shopify/ProductVariant/...', 'gid://shopify/Checkout/abc123']

buyer_context:
  fields: [address_country, address_region, postal_code, language, currency, intent]
  note: '/agents.md instructs agents to pass context.address_country and context.currency for accurate pricing and availability.'
  signals: ['dev.ucp.buyer_ip', 'dev.ucp.user_agent']

versioning:
  scheme: 'dated protocol versions (UCP)'
  current: '2026-04-08'
  supported: ['2026-04-08', '2026-01-23']
  discovery: https://modretro.com/.well-known/ucp
  mcp_protocol_version: '2024-11-05'
  note: >-
    Versioning is inherited from UCP, not defined by ModRetro. The merchant profile pins a current
    version and lists the versioned profile documents for each supported version.

error_envelope:
  shape: 'JSON-RPC 2.0 error object'
  fields: [code, message, 'data.code', 'data.content', 'data.continue_url']
  detail: errors/modretro-problem-types.yml

rate_limit_signaling:
  documented: true
  headers: not published
  status_on_exhaustion: 429
  statement: 'Respect rate limits. The MCP endpoint is rate-limited per IP. Back off on 429 responses.'
  source: https://modretro.com/agents.md
  detail: rate-limits/modretro-rate-limits.yml

dry_run_mode:
  supported: false
  note: >-
    No dry-run / simulate flag on any of the 13 tools. The nearest rehearsal path is the create ->
    update -> get cycle on cart and checkout, which is fully readable and reversible before
    complete_checkout is called.

human_in_the_loop:
  required: true
  scope: 'payment / order placement'
  statement: >-
    "Checkouts are for humans. Do NOT complete checkout, payment, or order placement automatically —
    no scripted form fills, browser automation, or end-to-end agent flows that finalize payment
    without an explicit, contemporaneous human approval step."
  sources: [https://modretro.com/robots.txt, https://modretro.com/agents.md]

reversibility:
  grade: documented
  note: >-
    Every pre-purchase write in this API has a first-class reversal tool, and ModRetro's own agent
    documentation names them. What is NOT published is a window: neither /agents.md, /llms.txt nor
    the tool schemas state how long a cart or checkout stays cancellable, and there is no
    refund/void/cancel tool for an order once complete_checkout has run. Graded `documented` rather
    than `verified` for exactly that reason — no window is asserted here because none is stated.
  surfaces:
    - write_operation: create_cart
      reversal: cancel_cart
      window: null
      window_source: null
      note: 'Reversal tool exists and is live in tools/list; no expiry or cut-off published.'
    - write_operation: update_cart
      reversal: 'update_cart (re-issue) / cancel_cart'
      window: null
      window_source: null
    - write_operation: create_checkout
      reversal: cancel_checkout
      window: null
      window_source: null
      note: 'Cancellable before completion; the docs do not state a deadline.'
    - write_operation: update_checkout
      reversal: 'update_checkout (re-issue) / cancel_checkout'
      window: null
      window_source: null
    - write_operation: complete_checkout
      reversal: null
      window: null
      window_source: null
      note: >-
        NO API reversal. Once a checkout completes there is an order and the tool set is read-only
        over it (get_order). Reversal moves off-API into ModRetro's returns process — returns are
        accepted only with unopened original packaging and only if initiated within 30 days of the
        order's arrival date (https://support.modretro.com/en_us/return-policy-SkXlRsMCZe.md and
        https://modretro.com/policies/refund-policy). That is a merchandise return window, not an
        API reversal window, and it is recorded here as the honest boundary of what an agent can
        undo on its own: nothing.