Spend Permission

Overview

Spend permissions define spending parameters and budgets for white label programs: purpose, amount, time window, and limits. They are created through the same allocation APIs as agentic flows, but this guide uses spend permission terminology. Each permission goes through an approval process before it becomes active.

Create spend permissions against a spend template (AllocatableType). Configure the template first, then call createActivity with that template’s id.

See also Merchant restriction to limit a spend permission to specific merchants via POST /md/api/Allocations/controlledSave.

Create Spend Permission

Creates a new spend permission for a specific spend template (AllocatableType: category such as Travel, IT, or Meals). The type id in the path selects the spend template. The body defines budget, dates, owner, and optional limits for spending under that permission.

Path Parameters

Request Body

The request body must contain the following required fields and can include optional fields for additional configuration.

Example Request

Using cURL:

curl -X POST https://sandbox.custodia-tech.com/md/api/AllocatableTypes/550e8400-e29b-41d4-a716-446655440000/createActivity \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "x-appid: YOUR_CLIENT_ID" \
  -H "Content-Type: application/json" \
  -d '{
    "amount": 1000,
    "start": "2024-01-15",
    "end": "2024-01-25",
    "ownerId": "user-id-123",
    "currency": "USD",
    "purpose": "Business trip to New York",
    "name": "NYC Business Trip"
  }'

Using JavaScript (fetch):

const allocatableTypeId = '550e8400-e29b-41d4-a716-446655440000';

const response = await fetch(`https://sandbox.custodia-tech.com/md/api/AllocatableTypes/${allocatableTypeId}/createActivity`, {
  method: 'POST',
  headers: {
    'Authorization': `Bearer ${accessToken}`,
    'x-appid': clientId,
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    amount: 1000,
    start: '2024-01-15',
    end: '2024-01-25',
    ownerId: 'user-id-123',
    currency: 'USD',
    purpose: 'Business trip to New York',
    name: 'NYC Business Trip'
  })
});

const spendPermission = await response.json();

Creating a spend permission with spending limits:

Using JavaScript (fetch):

const allocatableTypeId = '550e8400-e29b-41d4-a716-446655440000';

const response = await fetch(`https://sandbox.custodia-tech.com/md/api/AllocatableTypes/${allocatableTypeId}/createActivity`, {
  method: 'POST',
  headers: {
    'Authorization': `Bearer ${accessToken}`,
    'x-appid': clientId,
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    amount: 5000,
    start: '2024-02-01',
    end: '2024-02-28',
    ownerId: 'user-id-123',
    currency: 'USD',
    purpose: 'Monthly IT equipment budget',
    dailyLimit: 500,
    txLimit: 200,
    weekDaysLimit: '1111100', // Monday-Friday only
    hoursLimit: '000000000000111111110000', // 12:00 PM - 10:00 PM only
    txCountLimit: 50
  })
});

const spendPermission = await response.json();

Response

{
  "id": "7f3e2a1b-9c4d-4e8f-a5b6-1c2d3e4f5a6b",
  "subsidiaryId": null,
  "when": "2026-05-13T15:55:24.899Z",
  "status": "new",
  "companyId": "c8f46be5-2dd4-4f2e-8b91-3e7a5d1c9f20",
  "requesterId": "550e8400-e29b-41d4-a716-446655440001",
  "createdById": "550e8400-e29b-41d4-a716-446655440002",
  "workflowId": "default-other-request-approval",
  "associatedId": "25ba8b40-6a52-4a69-ac52-d6d43ac6c5da",
  "associatedType": "restaurant",
  "createdOn": "2026-05-13T15:55:24.899Z",
  "silent": false,
  "budgetId": "d290f1ee-6c54-4b01-9e3e-0242ac130002",
  "budgetIds": [
    "d290f1ee-6c54-4b01-9e3e-0242ac130002"
  ]
}

Get Spend Permissions (Allocations)

Retrieves a list of spend permissions (allocations) that are currently available. You can filter, sort, and paginate the results using query parameters.

Query Parameters

Use the filter query parameter to filter, sort, and paginate results. The filter should be a JSON object passed as a URL-encoded string.

Filter Options

The filter object supports the following properties:

Where Clause Examples

Common filter conditions for the where clause:

Example Requests

Get all active spend permissions for a user:

Using JavaScript (fetch):

const filter = {
  where: {
    ownerId: 'user-id-123',
    status: 'active'
  },
  utilization: true,
  order: 'activationDate DESC'
};

const filterParam = encodeURIComponent(JSON.stringify(filter));
const response = await fetch(`https://sandbox.custodia-tech.com/md/api/Allocations?filter=${filterParam}`, {
  method: 'GET',
  headers: {
    'Authorization': `Bearer ${accessToken}`,
    'x-appid': clientId
  }
});

const spendPermissions = await response.json();

Get active and new spend permissions with utilization metrics:

Using JavaScript (fetch):

const filter = {
  where: {
    ownerId: 'user-id-123',
    status: {inq: ['active', 'new']}
  },
  utilization: true,
  include: ['allocatedTo'],
  order: 'expirationDate ASC',
  limit: 50
};

