Create a spending pool

Create a spending pool on a customer. Agents assigned to it (with spendingPoolId on POST /agents or PATCH /agents/{agentId}) are held to its limits and allowed payment types together, in addition to each agent’s own policy. Available where the platform enables spending pools.

Every agent payment checks the pool: sends (including Lightning), bank payouts and card authorizations. A payment the pool refuses is rejected with AGENT_POLICY_DENIED and details.policyDenialReason POOL_LIMIT_EXCEEDED or POOL_PAYMENT_TYPE_NOT_ALLOWED; a card authorization is declined. Payments in flight hold their amount against the pool until they complete or fail, so concurrent payments cannot together exceed it. RECURRING limits reset on UTC calendar boundaries.

Send an Idempotency-Key header to make retries safe: a request carrying a key already used returns the pool the first request created, with a 200 instead of a 201. The request is compared with the pool as it is now, so reusing a key with a different name, currency, limit type, period, limit amount, per-transaction limit, approval threshold, daily limit, monthly limit, allowed payment types or requiresAdminApproval, after the pool was changed, or for a pool that was archived is rejected with 409. Without a key a retry cannot be recognised, so each request creates its own pool. Keys are scoped to the customer, so the same key on another customer creates a separate pool.

POST /spending-pools

Create a spending pool

cURL

curl --request POST \
  --url https://api.lightspark.com/grid/2025-10-13/spending-pools \
  --header 'Authorization: Basic <encoded-value>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "customerId": "Customer:019542f5-b3e7-1d02-0000-000000000001",
  "name": "Marketing",
  "limitType": "RECURRING",
  "limitAmount": 500000,
  "allowedPaymentTypes": [
    "CARDS"
  ],
  "currency": "USD",
  "period": "MONTH",
  "perTransactionLimit": 50000,
  "approvalThreshold": 25000,
  "dailyLimit": 100000,
  "monthlyLimit": 400000,
  "requiresAdminApproval": false
}
'

200

{
  "id": "SpendingPool:019542f5-b3e7-1d02-0000-000000000007",
  "customerId": "Customer:019542f5-b3e7-1d02-0000-000000000001",
  "name": "Marketing",
  "currency": "USD",
  "limitType": "RECURRING",
  "limitAmount": 500000,
  "allowedPaymentTypes": [
    "CARDS",
    "CRYPTO_SENDS"
  ],
  "requiresAdminApproval": false,
  "isArchived": false,
  "usage": {
    "spent": 125000,
    "remaining": 375000,
    "dailySpent": 2500,
    "monthlySpent": 125000,
    "periodStart": "2026-11-01",
    "periodEnd": "2026-12-01"
  },
  "createdAt": "2026-11-02T17:32:28Z",
  "updatedAt": "2026-11-02T17:32:28Z",
  "period": "MONTH",
  "perTransactionLimit": 50000,
  "approvalThreshold": 25000,
  "dailyLimit": 100000,
  "monthlyLimit": 400000
}

Authorizations

Authorization · string · header · required

API token authentication using format <api token id>:<api client secret>

Headers

Idempotency-Key · string

A unique identifier for the request. A retry with the same key returns the pool the first request created rather than creating a second one.

Maximum string length: 255

Example:

"550e8400-e29b-41d4-a716-446655440000"

Body

application/json

Request body for POST /spending-pools. period is required with limitType: RECURRING and rejected with TOTAL.

customerId · string · required

The customer whose agents will spend under the pool.

Example:

"Customer:019542f5-b3e7-1d02-0000-000000000001"

name · string · required

Required string length: 1 - 255

Example:

"Marketing"

limitType · enum<string> · required

How a spending pool's limitAmount applies.

Value	Description
RECURRING	Resets at the start of each period (UTC calendar week starting Monday, or calendar month)
TOTAL	A running total that never resets; raise limitAmount to allow more

Available options: RECURRING, TOTAL

Example:

"RECURRING"

limitAmount · integer<int64> · required

Required range: x >= 1

Example:

500000

allowedPaymentTypes · enum<string>[] · required

A kind of agent payment a spending pool may allow.

Value	Description
CARDS	Authorizations on the agents' cards
CRYPTO_SENDS	Sends to crypto destinations, Spark and Lightning included
BANK_PAYOUTS	Payouts to bank accounts

