Merchant Credit-Tier Upgrade Preview

GET /v2/merchant/credit-tier/upgrade-preview/:merchantId returns the merchant’s aspirational roadmap to higher credit-tier ceilings. Used by merchant portals to surface “settle X more on-time and the next lender that underwrites you will start from a T2 ceiling.”

Aspirational, not a promise. The actual issued tier on a Schema B attestation depends on the lender’s base tier mapping (revenue + inventory + sales-efficiency signals from CreditTierMappingService). This endpoint shows the floor the merchant can earn through repayment performance; the base is set by lender underwriting.

Request

GET /v2/merchant/credit-tier/upgrade-preview/:merchantId

Response (200)

{
  "merchantId": "6a207db0d29923bffaa983ca",
  "signals": {
    "totalSettledOnTime": 2,
    "totalLate": 0,
    "totalDefaults": 0,
    "trailingTwelveMonthDefaults": 0,
    "lenderCount": 1,
    "mostRecentSettlementAt": "2026-06-08T12:00:00Z"
  },
  "observedTier": "T1",
  "nextTierGap": {
    "targetTier": "T2",
    "onTimeSettlementsNeeded": 1,
    "blockingDefaultCount": 0,
    "guidance": "Settle 1 more on-time to reach T2 ceiling."
  },
  "topTierGap": {
    "targetTier": "T3",
    "onTimeSettlementsNeeded": 8,
    "blockingDefaultCount": 0,
    "guidance": "Settle 8 more on-time to reach T3 (top ceiling)."
  }
}

Tier ladder

Tier	Threshold from repayment history	Blocks
`T1`	Default — every new merchant starts here	—
`T2`	3+ on-time settlements	Lifetime defaults > 0 → blocked
`T3`	10+ on-time settlements	Trailing-12-month defaults > 0 → blocked

When the merchant reaches T3, both nextTierGap and topTierGap are null.

Discipline

Read-only. No mints. No reads of the lender base tier — pure “what’s possible with repayment history alone” surface.
@Public() — no PII beyond the merchant’s own settlement counts.

Underwriting Signals — composite read that bundles this preview with Schema B + C in one envelope
Schema C Repayment-History — the on-chain record the preview is computed from

Service-Provider Routing Recommendation Underwriting Signals Composite

Overview

Admin API

Public API

Trust Fabric API

EAS Schemas (Trust Fabric)

Merchant API

AI Endpoints

Merchant

Customer

Shop

Product

Collection

SKU

Shipping

Gift Card

Blog

Cart

Order

Address Book

Merchant Credit-Tier Upgrade Preview

Request

Response (200)

Tier ladder

Discipline

​Request

​Response (200)

​Tier ladder

​Discipline

​Related

Request

Response (200)

Tier ladder

Discipline

Related