Activating a listing creates an order. ZAM validates your input, signs the request with HMAC, calls the seller’s endpoint, and returns the result.
Prerequisites
- A ZAM API key with
order:create scope
- The ID of a
published listing
Activate
zam activate LISTING_ID --request-body '{"city": "San Francisco"}'
zam activate LISTING_ID --timeout 30 --request-body '{"city": "San Francisco"}'
curl -X POST https://api.zeroclick.am/v1/orders \
-H "Content-Type: application/json" \
-H "x-zam-api-key: zam_your_key_here" \
-d '{
"listingId": "LISTING_ID",
"requestBody": {"city": "San Francisco"}
}'
requestBody field is optional. Omit it for listings that take no input.Response:{
"id": "ORDER_ID",
"listingId": "LISTING_ID",
"orderState": "completed",
"result": {"forecast": "sunny, 72°F"},
"startedAt": "2025-01-15T10:30:00Z",
"completedAt": "2025-01-15T10:30:00Z"
}
completed (or failed) state with the result inline. Otherwise, the order returns as pending — poll for the result.
- Find a listing on the marketplace.
- Click Activate this Zam.
- Fill in any required fields (generated from the listing’s input schema).
- Confirm the activation.
- View the result on the Activations page in your dashboard.
What happens during activation
- ZAM validates your
requestBody against the listing’s inputSchema (if defined). Invalid input returns 400.
- ZAM creates an order in
pending state.
- ZAM signs the request with HMAC-SHA256 (if the seller has a signing secret) and calls the seller’s endpoint with a 30-second timeout.
- On success, the order moves to
completed and stores the response. On failure, it moves to failed and stores the error.
As a buyer, you don’t need to worry about HMAC signing — ZAM handles it automatically. The signing ensures the seller can trust the request came from ZAM.
Error cases
| HTTP status | Cause |
|---|
| 400 | Request body fails input schema validation |
| 401 | Missing or invalid API key |
| 403 | API key lacks order:create scope |
| 404 | Listing not found |
| 422 | Listing exists but has no run contract |
| 429 | Seller’s service has reached its invocation limit |
