Set limits

Cap how much you and each of your agents can move per transaction, per day, and per month. For how the levels combine, read the Limits overview. Each limit applies to a single payment (perTransaction), a UTC calendar day (perDay), or a calendar month (perMonth).

A limit never automatically fails a payment. A payment that breaches a limit returns a normal 2xx, no money moves, and it holds as an approval until someone approves or denies it. See Approve or deny a held payment.

Account limits

Your account limits are the backstop over everything you and every agent do.

Read your limits

GET /parties/me/limits returns the current limits. When no limit is set, limits is null.

limits = client.parties.get_limits()

const limits = await client.parties.getLimits();

natural parties get-limits

What are my account spending limits?

curl https://api.natural.com/parties/me/limits \
  -H "Authorization: Bearer $NATURAL_API_KEY"

Set your limits

PUT /parties/me/limits replaces all three windows at once. It requires party.update; agent keys cannot call it.

limits = client.parties.set_limits(
    per_transaction=250_000,  # $2,500 per payment
    per_day=1_000_000,        # $10,000 per day
    per_month=None,           # no monthly limit
)

const limits = await client.parties.setLimits({
  perTransaction: 250_000, // $2,500 per payment
  perDay: 1_000_000, // $10,000 per day
  perMonth: null, // no monthly limit
});

natural parties set-limits --per-transaction 250000 --per-day 1000000

curl -X PUT https://api.natural.com/parties/me/limits \
  -H "Authorization: Bearer $NATURAL_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "data": {
      "attributes": {
        "perTransaction": 250000,
        "perDay": 1000000,
        "perMonth": null
      }
    }
  }'

Remove all limits

DELETE /parties/me/limits clears every window in one call. To clear just one window, PUT that window as null and keep the others. Removing your account limits does not touch an agent’s own limits or a limit a customer set on your agent; clear those where you set them.

client.parties.disable_limits()

await client.parties.disableLimits();

natural parties disable-limits

curl -X DELETE https://api.natural.com/parties/me/limits \
  -H "Authorization: Bearer $NATURAL_API_KEY"

Agent limits

Give one agent (agt_*) a tighter budget than the rest of your account. Set limits when you create the agent with limits on POST /agents. To change them afterward, PATCH /agents/{agentId}. limits is a full replacement: sending it resets every window to what you pass.

import uuid

agent = client.agents.update(
    "agt_019cd1798d637a4da75dce386343931d",
    idempotency_key=str(uuid.uuid4()),
    limits={"per_transaction": 100_000},  # $1,000; clears perDay and perMonth
)

const agent = await client.agents.update({
  agentId: "agt_019cd1798d637a4da75dce386343931d",
  idempotencyKey: crypto.randomUUID(),
  limits: { perTransaction: 100_000 }, // $1,000; clears perDay and perMonth
});

natural agents update --agent-id agt_019cd1798d637a4da75dce386343931d \
  --idempotency-key "$(uuidgen)" \
  --json '{"limits": {"perTransaction": 100000}}'

curl -X PATCH https://api.natural.com/agents/agt_019cd1798d637a4da75dce386343931d \
  -H "Authorization: Bearer $NATURAL_API_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{
    "data": {
      "attributes": {
        "limits": { "perTransaction": 100000 }
      }
    }
  }'

How limits compose

A payment can pass through several limits: your account limit, the agent limit, and limits set by your customer. They are independent gates with no precedence: every applicable one must clear, so in effect the tightest limit wins.

Level	Limits	Set by
Account	`perTransaction`, `perDay`, `perMonth`	You, for your whole account
Agent	`perTransaction`, `perDay`, `perMonth`	You, per agent
On a customer’s behalf	`perTransaction` only	A customer, when they authorize your agent

A payment that breaches any limit holds for approval. All limits must clear or be approved for a payment to complete.

Overview

Common use cases

Products

Guides

Account limits

Read your limits

Set your limits

Remove all limits

Agent limits

How limits compose

​Account limits

​Read your limits

​Set your limits

​Remove all limits

​Agent limits

​How limits compose

Account limits

Read your limits

Set your limits

Remove all limits

Agent limits

How limits compose