Connect a developer or purchasing agent
Current status: owner-only test funding. Public real-money purchases are not enabled. These examples call the actual endpoint and require an authorized, funded test key. x402 and MCP purchasing are not available yet.
Choose the operation
Use Supplier Price Compare when an application needs exact-SKU evidence of price, pack size, minimum-order or margin changes. It accepts data supplied by you; it does not search for suppliers, scrape prices or place purchasing orders.
1. Create a scoped key
Sign in on the portal, fund the test account and create a key allowing Supplier Price Compare. Set a daily wallet cap. Included subscription comparisons use the plan quota independently of that cap; a zero wallet cap does not block included units. Store the key in your agent runtime’s secret store, rather than prompts, browser code or source control.
2. Run a comparison
Download the sample JSON and either the Node.js client or Python client. Both use built-in libraries, a 60-second timeout and no automatic retries. The commands below show environment variables; use your secret manager to inject the real key.
PAYLOADPIER_API_KEY="your-scoped-key" node compare.mjs comparison.json > result.json PAYLOADPIER_API_KEY="your-scoped-key" python compare.py comparison.json > result.json
The sample keeps the pack price at $120 but reduces its size from 12 to 10. The unit cost rises from $10 to $12, or 20%. It consumes one included comparison or $0.25 in test wallet credit on success.
3. Preserve the operation identity
Each client prints its Idempotency-Key to standard error before sending. Persist it with the job. To repeat the same operation, supply that value using PAYLOADPIER_IDEMPOTENCY_KEY. Reusing a recorded key returns HTTP 409 and a usage reference, without another charge; it does not replay the result. A timeout does not prove the operation failed. Check account usage or contact support before starting a replacement job with a new key.
Handle responses deliberately
- 200: save the result and billing reference.
- 401/403: check key, scope or account access.
- 402: check wallet, quota and spending cap. This is an ordinary funding error, not an x402 payment challenge.
- 409: inspect the existing usage record; do not loop with new keys.
- 429: wait for Retry-After seconds and retain the same operation key. Authenticated attempts are limited to 60 per account per UTC minute across all keys.
- 413/422: correct request size or input. Invalid input is not billed.
- 5xx or timeout: preserve the operation key and reconcile the outcome.
Inputs, limits and privacy
Use decimal strings for money, text SKUs and explicit currencies and units. JSON snapshots support at most 5,000 rows each; request bodies are limited to 5 MiB. CSV/XLSX files are limited to 2 MiB each. Uploaded sources and results are processed in memory and not retained for replay. Billing metadata persists. Keep commercially sensitive inputs out of agent logs.