Merchant Orders + Attestation JOIN (Merchant)

​

GET /v2/merchant/orders

​

Authentication

​

Query parameters

​

Example

curl "https://apiv3.droplinked.com/v2/merchant/orders?page=1&limit=20" \
  -H "Authorization: Bearer <MERCHANT_JWT>"

curl "https://apiv3.droplinked.com/v2/merchant/orders?page=1&limit=50&status=SETTLED&psp=stripe&startDate=2026-01-01T00:00:00Z&endDate=2026-06-14T23:59:59Z" \
  -H "Authorization: Bearer <MERCHANT_JWT>"

​

Response — 200 OK

{
  "rows": [
    {
      "orderId": "6657a1b2c3d4e5f60718293a",
      "orderNumber": "ORD-001",
      "customerEmail": "buyer@example.com",
      "items": 2,
      "grossUsdCents": 5000,
      "netUsdCents": 4500,
      "psp": "stripe",
      "status": "SETTLED",
      "attestation": {
        "uid": "0xUID1",
        "status": "MINTED",
        "rolledUpAt": "2026-06-13T00:00:00.000Z",
        "lenderId": "lender-A",
        "chain": "base",
        "schemaUid": "0xSCHEMAC"
      },
      "settledAt": "2026-06-12T00:00:00.000Z",
      "createdAt": "2026-06-10T00:00:00.000Z"
    }
  ],
  "kpis": {
    "totalOrdersInWindow": 4,
    "settledRevenueUsdCents": 30000,
    "avgOrderValueUsdCents": 15000,
    "attestationCoveragePctBps": 2500
  },
  "pagination": {
    "page": 1,
    "limit": 20,
    "totalPages": 1,
    "totalCount": 4
  },
  "windowDays": 90,
  "asOf": "2026-06-14T17:40:00.000Z"
}

​

Fields

​

Errors

​

Schema C JOIN

• Single bulk query. The JOIN is a single $in query against the sparse orderId index on repayment_history_attestations. No N+1; the service collects every orderId from the Prisma fetch first, then issues one Schema C read for the page.
• Newest-wins. If multiple Schema C rows reference the same orderId (re-mint flows), the most recently rolledUpAt row is returned. The collection retains history; the JOIN reads the latest.
• Schema UID. Every returned block carries the Schema C UID (0xSCHEMAC placeholder above; the production value is registered on Base mainnet — see the EAS Schema v2 shipped 2026-06-11 note in the trust-fabric concept page). Clients can use this to disambiguate from Schemas A / B / D in a future mixed-schema view.
• Missing coverage. Orders with no Schema C row land attestation.status: "NOT_APPLICABLE" (orders that don’t qualify, e.g. refunded-before-settlement) or "PENDING" (qualifying orders not yet rolled up). Rows are never dropped from rows[] because of a missing attestation — coverage is signaled via the per-row status field and aggregated into kpis.attestationCoveragePctBps.

​

KPI envelope

• totalOrdersInWindow — order rows matching the filter across the full window (not just the visible page).
• settledRevenueUsdCents — Σ grossUsdCents for rows whose FE bucket is SETTLED. Refunded / disputed rows are excluded.
• avgOrderValueUsdCents — settledRevenueUsdCents / count(SETTLED rows), integer division. 0 when no SETTLED rows in window.
• attestationCoveragePctBps — floor(10000 × count(attestation.status === "MINTED") / totalOrdersInWindow). Clamped to 0..10000. 0 when the window is empty.

​

Per-section fail-open

​

Notes

• 8→4 status mapping. The Prisma OrderStatus enum has 8 values (CREATED, CONFIRMED, PROCESSING, SHIPPED, DELIVERED, REFUNDED, CANCELLED, DISPUTED); the FE bucket has 4 (SETTLED / PENDING / REFUNDED / DISPUTED). Mapping is centralized in MerchantOrdersService.mapStatusBucket():
  • DELIVERED + SHIPPED + PROCESSING + CONFIRMED → SETTLED
  • REFUNDED + CANCELLED → REFUNDED
  • DISPUTED → DISPUTED
  • CREATED and unmapped → PENDING (excluded from SETTLED revenue; included in totalOrdersInWindow).
• Caching. The response carries Cache-Control: private, max-age=60. Clients may see up to a 60s lag for fresh order events through CDN caches.
• PSP filter is in-memory. Prisma’s Mongo provider does not efficiently filter on a composite-type payment.provider field, so the PSP filter is applied in-memory after the Prisma fetch. Pagination math is over the filtered set.
• Auth scope. shopId from req.user.shopId only. Any ?merchantId= / ?shopId= query parameter is silently dropped. A merchant cannot read another merchant’s orders through this endpoint.
• Currency. All monetary fields are USD cents, integer — same contract as x402 Earnings (Merchant). Divide by 100 for major-unit display.
• MCP twin. The same data feeds the get_merchant_orders MCP tool (Pillar 4). The wire shape is identical so a single OpenAPI schema generates both clients.

​

Related

• x402 Earnings (Merchant) — companion merchant-facing rollup of x402 settlement events.
• Billing Invoices (Merchant) — companion merchant-facing billing history (trailing 365 days).
• Brand Attestation Lifecycle — context on the Schema C → repayment-history → LenderRegistry attestation chain.
• Register Settlement Wallet — register where x402 micro-payments derived from these orders should route.