Create a spending pool

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,
  "dailyLimit": 100000,
  "monthlyLimit": 400000,
  "requiresAdminApproval": false
}
'

const options = {
  method: 'POST',
  headers: {Authorization: 'Basic <encoded-value>', 'Content-Type': 'application/json'},
  body: JSON.stringify({
    customerId: 'Customer:019542f5-b3e7-1d02-0000-000000000001',
    name: 'Marketing',
    limitType: 'RECURRING',
    limitAmount: 500000,
    allowedPaymentTypes: ['CARDS'],
    currency: 'USD',
    period: 'MONTH',
    perTransactionLimit: 50000,
    dailyLimit: 100000,
    monthlyLimit: 400000,
    requiresAdminApproval: false
  })
};

fetch('https://api.lightspark.com/grid/2025-10-13/spending-pools', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

val client = OkHttpClient()

val mediaType = MediaType.parse("application/json")
val body = RequestBody.create(mediaType, "{\n  \"customerId\": \"Customer:019542f5-b3e7-1d02-0000-000000000001\",\n  \"name\": \"Marketing\",\n  \"limitType\": \"RECURRING\",\n  \"limitAmount\": 500000,\n  \"allowedPaymentTypes\": [\n    \"CARDS\"\n  ],\n  \"currency\": \"USD\",\n  \"period\": \"MONTH\",\n  \"perTransactionLimit\": 50000,\n  \"dailyLimit\": 100000,\n  \"monthlyLimit\": 400000,\n  \"requiresAdminApproval\": false\n}")
val request = Request.Builder()
  .url("https://api.lightspark.com/grid/2025-10-13/spending-pools")
  .post(body)
  .addHeader("Authorization", "Basic <encoded-value>")
  .addHeader("Content-Type", "application/json")
  .build()

val response = client.newCall(request).execute()

{
  "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,
  "dailyLimit": 100000,
  "monthlyLimit": 400000
}

{
  "code": "INVALID_INPUT",
  "reason": "<string>",
  "details": {
    "errors": [
      {
        "field": "identifier",
        "constraint": {
          "format": "email",
          "pattern": "^\\d{5}(-\\d{4})?$",
          "enum": [
            "SSN",
            "ITIN",
            "NON_US_TAX_ID"
          ],
          "minLength": 1,
          "maxLength": 500
        },
        "message": "Value is not one of the allowed enum members."
      }
    ],
    "missingRequirements": [
      "SUPPORTING_PROOF"
    ],
    "refusalReason": "AGENT_POLICY_DENIED",
    "missingFields": [
      "PHONE_NUMBER"
    ]
  }
}

{
  "code": "UNAUTHORIZED",
  "reason": "<string>",
  "details": {}
}

{
  "code": "FORBIDDEN",
  "reason": "<string>",
  "details": {
    "refusalReason": "AGENT_POLICY_DENIED",
    "permission": "ISSUE_CARDS",
    "policyDenialReason": "DAILY_LIMIT_EXCEEDED"
  }
}

{
  "code": "TRANSACTION_NOT_FOUND",
  "reason": "<string>",
  "details": {}
}

{
  "code": "GRID_SWITCH_ERROR",
  "reason": "<string>",
  "details": {}
}

Agent Management

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.

POST

spending-pools

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,
  "dailyLimit": 100000,
  "monthlyLimit": 400000,
  "requiresAdminApproval": false
}
'

const options = {
  method: 'POST',
  headers: {Authorization: 'Basic <encoded-value>', 'Content-Type': 'application/json'},
  body: JSON.stringify({
    customerId: 'Customer:019542f5-b3e7-1d02-0000-000000000001',
    name: 'Marketing',
    limitType: 'RECURRING',
    limitAmount: 500000,
    allowedPaymentTypes: ['CARDS'],
    currency: 'USD',
    period: 'MONTH',
    perTransactionLimit: 50000,
    dailyLimit: 100000,
    monthlyLimit: 400000,
    requiresAdminApproval: false
  })
};

fetch('https://api.lightspark.com/grid/2025-10-13/spending-pools', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

val client = OkHttpClient()

val mediaType = MediaType.parse("application/json")
val body = RequestBody.create(mediaType, "{\n  \"customerId\": \"Customer:019542f5-b3e7-1d02-0000-000000000001\",\n  \"name\": \"Marketing\",\n  \"limitType\": \"RECURRING\",\n  \"limitAmount\": 500000,\n  \"allowedPaymentTypes\": [\n    \"CARDS\"\n  ],\n  \"currency\": \"USD\",\n  \"period\": \"MONTH\",\n  \"perTransactionLimit\": 50000,\n  \"dailyLimit\": 100000,\n  \"monthlyLimit\": 400000,\n  \"requiresAdminApproval\": false\n}")
val request = Request.Builder()
  .url("https://api.lightspark.com/grid/2025-10-13/spending-pools")
  .post(body)
  .addHeader("Authorization", "Basic <encoded-value>")
  .addHeader("Content-Type", "application/json")
  .build()

val response = client.newCall(request).execute()

{
  "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,
  "dailyLimit": 100000,
  "monthlyLimit": 400000
}

{
  "code": "INVALID_INPUT",
  "reason": "<string>",
  "details": {
    "errors": [
      {
        "field": "identifier",
        "constraint": {
          "format": "email",
          "pattern": "^\\d{5}(-\\d{4})?$",
          "enum": [
            "SSN",
            "ITIN",
            "NON_US_TAX_ID"
          ],
          "minLength": 1,
          "maxLength": 500
        },
        "message": "Value is not one of the allowed enum members."
      }
    ],
    "missingRequirements": [
      "SUPPORTING_PROOF"
    ],
    "refusalReason": "AGENT_POLICY_DENIED",
    "missingFields": [
      "PHONE_NUMBER"
    ]
  }
}

{
  "code": "UNAUTHORIZED",
  "reason": "<string>",
  "details": {}
}

{
  "code": "FORBIDDEN",
  "reason": "<string>",
  "details": {
    "refusalReason": "AGENT_POLICY_DENIED",
    "permission": "ISSUE_CARDS",
    "policyDenialReason": "DAILY_LIMIT_EXCEEDED"
  }
}

{
  "code": "TRANSACTION_NOT_FOUND",
  "reason": "<string>",
  "details": {}
}

{
  "code": "GRID_SWITCH_ERROR",
  "reason": "<string>",
  "details": {}
}

Authorizations

Authorization

string

header

required

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

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

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

Spending pool 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.

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

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

Using the API

API documentation

Create a spending pool

Authorizations

Body

Response