API
Endpoints
Description
Get price, availability, discount info, variants, and suggested max_budget for a product before purchasing. No auth required.
Base URL
https://api.agentmall.sh
Query parameters
urlstringrequiredProduct page URL from a supported retailer
Responses
200 OK
{ "title": "Apple Magic Mouse", "price": 6900, "listPrice": 7900, "discountPercent": 13, "currency": "USD", "availability": "In Stock", "retailer": "Amazon.com", "suggestedMaxBudget": 9085, "variants": [{ "label": "Style", "value": "USB-C", "price": 69.00 }] }400 Bad Request
{ "error": "Missing required query parameter: url" }429 Rate Limited
{ "error": "Rate limited" }502 Lookup Failed
{ "error": "Product lookup is temporarily unavailable..." }Try it
Description
Place a new order. Payment handled via MPP — first request returns 402 challenge, agent pays, then retries with receipt. Always look up the product first with GET /api/products. Successful responses include a buyerToken for checking order and refund status later.
Base URL
https://api.agentmall.sh
Headers
Content-Type: application/json (required)Authorization: MPP payment receipt (included on retry after 402)
Request body
itemsarrayrequiredProducts to order
items[].product_urlstringrequiredDirect product page URL (no short links)
items[].quantityintegerNumber of units. Default: 1
items[].variantarrayVariant selections [{label, value}], e.g. [{label: "Color", value: "Black"}]
delivery_addressobjectrequiredUS shipping address
delivery_address.first_namestringrequiredRecipient first name
delivery_address.last_namestringrequiredRecipient last name
delivery_address.address_line1stringrequiredStreet address
delivery_address.address_line2stringApt, suite, etc.
delivery_address.citystringrequiredCity
delivery_address.statestring2-letter state code
delivery_address.postal_codestringrequiredZIP code
delivery_address.phone_numberstringrequiredE.164 format with +1 (e.g. +14155550100)
delivery_address.countrystringrequiredMust be "US"
max_budgetintegerrequiredMaximum price in cents. Use suggestedMaxBudget from product lookup. Service fee of $1.50 is added on top.
buyer_emailstringrequiredEmail for order notifications (placed, shipped, delivered, failed)
idempotency_keystringUUID to prevent duplicate orders. Safe for retries.
metadataobjectArbitrary key-value data
Responses
201 Created
{ "id": "pur_1Mo5rKYlo2C8xQ", "status": "submitted", "buyerToken": "amtk_..." }200 Deduplicated
{ "id": "pur_1Mo5rKYlo2C8xQ", "status": "submitted", "buyerToken": "amtk_...", "deduplicated": true }402 Payment Required
WWW-Authenticate: Payment method="tempo", description="Purchase: $79.35 product + $1.50 service fee"
400 Validation Error
{ "error": "Missing required field: buyer_email" }409 Conflict
{ "error": "Payment receipt already used for a different purchase" }429 Rate Limited
{ "error": "Rate limited" }502 Provider Error
{ "error": "Unable to create purchase" }Try it
Description
Retrieve a single purchase using the buyer_token returned by create_purchase. No API key required.
Base URL
https://api.agentmall.sh
Headers
Content-Type: application/json (required)
Request body
idstringrequiredPurchase ID from create response
buyer_tokenstringrequiredOpaque buyer token returned by create_purchase
Responses
200 OK
{ "id": "pur_1Mo5rKYlo2C8xQ", "status": "ordered", "items": [{ "productRef": "https://amazon.com/dp/B0DDQJLVJW", "quantity": 1, "title": "SanDisk 64GB Phone Drive", "price": 2499 }], "maxBudget": 5000, "finalTotal": 2499, "tracking": [{ "carrier": "ups", "tracking_number": "1Z999AA10123456784" }], "failureReason": null, "createdAt": 1711036800000 }400 Bad Request
{ "error": "Missing required field: buyer_token" }401 Unauthorized
{ "error": "Invalid buyer token" }Try it
Description
Retrieve a refund using the buyer_token returned by create_purchase. No API key required.
Base URL
https://api.agentmall.sh
Headers
Content-Type: application/json (required)
Request body
purchase_idstringrequiredPurchase ID from create response
buyer_tokenstringrequiredOpaque buyer token returned by create_purchase
Responses
200 OK
{ "id": "rfd_1Mo5rKYlo2C8xQ", "purchaseId": "pur_1Mo5rKYlo2C8xQ", "amountCents": 1690, "reason": "Order failed: refund full charge of $16.90", "status": "pending", "createdAt": 1711036800000 }400 Bad Request
{ "error": "Missing required field: buyer_token" }401 Unauthorized
{ "error": "Invalid buyer token" }404 Not Found
{ "error": "Not found" }Try it
Fields
idstringrequiredUnique purchase identifier (pur_...)
statusstringrequiredpayment_received, submitted, pending, ordered, failed
itemsarrayrequiredItems with productRef, quantity, title, price
deliveryMethodstringShipping method selected
maxBudgetintegerrequiredMax budget in cents
finalTotalintegerActual total charged in cents (product + tax + shipping)
merchantReferencesarrayRetailer order/confirmation numbers
trackingarrayTracking entries with carrier and tracking number when available
failureReasonstringError code if failed, e.g. budget_exceeded
paymentMethodstring"mpp" when set
metadataobjectArbitrary data from creation
createdAtnumberrequiredUnix timestamp (ms)
updatedAtnumberrequiredUnix timestamp (ms)
Fields
idstringrequiredRefund public identifier
purchaseIdstringrequiredLinked purchase ID
payerAddressstringrequiredWallet receiving the refund
amountCentsintegerrequiredRefund amount in cents
reasonstringrequiredOverpayment or order failure
statusstringrequiredpending, approved, processing, processed, rejected
txHashstringOn-chain transaction hash
createdAtnumberrequiredUnix timestamp (ms)
processedAtnumberWhen refund was sent
01 - Agent sends POST
No payment credential. API returns 402 with WWW-Authenticate header containing the payment challenge.
02 - Agent pays on-chain
Sends USDC on Tempo to recipient address. Amount = max_budget + $1.50 service fee.
03 - Agent retries with receipt
Resends POST with Authorization header containing the payment receipt.
04 - API verifies and creates purchase
Payment verified on-chain. 201 response returned with Payment-Receipt header.
Example with tempo request
tempo request -X POST \
-H "Content-Type: application/json" \
--json '{
"items": [{
"product_url": "https://amazon.com/dp/B0DDQJLVJW",
"quantity": 1
}],
"delivery_address": {
"first_name": "Jane",
"last_name": "Doe",
"address_line1": "123 Main St",
"city": "San Francisco",
"state": "CA",
"postal_code": "94105",
"phone_number": "+14155550100",
"country": "US"
},
"max_budget": 5000,
"buyer_email": "jane@example.com"
}' \
https://api.agentmall.sh/api/purchases↑↓
Scroll123456
Go to sectionsENTERESC
ActionsX
Twitter(X)