Available options: CARDS, CRYPTO_SENDS, BANK_PAYOUTS

Example:

["CARDS"]

currency · string

ISO 4217 currency code of the pool's amounts. Defaults to USD.

Example:

"USD"

period · enum<string>

The UTC calendar period a RECURRING pool's limit resets on: a calendar month, or a week starting Monday 00:00 UTC.

Available options: MONTH, WEEK

Example:

"MONTH"

perTransactionLimit · integer<int64>

Required range: x >= 1

Example:

50000

approvalThreshold · integer<int64>

A payment by one of the pool's agents above this amount waits for approval. Absent means the agents' own policies alone decide.

Required range: x >= 0

Example:

25000

dailyLimit · integer<int64>

Required range: x >= 1

Example:

100000

monthlyLimit · integer<int64>

Required range: x >= 1

Example:

400000

requiresAdminApproval · boolean · default: false

Example:

false

Response

200

application/json

The Idempotency-Key was already used for this request: the pool the first request created

A spending limit shared by the agents assigned to it, on their customer's balance. A pool holds no money and no money moves between pools: it only limits what its agents may spend, in addition to each agent's own policy. Limits of different pools may add up to more than the balance. Each agent belongs to at most one pool.

id · string · required

System-generated unique identifier for the pool.

Example:

"SpendingPool:019542f5-b3e7-1d02-0000-000000000007"

customerId · string · required

The customer whose agents spend under the pool.

Example:

"Customer:019542f5-b3e7-1d02-0000-000000000001"

name · string · required

Human-readable name for the pool.

Example:

"Marketing"

currency · string · required

ISO 4217 currency code all of the pool's amounts are in. Only agents whose policy is in the same currency may be assigned to it. Immutable.

Example:

"USD"

limitType · enum<string> · required

How a spending pool's limitAmount applies.

Value	Description
RECURRING	Resets at the start of each period (UTC calendar week starting Monday, or calendar month)
TOTAL	A running total that never resets; raise limitAmount to allow more

Available options: RECURRING, TOTAL

Example:

"RECURRING"

limitAmount · integer<int64> · required

The most the pool's agents may spend together: per period for a RECURRING pool, in total for a TOTAL one.

Required range: x >= 1

Example:

500000

allowedPaymentTypes · enum<string>[] · required

The kinds of payment the pool's agents may make. Any other is refused with policyDenialReason POOL_PAYMENT_TYPE_NOT_ALLOWED.

A kind of agent payment a spending pool may allow.

Value	Description
CARDS	Authorizations on the agents' cards
CRYPTO_SENDS	Sends to crypto destinations, Spark and Lightning included
BANK_PAYOUTS	Payouts to bank accounts

Available options: CARDS, CRYPTO_SENDS, BANK_PAYOUTS

Example:

["CARDS", "CRYPTO_SENDS"]

requiresAdminApproval · boolean · required

Whether the platform requires an administrator to approve the pool's agents' payments that need approval. Grid stores it for the platform and does not act on it.

Example:

false

isArchived · boolean · required

Whether the pool was archived. An archived pool takes no agents and cannot be changed.

Example:

false

usage · object · required

What the pool's agents have spent, counting payments still in flight, as of the request. Amounts are in the smallest unit of the pool's currency.

Show child attributes

createdAt · string<date-time> · required

Creation timestamp.

Example:

"2026-11-02T17:32:28Z"

updatedAt · string<date-time> · required

Last update timestamp.

Example:

"2026-11-02T17:32:28Z"

period · enum<string>

The period a RECURRING pool resets on. Absent for TOTAL.

Available options: MONTH, WEEK

Example:

"MONTH"

perTransactionLimit · integer<int64>

The most a single payment may be. Absent for no cap.

Required range: x >= 1

Example:

50000

approvalThreshold · integer<int64>

A payment by one of the pool's agents above this amount waits for approval, even when the agent's own policy would execute it at once. In the pool's currency. Absent means the agents' own policies alone decide. Card authorizations are never held for approval.

Required range: x >= 0

Example:

25000

dailyLimit · integer<int64>

The most the pool's agents may spend together per UTC day. Absent for no cap.

Required range: x >= 1

Example:

100000

monthlyLimit · integer<int64>

The most the pool's agents may spend together per UTC calendar month. Absent for no cap.

Required range: x >= 1

Example:

400000