Donations

Preview a staff-entered donation receipt

Validates the proposed gift and renders the actual receipt plan without creating a donation, charging, advancing a commitment or sending email. Split amounts must align and sum to the gift total. Plans honor suppression, notification preferences, source-specific templates, disclosure and recipient selection. HTTP200 may report skipped/suppressed/unavailable. DAF/QCD source preview requires the organization rollout and eligible owner/advisor/custodian records. Requires permission: one of donations, reports_view, reports_manage.

POST

admin

donations

receipt-preview

Preview a staff-entered donation receipt

curl --request POST \
  --url https://api.gratona.com/v1/admin/donations/receipt-preview \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "donor_id": 21,
  "designation": "entity-42",
  "amount": 75,
  "method": 1,
  "split_amounts": [
    75
  ],
  "created_at": "2026-10-20T12:00:00Z",
  "currency": "$",
  "dont_notify": false,
  "in_kind_category": "goods",
  "check_number": "1042",
  "addSoftCredit": false,
  "soft_credit_donor_id": 24,
  "soft_credit_amount": 25,
  "soft_credit_split_amounts": [
    25
  ],
  "soft_credit_type": 2,
  "dont_send_soft_credit_email": false,
  "is_tax_deductible": false,
  "giving_source": "direct",
  "advisor_donor_id": 24,
  "intermediary_donor_id": 30,
  "daf_disclosure": "named",
  "daf_fund_name": "Community Fund",
  "source_reference": "Grant reference123",
  "custom_fields": {}
}
'

import requests

url = "https://api.gratona.com/v1/admin/donations/receipt-preview"

