Spend controls & MCC

Constrain how much, when, how often, and where a card can spend.

Every card carries a restrictions object — set at creation, adjustable later via PATCH /v1/cards/{id}. Four controls compose:

restrictions
├── spendLimit            required   caps total spend
├── activeDateRangeUTC    optional   bounds when the card can transact
├── maxTransactionCount   optional   caps usage, 1–10
└── merchantCategory      optional   allow/block merchant category groups

Spend limit

spendLimit is the maximum total amount the card can spend, in the card's local currency, and must be greater than 0. It is the only required restriction.

Active date range

activeDateRangeUTC.startDate / endDate (UTC timestamps) define the window in which the card can transact. Before startDate and after endDate, authorizations decline. Use it to make a card exist only for the trip, event, or billing period it was issued for.

{
  "activeDateRangeUTC": {
    "startDate": "2026-10-01 00:00:00",
    "endDate": "2026-10-15 23:59:59"
  }
}

Transaction count

maxTransactionCount (1–10) caps how many transactions the card can make. 1 produces a single-use card — the standard pattern for supplier payments and travel VCNs.

Merchant category controls

merchantCategory restricts where the card works, at the level of Jeeves category groups (each group maps to a set of ISO 18245 MCC codes):

{
  "merchantCategory": {
    "mode": "allow",
    "categoryIds": ["Airfare", "Lodging & Accommodations"]
  }
}

Discovering categories

GET /v1/cards/mcc/categories (scope cards:read) returns every category group with the MCC codes it contains:

curl 'https://public-sandbox.tryjeeves.com/v1/cards/mcc/categories' \
  -H "Authorization: Bearer $JEEVES_ACCESS_TOKEN"

{
  "rows": [
    {
      "merchantCategoryId": "Lodging & Accommodations",
      "merchantCategoryName": "Lodging",
      "merchantCategoryCodes": [
        { "code": "7011", "name": "Hotels, Motels, and Resorts" }
      ]
    }
  ],
  "count": 22
}

The 22 category groups:

Accounting · Airfare · Conference & Events · Contractor Services · Equipment Expense · Freight & Shipping · Insurance · Legal Expense · Lodging & Accommodations · Marketing · Meals & Entertainment · Membership Dues & Subscriptions · Office Expense · Other Expense · Other Miscellaneous · Postage & Shipping · Rent · Retail Purchases · Software Expense · Taxes and Licensing · Transportation Services · Utility Services

Use the merchantCategoryId values as categoryIds in the control. These are exact string identifiers — copy them verbatim from this endpoint (including capitalization, spacing, and the &); they are stable and not localized. Note these are Jeeves merchant category groups (expense-style groupings of ISO 18245 MCC codes), not the raw MCC taxonomy itself.

Changing controls later

All four controls are updatable in place — see Updating & deleting. Raising a spend limit or adding a category does not reissue the card; the change applies to the next authorization.

Composition example: a conference card

Spend up to $2,500, only during the event week, only on lodging and meals, at most 10 transactions:

curl -X POST \
  'https://public-sandbox.tryjeeves.com/v1/cards' \
  -H "Authorization: Bearer $JEEVES_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Conference Card",
    "restrictions": {
      "spendLimit": 2500,
      "activeDateRangeUTC": {
        "startDate": "2026-11-02 00:00:00",
        "endDate": "2026-11-08 23:59:59"
      },
      "maxTransactionCount": 10,
      "merchantCategory": {
        "mode": "allow",
        "categoryIds": ["Lodging & Accommodations", "Meals & Entertainment"]
      }
    }
  }'