Update a spending pool

Change a spending pool’s name, limits, allowed payment types or admin-approval flag. The change applies to payments decided after it.

PATCH /spending-pools/{spendingPoolId}

Update a spending pool

cURL

curl --request PATCH \
  --url https://api.lightspark.com/grid/2025-10-13/spending-pools/{spendingPoolId} \
  --header 'Authorization: Basic <encoded-value>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "name": "Marketing",
  "limitType": "RECURRING",
  "period": "MONTH",
  "limitAmount": 600000,
  "perTransactionLimit": 50000,
  "approvalThreshold": 25000,
  "dailyLimit": 100000,
  "monthlyLimit": 400000,
  "allowedPaymentTypes": [
    "CARDS",
    "BANK_PAYOUTS"
  ],
  "requiresAdminApproval": true
}
'

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>

Path Parameters

spendingPoolId · string · required

System-generated unique spending pool identifier

Body

application/json

Partial update to a spending pool. At least one field must be provided. A cap or approvalThreshold set to null is removed. Changing limitType to RECURRING requires period; changing it to TOTAL removes period. Lowering a limit below what is already spent refuses further payments; it never reverses one.

name · string

Required string length: 1 - 255

Example:

"Marketing"

limitType · enum<string>

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"

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"

limitAmount · integer<int64>

Required range: x >= 1

Example:

600000

perTransactionLimit · integer<int64> | null

Required range: x >= 1

Example:

50000

approvalThreshold · integer<int64> | null

Required range: x >= 0

Example:

25000

dailyLimit · integer<int64> | null

Required range: x >= 1

Example:

100000

monthlyLimit · integer<int64> | null

Required range: x >= 1

Example:

400000

allowedPaymentTypes · enum<string>[]

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", "BANK_PAYOUTS"]

requiresAdminApproval · boolean

Example:

true

Response

200

application/json

Spending pool updated

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