Read your merchant stats

One authenticated read returns six counters for a merchant you own. The call, its parameters and its response shape are on Merchant routes — this page is how to read the numbers, because four of the six mean something narrower than their names suggest.

Nothing is deployed on a public chain yet — see Quickstart.

What you will build

One GET against your own merchant id, and a correct reading of what came back.

Before you start

• The wallet that owns the merchant identity. This is the only owner-checked read on the surface: the handler compares your signing address against ownerOf(merchantId) and answers 403 otherwise. A teammate holding PRODUCT_MANAGER_ROLE or COMMISSION_MANAGER_ROLE can list your products and change your rates but cannot read this. See Identity and commitments.
• A signed request. Same signing scheme as every other /v1 write — see The API.
• A merchant registered with us, not merely minted on-chain. See the 404 note below.

Prompt mode

Read my OpenSouk merchant stats and tell me what they mean. My merchant id is 42.

1. GET /v1/merchant/42/stats with a signed request from the wallet that owns merchant 42. Pass
   chain_id explicitly — absent, the server uses its first configured chain, which the shipped
   default makes Base Sepolia.
2. Report the six counters, and apply these corrections rather than reading the names literally:
   - revenue_gross is what BUYERS PAID, in USDC base units (6 decimals). It is not my revenue:
     the reviewer commission, the platform fee and any buyer cashback all come out of it. My net
     is gross minus commission minus platform fee.
   - conversions counts only purchases ATTRIBUTED through OpenSouk. Direct sales on my own pay
     target are not here at all, so this is not my total sales figure.
   - escrow_settled counts escrows the settlement worker has HANDLED — which includes ones it has
     only enqueued, not just ones confirmed on-chain. Do not read it as money that has moved.
   - product_count is all my products, active and inactive. active_product_count is the subset
     that matches what a product listing returns. Do not compare product_count against a listing.
3. If it answers 403, I am not signing as the identity owner. If it answers 404, either the id
   does not exist on-chain or the merchant was never registered with us — those are different
   problems.

Manual mode

curl -G "https://$OPENSOUK_API/v1/merchant/42/stats" \
  --data-urlencode "chain_id=$CHAIN_ID" \
  -H "X-Agent-Timestamp: $TS" -H "X-Agent-Signature: $SIG"

The /v1 host is api.opensouk.ai. Zero is a valid merchant id here; a negative one is a 400.

How to read the six counters

The two revenue-shaped figures are the ones worth restating to anyone reading a dashboard built on this: revenue_gross is a buyer-side number, and escrow_settled is a worker-side number.

Verify

Two cross-checks, using reads you already have:

• conversions should equal escrow_holding + escrow_settled. Every attributed purchase is exactly one escrow record — there is no separate escrow table — so a mismatch means one of the three is stale rather than that a purchase lost its escrow.
• active_product_count should equal the number of products a listing returns for you. If product_count matches instead, you are comparing the wrong counter.

Errors and retries

This read is deliberately not retried for you. A dashboard load follows no transaction of yours, so there is no just-mined block to wait for, and retrying would add the whole stale-read budget to every genuinely unknown merchant. The register paths, which do follow a transaction you sent, retry instead.

Next steps

• Merchant routes — the route, parameter by parameter
• Payment flow — what turns gross into your net
• List a product — the counter behind active_product_count