Agent Spending
Let an API token or MCP client place orders from your credit balance, within a monthly cap you set, with email approval above it.
By default an agent can start an order but cannot pay for it. Orders it creates wait at their checkout_link for a person to pay. A spend grant lets one API token (or one MCP connection) pay for orders from your team's credit balance, within a monthly cap.
The rules
- Credits only. A granted agent pays from the balance. It never buys credits and never starts a card payment. If the balance cannot cover an order, the request is refused (
402). - Off by default. No token or MCP connection can spend until a team owner or admin switches it on. This includes existing tokens: before spend grants, a token paid from credits by default, and it now needs a grant to do so.
- Monthly cap. Each grant has a cap,
$1,000per UTC calendar month unless you change it. Spend counts from the moment an order is placed and resets at the start of the next UTC month. Refunds do not restore the cap. - Over the cap, ask first. An order that would pass the cap is held: nothing is placed or charged, and the grant owner gets an email with Approve and Decline links.
- The owner. For an API token, the owner is the person who created it. For an MCP connection, it is the person who connected it. The owner's account is also the buyer recorded on the orders.
Turn it on
In the app, open API Keys and switch on Let agents spend credits for a token, then set its cap. Only team owners and admins can do this, and a token can never change its own cap.
The same settings are available to a signed-in team owner or admin at PUT /teams/{team_id}/agent-spend-grants with { "api_key_id": "...", "monthly_cap": 1000 }. Send oauth_grant_id instead for an MCP connection; only the person who connected it can switch it on. Call it again to change the cap, and DELETE /teams/{team_id}/agent-spend-grants/{grant_id} takes the ability away at once, after which any held order of that token can no longer be approved.
What the agent sees
POST /orders/checkout behaves as before, plus:
| Situation | Response |
|---|---|
| Inside the cap, balance covers it | 200, the order, already PAID |
| Would pass the cap | 202 { "status": "pending_approval", "approval_id": "...", "amount": 300, "monthly_cap": 250, "spent_this_month": 200, "expires_at": "..." } |
| Balance does not cover it | 402 code: "INSUFFICIENT_CREDIT_BALANCE", with required, available and shortfall in meta. Ask a person to add credits |
| Token has no spend grant | 200, an unpaid order with a checkout_link (credits are not applied) |
| Approval email could not be sent | 503 code: "APPROVAL_EMAIL_FAILED". Nothing was held; retry shortly |
| Same cart still waiting for its approval email | 503 code: "APPROVAL_EMAIL_PENDING". The first identical request is still sending the email; retry shortly |
Do not resend a held order. Resending the same cart returns the same pending approval without another email. If the cart's price changed since it was held and it still passes the cap, a resend holds it again at the new price with a new approval email, and the old approval stops working. Checking the held order's state is cleaner:
curl "https://api.presscart.com/orders/approvals/APPROVAL_ID" \
-H "Authorization: Bearer $PRESSCART_API_TOKEN"It answers PENDING, APPROVED (with order_reference), DECLINED or EXPIRED. Only the token the order was held for can read it, and it needs the orders.read scope. MCP clients use GET /teams/{team}/orders/approvals/{approval_id}.
Approving
The email links open a page in the Presscart app. The owner must be signed in, sees what was ordered and what it costs, and presses Approve and place order or Decline. Opening the link changes nothing, so email scanners are harmless. Each link works once and expires after 48 hours.
Approving places the order from the balance, even though it passes the cap, and counts it toward that month. It is refused if the balance no longer covers the order, or if the price went up since the owner was emailed (the agent must order again).
Topping up
When the balance is short, a person adds credits in the app, then the agent can order again.