payload = {
    "donor_id": 21,
    "designation": "entity-42",
    "amount": 75,
    "method": 1,
    "split_amounts": [75],
    "created_at": "2026-10-20T12:00:00Z",
    "currency": "$",
    "dont_notify": False,
    "in_kind_category": "goods",
    "check_number": "1042",
    "addSoftCredit": False,
    "soft_credit_donor_id": 24,
    "soft_credit_amount": 25,
    "soft_credit_split_amounts": [25],
    "soft_credit_type": 2,
    "dont_send_soft_credit_email": False,
    "is_tax_deductible": False,
    "giving_source": "direct",
    "advisor_donor_id": 24,
    "intermediary_donor_id": 30,
    "daf_disclosure": "named",
    "daf_fund_name": "Community Fund",
    "source_reference": "Grant reference123",
    "custom_fields": {}
}
headers = {
    "Authorization": "Bearer <token>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

const options = {
  method: 'POST',
  headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
  body: JSON.stringify({
    donor_id: 21,
    designation: 'entity-42',
    amount: 75,
    method: 1,
    split_amounts: [75],
    created_at: '2026-10-20T12:00:00Z',
    currency: '$',
    dont_notify: false,
    in_kind_category: 'goods',
    check_number: '1042',
    addSoftCredit: false,
    soft_credit_donor_id: 24,
    soft_credit_amount: 25,
    soft_credit_split_amounts: [25],
    soft_credit_type: 2,
    dont_send_soft_credit_email: false,
    is_tax_deductible: false,
    giving_source: 'direct',
    advisor_donor_id: 24,
    intermediary_donor_id: 30,
    daf_disclosure: 'named',
    daf_fund_name: 'Community Fund',
    source_reference: 'Grant reference123',
    custom_fields: {}
  })
};

fetch('https://api.gratona.com/v1/admin/donations/receipt-preview', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api.gratona.com/v1/admin/donations/receipt-preview",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => json_encode([
    'donor_id' => 21,
    'designation' => 'entity-42',
    'amount' => 75,
    'method' => 1,
    'split_amounts' => [
        75
    ],
    'created_at' => '2026-10-20T12:00:00Z',
    'currency' => '$',
    'dont_notify' => false,
    'in_kind_category' => 'goods',
    'check_number' => '1042',
    'addSoftCredit' => false,
    'soft_credit_donor_id' => 24,
    'soft_credit_amount' => 25,
    'soft_credit_split_amounts' => [
        25
    ],
    'soft_credit_type' => 2,
    'dont_send_soft_credit_email' => false,
    'is_tax_deductible' => false,
    'giving_source' => 'direct',
    'advisor_donor_id' => 24,
    'intermediary_donor_id' => 30,
    'daf_disclosure' => 'named',
    'daf_fund_name' => 'Community Fund',
    'source_reference' => 'Grant reference123',
    'custom_fields' => [
        
    ]
  ]),
  CURLOPT_HTTPHEADER => [
    "Authorization: Bearer <token>",
    "Content-Type: application/json"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://api.gratona.com/v1/admin/donations/receipt-preview"

	payload := strings.NewReader("{\n  \"donor_id\": 21,\n  \"designation\": \"entity-42\",\n  \"amount\": 75,\n  \"method\": 1,\n  \"split_amounts\": [\n    75\n  ],\n  \"created_at\": \"2026-10-20T12:00:00Z\",\n  \"currency\": \"$\",\n  \"dont_notify\": false,\n  \"in_kind_category\": \"goods\",\n  \"check_number\": \"1042\",\n  \"addSoftCredit\": false,\n  \"soft_credit_donor_id\": 24,\n  \"soft_credit_amount\": 25,\n  \"soft_credit_split_amounts\": [\n    25\n  ],\n  \"soft_credit_type\": 2,\n  \"dont_send_soft_credit_email\": false,\n  \"is_tax_deductible\": false,\n  \"giving_source\": \"direct\",\n  \"advisor_donor_id\": 24,\n  \"intermediary_donor_id\": 30,\n  \"daf_disclosure\": \"named\",\n  \"daf_fund_name\": \"Community Fund\",\n  \"source_reference\": \"Grant reference123\",\n  \"custom_fields\": {}\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("Authorization", "Bearer <token>")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

HttpResponse<String> response = Unirest.post("https://api.gratona.com/v1/admin/donations/receipt-preview")
  .header("Authorization", "Bearer <token>")
  .header("Content-Type", "application/json")
  .body("{\n  \"donor_id\": 21,\n  \"designation\": \"entity-42\",\n  \"amount\": 75,\n  \"method\": 1,\n  \"split_amounts\": [\n    75\n  ],\n  \"created_at\": \"2026-10-20T12:00:00Z\",\n  \"currency\": \"$\",\n  \"dont_notify\": false,\n  \"in_kind_category\": \"goods\",\n  \"check_number\": \"1042\",\n  \"addSoftCredit\": false,\n  \"soft_credit_donor_id\": 24,\n  \"soft_credit_amount\": 25,\n  \"soft_credit_split_amounts\": [\n    25\n  ],\n  \"soft_credit_type\": 2,\n  \"dont_send_soft_credit_email\": false,\n  \"is_tax_deductible\": false,\n  \"giving_source\": \"direct\",\n  \"advisor_donor_id\": 24,\n  \"intermediary_donor_id\": 30,\n  \"daf_disclosure\": \"named\",\n  \"daf_fund_name\": \"Community Fund\",\n  \"source_reference\": \"Grant reference123\",\n  \"custom_fields\": {}\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://api.gratona.com/v1/admin/donations/receipt-preview")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["Authorization"] = 'Bearer <token>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"donor_id\": 21,\n  \"designation\": \"entity-42\",\n  \"amount\": 75,\n  \"method\": 1,\n  \"split_amounts\": [\n    75\n  ],\n  \"created_at\": \"2026-10-20T12:00:00Z\",\n  \"currency\": \"$\",\n  \"dont_notify\": false,\n  \"in_kind_category\": \"goods\",\n  \"check_number\": \"1042\",\n  \"addSoftCredit\": false,\n  \"soft_credit_donor_id\": 24,\n  \"soft_credit_amount\": 25,\n  \"soft_credit_split_amounts\": [\n    25\n  ],\n  \"soft_credit_type\": 2,\n  \"dont_send_soft_credit_email\": false,\n  \"is_tax_deductible\": false,\n  \"giving_source\": \"direct\",\n  \"advisor_donor_id\": 24,\n  \"intermediary_donor_id\": 30,\n  \"daf_disclosure\": \"named\",\n  \"daf_fund_name\": \"Community Fund\",\n  \"source_reference\": \"Grant reference123\",\n  \"custom_fields\": {}\n}"

response = http.request(request)
puts response.read_body

{
  "status": "available",
  "reason": "no_template",
  "trigger": "pay_receipt",
  "recipient": {
    "id": 21,
    "name": "Jane Donor",
    "email": "jane@example.org"
  },
  "previews": [
    {
      "label": "Education",
      "subject": "Thank you for your gift",
      "body": "<p>Thank you for supporting Education.</p>",
      "template_id": 42
    }
  ],
  "unavailable_designations": [
    "Education"
  ],
  "recipients": [
    {
      "role": "primary",
      "role_label": "Donor",
      "donation_type": "default",
      "status": "available",
      "reason": "no_email",
      "acknowledgement_path": "print",
      "recipient": {
        "id": 21,
        "name": "Jane Donor",
        "email": "jane@example.org"
      },
      "previews": [
        {
          "label": "Education",
          "subject": "Thank you for your gift",
          "body": "<p>Thank you for supporting Education.</p>",
          "template_id": 42
        }
      ],
      "unavailable_designations": [
        "Education"
      ],
      "template_setup_issues": [
        {}
      ]
    }
  ]
}

{
  "message": "Unauthorized",
  "status": "error"
}

{
  "errors": {},
  "status": "error",
  "message": "The given data was invalid."
}

Authorizations

Authorization

string

header

required

Passport bearer token authentication for legacy admin sessions.

Body

application/json

Validated request fields for this operation.

donor_id

integer

required

Active organization donor; financial party rules depend on giving_source.

Example:

21

designation

required

Organization-owned entity-ID or desig-ID reference, or split allocation references. Array form requires matching split_amounts.

Example:

"entity-42"

amount

number

required

Total amount, at most two decimal places. Splits must sum exactly to this amount.

Required range: x >= 0.01

Example:

75

method

required

Registered compatibility payment-method ID. DAF/QCD accept received-money methods1,2,4,7.

Example:

1

split_amounts

number[] | null

Required when designation is an array; one positive amount per reference.

Required range: x > 0

created_at

string<date-time> | null

Example:

"2026-10-20T12:00:00Z"

currency

string | null

Maximum string length: 10

Example:

"$"

dont_notify

Compatibility boolean flag; use0/1 or false/true.

Example:

false

in_kind_category

string | null

Maximum string length: 100

Example:

"goods"

check_number

string | null

Maximum string length: 100

Example:

"1042"

addSoftCredit

boolean | null

Enables manual Direct-gift recognition; requires donor, active type and positive amount.

Example:

false

soft_credit_donor_id

integer | null

Example:

24

soft_credit_amount

number | null

Required when addSoftCredit is enabled; cannot exceed the total gift.

Required range: x >= 0

Example:

25

soft_credit_split_amounts

number[] | null

For multiple allocations, sum to the soft credit total and never exceed corresponding gift splits.

Required range: x >= 0

soft_credit_type

integer | null

Active manual type; automatic DAF/QCD types are not selectable.

Example:

2

dont_send_soft_credit_email

Compatibility boolean flag; use0/1 or false/true.

Example:

false

is_tax_deductible

Scalar or allocation-aligned tax flag; QCD forces non-deductible treatment.

Example:

false

giving_source

string | null

Canonical source values; known compatibility aliases are normalized. Special sources require daf_qcd_giving_v1.

Maximum string length: 40

Example:

"direct"

advisor_donor_id

integer | null

DAF recommending supporter; named disclosure requires it.

Example:

24

intermediary_donor_id

integer | null

Organization-owned IRA custodian required for QCD.

Example:

30

daf_disclosure

enum<string> | null

DAF acknowledgement disclosure; fund_only requires a nonblank fund name.

Available options:

named,

fund_only,

anonymous,

null

Maximum string length: 16

Example:

"named"

daf_fund_name

string | null

Permitted only for named or fund_only disclosure.

Maximum string length: 191

Example:

"Community Fund"

source_reference

string | null

Maximum string length: 191

Example:

"Grant reference123"

custom_fields

object | null

Organization-defined gift field map. Definitions control keys, scalar types, choices and conditional requirements. Validated before preview; the receipt-preview handler forwards only its explicit preview fields.

Response

Operation result.

status

enum<string>

required

Available options:

available,

skipped,

suppressed,

unavailable

Example:

"available"

reason

string | null

required

Example:

"no_template"

trigger

enum<string>

required

Available options:

pay_receipt,

pay_fail

Example:

"pay_receipt"

recipient

object

required

Show child attributes

previews

object[]

required

Show child attributes

unavailable_designations

string[]

required

recipients

object[]

required

Show child attributes

Preview a staff-entered donation receipt

curl --request POST \
  --url https://api.gratona.com/v1/admin/donations/receipt-preview \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "donor_id": 21,
  "designation": "entity-42",
  "amount": 75,
  "method": 1,
  "split_amounts": [
    75
  ],
  "created_at": "2026-10-20T12:00:00Z",
  "currency": "$",
  "dont_notify": false,
  "in_kind_category": "goods",
  "check_number": "1042",
  "addSoftCredit": false,
  "soft_credit_donor_id": 24,
  "soft_credit_amount": 25,
  "soft_credit_split_amounts": [
    25
  ],
  "soft_credit_type": 2,
  "dont_send_soft_credit_email": false,
  "is_tax_deductible": false,
  "giving_source": "direct",
  "advisor_donor_id": 24,
  "intermediary_donor_id": 30,
  "daf_disclosure": "named",
  "daf_fund_name": "Community Fund",
  "source_reference": "Grant reference123",
  "custom_fields": {}
}
'

import requests

url = "https://api.gratona.com/v1/admin/donations/receipt-preview"

payload = {
    "donor_id": 21,
    "designation": "entity-42",
    "amount": 75,
    "method": 1,
    "split_amounts": [75],
    "created_at": "2026-10-20T12:00:00Z",
    "currency": "$",
    "dont_notify": False,
    "in_kind_category": "goods",
    "check_number": "1042",
    "addSoftCredit": False,
    "soft_credit_donor_id": 24,
    "soft_credit_amount": 25,
    "soft_credit_split_amounts": [25],
    "soft_credit_type": 2,
    "dont_send_soft_credit_email": False,
    "is_tax_deductible": False,
    "giving_source": "direct",
    "advisor_donor_id": 24,
    "intermediary_donor_id": 30,
    "daf_disclosure": "named",
    "daf_fund_name": "Community Fund",
    "source_reference": "Grant reference123",
    "custom_fields": {}
}
headers = {
    "Authorization": "Bearer <token>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

const options = {
  method: 'POST',
  headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
  body: JSON.stringify({
    donor_id: 21,
    designation: 'entity-42',
    amount: 75,
    method: 1,
    split_amounts: [75],
    created_at: '2026-10-20T12:00:00Z',
    currency: '$',
    dont_notify: false,
    in_kind_category: 'goods',
    check_number: '1042',
    addSoftCredit: false,
    soft_credit_donor_id: 24,
    soft_credit_amount: 25,
    soft_credit_split_amounts: [25],
    soft_credit_type: 2,
    dont_send_soft_credit_email: false,
    is_tax_deductible: false,
    giving_source: 'direct',
    advisor_donor_id: 24,
    intermediary_donor_id: 30,
    daf_disclosure: 'named',
    daf_fund_name: 'Community Fund',
    source_reference: 'Grant reference123',
    custom_fields: {}
  })
};

fetch('https://api.gratona.com/v1/admin/donations/receipt-preview', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api.gratona.com/v1/admin/donations/receipt-preview",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => json_encode([
    'donor_id' => 21,
    'designation' => 'entity-42',
    'amount' => 75,
    'method' => 1,
    'split_amounts' => [
        75
    ],
    'created_at' => '2026-10-20T12:00:00Z',
    'currency' => '$',
    'dont_notify' => false,
    'in_kind_category' => 'goods',
    'check_number' => '1042',
    'addSoftCredit' => false,
    'soft_credit_donor_id' => 24,
    'soft_credit_amount' => 25,
    'soft_credit_split_amounts' => [
        25
    ],
    'soft_credit_type' => 2,
    'dont_send_soft_credit_email' => false,
    'is_tax_deductible' => false,
    'giving_source' => 'direct',
    'advisor_donor_id' => 24,
    'intermediary_donor_id' => 30,
    'daf_disclosure' => 'named',
    'daf_fund_name' => 'Community Fund',
    'source_reference' => 'Grant reference123',
    'custom_fields' => [
        
    ]
  ]),
  CURLOPT_HTTPHEADER => [
    "Authorization: Bearer <token>",
    "Content-Type: application/json"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://api.gratona.com/v1/admin/donations/receipt-preview"

	payload := strings.NewReader("{\n  \"donor_id\": 21,\n  \"designation\": \"entity-42\",\n  \"amount\": 75,\n  \"method\": 1,\n  \"split_amounts\": [\n    75\n  ],\n  \"created_at\": \"2026-10-20T12:00:00Z\",\n  \"currency\": \"$\",\n  \"dont_notify\": false,\n  \"in_kind_category\": \"goods\",\n  \"check_number\": \"1042\",\n  \"addSoftCredit\": false,\n  \"soft_credit_donor_id\": 24,\n  \"soft_credit_amount\": 25,\n  \"soft_credit_split_amounts\": [\n    25\n  ],\n  \"soft_credit_type\": 2,\n  \"dont_send_soft_credit_email\": false,\n  \"is_tax_deductible\": false,\n  \"giving_source\": \"direct\",\n  \"advisor_donor_id\": 24,\n  \"intermediary_donor_id\": 30,\n  \"daf_disclosure\": \"named\",\n  \"daf_fund_name\": \"Community Fund\",\n  \"source_reference\": \"Grant reference123\",\n  \"custom_fields\": {}\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("Authorization", "Bearer <token>")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

HttpResponse<String> response = Unirest.post("https://api.gratona.com/v1/admin/donations/receipt-preview")
  .header("Authorization", "Bearer <token>")
  .header("Content-Type", "application/json")
  .body("{\n  \"donor_id\": 21,\n  \"designation\": \"entity-42\",\n  \"amount\": 75,\n  \"method\": 1,\n  \"split_amounts\": [\n    75\n  ],\n  \"created_at\": \"2026-10-20T12:00:00Z\",\n  \"currency\": \"$\",\n  \"dont_notify\": false,\n  \"in_kind_category\": \"goods\",\n  \"check_number\": \"1042\",\n  \"addSoftCredit\": false,\n  \"soft_credit_donor_id\": 24,\n  \"soft_credit_amount\": 25,\n  \"soft_credit_split_amounts\": [\n    25\n  ],\n  \"soft_credit_type\": 2,\n  \"dont_send_soft_credit_email\": false,\n  \"is_tax_deductible\": false,\n  \"giving_source\": \"direct\",\n  \"advisor_donor_id\": 24,\n  \"intermediary_donor_id\": 30,\n  \"daf_disclosure\": \"named\",\n  \"daf_fund_name\": \"Community Fund\",\n  \"source_reference\": \"Grant reference123\",\n  \"custom_fields\": {}\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://api.gratona.com/v1/admin/donations/receipt-preview")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["Authorization"] = 'Bearer <token>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"donor_id\": 21,\n  \"designation\": \"entity-42\",\n  \"amount\": 75,\n  \"method\": 1,\n  \"split_amounts\": [\n    75\n  ],\n  \"created_at\": \"2026-10-20T12:00:00Z\",\n  \"currency\": \"$\",\n  \"dont_notify\": false,\n  \"in_kind_category\": \"goods\",\n  \"check_number\": \"1042\",\n  \"addSoftCredit\": false,\n  \"soft_credit_donor_id\": 24,\n  \"soft_credit_amount\": 25,\n  \"soft_credit_split_amounts\": [\n    25\n  ],\n  \"soft_credit_type\": 2,\n  \"dont_send_soft_credit_email\": false,\n  \"is_tax_deductible\": false,\n  \"giving_source\": \"direct\",\n  \"advisor_donor_id\": 24,\n  \"intermediary_donor_id\": 30,\n  \"daf_disclosure\": \"named\",\n  \"daf_fund_name\": \"Community Fund\",\n  \"source_reference\": \"Grant reference123\",\n  \"custom_fields\": {}\n}"

response = http.request(request)
puts response.read_body

{
  "status": "available",
  "reason": "no_template",
  "trigger": "pay_receipt",
  "recipient": {
    "id": 21,
    "name": "Jane Donor",
    "email": "jane@example.org"
  },
  "previews": [
    {
      "label": "Education",
      "subject": "Thank you for your gift",
      "body": "<p>Thank you for supporting Education.</p>",
      "template_id": 42
    }
  ],
  "unavailable_designations": [
    "Education"
  ],
  "recipients": [
    {
      "role": "primary",
      "role_label": "Donor",
      "donation_type": "default",
      "status": "available",
      "reason": "no_email",
      "acknowledgement_path": "print",
      "recipient": {
        "id": 21,
        "name": "Jane Donor",
        "email": "jane@example.org"
      },
      "previews": [
        {
          "label": "Education",
          "subject": "Thank you for your gift",
          "body": "<p>Thank you for supporting Education.</p>",
          "template_id": 42
        }
      ],
      "unavailable_designations": [
        "Education"
      ],
      "template_setup_issues": [
        {}
      ]
    }
  ]
}

{
  "message": "Unauthorized",
  "status": "error"
}

{
  "errors": {},
  "status": "error",
  "message": "The given data was invalid."
}