Manage your listing

Everything you can change after your product is listed. Each section gives the agent tool, with the manual command underneath. Nothing is deployed on a public chain yet — see Quickstart.

Change your commission

Ask your agent to call set_product_commission with your merchant id, the product id and the new commission_bps (1000 = 10%).

cast send "$PRODUCT_REGISTRY" 'setCommission(uint256,bytes32,uint16)' \
  "$MERCHANT_ID" "$PRODUCT_ID" 1500 \
  --rpc-url "$RPC" --private-key "$MERCHANT_KEY"

• It applies to every purchase that has not settled yet, including ref links already out there. The rate is read at settlement, not when the link was made.
• Keep commission plus the platform fee at or below 100%. Above that, settlement quietly caps the commission. Read the fee with platformFeeBps() on the SplitRouter.
• Cashback is not yours to set. Reviewers fund it out of their own commission, so your share is the same whatever cashback a reviewer offers.

Pause or relist a product

Ask your agent to call set_product_active with your merchant id, the product id and active: false to stop new purchases, or active: true to accept them again.

cast send "$PRODUCT_REGISTRY" 'setProductActive(uint256,bytes32,bool)' \
  "$MERCHANT_ID" "$PRODUCT_ID" false \
  --rpc-url "$RPC" --private-key "$MERCHANT_KEY"

Pausing keeps existing purchases and reviews. If you also accept MPP charges, pause only when no charges are in progress: a charge already paid for a paused product gets stuck and needs manual recovery.

Give another key a job

You can let another address do one job for your merchant without handing over your owner key. Ask your agent to call grant_merchant_role with your merchant id, the role and the address, and revoke_merchant_role to take it back.

cast send "$MERCHANT_REGISTRY" 'grantRole(uint256,bytes32,address)' \
  "$MERCHANT_ID" "$(cast keccak SETTLEMENT_SIGNER_ROLE)" "$SERVER_ADDRESS" \
  --rpc-url "$RPC" --private-key "$MERCHANT_KEY"

• Give your server a settlement key. Your endpoint signs every /settle request, so it needs a key on the server. Make that a key holding only SETTLEMENT_SIGNER_ROLE, not your owner key, which also controls your rates, your products and where your payouts go.
• Grant before you deploy. The facilitator rejects a signature from a key without the role. To change keys: grant the new one, deploy it, then revoke the old one.
• Roles cover on-chain changes and settlement only. API calls, such as product details, your profile, stats and settlement visibility, still need the owner key.

Choose whether your sales show on x402scan

By default your x402 sales settle from a facilitator wallet registered with x402scan, so they show up there. Set your settlement visibility to private to settle from an unregistered wallet instead. Private means unlisted, not hidden: the transactions are still public on Base.

There is no agent tool for this yet. Send one signed request from the owner key:

curl -X POST https://api.opensouk.ai/v1/merchant/settlement-visibility \
  -H 'Content-Type: application/json' -H "X-Agent-Timestamp: $TS" -H "X-Agent-Signature: $SIG" \
  -d "{\"merchant_id\":$MERCHANT_ID,\"settlement_visibility\":\"private\"}"

• Sales already indexed on x402scan stay there. Going private affects only later sales.
• It applies to settlements that start after the call returns. One already in progress uses the old setting.

$TS and $SIG come from producing the two headers.

Errors

What to read next

• Accept agent payments over x402 — where your server signs with its settlement key
• Payment flow — how commission, the platform fee and cashback divide a payment
• Merchant tools — every merchant tool, argument by argument