Spend control

Spend control lets you declare velocity caps on each card without tracking the cardholder’s accrued spend yourself. You set the caps; the issuer enforces them at authorization time. Each card has two transaction-type buckets:

sales — purchase (point-of-sale) transactions
cash — cash withdrawal (ATM) transactions

Each bucket accepts up to six independent caps. Omit a key to leave that bucket uncapped on that horizon.

Cap key	Meaning
`perTransaction`	Maximum amount per single transaction
`daily`	Maximum total amount per calendar day
`monthly`	Maximum total amount per calendar month
`allTime`	Maximum total amount over the card’s lifetime

Set spend control

curl -X PATCH https://api.contro.me/v1/partner/cards/card_def456/limits \
  -H "x-contro-api-key: $CONTRO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "spendControl": {
      "sales": { "perTransaction": 200, "daily": 1000, "allTime": 50000 },
      "cash": { "allTime": 0 }
    }
  }'

await contro.cards.updateLimits("card_def456", {
  spendControl: {
    sales: { perTransaction: 200, daily: 1000, allTime: 50000 },
    cash: { allTime: 0 },
  },
});

The example above caps in-store purchases at $200 per transaction, $1,000 per day, and $50,000 over the card’s lifetime — and disables cash withdrawals entirely by setting an allTime cap of 0.

Read spend control

GET /partner/cards/{id} returns the active caps under spendControl. Where the card program supports it, accrued spend is reported under spendControl.spent:

{
  "id": "card_def456",
  "spendControl": {
    "sales": { "daily": 1000, "allTime": 50000 },
    "cash": { "allTime": 0 },
    "spent": {
      "sales": { "daily": 142.5, "allTime": 8420.10 }
    }
  }
}

Common patterns

Cash-disabled card. Set cash.allTime: 0 to block ATM withdrawals while leaving purchases uncapped.

{ "spendControl": { "cash": { "allTime": 0 } } }

Lifetime budget card. Cap total purchases over the card’s lifetime — useful for one-shot expense cards or per-vendor budgets.

{ "spendControl": { "sales": { "allTime": 1500 } } }

Daily allowance. Cap purchases per calendar day with a per-transaction ceiling for fraud control.

{
  "spendControl": {
    "sales": { "perTransaction": 100, "daily": 200 }
  }
}

Card program capabilities

Not every card program supports every cap horizon. Caps a program cannot enforce are rejected at request time with a 400 and the message Card program "<name>" does not support <capKey> spend-control cap. Ask your Contro admin which caps the programs assigned to your account support.

Migrating from `{ limit }`

The legacy body { "limit": 5000 } is still accepted on PATCH /partner/cards/{id}/limits and is mapped to:

{
  "spendControl": {
    "sales": { "allTime": 5000 },
    "cash":  { "allTime": 5000 }
  }
}

Send null to clear the cap. The legacy limit field will be removed in a future release — switch to spendControl to take advantage of per-transaction-type caps and finer-grained horizons.

Getting started

Core resources

Platform

Set spend control

Read spend control

Common patterns

Card program capabilities

Migrating from `{ limit }`

​Set spend control

​Read spend control

​Common patterns

​Card program capabilities

​Migrating from { limit }

Set spend control

Read spend control

Common patterns

Card program capabilities

Migrating from `{ limit }`