const filterParam = encodeURIComponent(JSON.stringify(filter));
const response = await fetch(`https://sandbox.custodia-tech.com/md/api/Allocations?filter=${filterParam}`, {
  method: 'GET',
  headers: {
    'Authorization': `Bearer ${accessToken}`,
    'x-appid': clientId
  }
});

const spendPermissions = await response.json();

Search spend permissions by title or purpose:

Using JavaScript (fetch):

const filter = {
  where: {
    ownerId: 'user-id-123',
    or: [
      {title: {like: '%Business Trip%'}},
      {purpose: {like: '%Conference%'}}
    ]
  },
  utilization: true
};

const filterParam = encodeURIComponent(JSON.stringify(filter));
const response = await fetch(`https://sandbox.custodia-tech.com/md/api/Allocations?filter=${filterParam}`, {
  method: 'GET',
  headers: {
    'Authorization': `Bearer ${accessToken}`,
    'x-appid': clientId
  }
});

const spendPermissions = await response.json();

Response

[
  {
    "id": "allocation-id-123",
    "title": "NYC Business Trip",
    "purpose": "Business trip to New York",
    "status": "active",
    "ownerId": "user-id-123",
    "companyId": "company-id-123",
    "amount": 1000,
    "currency": "USD",
    "used": 250,
    "pending": 50,
    "amountLeft": 700,
    "activationDate": "2024-01-15T00:00:00.000Z",
    "expirationDate": "2024-01-25T00:00:00.000Z",
    "activityStart": "2024-01-15",
    "activityEnd": "2024-01-25",
    "boundToCardId": null,
    "allocatedToType": "Travel",
    "created": "2024-01-10T10:00:00.000Z",
    "modified": "2024-01-15T00:00:00.000Z"
  },
  {
    "id": "allocation-id-456",
    "title": "Monthly IT Budget",
    "purpose": "IT equipment and software",
    "status": "active",
    "ownerId": "user-id-123",
    "companyId": "company-id-123",
    "amount": 5000,
    "currency": "USD",
    "used": 1200,
    "pending": 300,
    "amountLeft": 3500,
    "activationDate": "2024-02-01T00:00:00.000Z",
    "expirationDate": "2024-02-28T23:59:59.000Z",
    "activityStart": "2024-02-01",
    "activityEnd": "2024-02-28",
    "boundToCardId": "card-id-789",
    "allocatedToType": "IT",
    "created": "2024-01-25T10:00:00.000Z",
    "modified": "2024-02-01T00:00:00.000Z"
  }
]

Get Spend Permission by ID

Retrieves detailed information about a specific spend permission (allocation) by its ID. After you create a spend permission, use the associatedId from that response as this path’s allocationId (they are the same value).

Path Parameters

Query Parameters

Example Request

Using cURL:

curl -X GET "https://sandbox.custodia-tech.com/md/api/Allocations/allocation-id-123?filter=%7B%22utilization%22%3Atrue%7D" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "x-appid: YOUR_CLIENT_ID"

Using JavaScript (fetch):

const allocationId = 'allocation-id-123';

const filter = {
  utilization: true,
  include: ['allocatedTo', 'budgetAllocations']
};

const filterParam = encodeURIComponent(JSON.stringify(filter));
const response = await fetch(`https://sandbox.custodia-tech.com/md/api/Allocations/${allocationId}?filter=${filterParam}`, {
  method: 'GET',
  headers: {
    'Authorization': `Bearer ${accessToken}`,
    'x-appid': clientId
  }
});

const spendPermission = await response.json();

Response

{
  "id": "allocation-id-123",
  "title": "NYC Business Trip",
  "description": null,
  "purpose": "Business trip to New York",
  "status": "active",
  "ownerId": "user-id-123",
  "companyId": "company-id-123",
  "amount": 1000,
  "currency": "USD",
  "used": 250,
  "pending": 50,
  "amountLeft": 700,
  "activationDate": "2024-01-15T00:00:00.000Z",
  "expirationDate": "2024-01-25T00:00:00.000Z",
  "activityStart": "2024-01-15",
  "activityEnd": "2024-01-25",
  "boundToCardId": null,
  "allocatedToType": "Travel",
  "allocatedToId": "allocatable-type-id",
  "dailyLimit": null,
  "txLimit": null,
  "weekDaysLimit": "1111111",
  "hoursLimit": "111111111111111111111111",
  "txCountLimit": null,
  "merchants": [],
  "keywords": [],
  "created": "2024-01-10T10:00:00.000Z",
  "modified": "2024-01-15T00:00:00.000Z"
}

Spend Permission Fields

The following fields are available in spend permission (allocation) responses:

Balance Update

Adjust the available budget on an existing spend permission (allocation) by posting a manual credit or debit. This uses the allocation updateBalance API. The path id is the spend permission’s allocation id, the same value as associatedId from create activity, or id on GET /md/api/Allocations/{allocationId}.

Headers

Send Content-Type: application/x-www-form-urlencoded. Include Authorization: Bearer {access_token} and x-appid: {clientId} as for other MD API calls.

Form Fields

Example (cURL)

