Skip to main content

​
Endpoint

POST /v1/budget/debit

​
Authentication

Requires a developer API key in the Authorization header.

​
Request Headers

HeaderValue
AuthorizationBearer <api_key>
Content-Typeapplication/json

​
Request Body

FieldTypeRequiredDescription
grantIdstringYesThe grant whose budget to debit
amountnumberYesThe amount to debit (must be positive)
descriptionstringNoHuman-readable description of the charge
metadataobjectNoArbitrary metadata to attach to the transaction

​
Example Request

curl -X POST https://grantex-auth-dd4mtrt2gq-uc.a.run.app/v1/budget/debit \
  -H "Authorization: Bearer gx_..." \
  -H "Content-Type: application/json" \
  -d '{
    "grantId": "grnt_01HXYZ...",
    "amount": 5.50,
    "description": "GPT-4 API call",
    "metadata": { "model": "gpt-4", "tokens": 1500 }
  }'

​
Response — 200 OK

{
  "remaining": 94.50,
  "transactionId": "txn_01HXYZ...",
  "grantId": "grnt_01HXYZ..."
}

​
Response Fields

FieldTypeDescription
remainingnumberBudget remaining after the debit
transactionIdstringUnique transaction ID for this debit
grantIdstringThe grant that was debited

​
Error Responses

StatusCodeDescription
400BAD_REQUESTMissing grantId or amount not positive
401UNAUTHORIZEDInvalid or missing API key
402INSUFFICIENT_BUDGETThe grant’s remaining budget is less than the requested amount

​
SDK Examples

import Grantex from '@grantex/sdk';

const grantex = new Grantex({ apiKey: 'gx_...' });

const result = await grantex.budgets.debit({
  grantId: 'grnt_01HXYZ...',
  amount: 5.50,
  description: 'GPT-4 API call',
});
// result.remaining === 94.50