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

{
  "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
}

{
  "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": "TRANSACTION_NOT_PENDING_PLATFORM_APPROVAL",
  "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.

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 --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
}
'

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

{
  "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
}

{
  "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": "TRANSACTION_NOT_PENDING_PLATFORM_APPROVAL",
  "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>

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

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.

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

Using the API

API documentation

Create a spending pool

Authorizations

Headers

Body

Response