curl -X POST https://sandbox.custodia-tech.com/md/api/Allocations/25ba8b40-6a52-4a69-ac52-d6d43ac6c5da/updateBalance \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "x-appid: YOUR_CLIENT_ID" \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d 'amount=15' \
  -d 'sequence=57547456363'

Using JavaScript (fetch):

const allocationId = '25ba8b40-6a52-4a69-ac52-d6d43ac6c5da';
const body = new URLSearchParams({
  amount: '15',
  sequence: '57547456363'
});

const response = await fetch(`https://sandbox.custodia-tech.com/md/api/Allocations/${allocationId}/updateBalance`, {
  method: 'POST',
  headers: {
    'Authorization': `Bearer ${accessToken}`,
    'x-appid': clientId,
    'Content-Type': 'application/x-www-form-urlencoded'
  },
  body
});

const delta = await response.json();

To reduce the balance by 15 in the same currency, send a negative amount (use a new sequence for a new debit, not a retry):

curl -X POST https://sandbox.custodia-tech.com/md/api/Allocations/25ba8b40-6a52-4a69-ac52-d6d43ac6c5da/updateBalance \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "x-appid: YOUR_CLIENT_ID" \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d 'amount=-15' \
  -d 'sequence=57547456364'

Using JavaScript (fetch):

const allocationId = '25ba8b40-6a52-4a69-ac52-d6d43ac6c5da';
const bodyDebit = new URLSearchParams({
  amount: '-15',
  sequence: '57547456364'
});

const response = await fetch(`https://sandbox.custodia-tech.com/md/api/Allocations/${allocationId}/updateBalance`, {
  method: 'POST',
  headers: {
    'Authorization': `Bearer ${accessToken}`,
    'x-appid': clientId,
    'Content-Type': 'application/x-www-form-urlencoded'
  },
  body: bodyDebit
});

const delta = await response.json();

Response

Success returns a numeric delta (root body): the amount applied after internal rules (for example debits are capped by remaining unused budget).

Lock and unlock spend permission

Lock or unlock an existing spend permission (allocation) by id. Use lock to set the allocation to locked so spending against it is blocked until you call unlock. The path {allocationId} is the spend permission id (same as associatedId from create activity, or id from GET /md/api/Allocations/{allocationId}).

Both calls are POST with no required body. Send Authorization: Bearer {access_token} and x-appid: {clientId} like other MD API calls.

Lock

curl -X POST https://sandbox.custodia-tech.com/md/api/Allocations/25ba8b40-6a52-4a69-ac52-d6d43ac6c5da/lock \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "x-appid: YOUR_CLIENT_ID"

Using JavaScript (fetch):

const allocationId = '25ba8b40-6a52-4a69-ac52-d6d43ac6c5da';

const response = await fetch(`https://sandbox.custodia-tech.com/md/api/Allocations/${allocationId}/lock`, {
  method: 'POST',
  headers: {
    'Authorization': `Bearer ${accessToken}`,
    'x-appid': clientId
  }
});

const allocation = await response.json();

Unlock

curl -X POST https://sandbox.custodia-tech.com/md/api/Allocations/25ba8b40-6a52-4a69-ac52-d6d43ac6c5da/unlock \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "x-appid: YOUR_CLIENT_ID"

Using JavaScript (fetch):

const allocationId = '25ba8b40-6a52-4a69-ac52-d6d43ac6c5da';

const response = await fetch(`https://sandbox.custodia-tech.com/md/api/Allocations/${allocationId}/unlock`, {
  method: 'POST',
  headers: {
    'Authorization': `Bearer ${accessToken}`,
    'x-appid': clientId
  }
});

const allocation = await response.json();

Response (success)

On success the API returns the updated allocation as JSON (root object). The payload is large in production; partners typically care about identity, status, dates, owner, amounts, and category fields. Example shape (ids and values are illustrative):

{
  "id": "25ba8b40-6a52-4a69-ac52-d6d43ac6c5da",
  "title": "August restaurant meals",
  "description": "USD 100 budget for approved restaurant spend",
  "purpose": null,
  "status": "active",
  "activationDate": "2026-08-21T00:00:00.000Z",
  "expirationDate": "2026-08-31T23:59:59.999Z",
  "activityStart": "2026-08-21",
  "activityEnd": "2026-08-31",
  "companyId": "c8f46be5-2dd4-4f2e-8b91-3e7a5d1c9f20",
  "ownerId": "550e8400-e29b-41d4-a716-446655440001",
  "allocatedToType": "restaurant",
  "activityType": "restaurant",
  "amount": 100,
  "currency": "USD",
  "originalAmount": 100,
  "originalCurrency": "USD",
  "boundToCardId": null,
  "version": 2,
  "activityStatus": "approved",
  "createdOn": "2026-05-13T15:55:24.000Z",
  "updatedOn": "2026-05-14T13:12:52.464Z"
}

After lock, expect "status": "locked" when the operation succeeds. After unlock, expect "status": "active" (or the prior non-locked state your workflow allows). Other fields (for example statusChangedById, costCenterIds, actualBudgetId, _history) are returned as in a full allocation record; omit them from integrations unless you need them.

Error Responses

All endpoints may return the following error responses: