> This page is for version v2026-04-01 (default).
> For other versions, use one of these documentation indexes:
> - v2026-04-01 (default): https://docs.givechariot.com/v2026-04-01/llms.txt

> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://docs.givechariot.com/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.givechariot.com/_mcp/server.

# Creating Grants

## Create the Grant

Once `CHARIOT_SUCCESS` fires, call [Create Grant](/api/grants/create) from your server to submit the gift. The call is made with your server-side credentials, never from the browser; see [Authentication](/api/authentication) for keys and base URLs.

### Request

POST [https://api.givechariot.com/v1/grants](https://api.givechariot.com/v1/grants)

**`Simple grant output`**

```curl Simple grant output
curl -X POST https://api.givechariot.com/v1/grants \
     -H "Authorization: Bearer <token>" \
     -H "Content-Type: application/json" \
     -d '{
  "workflowSessionId": "string",
  "amount": 15000
}'
```

**`Simple grant output`**

```typescript Simple grant output
import { ChariotClient } from "@chariot-giving/typescript-sdk";

async function main() {
    const client = new ChariotClient({
        token: "YOUR_TOKEN_HERE",
    });
    await client.grants.create({
        workflowSessionId: "string",
        amount: 15000,
    });
}
main();

```

### Server-Side Sequence

1. Receive the workflow session ID and amount returned by DAFpay.
2. Resolve the nonprofit and platform transaction from your stored session record.
3. Save the platform transaction, and submit your own donation form first.
4. Call [Create Grant](/api/grants/create) with the server-side API key.
5. Store the Grant ID and response.

> **Submit Your Form First**
>
> If your form fails after the Grant exists, the donor sees an error for a gift that was already submitted to their DAF provider, with no way to tell.

Complete this sequence within 15 minutes of authorization.

**Loading screen:** Show a loading state while your server calls Create Grant, and show final success only once the Grant exists. If the request is queued for retry, show a pending message until Grant creation is confirmed.

![](/_fern-files/_img/d1df2925ba2cca6241f140c36c402fc6557e818832404cc0586204482fdd500b.webp)![](/_fern-files/_img/79146b327d920082d558e486410e7cdf0b829a9d67c13f216d4fb7f3a7711c2c.webp)

**Success screen:** A created Grant means the gift was successfully initiated, not that the funds were sent, so use language that says the Grant was submitted to their DAF provider. DAF donors are not eligible for tax receipts when recommending a Grant, so do not include receipt language in your success screen or confirmation emails.

### Retry Safely

[Create Grant](/api/grants/create) and [Create Recurring Grant](/api/recurring-grants/create) are both idempotent for a workflow session. If the first request times out, call the same endpoint again with the same `workflowSessionId`.

A `201` means the Grant was created and a `200` means one already existed for that session. Both are success, so store the Grant and stop retrying. Keep retrying only on a `409`, while submission is still in flight, and on a `502`, remembering that each `502` retry submits the gift to the provider again.

Stop and change what the donor sees on the rest. A `410` means the authorization expired without a Grant, so the donor has to complete DAFpay again. A `404` means the provider does not recognize the nonprofit and a `412` means the nonprofit cannot receive DAF gifts, so offer another payment method. Keep the donor's transaction pending until you know which of these happened, and never mark it complete on an error.

[Create Grant](/api/grants/create) lists every response it returns and what each one means.

### A Server-Side Example

> **Same Workflow Session**
>
> Retry with the same `workflowSessionId`. Starting a new session creates a new authorization and can result in a duplicate gift.

```javascript
class CreateGrantError extends Error {
  constructor(status, body) {
    super(`Create Grant failed: ${status}`);
    this.status = status;
    this.body = body;
  }
}

async function createGrant({ workflowSessionId, amount, applicationFeeAmount }) {
  const deadline = Date.now() + 60_000;

  for (let attempt = 0; Date.now() < deadline; attempt++) {
    const controller = new AbortController();
    const timer = setTimeout(() => controller.abort(), 10_000);

    try {
      const res = await fetch(`${CHARIOT_BASE_URL}/v1/grants`, {
        method: "POST",
        headers: {
          Authorization: `Bearer ${CHARIOT_API_KEY}`,
          "Content-Type": "application/json"
        },
        body: JSON.stringify({ workflowSessionId, amount, applicationFeeAmount }),
        signal: controller.signal
      });

      // 201 created it, 200 means it already existed. Both are success.
      if (res.status === 201 || res.status === 200) return res.json();

      // Submission is still running, or the request is worth sending again.
      if (res.status === 409 || res.status >= 500) {
        await backoff(attempt);
        continue;
      }

      // 410 expired, 400 invalid, 401/403 wrong credentials. The caller decides.
      throw new CreateGrantError(res.status, await res.json().catch(() => null));
    } catch (err) {
      // A timed-out request may still have created the Grant. Ask again with the
      // same session: that is what the idempotency contract is for.
      if (err.name === "AbortError") {
        await backoff(attempt);
        continue;
      }
      throw err;
    } finally {
      clearTimeout(timer);
    }
  }

  throw new CreateGrantError(408, null);
}

const backoff = (attempt) =>
  new Promise((r) => setTimeout(r, 2 ** attempt * 500 + Math.random() * 250));
```

### Amount Validation

Use the amount returned by `CHARIOT_SUCCESS` rather than the amount your form collected. A donor who selected \$75 on your form can change it to \$150 inside DAFpay, and the returned amount is the one they authorized.

The amount is in cents and must be a whole-dollar amount, divisible by 100. [Create Grant](/api/grants/create) rejects anything else, so validate it before you open DAFpay.

Do not set a universal minimum for DAFpay. Minimum Grant amounts vary by provider, and DAFpay prompts the donor to adjust an amount that is below the selected provider's minimum or above their available balance.

![](/_fern-files/_img/60024519926531cee8b2bdec35b9c16112b725af56b3299f984d342e52d80af7.webp)

Create Grant may still return a validation error if the final amount cannot be submitted. Handle that error without marking the transaction complete.

### Platform Fees

Use `applicationFeeAmount` only for the platform fee defined in your Chariot agreement. It is denominated in cents.

[Create Grant](/api/grants/create) validates `applicationFeeAmount` on its own against the Grant amount. The default ceiling is 210 basis points, and your Chariot agreement can raise it for your application. Chariot's own fee is charged separately and is not part of this check.

A donor-covered fee increases the Grant amount. It is not a separate tip. Do not offer a tip to a for-profit platform in a DAF transaction.

## Unintegrated Providers

Some DAF providers cannot accept a Grant directly through DAFpay. Chariot sets one of two behaviors for your platform:

1. Return the donor to your form to choose another payment method.
2. Record the donor's intent and help them complete the Grant in the provider's portal.

![](/_fern-files/_img/1217d88ae77aba5b5c616ae6e24c0e57503cbc79fbbd0297d9284a96f5cd84e3.webp)![](/_fern-files/_img/d26019613a01bcd60e3eef0b5cbda5bf58f04c16172c710c27c7fd86ba64166c.webp)

### How the Confirmation Arrives

If unintegrated Grants are enabled and a donor selects an unintegrated DAF and submits their intent, Chariot calls the Create Unintegrated Grant endpoint and `CHARIOT_EXIT` fires with the reason `UNINTEGRATED_GRANT_CONFIRMED`.

The exit event's `detail` includes the nonprofit and the Unintegrated Grant Chariot created:

```json
{
  "reason": "UNINTEGRATED_GRANT_CONFIRMED",
  "workflowSessionId": "79e772be-547d-4c9c-8b76-4ac4ed4c441a",
  "nonprofit": { "name": "Example Nonprofit", "ein": "12-3456789" },
  "unintegratedGrant": {
    "id": "67d66b89-51a0-4f17-a7b3-18c5dbac5361",
    "workflowSessionId": "79e772be-547d-4c9c-8b76-4ac4ed4c441a",
    "trackingId": "7HX2KNQ4R8",
    "amount": 25000,
    "fundId": "bbf485dd-a056-4a9d-89a8-06e201cdbf7f",
    "firstName": "Michael",
    "lastName": "Scott",
    "email": "michael@example.org",
    "metadata": { "platformTransactionId": "txn_123" },
    "fund": {
      "id": "bbf485dd-a056-4a9d-89a8-06e201cdbf7f",
      "name": "Example Charitable",
      "redirectUrl": "https://provider.example.com/grants/new"
    }
  }
}
```

### Confirmation Experience

Listen for the `CHARIOT_EXIT` with the reason `UNINTEGRATED_GRANT_CONFIRMED` and show instructions to complete the Grant through their provider portal:

* the nonprofit's name and EIN, from `detail.nonprofit`
* the intended amount
* the DAF provider link
* the tracking ID with the `Tracking ID:` prefix and a copy control

![](/_fern-files/_img/a1aef713f520a046d09c803bf6306c708a2cc78cd108f526262c1b16893ccc2a.webp)

DAFpay also emails the donor these instructions.

![](/_fern-files/_img/c4485b6a0bf36c8725aac9714fbf4d5cbc371a5483ec2b0c4d12b9f3de400cc8.webp)

### Unintegrated Grant Statuses

Unintegrated Grants are created with `status: Unknown`, which means the donor received instructions, not that they submitted the recommendation in their provider's portal. The status reaches `Completed` when the funds arrive, either in the nonprofit's Chariot Deposit Account or marked received outside it, and `Canceled` if the gift is ruled out. `unintegrated_grant.updated` fires on every status change, and most Grants stay at `Unknown`.

### Request

GET [https://api.givechariot.com/v1/unintegrated_grants](https://api.givechariot.com/v1/unintegrated_grants)

**`unintegrated_grants_list_example`**

```curl unintegrated_grants_list_example
curl -G https://api.givechariot.com/v1/unintegrated_grants \
     -H "Authorization: Bearer <token>" \
     -d connect_id=live_2d821da0ed8bc7256e260f4eb5244f2d8f06c576342f922ba2f0a416d8c98002 \
     -d tracking_id=L9E182VBGP
```

**`unintegrated_grants_list_example`**

```typescript unintegrated_grants_list_example
import { ChariotClient } from "@chariot-giving/typescript-sdk";

async function main() {
    const client = new ChariotClient({
        token: "YOUR_TOKEN_HERE",
    });
    await client.unintegratedGrants.list({
        connect_id: "live_2d821da0ed8bc7256e260f4eb5244f2d8f06c576342f922ba2f0a416d8c98002",
        tracking_id: "L9E182VBGP",
    });
}
main();

```

## Recurring Grants

A donor can set up a monthly recurring Grant from their donor advised fund. `MONTHLY` is the only supported frequency.

### The Provider Runs the Schedule

Chariot records that the donor set the gift up monthly. The DAF provider issues each month's Grant, and the donor changes or cancels it in their provider's portal, so Chariot is not notified and does not create a Grant each month. Reconcile the later Donations individually.

### Create the Recurring Grant

When the donor sets up a recurring gift, `CHARIOT_SUCCESS` carries a `recurringGrantIntent` in place of the `grantIntent`:

```json
{
  "workflowSessionId": "79e772be-547d-4c9c-8b76-4ac4ed4c441a",
  "recurringGrantIntent": {
    "fundId": "bbf485dd-a056-4a9d-89a8-06e201cdbf7f",
    "amount": 2000,
    "frequency": "MONTHLY",
    "metadata": {
      "platformTransactionId": "txn_123"
    }
  }
}
```

Call [Create Recurring Grant](/api/recurring-grants/create) rather than [Create Grant](/api/grants/create). An application fee applies to the first Grant only.

### Request

POST [https://api.givechariot.com/v1/recurring_grants](https://api.givechariot.com/v1/recurring_grants)

**`Simple recurring grant output.`**

```curl Simple recurring grant output.
curl -X POST https://api.givechariot.com/v1/recurring_grants \
     -H "Authorization: Bearer <token>" \
     -H "Content-Type: application/json" \
     -d '{
  "workflowSessionId": "string",
  "frequency": "MONTHLY",
  "amount": 15000
}'
```

**`Simple recurring grant output.`**

```typescript Simple recurring grant output.
import { ChariotClient } from "@chariot-giving/typescript-sdk";

async function main() {
    const client = new ChariotClient({
        token: "YOUR_TOKEN_HERE",
    });
    await client.recurringGrants.create({
        workflowSessionId: "string",
        frequency: "MONTHLY",
        amount: 15000,
    });
}
main();

```

```javascript
const res = await fetch(`${CHARIOT_BASE_URL}/v1/recurring_grants`, {
  method: "POST",
  headers: {
    Authorization: `Bearer ${process.env.CHARIOT_API_KEY}`,
    "Content-Type": "application/json"
  },
  body: JSON.stringify({
    workflowSessionId: "79e772be-547d-4c9c-8b76-4ac4ed4c441a",
    frequency: "MONTHLY",
    amount: 2000
  })
});
```

> **Info**
>
> Chariot is a financial technology company, not a bank. Chariot Accounts come with a Demand Deposit Account through our banking services partner, Column N.A., Member FDIC. Deposits in Chariot Accounts are eligible for FDIC insurance up to \$250,000 per depositor, for each insurable capacity in which the account is held.